                          The XKB Configuration Guide

                                  Kamil Toman

                                 Ivan U. Pascal

                           X Version 11, Release 7.7

                                 November 2010

   This document describes how to configure Xorg XKB from a user's point of
   view. It covers basic configuration syntax and gives also a few examples.

   This version covers Xorg server versions 1.8 and later, used with the data
   files from the [1]xkeyboard-config project.

   --------------------------------------------------------------------------

                               Table of Contents

   [2]Overview

   [3]Selecting XKB Configuration

                [4]Basic Configuration

                [5]Advanced Configuration

                [6]Even More Advanced Configuration

                [7]Basic Global Options

   [8]Keymap XKB Configuration

                                    Overview

   The XKB configuration is decomposed into a number of components. Selecting
   proper parts and combining them back you can achieve most of the
   configurations you might need. Unless you have a completely atypical
   keyboard you really don't need to touch any of the xkb configuration
   files.

   Some desktop environments now provide integrated graphical configuration
   tools for setting XKB configuration as part of your desktop session. The
   instructions in this document are provided for those without such support,
   those who need to configure XKB before the session startup (such as at the
   login screen), or those who need to perform more advanced configuration
   than those tools provide.

                          Selecting XKB Configuration

   The easiest and the most natural way to specify a keyboard mapping is to
   use the rules component. As its name suggests it describes a number of
   general rules to combine all bits and pieces into a valid and useful
   keyboard mapping. All you need to do is to select a suitable rules file
   and then to feed it with a few parameters that will adjust the keyboard
   behaviour to fulfill your needs.

   The parameters are:

   XkbRules   files of rules to be used for keyboard mapping composition
   XkbModel   name of the model of your keyboard type
   XkbLayout  layout(s) you intend to use
   XkbVariant variant(s) of the layout you intend to use
   XkbOptions extra xkb configuration options

   The rules file used depends on your system. The rules files commonly used
   with Xorg are provided by the [9]xkeyboard-config project. On Linux
   systems, the evdev rules are most commonly used, on other systems the base
   rules are used. Some additional rules files exist for historical reasons,
   but are no longer widely used. In general, it's best to simply not specify
   the rules file, in order to use the default rules selected automatically
   by the X server.

   For each rules file there is a description file named <vendor-rules>.lst,
   for instance base.lst which is located in the xkb configuration
   subdirectory rules (for example /usr/share/X11/xkb/rules).

  Basic Configuration

   Let's say you want to configure a PC-style American keyboard with 104 keys
   as described in base.lst. This can be done by simply writing several lines
   from below to a new configuration file in /etc/X11/xorg.conf.d, such as
   /etc/X11/xorg.conf.d/90-custom-kbd.conf.

 Section "InputClass"
     Identifier "keyboard defaults"
     MatchIsKeyboard "on"

     Option "XkbModel" "pc104"
     Option "XkbLayout" "us"
     Option "XKbOptions" ""
 EndSection


   The values of XkbModel and XkbLayout are really not surprising. The
   XkbOptions has been explicitly set to the empty set of parameters. The
   XkbVariant option has been left out. That means the default variant named
   basic is loaded.

   Of course, this can be also done at runtime using the utility setxkbmap.
   The shell command loading the same keyboard mapping would look like:

 setxkbmap -model pc104 -layout us -option ""


   The configuration and the shell command would be very analogous for most
   other layouts (internationalized mappings).

   If you wanted to enable the Ctrl+Alt+Backspace sequence to kill the X
   server by default, you could create a configuration snippet
   /etc/X11/xorg.conf.d/90-zap.conf containing:

 Section "InputClass"
     Identifier "keyboard defaults"
     MatchIsKeyboard "on"

     Option "XKbOptions" "terminate:ctrl_alt_bksp"
 EndSection


   This would be equivalent to running the shell command:

 setxkbmap -option "terminate:ctrl_alt_bksp"


  Advanced Configuration

   You can use multi-layouts xkb configuration. What does it mean? Basically
   it allows to load up to four different keyboard layouts at a time. Each
   such layout would reside in its own group. The groups (unlike complete
   keyboard remapping) can be switched very fast from one to another by a
   combination of keys.

   Let's say you want to configure your new Logitech cordless desktop
   keyboard, you intend to use three different layouts at the same time - us,
   czech and german (in this order), and that you are used to Alt+Shift
   combination for switching among them.

   Then the configuration snippet could look like this:

 Section "InputClass"
     Identifier "Logitech Cordless"
     MatchIsKeyboard   "on"

     Option "XkbModel" "logicordless"
     Option "XkbLayout" "us,cz,de"
     Option "XKbOptions" "grp:alt_shift_toggle"
 EndSection


   Of course, this can be also done at runtime using the utility setxkbmap.
   The shell command loading the same keyboard mapping would look like:

 setxkbmap -model logicordless -layout "us,cz,de" \
          -option "grp:alt_shift_toggle"


  Even More Advanced Configuration

   Okay, let's say you are more demanding. You do like the example above but
   you want it to change a bit. Let's imagine you want the czech keyboard
   mapping to use another variant but basic. The configuration snippet then
   changes into:

 Section "InputClass"
     Identifier "Logitech Cordless"
     MatchIsKeyboard   "on"

     Option "XkbModel" "logicordless"
     Option "XkbLayout" "us,cz,de"
     Option "XkbVariant" ",bksl,"
     Option "XKbOptions" "grp:alt_shift_toggle"
 EndSection


   That seems tricky but it is not. The logic for settings of variants is the
   same as for layouts, that means the first and the third variant settings
   are left out (set to basic), the second is set to bksl (a special variant
   with an enhanced definition of the backslash key).

   Analogously, the loading runtime will change to:

 setxkbmap -model logicordless -layout "us,cz,de" \
          -variant ",bksl," -option "grp:alt_shift_toggle"


  Basic Global Options

   For a list of available options, with a short description of what they do,
   see the section starting with "! option" in the rules/*.lst files.

                            Keymap XKB Configuration

   Keymap configuration is the way formerly used to configure xkb. The user
   included a special keymap file which specified the direct xkb
   configuration. This method has been obsoleted by previously described
   rules files which are far more flexible and allow simpler and more
   intuitive syntax. It is preserved merely for compatibility reasons and
   should be avoided if possible.

References

   Visible links
   1. http://www.freedesktop.org/wiki/Software/XKeyboardConfig
   2. file:///tmp/xmlto.IUovBi/XKB-Config.proc#Overview
   3. file:///tmp/xmlto.IUovBi/XKB-Config.proc#Selecting_XKB_Configuration
   4. file:///tmp/xmlto.IUovBi/XKB-Config.proc#Basic_Configuration
   5. file:///tmp/xmlto.IUovBi/XKB-Config.proc#Advanced_Configuration
   6. file:///tmp/xmlto.IUovBi/XKB-Config.proc#Even_More_Advanced_Configuration
   7. file:///tmp/xmlto.IUovBi/XKB-Config.proc#Basic_Global_Options
   8. file:///tmp/xmlto.IUovBi/XKB-Config.proc#Keymap_XKB_Configuration
   9. http://www.freedesktop.org/wiki/Software/XKeyboardConfig
