• Home
Name
Date
Size
#Lines
LOC

..--

HOWTO.testingD12-May-2024861 2316

HOWTO.transitionD12-May-20242.2 KiB2010

MakefileD12-May-202413.9 KiB463396

Makefile.amD12-May-202489 21

README.configD12-May-20247.3 KiB196137

README.enhancingD12-May-202423.4 KiB521403

README.symbolsD12-May-20241.8 KiB4834

README.config

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

README.enhancing

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

README.symbols

1
2The files in the symbols directory describe possible keyboard layouts
3for a given  country or language or script.
4
5The default layout in each file should describe the most common layout
6for its kind, usually the one that matches the symbols printed on the
7keys.  Layout variants can describe common deviations that are not
8necessarily printed on the keys (e.g. a phonetic version of Cyrillic).
9
10The names of the files are referenced throughout the XKB rules, and may
11be exposed in the X server configuration and in user configuration tools.
12The filenames use the following convention:
13
14Country layouts:
15  Keyboard layouts for a country must use the 2-letter code from the
16  ISO-3166 standard.
17
18Language layouts:
19  Keyboard layouts for a language must use the 3-letter code from the
20  ISO-639 standard.
21
22Script layouts:
23  Keyboard layouts for a script must use the 4-letter code from the
24  ISO-15924 standard.
25
26Other:
27  Keyboard layouts that do not fit in the above categories must use a
28  filename between 5 and 8 characters.
29
30The relevant ISO codes can be found at the following addresses:
31
32Country layouts:  http://www.iso.org/iso/home/standards/country_codes/iso-3166-1_decoding_table.htm
33Language layouts: http://www.loc.gov/standards/iso639-2/php/code_list.php
34Script layouts:   http://www.unicode.org/iso15924/iso15924-codes.html
35
36The descriptions of the layouts in the file base.xml.in should match the
37group names in the symbols file.
38
39If the layout is country-based, the group name has to be the full name of
40the country.  It is highly discouraged to use forms like "Republic of XXX"
41or "XXX Republic" -- the form "XXX" should be used instead.
42
43If the layout is language-based, the group name has to be the name of the
44language.
45
46Within a single symbols file, all the variants should have the same group name
47(implemented using the "include" directive wherever possible).
48