1
2                         The XKB Configuration Guide
3
4                         Kamil Toman, Ivan U. Pascal
5
6                              25 November 2002
7
8                                  Abstract
9
10     This document describes how to configure XFree86 XKB from a user's
11     point of view. It covers the basic configuration syntax and gives
12     a few examples.
13
14
151.  Overview
16
17The XKB configuration system consists of a number of components. Selecting
18and combining the proper parts, you can achieve most of the configurations
19you might need. Unless you have a completely atypical keyboard, you really
20don't need to touch any of the xkb component files themselves.
21
22
232.  Selecting an XKB configuration
24
25The easiest and most natural way to specify a keyboard mapping is to use
26the rules component. As its name suggests, it describes a number of general
27rules on how to combine the bits and pieces into a valid and useful keyboard
28mapping. All you need to do is to select a suitable rules file and then to
29feed it with a few parameters that will adjust the keyboard behaviour to
30fulfill your needs.
31
32The parameters are:
33
34   o XkbRules - the file of rules to be used for keyboard mapping composition
35
36   o XkbModel - the name of the model of your keyboard
37
38   o XkbLayout - the layout(s) you intend to use
39
40   o XkbVariant - the variant(s) of the layout(s) you intend to use
41
42   o XkbOptions - extra xkb configuration options
43
44The proper rules file depends on your vendor. In reality, the commonest
45file of rules is xfree86. For each rules file there is a description file
46named <vendor>.lst, for instance xfree86.lst, which is located in the xkb
47configuration subdirectory 'rules' (for example /etc/X11/xkb/rules).
48
492.1  Basic Configuration
50
51Let's say you want to configure a PC-style American keyboard with 104 keys
52as described in xfree86.lst. It can be done by simply writing several lines
53to your XFree86 configuration file (often found as /etc/X11/XF86Config):
54
55     Section "InputDevice"
56         Identifier "Keyboard1"
57         Driver "Keyboard"
58
59         Option "XkbModel" "pc104"
60         Option "XkbLayout" "us"
61         Option "XKbOptions" ""
62     EndSection
63
64The values of the parameters XkbModel and XkbLayout are really not surprising.
65The parameter XkbOptions has been explicitly set to empty, meaning no options.
66The parameter XkbVariant has been left out, meaning that the default variant
67(the first variant in the file, often named 'basic') will be loaded.
68
69Of course, this can also be done at runtime using the utility setxkbmap.
70The shell command loading the same keyboard mapping would look like:
71
72     setxkbmap -rules xfree86 -model pc104 -layout us -option ""
73
74The configuration snippet and the shell command will be very similar for most
75other layouts (internationalized mappings).
76
772.2  Advanced Configuration
78
79Since XFree86 4.3.x, you can use multi-layouts xkb configuration. What does
80it mean? Basically it allows you to load up to four different keyboard layouts
81at a time. Each such layout will reside in its own group. The groups (unlike
82a complete keyboard remapping) can be switched very fast from one to another
83with some key combination.
84
85Let's say you want to configure your new Logitech cordless desktop keyboard,
86you intend to use three different layouts at the same time - US, Czech and
87German (in this order), and that you are used to the Alt+Shift combination
88for switching among them.
89
90Then the configuration snippet could look like this:
91
92     Section "InputDevice"
93         Identifier "Keyboard2"
94         Driver "Keyboard"
95
96         Option "XkbModel" "logicordless"
97         Option "XkbLayout" "us,cz,de"
98         Option "XKbOptions" "grp:alt_shift_toggle"
99     EndSection
100
101Of course, this can also be done at runtime using the utility setxkbmap.
102The shell command loading the same keyboard mapping would look like:
103
104     setxkbmap -rules xfree86 -model logicordless -layout "us,cz,de" \
105               -option "grp:alt_shift_toggle"
106
1072.3  Even More Advanced Configuration
108
109Okay, let's say you are more demanding. You do like the example above but you
110want to change it a bit. Let's imagine you want the Czech keyboard mapping to
111use another variant than basic. The configuration snippet then changes into:
112
113     Section "InputDevice"
114         Identifier "Keyboard2"
115         Driver "Keyboard"
116
117         Option "XkbModel" "logicordless"
118         Option "XkbLayout" "us,cz,de"
119         Option "XkbVariant" ",bksl,"
120         Option "XKbOptions" "grp:alt_shift_toggle"
121     EndSection
122
123That seems tricky but it is not. The logic for setting variants is the same
124as for layouts, which means that the first and the third variant settings are
125left out (set to basic), and the second is set to bksl (a special variant with
126an enhanced definition of the backslash key).
127
128Analogically, the loading at runtime will change to:
129
130     setxkmap -rules xfree86 -model logicordless -layout "us,cz,de" \
131              -variant ",bksl," -option "grp:alt_shift_toggle"
132
1332.4  Basic Global Options
134
135See the rules/*.lst files.
136
137
1383.  Direct XKB Configuration
139
140Generally, you can directly prescribe what configuration for each of the basic
141xkb components should be used to form the resulting keyboard mapping. This
142method is rather "brute force". You precisely need to know the structure and
143the meaning of all of the used configuration components.
144
145This method also exposes all xkb configuration details directly into the
146XFree86 configuration file, which is a not very fortunate fact. In rare
147occasions it may be needed, though. So how does it work?
148
1493.1  Basic Components
150
151There are five basic components used to form a keyboard mapping:
152
153   o key codes - a translation of the scan codes produced by the keyboard
154     into a suitable symbolic form
155
156   o types - a specification of what various combinations of modifiers produce
157
158   o key symbols - a translation of symbolic key codes into actual symbols
159
160   o geometry - a description of all physical keyboard dimensions
161
162   o compatibility maps - a specification of what action each key should
163     produce in order to preserve compatibility with XKB-unware clients
164
1653.2  Example Configuration
166
167Look at the following example:
168
169     Section "InputDevice"
170         Identifier "Keyboard0"
171         Driver "Keyboard"
172
173         Option "XkbKeycodes" "xfree86"
174         Option "XkbTypes"    "default"
175         Option "XkbSymbols"  "en_US(pc104)+de+swapcaps"
176         Option "XkbGeometry" "pc(pc104)"
177         Option "XkbCompat"   "basic+pc+iso9995"
178     EndSection
179
180This configuration sets the standard XFree86 interpretation of keyboard
181keycodes, and sets the default modificator types. The symbol table is
182composed of an extended US keyboard layout in its variant for PC keyboards
183with 104 keys, and all keys for a German layout are redefined. Also the
184logical meanings of the Caps-lock and Control keys are swapped. The standard
185keyboard geometry (physical look) is set to a PC-style keyboard with 104 keys.
186The compatibility map is set to allow basic shifting, to allow Alt keys to be
187interpreted and also to allow iso9995 group shifting.
188
189
1904.  Keymap XKB Configuration
191
192This is the formerly used way to configure xkb. The user included a special
193keymap file which specified the direct xkb configuration. This method has
194been obsoleted by the previously described rules files which are far more
195flexible and allow a simpler and more intuitive syntax. The obsolete method
196is preserved merely for compatibility reasons. Avoid using it if possible.
197