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