diff options
Diffstat (limited to 'doc/keymap-format-text-v1.md')
| -rw-r--r-- | doc/keymap-format-text-v1.md | 172 |
1 files changed, 117 insertions, 55 deletions
diff --git a/doc/keymap-format-text-v1.md b/doc/keymap-format-text-v1.md index b25c491..12d6201 100644 --- a/doc/keymap-format-text-v1.md +++ b/doc/keymap-format-text-v1.md @@ -1,8 +1,8 @@ -# The XKB keymap text format, V1 +# The XKB keymap text format, V1 {#keymap-text-format-v1} <!-- NOTE: -• The Markdown supported in doxygen is limitated and buggy. +• The Markdown supported in Doxygen is limited and buggy. Current issues and solutions: • In headers, only plain text is supported. • Use the language tag “c” for block code to give them a nice (approximated) @@ -15,16 +15,27 @@ as implemented by libxkbcommon. The standard database of keyboard configuration data is [xkeyboard-config]. +@note Due to the complexity of the format, this document is still is construction. +Some additional resources are: + +@note +- [Ivan Pascal's XKB documentation][ivan-pascal] +- [An Unreliable Guide to XKB Configuration][unreliable-guide] +- [The X Keyboard Extension: Protocol Specification][XKB Protocol] +- [How to enhance XKB configuration][xkeyboard-config doc] +- [ArchWiki XKB page][arch-wiki] + [xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config +[ivan-pascal]: https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/ +[unreliable-guide]: https://www.charvolant.org/doug/xkb/html/index.html +[XKB Protocol]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html +[xkeyboard-config doc]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/blob/master/docs/README.enhancing +[arch-wiki]: https://wiki.archlinux.org/index.php/X_keyboard_extension -NOTE: Due to the complexity of the format, this document is still is construction. -Some additional resources are: -- [Ivan Pascal's XKB documentation](https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/) -- [An Unreliable Guide to XKB Configuration](https://www.charvolant.org/doug/xkb/html/index.html) -- [The X Keyboard Extension: Protocol Specification](https://www.x.org/releases/current/doc/kbproto/xkbproto.html) -- [ArchWiki XKB page](https://wiki.archlinux.org/index.php/X_keyboard_extension) +@tableofcontents{html:2} +<!-- ## Table of contents 1. [Terminology][terminology] @@ -37,6 +48,7 @@ Some additional resources are: 8. [Virtual modifier statements][virtual modifier statements] 9. [Modifiers bindings][modifiers bindings] 10. [Key actions][actions] +--> [terminology]: @ref terminology [introduction]: @ref introduction @@ -75,8 +87,8 @@ Some additional resources are: - A _character:_ e.g. `a` and `A` for Latin scripts, `alpha` “α” and `ALPHA` “Α” for Greek, etc. - - A _dead key:_ e.g. `dead_grave` and `dead_diaeresis`, corresponding repectively - to the [grave accent](https://en.wikipedia.org/wiki/Grave_accent) + - A _dead key:_ e.g. `dead_grave` and `dead_diaeresis`, corresponding + respectively to the [grave accent](https://en.wikipedia.org/wiki/Grave_accent) and the [diaeresis](https://en.wikipedia.org/wiki/Diaeresis_%28diacritic%29) diacritics. @@ -84,7 +96,7 @@ Some additional resources are: that does not generate a character by itself, but modifies the character generated by the key struck(s) immediately after. - A <em>[modifier]:</em> e.g. `Shift_L`, `Control_R`, `Caps_Lock`. - See herinafter. + See hereinafter. - A _system action:_ e.g. the arrow `Left`, `Pause`, `Escape`, `F1`. The complete list of keysyms is defined in `xkbcommon/xkbcommon-keysyms.h`. @@ -165,12 +177,12 @@ Some additional resources are: <dd>Active while depressed; e.g. the usual Shift.</dd> <dt><a name="latched-mod-def">Latched</a></dt> <dd> - Actived when pressed and deactivated after the next + Activated when pressed and deactivated after the next non-modifier key press. </dd> <dt><a name="locked-mod-def">Locked</a></dt> <dd> - Actived when pressed and deactivated when pressed again; + Activated when pressed and deactivated when pressed again; e.g. the usual Caps Lock. </dd> </dl> @@ -263,7 +275,7 @@ Some additional resources are: <dl> <dt><em>Physical</em> indicator</dt> <dd> - Typcally a labelled LED on the keyboard, e.g. “Caps Lock” and + Typically a labelled LED on the keyboard, e.g. “Caps Lock” and “Num Lock”. </dd> <dt><em>Logical</em> indicator</dt> @@ -280,7 +292,7 @@ Some additional resources are: Because indicators are customizable, if one misses a “Num Lock” LED, one could define instead the “Caps Lock” _indicator_ to activate its LED when the “Num Lock” _modifier_ is active. - - _Virtual_ indicators are not assiociated to a physical indicator. + - _Virtual_ indicators are not associated to a physical indicator. Their effect is only visible for programs monitoring them. Note that the meanings of _real_ and _virtual_ is slightly @@ -295,7 +307,7 @@ Some additional resources are: <dd> The _complete_ definition of the mapping of raw keycodes to symbols and actions. - It fully defines the behaviour of a keyboard. + It fully defines the behavior of a keyboard. See [xkb_keymap] for further details. </dd> @@ -324,20 +336,70 @@ Some additional resources are: ## Introduction to the XKB text format {#introduction} -The XKB text format uses a language similar to the C program language. +The XKB text format uses a syntax similar to the [C programming language][C]. + +@todo general comment on syntax: section, values, etc. + +@todo the import mechanism + +@todo recommended ways to feed xkbcommon + +[C]: https://en.wikipedia.org/wiki/C_(programming_language)#Syntax + +### Keywords + +@todo keywords, other settings such as “SetMods” -<span class="TODO">TODO:</span> general comment on syntax: section, -values, etc. +<!-- +TODO: SetMods is not a keyword, but how call it for using-facing doc? + +There are many keywords + +The key words are _case-insensitive_, e.g. the following strings denote +the same key word: `SETMODS`, `SetMods`, `setMods` and `setmods`. +--> + +### Literals + +<dl> + <dt>String literal</dt> + <dd> + A string is surrounded by double quotes: “<code>"</code>”. + The following _escape sequences_ are supported: + + | Escape sequence | Meaning | + | ------------------ | ------------------------------------------------------- | + | `\\` | Backslash “`\`” | + | `\b` | Backspace | + | `\e` | Escape | + | `\f` | Form feed | + | `\n` | Line feed (newline) | + | `\r` | Carriage return | + | `\t` | Horizontal tabulation | + | `\v` | Vertical tabulation | + | `\` + octal number | Corresponding ASCII character: `\0` → NULL, `\42` → `"` | + + @note The string _encoding_ is unspecified and not validated, but for best + results, stick to ASCII. + + <!-- TODO: check UTF-8 encoding result --> -<span class="TODO">TODO:</span> the import mecanism + </dd> + <dt>Number literal</dt> + <dd> + A number can be written in three forms: -<span class="TODO">TODO:</span> recommended ways to feed xkbcommon + - _decimal integer:_ `1`, `123`, etc. + - _decimal floating-point number:_ `1.23`, etc. + - _hexadecimal integer:_ prefixed with `0x`: `0x123`, `0xff`, `0xAB`, etc. + </dd> +</dl> ## The “xkb_keymap” block {#the-xkb_keymap-block} A <strong>[keymap]</strong> consists of a single top-level `xkb_keymap` -block, underwhich are nested the following sections: +block, under which are nested the following sections: <dl> <dt><code>[xkb_keycodes]</code></dt> @@ -761,12 +823,12 @@ satisfied the LED is lit. ### Default values -<span class="TODO">TODO:</span> e.g. `setMods.clearLocks= True;` +@todo e.g. `setMods.clearLocks= True;` ## The “xkb_symbols” section {#the-xkb_symbols-section} -<span class="TODO">TODO:</span> complete this section. +@todo complete this section. This section is the fourth to be processed, after `xkb_keycodes`, `xkb_types` and `xkb_compat`. @@ -850,7 +912,7 @@ level 1 and `XKB_KEY_Q` for level 2. #### Actions -<span class="TODO">TODO:</span> how to bind key actions +@todo how to bind key actions For further details see [key actions][actions]. @@ -878,11 +940,11 @@ statement only defines the Group3 of a mapping: #### Additional attributes -<span class="TODO">TODO:</span> virtualmodifiers, repeats +@todo virtualmodifiers, repeats ## Virtual modifier statements {#virtual-modifier-statements} -<span class="TODO">TODO:</span> rework this section +@todo rework this section Statements of the form: @@ -933,7 +995,7 @@ modifier `LevelThree` in `xkeyboard-config`. In order to define and use a modifier, one must: -1. Define its behaviour and [keysym] binding in the +1. Define its behavior and [keysym] binding in the <code>[xkb_compat]</code> section: ```c @@ -941,7 +1003,7 @@ In order to define and use a modifier, one must: // we do not need to add it here. virtual_modifiers LevelThree; - // Set defaults. They are overriden if set directly in the xkb_symbols. + // Set defaults. They are overridden if set directly in the xkb_symbols. interpret.repeat= False; // only applied on first level setMods.clearLocks= True; latchMods.clearLocks= True; @@ -981,7 +1043,7 @@ In order to define and use a modifier, one must: // • The condition is equivalent to // ISO_Level3_Shift+AnyOfOrNone(all), but since // the previous statement ISO_Level3_Shift+Any is more - // specififc, it will be matched before this one. + // specific, it will be matched before this one. interpret ISO_Level3_Shift { // Activate the LevelThree modifier (depressed mode) action= SetMods(modifiers=LevelThree); @@ -1083,7 +1145,7 @@ In order to define and use a modifier, one must: ## Key actions {#key-actions} -<span class="TODO">TODO:</span> list of all actions and their parameters +@todo list of all actions and their parameters The following table provide an overview of the available actions: @@ -1093,18 +1155,18 @@ The following table provide an overview of the available actions: | [Modifier action] | `SetMods` | | Modifies the _depressed_ modifiers | | ^ | `LatchMods` | | Modifies the _latched_ modifiers | | ^ | `LockMods` | | Modifies the _locked_ modifiers | -| [Group action] | `SetGroup` | | <span class="TODO">TODO</span> | -| ^ | `LatchGroup` | | <span class="TODO">TODO</span> | -| ^ | `LockGroup` | | <span class="TODO">TODO</span> | -| [Legacy action] | `MovePointer` | `MovePtr` | <span class="TODO">TODO</span> | -| ^ | `PointerButton` | `PtrBtn` | <span class="TODO">TODO</span> | -| ^ | `LockPointerButton` | `LockPtrBtn` | <span class="TODO">TODO</span> | -| ^ | `SetPointerDefault` | `SetPtrDflt` | <span class="TODO">TODO</span> | -| ^ | `SetControls` | | <span class="TODO">TODO</span> | -| ^ | `LockControls` | | <span class="TODO">TODO</span> | -| ^ | `TerminateServer` | `Terminate` | <span class="TODO">TODO</span> | -| ^ | `SwitchScreen` | | <span class="TODO">TODO</span> | -| ^ | `Private` | | <span class="TODO">TODO</span> | +| [Group action] | `SetGroup` | | <span class="todo">TODO</span> | +| ^ | `LatchGroup` | | <span class="todo">TODO</span> | +| ^ | `LockGroup` | | <span class="todo">TODO</span> | +| [Legacy action] | `MovePointer` | `MovePtr` | <span class="todo">TODO</span> | +| ^ | `PointerButton` | `PtrBtn` | <span class="todo">TODO</span> | +| ^ | `LockPointerButton` | `LockPtrBtn` | <span class="todo">TODO</span> | +| ^ | `SetPointerDefault` | `SetPtrDflt` | <span class="todo">TODO</span> | +| ^ | `SetControls` | | <span class="todo">TODO</span> | +| ^ | `LockControls` | | <span class="todo">TODO</span> | +| ^ | `TerminateServer` | `Terminate` | <span class="todo">TODO</span> | +| ^ | `SwitchScreen` | | <span class="todo">TODO</span> | +| ^ | `Private` | | <span class="todo">TODO</span> | Common syntax: - Boolean values: @@ -1115,7 +1177,7 @@ Common syntax: [modifier action]: @ref modifiers-actions -<span class="TODO">TODO:</span> default values +@todo default values There are 3 modifiers actions: @@ -1155,7 +1217,7 @@ There are 3 modifiers actions: </dd> </dl> -<span class="TODO">TODO:</span> highlight that there is reference counting for +@todo highlight that there is reference counting for the modifiers, e.g. to manage multiple physical keys for the same modifier. These actions perform different tasks on key press and on key release: @@ -1240,7 +1302,7 @@ These actions perform different tasks on key press and on key release: <!-- </tbody> --> </table> -<span class="TODO">TODO:</span> Finish +@todo Finish ### Group actions {#group-actions} @@ -1251,25 +1313,25 @@ There are 3 group actions: <dl> <dt>SetGroup</dt> <dd> - <span class="TODO">TODO</span> + <span class="todo">TODO</span> </dd> <dt>LatchGroup</dt> <dd> - <span class="TODO">TODO</span> + <span class="todo">TODO</span> </dd> <dt>LockGroup</dt> <dd> - <span class="TODO">TODO</span> + <span class="todo">TODO</span> </dd> </dl> -<span class="TODO">TODO:</span> Describe each action +@todo Describe each action ### Unsupported legacy actions {#legacy-actions} [legacy action]: @ref legacy-actions -The following legacy actions are kept for compatibility only: they are parsed +@attention The following legacy actions are kept for compatibility only: they are parsed and validated but have no effect. This allows to use keymaps defined in <code>[xkeyboard-config]</code> for both X11 and Wayland. @@ -1283,16 +1345,16 @@ and validated but have no effect. This allows to use keymaps defined in | `LockPointerButton` | `LockPointerBtn` | | | `SetPointerDefault` | `SetPtrDflt` | | -<span class="TODO">TODO:</span> Describe each action +@todo Describe each action #### Control flags actions -<span class="TODO">TODO:</span> `SetControls`, `LockControls` +@todo `SetControls`, `LockControls` #### Server actions -<span class="TODO">TODO:</span> `TerminateServer`, `SwitchScreen` +@todo `TerminateServer`, `SwitchScreen` #### Private action -<span class="TODO">TODO:</span> `Private` +@todo `Private` |