Hash :
44df69c9
Author :
Date :
2020-12-27T09:47:08
This document describes the XKB_KEYMAP_FORMAT_TEXT_V1
keymap format,
as implemented by libxkbcommon.
A keymap consists of a single top-level xkb_keymap
block, underwhich
are nested the following sections.
xkb_keycodes
sectionThis is the simplest section type, and is the first one to be compiled. The purpose of this is mostly to map between the hardware/evdev scancodes and xkb keycodes. Each key is given a name by which it can be referred to later, e.g. in the symbols section.
Statements of the form:
<TLDE> = 49;
<AE01> = 10;
The above would let 49 and 10 be valid keycodes in the keymap, and
assign them the names TLDE
and AE01
respectively. The format
<WXYZ>
is always used to refer to a key by name.
[The naming convention <AE01>
just denotes the position of the key
in the main alphanumric section of a standard QWERTY keyboard, with
the two letters specifying the row and the two digits specifying the
column, from the bottom left.]
In the common case this just maps to the evdev scancodes from
/usr/include/linux/input.h
, e.g. the following definitions:
#define KEY_GRAVE 41
#define KEY_1 2
correspond to the ones above. Similar definitions appear in the xf86-input-keyboard driver. Note that in all current keymaps there’s a constant offset of 8 (for historical reasons).
If there’s a conflict, like the same name given to different keycodes, or same keycode given different names, it is resolved according to the merge mode which applies to the definitions.
Statements of the form:
alias <MENU> = <COMP>;
Allows to refer to a previously defined key (here <COMP>
) by another
name (here <MENU>
). Conflicts are handled similarly to keycode
statements.
Statements of the form:
indicator 1 = "Caps Lock";
indicator 2 = "Num Lock";
indicator 3 = "Scroll Lock";
Assigns a name to the keyboard LED (AKA indicator) with the given index. The LED may be referred by this name later in the compat section and by the user.
xkb_types
section
This section is the second to be processesed, after xkb_keycodes
.
However, it is completely independent and could have been the first to
be processed (it does not refer to specific keys as specified in the
xkb_keycodes
section).
This section defines key types, which, given a key and a keyboard
state (i.e. modifier state and group), determine the shift level to be
used in translating the key to keysyms. These types are assigned to
each group in each key, in the xkb_symbols
section.
Key types are called this way because, in a way, they really describe
the “type” of the key (or more correctly, a specific group of the
key). For example, an ordinary keymap will provide a type called
KEYPAD
, which consists of two levels, with the second level being
chosen according to the state of the Num Lock (or Shift) modifiers.
Another example is a type called ONE_LEVEL
, which is usually
assigned to keys such as Escape; these have just one level and are not
affected by the modifier state. Yet more common examples are
TWO_LEVEL
(with Shift choosing the second level), ALPHABETIC
(where Caps Lock may also choose the second level), etc.
Statements of the form:
type "FOUR_LEVEL" { ... }
The above would create a new type named FOUR_LEVEL
.
The body of the definition may include statements of the following
forms:
level_name
statementslevel_name[Level1] = "Base";
Mandatory for each level in the type.
Gives each level in this type a descriptive name. It isn’t used for anything.
Note: A level may be specified as Level[1-8] or just a number (can be more than 8).
modifiers
statementmodifiers = Shift+Lock+LevelThree;
Mandatory, should be specified only once.
A mask of real and virtual modifiers. These are the only modifiers being considered when matching the modifier state against the type. The other modifiers, whether active or not, are masked out in the calculation.
map
entry statementsmap[Shift+LevelThree] = Level4;
Should have at least as many mappings as there are levels in the type.
If the active modifiers, masked with the type’s modifiers (as stated
above), match (i.e. equal) the modifiers inside the map[]
statement,
then the level in the right hand side is chosen. For example, in the
above, if in the current keyboard state the Shift
and LevelThree
modifiers are active, while the Lock
modifier is not, then the
keysym(s) in the 4th level of the group will be returned to the user.
preserve
statementsmap[Shift+Lock+LevelThree] = Level5;
preserve[Shift+Lock+LevelThree] = Lock;
When a key type is used for keysym translation, its modifiers are said
to be “consumed”. For example, in a simple US keymap, the “g” “g” key
is assigned an ordinary ALPHABETIC
key type, whose modifiers are
Shift and Lock; then for the “g” key, these two modifiers are consumed
by the translation. This information is relevant for applications
which further process the modifiers, since by then the consumed
modifiers have already “done their part” and should be masked out.
However, sometimes even if a modifier had already affected the key
translation through the type, it should not be reported as consumed,
for various reasons. In this case, a preserve[]
statement can be
used to augment the map entry. The modifiers inside the square
brackets should match one of the map[] statements in the type (if
there is no matching map entry, one mapping to Level1 is implicitly
added). The right hand side should consists of modifiers from the
type’s modifiers; these modifiers are then “preserved” and not
reported as consumed.
xkb_compat
section
This section is the third to be processed, after xkb_keycodes
and
xkb_types
.
Statements of the form:
interpret Num_Lock+Any { ... }
interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
The xkb_symbols
section (see below) allows the keymap author to
perform, among other things, the following things for each key:
Bind an action, like SetMods or LockGroup, to the key. Actions, like symbols, are specified for each level of each group in the key separately.
Add a virtual modifier to the key’s virtual modifier mapping (vmodmap).
Specify whether the key should repeat or not.
However, doing this for each key (or level) is tedious and inflexible. Interpret’s are a mechanism to apply these settings to a bunch of keys/levels at once.
Each interpret specifies a condition by which it attaches to certain levels. The condition consists of two parts:
A keysym. If the level has a different (or more than one) keysym,
the match fails. Leaving out the keysym is equivalent to using the
NoSymbol
keysym, which always matches successfully.
A modifier predicate. The predicate consists of a matching operation and a mask of (real) modifiers. The modifiers are matched against the key’s modifier map (modmap). The matching operation can be one of the following:
AnyOfOrNone
- The modmap must either be empty or include at
least one of the specified modifiers. AnyOf
- The modmap must include at least one of the specified
modifiers. NoneOf
- The modmap must not include any of the specified
modifiers. AllOf
- The modmap must include all of the specified modifiers
(but may include others as well). Exactly
- The modmap must be exactly the same as the specified
modifiers.
Leaving out the predicate is equivalent to using AnyOfOrNone
while
specifying all modifiers. Leaving out just the matching condition is
equivalent to using Exactly
.
An interpret may also include useModMapMods = level1;
- see below.
If a level fulfils the conditions of several interprets, only the most specific one is used:
A specific keysym will always match before a generic NoSymbol
condition.
If the keysyms are the same, the interpret with the more specific matching operation is used. The above list is sorted from least to most specific.
If both the keysyms and the matching operations are the same (but the modifiers are different), the first interpret is used.
As described above, once an interpret “attaches” to a level, it can bind an action to that level, add one virtual modifier to the key’s vmodmap, or set the key’s repeat setting. You should note the following:
The key repeat is a property of the entire key; it is not level-specific. In order to avoid confusion, it is only inspected for the first level of the first group; the interpret’s repeat setting is ignored when applied to other levels.
If one of the above fields was set directly for a key in
xkb_symbols
, the explicit setting takes precedence over the
interpret.
The body of the statement may include statements of the following forms (all of which are optional):
useModMapMods
statementuseModMapMods = level1;
When set to level1
, the interpret will only match levels which are
the first level of the first group of the keys. This can be useful in
conjunction with e.g. a virtualModifier
statement.
action
statementaction = LockMods(modifiers=NumLock);
Bind this action to the matching levels.
virtualModifier
statementvirtualModifier = NumLock;
Add this virtual modifier to the key’s vmodmap. The given virtual
modifier must be declared at the top level of the file with a
virtual_modifiers
statement, e.g.:
virtual_modifiers NumLock;
repeat
statementrepeat = True;
Set whether the key should repeat or not. Must be a boolean value.
Statements of the form:
indicator "Shift Lock" { ... }
This statement specifies the behavior and binding of the LED (AKA
indicator) with the given name (“Shift Lock” above). The name should
have been declared previously in the xkb_keycodes
section (see LED
name statement), and given an index there. If it wasn’t, it is created
with the next free index.
The body of the statement describes the conditions of the keyboard state which will cause the LED to be lit. It may include the following statements:
modifiers
statementmodifiers = ScrollLock;
If the given modifiers are in the required state (see below), the LED is lit.
whichModState
statmentwhichModState = Latched+Locked;
Can be any combination of:
base
, latched
, locked
, effective
any
(i.e. all of the above) none
(i.e. none of the above) compat
(legacy value, treated as effective)
This will cause the respective portion of the modifier state (see
struct xkb_state
) to be matched against the modifiers given in the
modifiers
statement.
Here’s a simple example:
indicator “Num Lock” {
modifiers = NumLock;
whichModState = Locked;
};
Whenever the NumLock modifier is locked, the Num Lock LED will light up.
groups
statementgroups = All - group1;
If the given groups are in the required state (see below), the LED is lit.
whichGroupState
statementwhichGroupState = Effective;
Can be any combination of:
base
, latched
, locked
, effective
any
(i.e. all of the above) none
(i.e. none of the above)
This will cause the respective portion of the group state (see
struct xkb_state
) to be matched against the groups given in the
groups
statement.
Note: the above conditions are disjunctive, i.e. if any of them are satisfied the LED is lit.
xkb_symbols
sectionNOTE: The documentation of this section is incomplete.
This section is the fourth to be processed, after xkb_keycodes
, xkb_types
and xkb_compat
.
Statements of the form:
xkb_symbols "basic" {
...
}
Declare a symbols map named basic
. Statements inside the curly braces only
affect the symbols map.
A map can have various flags applied to it above the statement, separated by whitespace:
partial alphanumeric_keys
xkb_symbols "basic" {
...
}
The possible flags are:
partial
- Indicates that the map doesn’t cover a complete keyboard. default
- Marks the symbol map as the default map in the file when no
explicit map is specified. If no map is marked as a default, the first map
in the file is the default. hidden
- Variant that can only be used internally alphanumeric_keys
- Indicates that the map contains alphanumeric keys modifier_keys
- Indicates that the map contains modifier keys keypad_keys
- Indicates that the map contains keypad keys function_keys
- Indicates that the map contains function keys alternate_group
- Indicates that the map contains keys for an alternate
group
If no *_keys
flags are supplied, then the map is assumed to cover a complete
keyboard.
At present, except for default
, none of the flags affect key processing in
libxkbcommon, and only serve as metadata.
Statements of the form:
name[Group1] = "US/ASCII";
groupName[1] = "US/ASCII";
Gives the name “US/ASCII” to the first group of symbols. Other groups can be
named using a different group index (ex: Group2
), and with a different name.
A group must be named.
group
and groupName
mean the same thing, and the Group
in Group1
is
optional.
Statements of the form:
include "nokia_vndr/rx-51(nordic_base)
Will include data from another xkb_symbols
section, possibly located in
another file. Here it would include the xkb_symbols
section called
nordic_base
, from the file rx-51
located in the nokia_vndr
folder, itself
located in an XKB include path.
Statements of the form:
key <AD01> { [ q, Q ] };
Describes the mapping of a keycode <AD01>
to a given group of symbols. The
possible keycodes are the keycodes defined in the xkb_keycodes
section.
Symbols are named using the symbolic names from the
xkbcommon/xkbcommon-keysyms.h
file. A group of symbols is enclosed in brackets
and separated by commas. Each element of the symbol arrays corresponds to a
different modifier level. In this example, the symbol (keysym) XKB_KEY_q
for
level 1 and XKB_KEY_Q
for level 2.
Each group represents a list of symbols mapped to a keycode:
name[Group1]= "US/ASCII";
name[Group2]= "Russian";
...
key <AD01> { [ q, Q ],
[ Cyrillic_shorti, Cyrillic_SHORTI ] };
A long-form syntax can also be used:
key <AD01> {
symbols[Group1]= [ q, Q ],
symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ]
};
Groups can also be omitted, but the brackets must be present. The following statement only defines the Group3 of a mapping:
key <AD01> { [], [], [ q, Q ] };
Statements of the form:
virtual_modifiers LControl;
Can appear in the xkb_types
, xkb_compat
, xkb_symbols
sections.
TODO
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466
# The XKB keymap text format, V1
This document describes the `XKB_KEYMAP_FORMAT_TEXT_V1` keymap format,
as implemented by libxkbcommon.
A keymap consists of a single top-level `xkb_keymap` block, underwhich
are nested the following sections.
## The `xkb_keycodes` section
This is the simplest section type, and is the first one to be
compiled. The purpose of this is mostly to map between the
hardware/evdev scancodes and xkb keycodes. Each key is given a name
by which it can be referred to later, e.g. in the symbols section.
### Keycode statements
Statements of the form:
<TLDE> = 49;
<AE01> = 10;
The above would let 49 and 10 be valid keycodes in the keymap, and
assign them the names `TLDE` and `AE01` respectively. The format
`<WXYZ>` is always used to refer to a key by name.
[The naming convention `<AE01>` just denotes the position of the key
in the main alphanumric section of a standard QWERTY keyboard, with
the two letters specifying the row and the two digits specifying the
column, from the bottom left.]
In the common case this just maps to the evdev scancodes from
`/usr/include/linux/input.h`, e.g. the following definitions:
#define KEY_GRAVE 41
#define KEY_1 2
correspond to the ones above. Similar definitions appear in the
xf86-input-keyboard driver. Note that in all current keymaps there's a
constant offset of 8 (for historical reasons).
If there's a conflict, like the same name given to different keycodes,
or same keycode given different names, it is resolved according to the
merge mode which applies to the definitions.
### Alias statements
Statements of the form:
alias <MENU> = <COMP>;
Allows to refer to a previously defined key (here `<COMP>`) by another
name (here `<MENU>`). Conflicts are handled similarly to keycode
statements.
### LED name statements
Statements of the form:
indicator 1 = "Caps Lock";
indicator 2 = "Num Lock";
indicator 3 = "Scroll Lock";
Assigns a name to the keyboard LED (AKA indicator) with the given
index. The LED may be referred by this name later in the compat
section and by the user.
## The `xkb_types` section
This section is the second to be processesed, after `xkb_keycodes`.
However, it is completely independent and could have been the first to
be processed (it does not refer to specific keys as specified in the
`xkb_keycodes` section).
This section defines key types, which, given a key and a keyboard
state (i.e. modifier state and group), determine the shift level to be
used in translating the key to keysyms. These types are assigned to
each group in each key, in the `xkb_symbols` section.
Key types are called this way because, in a way, they really describe
the "type" of the key (or more correctly, a specific group of the
key). For example, an ordinary keymap will provide a type called
`KEYPAD`, which consists of two levels, with the second level being
chosen according to the state of the Num Lock (or Shift) modifiers.
Another example is a type called `ONE_LEVEL`, which is usually
assigned to keys such as Escape; these have just one level and are not
affected by the modifier state. Yet more common examples are
`TWO_LEVEL` (with Shift choosing the second level), `ALPHABETIC`
(where Caps Lock may also choose the second level), etc.
### Type definitions
Statements of the form:
type "FOUR_LEVEL" { ... }
The above would create a new type named `FOUR_LEVEL`.
The body of the definition may include statements of the following
forms:
#### `level_name` statements
level_name[Level1] = "Base";
Mandatory for each level in the type.
Gives each level in this type a descriptive name. It isn't used
for anything.
Note: A level may be specified as Level[1-8] or just a number (can
be more than 8).
#### `modifiers` statement
modifiers = Shift+Lock+LevelThree;
Mandatory, should be specified only once.
A mask of real and virtual modifiers. These are the only modifiers
being considered when matching the modifier state against the type.
The other modifiers, whether active or not, are masked out in the
calculation.
#### `map` entry statements
map[Shift+LevelThree] = Level4;
Should have at least as many mappings as there are levels in the type.
If the active modifiers, masked with the type's modifiers (as stated
above), match (i.e. equal) the modifiers inside the `map[]` statement,
then the level in the right hand side is chosen. For example, in the
above, if in the current keyboard state the `Shift` and `LevelThree`
modifiers are active, while the `Lock` modifier is not, then the
keysym(s) in the 4th level of the group will be returned to the user.
#### `preserve` statements
map[Shift+Lock+LevelThree] = Level5;
preserve[Shift+Lock+LevelThree] = Lock;
When a key type is used for keysym translation, its modifiers are said
to be "consumed". For example, in a simple US keymap, the "g" "g" key
is assigned an ordinary `ALPHABETIC` key type, whose modifiers are
Shift and Lock; then for the "g" key, these two modifiers are consumed
by the translation. This information is relevant for applications
which further process the modifiers, since by then the consumed
modifiers have already "done their part" and should be masked out.
However, sometimes even if a modifier had already affected the key
translation through the type, it should *not* be reported as consumed,
for various reasons. In this case, a `preserve[]` statement can be
used to augment the map entry. The modifiers inside the square
brackets should match one of the map[] statements in the type (if
there is no matching map entry, one mapping to Level1 is implicitly
added). The right hand side should consists of modifiers from the
type's modifiers; these modifiers are then "preserved" and not
reported as consumed.
## The `xkb_compat` section
This section is the third to be processed, after `xkb_keycodes` and
`xkb_types`.
### Interpret statements
Statements of the form:
interpret Num_Lock+Any { ... }
interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
The `xkb_symbols` section (see below) allows the keymap author to
perform, among other things, the following things for each key:
- Bind an action, like SetMods or LockGroup, to the key. Actions, like
symbols, are specified for each level of each group in the key
separately.
- Add a virtual modifier to the key's virtual modifier mapping
(vmodmap).
- Specify whether the key should repeat or not.
However, doing this for each key (or level) is tedious and inflexible.
Interpret's are a mechanism to apply these settings to a bunch of
keys/levels at once.
Each interpret specifies a condition by which it attaches to certain
levels. The condition consists of two parts:
- A keysym. If the level has a different (or more than one) keysym,
the match fails. Leaving out the keysym is equivalent to using the
`NoSymbol` keysym, which always matches successfully.
- A modifier predicate. The predicate consists of a matching operation
and a mask of (real) modifiers. The modifiers are matched against
the key's modifier map (modmap). The matching operation can be one
of the following:
* `AnyOfOrNone` - The modmap must either be empty or include at
least one of the specified modifiers.
* `AnyOf` - The modmap must include at least one of the specified
modifiers.
* `NoneOf` - The modmap must not include any of the specified
modifiers.
* `AllOf` - The modmap must include all of the specified modifiers
(but may include others as well).
* `Exactly` - The modmap must be exactly the same as the specified
modifiers.
Leaving out the predicate is equivalent to using `AnyOfOrNone` while
specifying all modifiers. Leaving out just the matching condition is
equivalent to using `Exactly`.
An interpret may also include `useModMapMods = level1;` - see below.
If a level fulfils the conditions of several interprets, only the
most specific one is used:
- A specific keysym will always match before a generic `NoSymbol`
condition.
- If the keysyms are the same, the interpret with the more specific
matching operation is used. The above list is sorted from least to
most specific.
- If both the keysyms and the matching operations are the same (but the
modifiers are different), the first interpret is used.
As described above, once an interpret "attaches" to a level, it can bind
an action to that level, add one virtual modifier to the key's vmodmap,
or set the key's repeat setting. You should note the following:
- The key repeat is a property of the entire key; it is not
level-specific. In order to avoid confusion, it is only inspected
for the first level of the first group; the interpret's repeat
setting is ignored when applied to other levels.
- If one of the above fields was set directly for a key in
`xkb_symbols`, the explicit setting takes precedence over the
interpret.
The body of the statement may include statements of the following
forms (all of which are optional):
#### `useModMapMods` statement
useModMapMods = level1;
When set to `level1`, the interpret will only match levels which are
the first level of the first group of the keys. This can be useful in
conjunction with e.g. a `virtualModifier` statement.
#### `action` statement
action = LockMods(modifiers=NumLock);
Bind this action to the matching levels.
#### `virtualModifier` statement
virtualModifier = NumLock;
Add this virtual modifier to the key's vmodmap. The given virtual
modifier must be declared at the top level of the file with a
`virtual_modifiers` statement, e.g.:
virtual_modifiers NumLock;
#### `repeat` statement
repeat = True;
Set whether the key should repeat or not. Must be a boolean value.
### LED map statements
Statements of the form:
indicator "Shift Lock" { ... }
This statement specifies the behavior and binding of the LED (AKA
indicator) with the given name ("Shift Lock" above). The name should
have been declared previously in the `xkb_keycodes` section (see LED
name statement), and given an index there. If it wasn't, it is created
with the next free index.
The body of the statement describes the conditions of the keyboard
state which will cause the LED to be lit. It may include the following
statements:
#### `modifiers` statement
modifiers = ScrollLock;
If the given modifiers are in the required state (see below), the
LED is lit.
#### `whichModState` statment
whichModState = Latched+Locked;
Can be any combination of:
* `base`, `latched`, `locked`, `effective`
* `any` (i.e. all of the above)
* `none` (i.e. none of the above)
* `compat` (legacy value, treated as effective)
This will cause the respective portion of the modifier state (see
`struct xkb_state`) to be matched against the modifiers given in the
`modifiers` statement.
Here's a simple example:
indicator "Num Lock" {
modifiers = NumLock;
whichModState = Locked;
};
Whenever the NumLock modifier is locked, the Num Lock LED will light
up.
#### `groups` statement
groups = All - group1;
If the given groups are in the required state (see below), the LED is
lit.
#### `whichGroupState` statement
whichGroupState = Effective;
Can be any combination of:
* `base`, `latched`, `locked`, `effective`
* `any` (i.e. all of the above)
* `none` (i.e. none of the above)
This will cause the respective portion of the group state (see
`struct xkb_state`) to be matched against the groups given in the
`groups` statement.
Note: the above conditions are disjunctive, i.e. if any of them are
satisfied the LED is lit.
## The `xkb_symbols` section
NOTE: The documentation of this section is incomplete.
This section is the fourth to be processed, after `xkb_keycodes`, `xkb_types`
and `xkb_compat`.
Statements of the form:
xkb_symbols "basic" {
...
}
Declare a symbols map named `basic`. Statements inside the curly braces only
affect the symbols map.
A map can have various flags applied to it above the statement, separated by
whitespace:
partial alphanumeric_keys
xkb_symbols "basic" {
...
}
The possible flags are:
* `partial` - Indicates that the map doesn't cover a complete keyboard.
* `default` - Marks the symbol map as the default map in the file when no
explicit map is specified. If no map is marked as a default, the first map
in the file is the default.
* `hidden` - Variant that can only be used internally
* `alphanumeric_keys` - Indicates that the map contains alphanumeric keys
* `modifier_keys` - Indicates that the map contains modifier keys
* `keypad_keys` - Indicates that the map contains keypad keys
* `function_keys` - Indicates that the map contains function keys
* `alternate_group` - Indicates that the map contains keys for an alternate
group
If no `*_keys` flags are supplied, then the map is assumed to cover a complete
keyboard.
At present, except for `default`, none of the flags affect key processing in
libxkbcommon, and only serve as metadata.
### Name statements
Statements of the form:
name[Group1] = "US/ASCII";
groupName[1] = "US/ASCII";
Gives the name "US/ASCII" to the first group of symbols. Other groups can be
named using a different group index (ex: `Group2`), and with a different name.
A group must be named.
`group` and `groupName` mean the same thing, and the `Group` in `Group1` is
optional.
### Include statements
Statements of the form:
include "nokia_vndr/rx-51(nordic_base)
Will include data from another `xkb_symbols` section, possibly located in
another file. Here it would include the `xkb_symbols` section called
`nordic_base`, from the file `rx-51` located in the `nokia_vndr` folder, itself
located in an XKB include path.
### Key statement
Statements of the form:
key <AD01> { [ q, Q ] };
Describes the mapping of a keycode `<AD01>` to a given group of symbols. The
possible keycodes are the keycodes defined in the `xkb_keycodes` section.
Symbols are named using the symbolic names from the
`xkbcommon/xkbcommon-keysyms.h` file. A group of symbols is enclosed in brackets
and separated by commas. Each element of the symbol arrays corresponds to a
different modifier level. In this example, the symbol (keysym) `XKB_KEY_q` for
level 1 and `XKB_KEY_Q` for level 2.
#### Groups
Each group represents a list of symbols mapped to a keycode:
name[Group1]= "US/ASCII";
name[Group2]= "Russian";
...
key <AD01> { [ q, Q ],
[ Cyrillic_shorti, Cyrillic_SHORTI ] };
A long-form syntax can also be used:
key <AD01> {
symbols[Group1]= [ q, Q ],
symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ]
};
Groups can also be omitted, but the brackets must be present. The following
statement only defines the Group3 of a mapping:
key <AD01> { [], [], [ q, Q ] };
## Virtual modifier statements
Statements of the form:
virtual_modifiers LControl;
Can appear in the `xkb_types`, `xkb_compat`, `xkb_symbols` sections.
TODO