* 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 <control-file>
   #+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