Tool for setting up a custom keyboard layout in X

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

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:

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

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:

make image

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:

./generate-xkl.sh fi-hs-qwerty
make BINDIR=~/bin

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:

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

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:

./generate-deb-pkg.sh <control-file>

There are example control files in the directory packages. To generate all packages in that directory, run the following command:

make pkg

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.

./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

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:

sudo xkl-regen-evdev update

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