Choosing an XKB Configuration

The most likely approach to configuring XKB is to use the already existing configuration files, and you want to stick components together so that you have your own private eccentricities.

Ivan Pascal has a web page that describes how to do this in various levels of detail.[6] Like Pascal, I'm going to assume that you are using XFree86 and that you are going to be using the /etc/X11/XF86Config-4 configuration file to set things up. People using other X11 implementations will need to find the appropriate file for themselves.

The first thing to learn is how to access the definitions in the configuration files. To start with, the configuration files are in various subdirectories named after the type of components that they represent. Since it will always be obvious when you are using, say, a compat component instead of a keycodes component, it is unnecessary to explicitly name the component type in the name.

In the subdirectories, there are configuration files and further subdirectories. To access a configuration file, you just use its name, eg. xfree86. If the file is in a subdirectory, then the subdirectory also has to be named, eg. sgi/iris.

Each file can contain multiple configuration variants. So, for example, in the xfree86 keycodes file, there are several variants: xfree86, basic, 102, jp106, jp109usb and abnt2. One of these variants will be marked as the default, which is what you get if you don't specify an explicit variant. Otherwise, you have to include the variant name in brackets, eg. xfree86(pc102).

Once you have a basic component, you can extend that component by adding additional components to it. These additional components modify or augment the meaning of the basic component. The notation here is that you use + to override any existing definitions and | to augment. An overridden definition always replaces an existing one, an augmented definition is only used if a definition doesn't already exist. Hence, to specify symbols where you are using a US keyboard on a 101-key PC keyboard, but you want to swap the caps-lock and left-control keys, you could say us(pc101)+ctrl(swapcaps).

Doing it the Easy Way

Rather than worry too much about the exact combinations of basic components and their extensions, XKB uses the rules component to allow suitable combinations to be picked. The rules allow a few key words to be specified in the XF86Config-4 file and the results are translated into a suitable XKB configuration.

In the XF86Config-4 file, there will be a section which looks something like this:

Section "InputDevice"
        Identifier  "Keyboard0"
        Driver      "keyboard"

        Option  "XkbRules"      "xfree86"
        Option  "XkbModel"      "pc104"
        Option  "XkbLayout"     "us"
        Option  "XkbVariant"    "basic"
        Option  "XkbOptions"    "grp:menu_toggle"
EndSection

The Option statements contain the interesting bits. For XFree86, the file
/usr/X11R6/lib/X11/xkb/rules/xfree86.lst contains descriptions of the various elements. The various elements that you can have are:

XkbRules

The set of rules that should be followed to get a configuration. For XFree86, this should -- pretty obviously - be xfree86. Other options are sgi and sun.

XkbModel

The type of keyboard that you are using. For example, pc104 is a generic 104-key PC keyboard.

XkbLayout

The keyboard layout that you want. Layouts usually express national variations (eg. de for a German keyboard) but they can also be used for alternate keyboard layouts (eg. dvorak for a Dvorak layout) or other oddities. Users of US keyboards have two options: us for plain vanilla US keys and en_US for a keyboard with a group of interesting additional characters.

XkbVariant

Any minor variants on the general layout. This is usually set to basic.

XkbOptions

Any specific options. Options usually relate to how to shift groups, the position of the control keys and how to indicate that the group has been changed. For example, the option grp:toggle means that the Right-Alt key toggles between groups.

Note that, if you want to use more than one group, you have to specify a group-change option.

Doing it the Slightly Cruder Way

The keymap component provides a way of setting up basic national variants, without the level of detail required by the rules component. An extended PC keyboard (ie. with the Windows keys, etc.) is generally assumed and the national symbol sets are mapped onto that keyboard.

To use key maps, use the XkbKeymap option in the XF86Config-4 file to specify the national set. For example, the following setup configures the keyboard for Belgian use:

Section "InputDevice"
        Identifier  "Keyboard0"
        Driver      "keyboard"

        Option  "XkbKeymap"      "be"
EndSection

Doing it the Hard Way

Doing it the hard way involves specifying the five major XKB components explicitly. If you do things this way, then you need to explicitly include any special options or variants that you might want to use. The benefit to doing things this way, of course, is that you have a lot of control over the exact keyboard configuration.

To specify the major components, you will need to explicitly state the following options: XkbKeycodes, XkbTypes, XkbCompat, XkbSymbols and XkbGeometry. As an example, you might have:

Section "InputDevice"
        Identifier  "Keyboard0"
        Driver      "keyboard"

        Option  "XkbKeycodes"      "xfree86"
        Option  "XkbTypes"         "default"
        Option  "XkbCompat"        "basic+pc+iso9995+norepeat"
        Option  "XkbSymbols"       "en_US(pc104)+dk+ctrl(swapcaps)+group(switch)"
        Option  "XkbGeometry"      "pc(pc104)"
EndSection

What all this means is:

xfree86

Use the standard XFree86 interpretation of keyboard codes. This essentially corresponds to a standard PC keyboard.

default

Use the default types (interpretation of level shifts). The default types are the standard no-level, alphanumeric and two-level shifts, along with some extensions for things like the SysRq key.

basic+pc+iso9995+norepeat

Use a basic compatibility map, which allows basic level and group shifts, allow the Alt keys to be interpreted, allow group shifts in the way that ISO9995 specifies and don't repeat the return key when it is held down.

en_US(pc104)+dk+ctrl(swapcaps)+group(switch)

Use an extended English/US keyboard layout for a 104-key PC keyboard, add the extra characters that you would need to use for Danish, swap the Caps Lock and Control keys, so that the control key is next to the A key and use the Right-Alt key to switch groups while the key is held down.

pc(pc104)

We're using a bog-standard 104-key PC keyboard.