https://github.com/kopoli/keyboard

A tool for setting custom keyboard layout in X
https://github.com/kopoli/keyboard

Last synced: 8 days ago
JSON representation

A tool for setting custom keyboard layout in X

• Host: GitHub
• URL: https://github.com/kopoli/keyboard
• Owner: kopoli
• License: mit
• Created: 2014-09-21T16:40:37.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2015-09-06T18:14:11.000Z (over 9 years ago)
• Last Synced: 2024-11-14T08:15:10.607Z (2 months ago)
• Language: Shell
• Homepage:
• Size: 277 KB
• Stars: 5
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

        
* Tool for setting up a custom keyboard layout in X

  I use this tool to set my keyboards to the following layout:

  [[./img/keyboard-layout.png]]

  This is a typical QWERTY layout with Finnish configuration with the

  following changes:

  - Control_L replaces caps-lock.

  - Hyper_L replaces Control_L.

  - Tab and Meta_L are swapped.

  - There is a layout for Kinesis Freestyle2 keyboard with the

    following additional changes:

    - Insert and pause-break buttons are swapped. In Freestyle2 the insert

      button is behind a modal Fn key.

    - Reorganize the Home-column into the following order: Home, PageUp,

      PageDown, End

  Contents:

  - xkb-layout.sh: A script that sets the current keyboard layout.

  - xkb-unlocker: A C program that disables caps lock if it is currently

    enabled.

  - keyboard layout files:

    - keyboard/*.xkb: Layouts that are selectable using xkb-layout.

  - keyboard symbols files:

    - keyboard/symbols/special: The configuration for the above paragraph.

  - generate-deb-pkg.sh: A script to generate debian packages of layouts described by

    the files in directory packages.

  - generate-xkl.sh: generates a script that runs the xkb-layout.sh with the

    wanted keyboard layout. The generated script is called 'xkl' and should be

    copied somewhere in $PATH.

** Requirements

  For xkb-layout script:

  - xkbcomp

  - setxkbmap

  - notify-send (for displaying the changed keymap)

  For caps-lock unlocking:

  - A C-compiler

  - libx11 development packages

  For building and generating the keyboard layout file:

  - GNU Make

  - xkbprint

  - ps2pdf

  For generating debian packages:

  - dpkg-deb

  - fakeroot

** Basic usage of xkb-layout script

   Running the ./xkb-layout.sh without arguments gives the basic

   usage. Example:

   #+begin_src shell

   ./xkb-layout.sh fi-hs-qwerty

   #+end_src

   This will enable the keyboard layout described in the introduction of this

   file.

** Displaying of the current keyboard layout

   You can create a PDF-image of the current keyboard layout with the

   following:

   #+begin_src shell

   make image

   #+end_src

   The first image is with no modifiers pressed, the following is with shift

   and thereafter is shift+alt-gr. The image will be similar to the one

   displayed in this README. See manpage of xkbprint(1).

** Installing the layout setting script $PATH

   You should run the './generate-xkl.sh' script and select your wanted

   keyboard layout. This will create the 'xkl' script. Afterwards the Makefile

   can install that wrapper to BINDIR. It will also create *.desktop -files

   for the keyboard setting and install them into INSTDIR. Look into the

   Makefile for details.

   The following command compiles the xkb-unlocker, installs the wrapperscript,

   xkb-unlocker to ~/bin and the desktop-files to ~/.local/share/applications:

   #+begin_src shell

   ./generate-xkl.sh fi-hs-qwerty

   make BINDIR=~/bin

   #+end_src

   This git repository needs to exist when running the wrapper script, because

   the keyboard configurations are kept in the keyboard/ subdirectory.

   There is also a make uninstall command to remove the installed files from

   the aforementioned directories.

** Modifying and creating layouts

   You can modify whole layouts by modifying the xkb-files in the keyboard

   directory. You can add or modify partial symbol mappings in the files of

   the keyboard/symbols directory.

   Guides on the syntax can be found through google and for example:

   - http://www.charvolant.org/~doug/xkb/html/node5.html

   - https://wiki.archlinux.org/index.php/X_KeyBoard_extension#xkb_symbols

   When developing keyboard layouts the X will cache the generated keymap when

   it is enabled the first time and it will use the cache from then

   on. Therefore one should remove the cache in the following way:

   #+begin_src shell

   rm -f /var/lib/xkb/server-*.xkm

   #+end_src

** Creating a debian package of a keyboard layout

   You can create a proper keyboard layout file that can be loaded with

   setxkbmap with the generate-deb-pkg.sh script. The basic usage is the

   following:

   #+begin_src shell

   ./generate-deb-pkg.sh 

   #+end_src

   There are example control files in the directory packages. To generate all

   packages in that directory, run the following command:

   #+begin_src shell

   make pkg

   #+end_src

*** The control file for generating the package

    The control file is a debian control file with some special headers:

    XKL-symbols: The partial xkb_symbols -sections that will be included to the

    default xkb_symbols -section in the generated symbols file.

    XKL-name: The string that will be in the name[Group1] -item in the

    xkb_symbols section.

    XKL-data: The file that is used as the base of the xkb_symbols -file. The

    path is relative to the directory the command is run from. The file is

    parsed until a row with string "IGNORE-FOLLOWING-XKL-DATA" is found. This

    is to make possible to have keymaps that collect the different

    sub-keymaps, but not have them in the installed keymap file

    XKL-shortDescription: The contents of the shortDescription tag in the

    evdev.xml file.

    XKL-langiso639Id: The contents of langiso639Id tag in the evdev.xml file.

    XKL-files: Files that are searched from directory ${PKGNAME}-files and

    installed to given directory. The arguments are a space separated list of

    the following format "filename|directory" See an example in the file

    packages/xkl-common.

    Some variables are expanded with shell. Notable ones:

    ${PKGNAME} - The filename of the keymap.

*** Example usage

    The following will generate and install keymap package. Finally it will

    create a keyboard.pdf with the current keyboard layout.

    #+begin_src shell

    ./generate-deb-pkg.sh xkl-common

    ./generate-deb-pkg.sh xkl-hyper

    sudo dpkg -i xkl-common*deb

    sudo dpkg -i xkl-hyper_*deb

    setxkbmap xkl-hyper

    make image

    #+end_src

*** Making it available for the system's keyboard layout utility

    To add a layout to a system's own utility, usually the

    /usr/share/X11/xkb/rules/evdev.xml file needs to be modified. The package

    xkl-common contains a script called xkl-regen-evdev which will modify that

    file in accordance to xml fragments found in directory

    /usr/share/X11/xkb/rules/evdev.xml.d. All control files containing the

    XKL-name (etc.) will generate an xml-fragment in addition to the actual

    keyboard layout files. Run the following command after installing the

    xkb-* packages to regenerate the evdev.xml file:

    #+begin_src shell

    sudo xkl-regen-evdev update

    #+end_src

    When your system recognizes the keyboard layout you don't need to run any

    scripts to enable it. Which makes the 'xkl' trickery unnecessary.

    *Note:* If the evdev.xml file gets corrupted, you should just install it

    back from the 'xkb-data' debian package. (This is just for being prepared,

    because the script might contain bugs.)

** License

   MIT