The XKB Configuration Guide
Kamil Toman, Ivan U. Pascal
25 November 2002
Abstract
This document describes how to configure X11R6.9 XKB from a user's
point of view. It covers basic configuration syntax and gives also
a few examples.
1. Overview
The XKB configuration is decomposed into a number of components. Selecting
proper parts and combining them back you can achieve most of the configura-
tions you might need. Unless you have a completely atypical keyboard you
really don't need to touch any of the xkb configuration files.
2. 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 map-
ping. 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 - files of rules to be used for keyboard mapping composition
o XkbModel - name of the model of your keyboard type
o XkbLayout - layout(s) you intend to use
o XkbVariant - variant(s) of the layout 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 xorg. For each rules file there is a description file named <ven-
dor-rules>.lst, for instance xorg.lst which is located in the xkb configura-
tion 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 xorg.lst. This can be done by simply writing several lines from
below to your xorg.conf configuration file (previously known as
/etc/X11/XF86Config-4 or /etc/X11/XF86Config):
Section "InputDevice"
Identifier "Keyboard1"
Driver "kbd"
Option "XkbModel" "pc104"
Option "XkbLayout" "us"
Option "XKbOptions" ""
EndSection
The values of XkbModel and XkbLayout are really not surprising. The XkbOp-
tions 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 -rules xorg -model pc104 -layout us -option ""
The configuration and the shell command would be very analogous for most
other layouts (internationalized mappings).
2.2 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 "InputDevice"
Identifier "Keyboard1"
Driver "kbd"
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 -rules xorg -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 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 "InputDevice"
Identifier "Keyboard1"
Driver "kbd"
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 -rules xorg -model logicordless -layout "us,cz,de" \
-variant ",bksl," -option "grp:alt_shift_toggle"
2.4 Basic Global Options
See rules/*.lst files.
3. Direct XKB Configuration
Generally, you can directly prescribe what configuration of each of 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 used configuration components.
This method also exposes all xkb configuration details directly into
xorg.conf 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 pro-
duce
o key symbols - a translation of symbolic key codes into actual symbols
o geometry - a description of physical keyboard geometry
o compatibility maps - a specification of what action should each key pro-
duce in order to preserve compatibility with XKB-unware clients
3.2 Example Configuration
Look at the following example:
Section "InputDevice"
Identifier "Keyboard0"
Driver "kbd"
Option "XkbKeycodes" "xorg"
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 X server default interpretation of key-
board keycodes, and sets the default modifier types. The symbol table is com-
posed of extended US keyboard layout in its variant for pc keyboards with 104
keys plus all keys for german layout are redefined respectively. Also the
logical meaning of Caps-lock and Control keys is swapped. The standard key-
board geometry (physical look) is set to 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
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 pre-
served merely for compatibility reasons and should be avoided if possible.
$XdotOrg: xc/programs/xkbcomp/README.config,v 1.4 2005/12/21 05:39:05 kem Exp $
