Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
HOWTO.testing | D | 12-May-2024 | 861 | 23 | 16 | |
HOWTO.transition | D | 12-May-2024 | 2.2 KiB | 20 | 10 | |
Makefile | D | 12-May-2024 | 13.9 KiB | 463 | 396 | |
Makefile.am | D | 12-May-2024 | 89 | 2 | 1 | |
README.config | D | 12-May-2024 | 7.3 KiB | 196 | 137 | |
README.enhancing | D | 12-May-2024 | 23.4 KiB | 521 | 403 | |
README.symbols | D | 12-May-2024 | 1.8 KiB | 48 | 34 |
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