README.enhancing revision 1.1
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 13 1. Overview 14 15 The developer of a new layout should read the xkb protocol specification (The 16 X Keyboard Extension: Protocol Specification <URL:http://www.x- 17 docs.org/XKB/XKBproto.pdf>) at least to clarify for himself some xkb-specific 18 terms used in this document and elsewhere in xkb configuration. Also it shows 19 wise to understand how the X server and a client digest their keyboard inputs 20 (with and without xkb). 21 22 A useful source is also Ivan Pascal's text about xkb configuration 23 <URL:http://www.tsu.ru/~pascal/en/xkb> often referenced throughout this docu- 24 ment. 25 26 Note that this document covers only enhancements which are to be made to 27 XFree86 version 4.3.x and above. 28 29 2. The Basics 30 31 At the startup (or at later at user's command) X server starts its xkb key- 32 board module extension and reads data from a compiled configuration file. 33 34 This compiled configuration file is prepared by the program xkbcomp which 35 behaves altogether as an ordinary compiler (see man xkbcomp). Its input are 36 human readable xkb configuration files which are verified and then composed 37 into a useful xkb configuration. Users don't need to mess with xkbcomp them- 38 selves, for them it is invisible. Usually, it is started upon X server 39 startup. 40 41 As you probably already know, the xkb configuration consists of five main 42 modules: 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 83 All these components have the files located in xkb configuration tree in sub- 84 directories with the same names (usually in /usr/lib/X11/xkb). 85 86 3. Enhancing XKB Configuration 87 88 Most of xkb enhancements concerns a need to define new output symbols for the 89 some input key events. In other words, a need to define a new symbol map (for 90 a new language, standard or just to feel more comfortable when typing text). 91 92 What 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 100 First of all, it is good to go through existing layouts and to examine them 101 if there is something you could easily adjust to fit your needs. Even if 102 there is nothing similar you may get some ideas about basic concepts and used 103 tricks. 104 105 3.1 Levels And Groups 106 107 Since XFree86 4.3.0 you can use multi-layout concept of xkb configuration. 108 Though it is still in boundaries of xkb protocol and general ideas, the 109 keymap designer must obey new rules when creating new maps. In exchange we 110 get a more powerful and cleaner configuration system. 111 112 Remember that it is the application which must decide which symbol matches 113 which keycode according to effective modifier state. The X server itself 114 sends only an input event message to. Of course, usually the general inter- 115 pretation is processed by Xlib, Xaw, Motif, Qt, Gtk and similar libraries. 116 The X server only supplies its mapping table (usually upon an application 117 startup). 118 119 You can think of the X server's symbol table as of a irregular table where 120 each keycode has its row and where each combination of modifiers determines 121 exactly one column. The resulting cell then gives the proper symbolic value. 122 Not all keycodes need to bind different values for different combination of 123 modifiers. <ENTER> key, for instance, usually doesn't depend on any modi- 124 fiers so it its row has only one column defined. 125 126 Note that in XKB there is no prior assumption that certain modifiers are 127 bound to certain columns. By editing proper files (see keytypes (section 4.2, 128 page 1)) this mapping can be changed as well. 129 130 Unlike the original X protocol the XKB approach is far more flexible. It is 131 comfortable to add one additional XKB term - group. You can think of a group 132 as of a vector of columns per each keycode (naturally the dimension of this 133 vector may differ for different keycodes). What is it good for? The group is 134 not very useful unless you intend to use more than one logically different 135 set of symbols (like more than one alphabet) defined in a single mapping ta- 136 ble. But then, the group has a natural meaning - each symbol set has its own 137 group and changing it means selecting a different one. XKB approach allows 138 up to four different groups. The columns inside each group are called (shift) 139 levels. The X server knows the current group and reports it together with 140 modifier set and with a keycode in key events. 141 142 To 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 158 It is clear that if you sanely define levels, groups and sanely bind modi- 159 fiers and associated actions you can have simultaneously loaded up to four 160 different symbol sets where each of them would reside in its own group. 161 162 The multi-layout concept provides a facility to manipulate xkb groups and 163 symbol definitions in a way that allows almost arbitrary composition of pre- 164 defined 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 171 4. Defining New Layouts 172 173 See Some Words About XKB internals <URL:http://www.tsu.ru/~pas- 174 cal/en/xkb/internals.html> for explanation of used xkb terms and problems 175 addressed by XKB extension. 176 177 See Common notes about XKB configuration files language 178 <URL:http://www.tsu.ru/~pascal/en/xkb/gram-common.html> for more precise 179 explanation of syntax of xkb configuration files. 180 181 4.1 Predefined XKB Symbol Sets 182 183 If you are about to define some European symbol map extension, you might want 184 to use on of four predefined latin alphabet layouts. 185 186 Okay, let's assume you want extend an existing keymap and you want to over- 187 ride a few keys. Let's take a simple U.K. keyboard as an example (defined in 188 pc/gb): 189 190 partial default 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 207 It defines a new layout in basic variant as an extension of common latin 208 alphabet layout. The layout (symbol set) name is set to "Great Britain". 209 Then there are redefinitions of a few keycodes and a modifiers binding. As 210 you 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 214 Note that the <RALT> key itself is a binding key for Mod5 and that it serves 215 like a shift modifier for LevelThree, together with Shift as a multi-key. It 216 is a good habit to respect this rule in a new similar layout. 217 218 Okay, you could now define more variants of your new layout besides basic 219 simply by including (augmenting/overriding/...) the basic definition and 220 altering what may be needed. 221 222 4.2 Key Types 223 224 The differences in the number of columns (shift levels) are caused by a dif- 225 ferent types of keys (see the types definition in section basics). Most key- 226 codes have implicitly set the keytype in the included "pc/latin" file to 227 "FOUR_LEVEL_ALPHABETIC". The only exception is <RALT> keycode which is 228 explicitly set "TWO_LEVEL" keytype. 229 230 All those names refer to pre-defined shift level schemes. Usually you can 231 choose a suitable shift level scheme from default types scheme list in proper 232 xkb component's subdirectory. 233 234 The 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 310 Besides 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 334 If needed, special caps schemes may be used. They redefine the standard 335 behaviour of all *ALPHABETIC types. The layouts (maps of symbols) with keys 336 defined in respective types then automatically change their behaviour accord- 337 ingly. Possible redefinitions are: 338 339 o internal 340 341 o internal_nocancel 342 343 o shift 344 345 o shift_nocancel 346 347 None of these schemes should be used directly. They are defined merely for 348 'caps:' xkb options (used to globally change the layouts behaviour). 349 350 Don't alter any of existing key types. If you need a different behaviour cre- 351 ate a new one. 352 353 4.2.1 More On Definitions Of Types 354 355 When the XKB software deals with a separate type description it gets a com- 356 plete list of modifiers that should be taken into account from the 'modi- 357 fiers=<list of modifiers>' list and expects that a set of 'map[<combination 358 of modifiers>]=<list of modifiers>' instructions that contain the mapping for 359 each combination of modifiers mentioned in that list. Modifiers that are not 360 explicitly listed are NOT taken into account when the resulting shift level 361 is computed. If some combination is omitted the program (subroutine) should 362 choose the first level for this combination (a quite reasonable behavior). 363 364 Lets 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 372 In this case the map statements for ModTwo only and ModOne+ModTwo are omit- 373 ted. It means that if the ModTwo is active the subroutine can't found 374 explicit mapping for such combination an will use the default level i.e. 375 Level1. 376 377 But in the case the type described as: 378 379 type "..." { 380 modifiers = ModOne; 381 map[None] = Level1; 382 map[ModOne] = Level2; 383 }; 384 385 the ModTwo will not be taken into account and the resulting level depends on 386 the ModOne state only. That means, ModTwo alone produces the Level1 but the 387 combination ModOne+ModTwo produces the Level2 as well as ModOne alone. 388 389 What does it mean if the second modifier is the Lock? It means that in the 390 first case (the Lock itself is included in the list of modifiers but combina- 391 tions with this modifier aren't mentioned in the map statements) the internal 392 capitalization rules will be applied to the symbol from the first level. But 393 in the second case the capitalization will be applied to the symbol chosen 394 accordingly to he first modifier - and this can be the symbol from the first 395 as well as from the second level. 396 397 Usually, all modifiers introduced in 'modifiers=<list of modifiers>' list are 398 used for shift level calculation and then discarded. Sometimes this is not 399 desirable. If you want to use a modifier for shift level calculation but you 400 don't want to discard it, you may list in 'preserve[<combination of modi- 401 fiers>]=<list of modifiers>'. That means, for a given combination all listed 402 modifiers will be preserved. If the Lock modifier is preserved then the 403 resulting symbol is passed to internal capitalization routine regardless 404 whether it has been used for a shift level calculation or not. 405 406 Any key type description can use both real and virtual modifiers. Since real 407 modifiers always have standard names it is not necessary to explicitly 408 declare 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 413 as seen in for example basic, pc or mousekeys key type definitions. 414 415 4.3 Rules 416 417 Once you are finished with your symbol map you need to add it to rules file. 418 The rules file describes how all the five basic keycodes, types, compat, sym- 419 bols and geometry components should be composed to give a sensible resulting 420 xkb configuration. 421 422 The main advantage of rules over formerly used keymaps is a possibility to 423 simply parameterize (once) fixed patterns of configurations and thus to ele- 424 gantly allow substitutions of various local configurations into predefined 425 templates. 426 427 A pattern in a rules file (often located in /usr/lib/X11/xkb/rules) can be 428 parameterized with four other arguments: Model, Layout, Variant and Options. 429 For most cases parameters model and layout should be sufficient for choosing 430 a functional keyboard mapping. 431 432 The rules file itself is composed of pattern lines and lines with rules. The 433 pattern line starts with an exclamation mark ('!') and describes how will the 434 xkb interpret the following lines (rules). A sample rules file looks like 435 this: 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 459 Each rule defines what certain combination of values on the left side of 460 equal sign ('=') results in. For example a (keyboard) model macintosh_old 461 instructs xkb to take definitions of keycodes from file keycodes/macintosh 462 while the rest of models (represented by a wild card '*') instructs it to 463 take them from file keycodes/xfree86. The wild card represents all possible 464 values on the left side which were not found in any of the previous rules. 465 The more specialized (more complete) rules have higher precedence than gen- 466 eral ones, i.e. the more general rules supply reasonable default values. 467 468 As you can see some lines contain substitution parameters - the parameters 469 preceded by the percent sign ('%'). The first alphabetical character after 470 the percent sign expands to the value which has been found on the left side. 471 For example +%l%(v) expands into +cz(bksl) if the respective values on the 472 left side were cz layout in its bksl variant. More, if the layout resp. vari- 473 ant parameter is followed by a pair of brackets ('[', ']') it means that xkb 474 should place the layout resp. variant into specified xkb group. If the brack- 475 ets are omitted the first group is the default value. 476 477 So the second block of rules enhances symbol definitions for some particular 478 keyboard models with extra keys (for internet, multimedia, ...) . Other mod- 479 els are left intact. Similarly, the last block overrides some key type defi- 480 nitions, so the common global behaviour ''shift cancels caps'' or ''shift 481 doesn't cancel caps'' can be selected. The rest of rules produces special 482 symbols for each variant us layout of macintosh keyboard and standard pc sym- 483 bols in appropriate variants as a default. 484 485 4.4 Descriptive Files of Rules 486 487 Now you just need to add a detailed description to <rules>.xml description 488 file so the other users (and external programs which often parse this file) 489 know what is your work about. 490 491 4.4.1 Old Descriptive Files 492 493 The formerly used descriptive files were named <rules>.lst Its structure is 494 very simple and quite self descriptive but such simplicity had also some cav- 495 ities, for example there was no way how to describe local variants of layouts 496 and there were problems with the localization of descriptions. To preserve 497 compatibility with some older programs, new XML descriptive files can be con- 498 verted to old format '.lst'. 499 500 For each parameter of rules file should be described its meaning. For the 501 rules 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 520 And that should be it. Enjoy creating your own xkb mapping. 521 522 Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/XKB-Enhancing.sgml,v 1.2 dawes Exp $ 523 524 525 $XFree86: xc/programs/xkbcomp/README.enhancing,v 1.5 2003/10/19 19:57:44 dawes Exp $ 526
Indexes created Sat Apr 25 00:22:52 UTC 2026