The XKB Configuration Guide

                         Kamil Toman, Ivan U. Pascal

                              25 November 2002

                                  Abstract

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


1.  Overview

The XKB configuration system consists of a number of components. Selecting
and combining the proper parts, 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 component files themselves.


2.  Selecting an XKB configuration

The easiest and 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 on how to combine the 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:

   o XkbRules - the file of rules to be used for keyboard mapping composition

   o XkbModel - the name of the model of your keyboard

   o XkbLayout - the layout(s) you intend to use

   o XkbVariant - the variant(s) of the layout(s) you intend to use

   o XkbOptions - extra xkb configuration options

The proper rules file depends on your vendor. In reality, the commonest
file of rules is xfree86. For each rules file there is a description file
named <vendor>.lst, for instance xfree86.lst, which is located in the xkb
configuration subdirectory 'rules' (for example /etc/X11/xkb/rules).

2.1  Basic Configuration

Let's say you want to configure a PC-style American keyboard with 104 keys
as described in xfree86.lst. It can be done by simply writing several lines
to your XFree86 configuration file (often found as /etc/X11/XF86Config):

     Section "InputDevice"
         Identifier "Keyboard1"
         Driver "Keyboard"

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

The values of the parameters XkbModel and XkbLayout are really not surprising.
The parameter XkbOptions has been explicitly set to empty, meaning no options.
The parameter XkbVariant has been left out, meaning that the default variant
(the first variant in the file, often named 'basic') will be loaded.

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

     setxkbmap -rules xfree86 -model pc104 -layout us -option ""

The configuration snippet and the shell command will be very similar for most
other layouts (internationalized mappings).

2.2  Advanced Configuration

Since XFree86 4.3.x, you can use multi-layouts xkb configuration. What does
it mean? Basically it allows you to load up to four different keyboard layouts
at a time. Each such layout will reside in its own group. The groups (unlike
a complete keyboard remapping) can be switched very fast from one to another
with some key combination.

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 the Alt+Shift combination
for switching among them.

Then the configuration snippet could look like this:

     Section "InputDevice"
         Identifier "Keyboard2"
         Driver "Keyboard"

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

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

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

2.3  Even More Advanced Configuration

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

     Section "InputDevice"
         Identifier "Keyboard2"
         Driver "Keyboard"

         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 setting variants is the same
as for layouts, which means that the first and the third variant settings are
left out (set to basic), and the second is set to bksl (a special variant with
an enhanced definition of the backslash key).

Analogically, the loading at runtime will change to:

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

2.4  Basic Global Options

See the rules/*.lst files.


3.  Direct XKB Configuration

Generally, you can directly prescribe what configuration for each of the basic
xkb components should be used to form the resulting keyboard mapping. This
method is rather "brute force". You precisely need to know the structure and
the meaning of all of the used configuration components.

This method also exposes all xkb configuration details directly into the
XFree86 configuration file, which is a not very fortunate fact. In rare
occasions it may be needed, though. So how does it work?

3.1  Basic Components

There are five basic components used to form a keyboard mapping:

   o key codes - a translation of the scan codes produced by the keyboard
     into a suitable symbolic form

   o types - a specification of what various combinations of modifiers produce

   o key symbols - a translation of symbolic key codes into actual symbols

   o geometry - a description of all physical keyboard dimensions

   o compatibility maps - a specification of what action each key should
     produce in order to preserve compatibility with XKB-unware clients

3.2  Example Configuration

Look at the following example:

     Section "InputDevice"
         Identifier "Keyboard0"
         Driver "Keyboard"

         Option "XkbKeycodes" "xfree86"
         Option "XkbTypes"    "default"
         Option "XkbSymbols"  "en_US(pc104)+de+swapcaps"
         Option "XkbGeometry" "pc(pc104)"
         Option "XkbCompat"   "basic+pc+iso9995"
     EndSection

This configuration sets the standard XFree86 interpretation of keyboard
keycodes, and sets the default modificator types. The symbol table is
composed of an extended US keyboard layout in its variant for PC keyboards
with 104 keys, and all keys for a German layout are redefined. Also the
logical meanings of the Caps-lock and Control keys are swapped. The standard
keyboard geometry (physical look) is set to a PC-style keyboard with 104 keys.
The compatibility map is set to allow basic shifting, to allow Alt keys to be
interpreted and also to allow iso9995 group shifting.


4.  Keymap XKB Configuration

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