From 42664023454783c7e7a216075244fa675248f315 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 21 Nov 2015 23:12:18 +0200 Subject: [PATCH] doc/keymap-format-text-v1: convert to markdown Make it more readable for random browsing. Signed-off-by: Ran Benita --- doc/keymap-format-text-v1.md | 359 ++++++++++++++++++++++++++++++++++ doc/keymap-format-text-v1.txt | 354 --------------------------------- 2 files changed, 359 insertions(+), 354 deletions(-) create mode 100644 doc/keymap-format-text-v1.md delete mode 100644 doc/keymap-format-text-v1.txt diff --git a/doc/keymap-format-text-v1.md b/doc/keymap-format-text-v1.md new file mode 100644 index 0000000..27e561e --- /dev/null +++ b/doc/keymap-format-text-v1.md @@ -0,0 +1,359 @@ +# 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: + + = 49; + = 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 +`` is always used to refer to a key by name. + +[The naming convention `` 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 = ; + +Allows to refer to a previously defined key (here ``) by another +name (here ``). 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 + +This section is the fourth to be processed, after `xkb_keycodes`, +`xkb_types` and `xkb_compat`. + +TODO + + +# Virtual modifier statements + +Statements of the form: + + virtual_modifiers LControl; + +Can appear in the `xkb_types`, `xkb_compat`, `xkb_symbols` sections. + +TODO diff --git a/doc/keymap-format-text-v1.txt b/doc/keymap-format-text-v1.txt deleted file mode 100644 index c32f44e..0000000 --- a/doc/keymap-format-text-v1.txt +++ /dev/null @@ -1,354 +0,0 @@ -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: - - = 49; - = 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 is -always used to refer to a key by name. - -[The naming convention just denoted the position of the key -in the main alphanumric section of the 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 = ; - -Allows to refer to a previously defined key (here ) by another -name (here ). 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 (a.k.a 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 (mandatory for each level in the type): - - level_name[Level1] = "Base"; - - 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 (mandatory, should be specified only once): - - modifiers = Shift+Lock+LevelThree; - - 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 (should have at least as many mappings as there - are levels in the type): - - map[Shift+LevelThree] = Level4; - - 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 interpret's, 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. - -- virtual modifier 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 (a.k.a -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. - -- whichModifierState 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 modifer 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 statment: - - groups = All - group1; - - If the given groups are in the required state (see below), the LED - is lit. - -- whichGroupState statment: - - 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 -======================= - -This section is the fourth to be processed, after xkb_keycodes, -xkb_types and xkb_compat. - -TODO - - -Virtual modifier statements -=========================== - -Statements of the form: - virtual_modifiers LControl; - -Can appear in the xkb_types, xkb_compat, xkb_symbols sections. -TODO