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. 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).
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:
Note that, if you want to use more than one group, you have to specify a group-change option.
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 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:
Doug Palmer 2004-10-11