component(developer/golang-123): Add Component
[oi-userland.git] / components / x11 / xorg-docs / src / input / XKB-Enhancing.txt
blob53adecbbbf04697b9422a21f885c760ff8432532
1 How to further enhance XKB configuration
3 Kamil Toman
5 Ivan U. Pascal
7 X Version 11, Release 7.7
9 25 November 2002
11 This guide is aimed to relieve one's labour to create a new (internationalized)
12 keyboard layout. Unlike other documents this guide accents the keymap
13 developer's point of view.
15 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
17 Table of Contents
19 Overview
20 The Basics
21 Enhancing XKB Configuration
23     Levels And Groups
25 Defining New Layouts
27     Predefined XKB Symbol Sets
28     Key Types
29     Rules
30     Descriptive Files of Rules
32 Overview
34 The developer of a new layout should read the xkb protocol specification (The X
35 Keyboard Extension: Protocol Specification) at least to clarify for himself
36 some xkb-specific terms used in this document and elsewhere in xkb
37 configuration. Also it shows wise to understand how the X server and a client
38 digest their keyboard inputs (with and without xkb).
40 A useful source is also Ivan Pascal's text about xkb configuration often
41 referenced throughout this document.
43 Note that this document covers only enhancements which are to be made to
44 XFree86 version 4.3 and X11R6.7.0 and above.
46 The Basics
48 At the startup (or at later at user's command) X server starts its xkb keyboard
49 module extension and reads data from a compiled configuration file.
51 This compiled configuration file is prepared by the program xkbcomp which
52 behaves altogether as an ordinary compiler (see man xkbcomp). Its input are
53 human readable xkb configuration files which are verified and then composed
54 into a useful xkb configuration. Users don't need to mess with xkbcomp
55 themselves, for them it is invisible. Usually, it is started upon X server
56 startup.
58 As you probably already know, the xkb configuration consists of five main
59 modules:
61          Tables that defines translation from keyboard scan codes into
62          reasonable symbolic names, maximum, minimum legal keycodes, symbolic
63          aliases and description of physically present LED-indicators. The
64          primary sence of this component is to allow definitions of maps of
65          symbols (see below) to be independent of physical keyboard scancodes.
66          There are two main naming conventions for symbolic names (always four
67 Keycodes bytes long):
69            ● names which express some traditional meaning like <SPCE> (stands
70              for space bar) or
72            ● names which express some relative positioning on a keyboard, for
73              example <AE01> (an exclamation mark on US keyboards), on the right
74              there are keys <AE02>, <AE03> etc.
76          Types describe how the produced key is changed by active modifiers
77 Types    (like Shift, Control, Alt, ...). There are several predefined types
78          which cover most of used combinations.
80          Compatibility component defines internal behaviour of modifiers. Using
81 Compat   compat component you can assign various actions (elaborately described
82          in xkb specification) to key events. This is also the place where
83          LED-indicators behaviour is defined.
85          For i18n purposes, this is the most important table. It defines what
86          values (=symbols) are assigned to what keycodes (represented by their
87 Symbols  symbolic name, see above). There may be defined more than one value
88          for each key and then it depends on a key type and on modifiers state
89          (respective compat component) which value will be the resulting one.
91 Geometry Geometry files aren't used by xkb itself but they may be used by some
92          external programs to depict a keyboard image.
94 All these components have the files located in xkb configuration tree in
95 subdirectories with the same names (usually in /usr/lib/X11/xkb).
97 Enhancing XKB Configuration
99 Most of xkb enhancements concerns a need to define new output symbols for the
100 some input key events. In other words, a need to define a new symbol map (for a
101 new language, standard or just to feel more comfortable when typing text).
103 What do you need to do? Generally, you have to define following things:
105   ● the map of symbols itself
107   ● the rules to allow users to select the new mapping
109   ● the description of the new layout
111 First of all, it is good to go through existing layouts and to examine them if
112 there is something you could easily adjust to fit your needs. Even if there is
113 nothing similar you may get some ideas about basic concepts and used tricks.
115 Levels And Groups
117 Since XFree86 4.3.0 and X11R6.7.0 you can use multi-layout concept of xkb
118 configuration. Though it is still in boundaries of xkb protocol and general
119 ideas, the keymap designer must obey new rules when creating new maps. In
120 exchange we get a more powerful and cleaner configuration system.
122 Remember that it is the application which must decide which symbol matches
123 which keycode according to effective modifier state. The X server itself sends
124 only an input event message to. Of course, usually the general interpretation
125 is processed by Xlib, Xaw, Motif, Qt, Gtk and similar libraries. The X server
126 only supplies its mapping table (usually upon an application startup).
128 You can think of the X server's symbol table as of a irregular table where each
129 keycode has its row and where each combination of modifiers determines exactly
130 one column. The resulting cell then gives the proper symbolic value. Not all
131 keycodes need to bind different values for different combination of modifiers.
132 <ENTER> key, for instance, usually doesn't depend on any modifiers so it its
133 row has only one column defined.
135 Note that in XKB there is no prior assumption that certain modifiers are bound
136 to certain columns. By editing proper files (see Key Types) this mapping can be
137 changed as well.
139 Unlike the original X protocol the XKB approach is far more flexible. It is
140 comfortable to add one additional XKB term - group. You can think of a group as
141 of a vector of columns per each keycode (naturally the dimension of this vector
142 may differ for different keycodes). What is it good for? The group is not very
143 useful unless you intend to use more than one logically different set of
144 symbols (like more than one alphabet) defined in a single mapping table. But
145 then, the group has a natural meaning - each symbol set has its own group and
146 changing it means selecting a different one. XKB approach allows up to four
147 different groups. The columns inside each group are called (shift) levels. The
148 X server knows the current group and reports it together with modifier set and
149 with a keycode in key events.
151 To sum it up:
153   ● for each keycode XKB keyboard map contains up to four one-dimensional
154     tables - groups (logically different symbol sets)
156   ● for each group of a keycode XKB keyboard map contains some columns - shift
157     levels (values reached by combinations of Shift, Ctrl, Alt, ... modifiers)
159   ● different keycodes can have different number of groups
161   ● different groups of one keycode can have different number of shift levels
163   ● the current group number is tracked by X server
165 It is clear that if you sanely define levels, groups and sanely bind modifiers
166 and associated actions you can have simultaneously loaded up to four different
167 symbol sets where each of them would reside in its own group.
169 The multi-layout concept provides a facility to manipulate xkb groups and
170 symbol definitions in a way that allows almost arbitrary composition of
171 predefined symbol tables. To keep it fully functional you have to:
173   ● define all symbols only in the first group
175   ● (re)define any modifiers with extra care to avoid strange (anisometric)
176     behaviour
178 Defining New Layouts
180 See Some Words About XKB internals for explanation of used xkb terms and
181 problems addressed by XKB extension.
183 See Common notes about XKB configuration files language for more precise
184 explanation of syntax of xkb configuration files.
186 Predefined XKB Symbol Sets
188 If you are about to define some European symbol map extension, you might want
189 to use on of four predefined latin alphabet layouts.
191 Okay, let's assume you want extend an existing keymap and you want to override
192 a few keys. Let's take a simple U.K. keyboard as an example (defined in pc/gb):
194 partial default alphanumeric_keys
195 xkb_symbols "basic" {
196   include "pc/latin"
198   name[Group1]="Great Britain";
200   key <AE02>  { [         2,   quotedbl,  twosuperior,    oneeighth ] };
201   key <AE03>  { [         3,   sterling, threesuperior,    sterling ] };
202   key <AC11>  { [apostrophe,         at, dead_circumflex, dead_caron] };
203   key <TLDE>  { [     grave,    notsign,          bar,          bar ] };
204   key <BKSL>  { [numbersign, asciitilde,   dead_grave,   dead_breve ] };
205   key <RALT>  { type[Group1]="TWO_LEVEL",
206                 [ ISO_Level3_Shift, Multi_key ]   };
208   modifier_map Mod5   { <RALT> };
212 It defines a new layout in basic variant as an extension of common latin
213 alphabet layout. The layout (symbol set) name is set to "Great Britain". Then
214 there are redefinitions of a few keycodes and a modifiers binding. As you can
215 see the number of shift levels is the same for <AE02>, <AE03>, <AC11>, <TLDE>
216 and <BKSL> keys but it differs from number of shift levels of <RALT>.
218 Note that the <RALT> key itself is a binding key for Mod5 and that it serves
219 like a shift modifier for LevelThree, together with Shift as a multi-key. It is
220 a good habit to respect this rule in a new similar layout.
222 Okay, you could now define more variants of your new layout besides basic
223 simply by including (augmenting/overriding/...) the basic definition and
224 altering what may be needed.
226 Key Types
228 The differences in the number of columns (shift levels) are caused by a
229 different types of keys (see the types definition in section basics). Most
230 keycodes have implicitly set the keytype in the included “pc/latin” file to
231 “FOUR_LEVEL_ALPHABETIC”. The only exception is <RALT> keycode which is
232 explicitly set “TWO_LEVEL” keytype.
234 All those names refer to pre-defined shift level schemes. Usually you can
235 choose a suitable shift level scheme from default types scheme list in proper
236 xkb component's subdirectory.
238 The most used schemes are:
240 ONE_LEVEL             The key does not depend on any modifiers. The symbol from
241                       first level is always chosen.
243                       The key uses a modifier Shift and may have two possible
244                       values. The second level may be chosen by Shift modifier.
245                       If Lock modifier (usually Caps-lock) applies the symbol
246 TWO_LEVEL             is further processed using system-specific capitalization
247                       rules. If both Shift+Lock modifier apply the symbol from
248                       the second level is taken and capitalization rules are
249                       applied (and usually have no effect).
251                       The key uses modifiers Shift and Lock. It may have two
252                       possible values. The second level may be chosen by Shift
253                       modifier. When Lock modifier applies, the symbol from the
254 ALPHABETIC            first level is taken and further processed using
255                       system-specific capitalization rules. If both Shift+Lock
256                       modifier apply the symbol from the first level is taken
257                       and no capitalization rules applied. This is often called
258                       shift-cancels-caps behaviour.
260                       Is the same as TWO_LEVEL but it considers an extra
261                       modifier - LevelThree which can be used to gain the
262                       symbol value from the third level. If both
263                       Shift+LevelThree modifiers apply the value from the third
264 THREE_LEVEL           level is also taken. As in TWO_LEVEL, the Lock modifier
265                       doesn't influence the resulting level. Only Shift and
266                       LevelThree are taken into that consideration. If the Lock
267                       modifier is active capitalization rules are applied on
268                       the resulting symbol.
270                       Is the same as THREE_LEVEL but unlike LEVEL_THREE if both
271 FOUR_LEVEL            Shift+LevelThree modifiers apply the symbol is taken from
272                       the fourth level.
274                       Is similar to FOUR_LEVEL but also defines
275                       shift-cancels-caps behaviour as in ALPHABETIC. If
276 FOUR_LEVEL_ALPHABETIC Lock+LevelThree apply the symbol from the third level is
277                       taken and the capitalization rules are applied. If
278                       Lock+Shift+LevelThree apply the symbol from the third
279                       level is taken and no capitalization rules are applied.
281                       As the name suggest this scheme is primarily used for
282                       numeric keypads. The scheme considers two modifiers -
283                       Shift and NumLock. If none of modifiers applies the
284 KEYPAD                symbol from the first level is taken. If either Shift or
285                       NumLock modifiers apply the symbol from the second level
286                       is taken. If both Shift+NumLock modifiers apply the
287                       symbol from the first level is taken. Again,
288                       shift-cancels-caps variant.
290                       Is similar to KEYPAD scheme but considers also LevelThree
291                       modifier. If LevelThree modifier applies the symbol from
292                       the third level is taken. If Shift+LevelThree or
293 FOUR_LEVEL_KEYPAD     NumLock+LevelThree apply the symbol from the fourth level
294                       is taken. If all Shift+NumLock+LevelThree modifiers apply
295                       the symbol from the third level is taken. This also,
296                       shift-cancels-caps variant.
298 Besides that, there are several schemes for special purposes:
300           It is similar to TWO_LEVEL scheme but it considers the Control
301 PC_BREAK  modifier rather than Shift. That means, the symbol from the second
302           level is chosen by Control rather than by Shift.
304           It is similar to TWO_LEVEL scheme but it considers the Alt modifier
305 PC_SYSRQ  rather than Shift. That means, the symbol from the second level is
306           chosen by Alt rather than by Shift.
308           The key uses modifiers Alt and Control. It may have two possible
309 CTRL+ALT  values. If only one modifier (Alt or Control) applies the symbol from
310           the first level is chosen. Only if both Alt+Control modifiers apply
311           the symbol from the second level is chosen.
313           The key uses modifiers Shift and Alt. It may have two possible
314 SHIFT+ALT values. If only one modifier (Alt or Shift) applies the symbol from
315           the first level is chosen. Only if both Alt+Shift modifiers apply the
316           symbol from the second level is chosen.
318 If needed, special caps schemes may be used. They redefine the standard
319 behaviour of all *ALPHABETIC types. The layouts (maps of symbols) with keys
320 defined in respective types then automatically change their behaviour
321 accordingly. Possible redefinitions are:
323   ● internal
325   ● internal_nocancel
327   ● shift
329   ● shift_nocancel
331 None of these schemes should be used directly. They are defined merely for
332 'caps:' xkb options (used to globally change the layouts behaviour).
334 Don't alter any of existing key types. If you need a different behaviour create
335 a new one.
337 More On Definitions Of Types
339 When the XKB software deals with a separate type description it gets a complete
340 list of modifiers that should be taken into account from the 'modifiers=<list
341 of modifiers>' list and expects that a set of 'map[<combination of modifiers>]=
342 <list of modifiers>' instructions that contain the mapping for each combination
343 of modifiers mentioned in that list. Modifiers that are not explicitly listed
344 are NOT taken into account when the resulting shift level is computed. If some
345 combination is omitted the program (subroutine) should choose the first level
346 for this combination (a quite reasonable behavior).
348 Lets consider an example with two modifiers ModOne and ModTwo:
350 type "..." {
351     modifiers = ModOne+ModTwo;
352     map[None] = Level1;
353     map[ModOne] = Level2;
357 In this case the map statements for ModTwo only and ModOne+ModTwo are omitted.
358 It means that if the ModTwo is active the subroutine can't found explicit
359 mapping for such combination an will use the default level i.e. Level1.
361 But in the case the type described as:
363 type "..." {
364     modifiers = ModOne;
365     map[None] = Level1;
366     map[ModOne] = Level2;
370 the ModTwo will not be taken into account and the resulting level depends on
371 the ModOne state only. That means, ModTwo alone produces the Level1 but the
372 combination ModOne+ModTwo produces the Level2 as well as ModOne alone.
374 What does it mean if the second modifier is the Lock? It means that in the
375 first case (the Lock itself is included in the list of modifiers but
376 combinations with this modifier aren't mentioned in the map statements) the
377 internal capitalization rules will be applied to the symbol from the first
378 level. But in the second case the capitalization will be applied to the symbol
379 chosen accordingly to he first modifier - and this can be the symbol from the
380 first as well as from the second level.
382 Usually, all modifiers introduced in 'modifiers=<list of modifiers>' list are
383 used for shift level calculation and then discarded. Sometimes this is not
384 desirable. If you want to use a modifier for shift level calculation but you
385 don't want to discard it, you may list in 'preserve[<combination of modifiers>]
386 =<list of modifiers>'. That means, for a given combination all listed modifiers
387 will be preserved. If the Lock modifier is preserved then the resulting symbol
388 is passed to internal capitalization routine regardless whether it has been
389 used for a shift level calculation or not.
391 Any key type description can use both real and virtual modifiers. Since real
392 modifiers always have standard names it is not necessary to explicitly declare
393 them. Virtual modifiers can have arbitrary names and can be declared (prior
394 using them) directly in key type definition:
396 virtual_modifiers <comma-separated list of modifiers>  ;
399 as seen in for example basic, pc or mousekeys key type definitions.
401 Rules
403 Once you are finished with your symbol map you need to add it to rules file.
404 The rules file describes how all the five basic keycodes, types, compat,
405 symbols and geometry components should be composed to give a sensible resulting
406 xkb configuration.
408 The main advantage of rules over formerly used keymaps is a possibility to
409 simply parameterize (once) fixed patterns of configurations and thus to
410 elegantly allow substitutions of various local configurations into predefined
411 templates.
413 A pattern in a rules file (often located in /usr/lib/X11/xkb/rules) can be
414 parameterized with four other arguments: Model, Layout, Variant and Options.
415 For most cases parameters model and layout should be sufficient for choosing a
416 functional keyboard mapping.
418 The rules file itself is composed of pattern lines and lines with rules. The
419 pattern line starts with an exclamation mark ('!') and describes how will the
420 xkb interpret the following lines (rules). A sample rules file looks like this:
422 ! model                         =       keycodes
423   macintosh_old                 =       macintosh
424   ...
425   *                             =       xorg
427 ! model                         =       symbols
428   hp                            =       +inet(%m)
429   microsoftpro                  =       +inet(%m)
430   geniuscomfy                   =       +inet(%m)
432 ! model     layout[1]           =       symbols
433   macintosh     us              =       macintosh/us%(v[1])
434   *             *               =       pc/pc(%m)+pc/%l[1]%(v[1])
436 ! model     layout[2]           =       symbols
437   macintosh     us              =       +macintosh/us[2]%(v[2]):2
438   *             *               =       +pc/%l[2]%(v[2]):2
440 ! option                        =       types
441   caps:internal                 =       +caps(internal)
442   caps:internal_nocancel        =       +caps(internal_nocancel)
445 Each rule defines what certain combination of values on the left side of equal
446 sign ('=') results in. For example a (keyboard) model macintosh_old instructs
447 xkb to take definitions of keycodes from file keycodes/macintosh while the rest
448 of models (represented by a wild card '*') instructs it to take them from file
449 keycodes/xorg. The wild card represents all possible values on the left side
450 which were not found in any of the previous rules. The more specialized (more
451 complete) rules have higher precedence than general ones, i.e. the more general
452 rules supply reasonable default values.
454 As you can see some lines contain substitution parameters - the parameters
455 preceded by the percent sign ('%'). The first alphabetical character after the
456 percent sign expands to the value which has been found on the left side. For
457 example +%l%(v) expands into +cz(bksl) if the respective values on the left
458 side were cz layout in its bksl variant. More, if the layout resp. variant
459 parameter is followed by a pair of brackets ('[', ']') it means that xkb should
460 place the layout resp. variant into specified xkb group. If the brackets are
461 omitted the first group is the default value.
463 So the second block of rules enhances symbol definitions for some particular
464 keyboard models with extra keys (for internet, multimedia, ...) . Other models
465 are left intact. Similarly, the last block overrides some key type definitions,
466 so the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel
467 caps'' can be selected. The rest of rules produces special symbols for each
468 variant us layout of macintosh keyboard and standard pc symbols in appropriate
469 variants as a default.
471 Descriptive Files of Rules
473 Now you just need to add a detailed description to <rules>.xml description file
474 so the other users (and external programs which often parse this file) know
475 what is your work about.
477 Old Descriptive Files
479 The formerly used descriptive files were named <rules>.lst Its structure is
480 very simple and quite self descriptive but such simplicity had also some
481 cavities, for example there was no way how to describe local variants of
482 layouts and there were problems with the localization of descriptions. To
483 preserve compatibility with some older programs, new XML descriptive files can
484 be converted to old format '.lst'.
486 For each parameter of rules file should be described its meaning. For the rules
487 file described above the .lst file could look like:
489 ! model
490   pc104         Generic 104-key PC
491   microsoft     Microsoft Natural
492   pc98          PC-98xx Series
493   macintosh     Original Macintosh
494   ...
496 ! layout
497   us            U.S. English
498   cz            Czech
499   de            German
500   ...
502 ! option
503   caps:internal          uses internal capitalization. Shift cancels Caps
504   caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
508 And that should be it. Enjoy creating your own xkb mapping.