From f9258804d40bb5a803fe341fcd9abe4e3a78951c Mon Sep 17 00:00:00 2001 From: Pierre Le Marre Date: Wed, 20 Sep 2023 08:50:03 +0200 Subject: [PATCH] Doc: add introduction to keymap and its components Add a diagram to explain the relationships between RMLVO and KcCGST. --- doc/diagrams/xkb-keymap-components.dot | 55 ++++++ doc/keymap-format-text-v1.md | 252 +++++++++++++++++++++++-- meson.build | 1 + 3 files changed, 295 insertions(+), 13 deletions(-) create mode 100644 doc/diagrams/xkb-keymap-components.dot diff --git a/doc/diagrams/xkb-keymap-components.dot b/doc/diagrams/xkb-keymap-components.dot new file mode 100644 index 000000000..bbafe4aab --- /dev/null +++ b/doc/diagrams/xkb-keymap-components.dot @@ -0,0 +1,55 @@ +digraph { + node [shape=box] + + database [shape=none, label=< + + +
+ + + + + + +
Layout Database
Rules files
Keycodes files
Compat files
(Geometry files)
Symbols files
Key types files
+ >]; + + server [ + label=<Server>, + style=rounded + ]; + + client [ + label=<Client>, + style=rounded + ]; + + { rank="same"; database; server; client } + + database:keycodes -> server [ + label=<xkb_keycodes section>, + labelhref="@ref the-xkb_keycodes-section" + ]; + database:compat -> server [ + label=<xkb_compat section>, + labelhref="@ref the-xkb_compat-section" + ]; + database:symbols -> server [ + label=<xkb_symbols section>, + labelhref="@ref the-xkb_symbols-section" + ]; + database:types -> server [ + label=<xkb_types section>, + labelhref="@ref the-xkb_types-section" + ]; + + server:n -> database:rules [ + label=, + labelhref="@ref RMLVO-intro", + labeltooltip="Rules, Model, Layout, Variant, Options" + ]; + server -> client [ + label=xkb_keymap block =
xkb_keycodes +
xkb_compat +
xkb_symbols +
xkb_types>, + labelhref="@ref the-xkb_keymap-block" + ]; +} diff --git a/doc/keymap-format-text-v1.md b/doc/keymap-format-text-v1.md index 12d62016c..f819fa812 100644 --- a/doc/keymap-format-text-v1.md +++ b/doc/keymap-format-text-v1.md @@ -9,11 +9,15 @@ NOTE: syntax highlighting. --> -This document describes the `XKB_KEYMAP_FORMAT_TEXT_V1` keymap format, +This document describes the `XKB_KEYMAP_FORMAT_TEXT_V1` [keymap] format, as implemented by libxkbcommon. -The standard database of keyboard configuration data is -[xkeyboard-config]. +@see For an overview of the role of this format, please see “@ref xkb-the-config ""”. + +@see For examples of keymaps in this format, please see [xkeyboard-config], the +standard database of keyboard configuration data. + + @note Due to the complexity of the format, this document is still is construction. Some additional resources are: @@ -311,6 +315,11 @@ Some additional resources are: See [xkb_keymap] for further details. +
Keymap configuration database @anchor database-def
+
+ TODO: [xkeyboard-config], the + standard database of keyboard configuration data. +
[keycode]: @ref keycode-def @@ -331,33 +340,168 @@ Some additional resources are: [action]: @ref key-action-def [indicator]: @ref indicator-def [keymap]: @ref keymap-def +[database]: @ref database-def [ISO9995]: https://en.wikipedia.org/wiki/ISO/IEC_9995 ## Introduction to the XKB text format {#introduction} The XKB text format uses a syntax similar to the [C programming language][C]. +Note that the similarity with C stops here: the XKB text format is only a +_configuration_ format and is not intended for programming. + +The XKB text format is used to configure a _keyboard keymap_, which is +introduced in “@ref xkb-the-config ""”. It has the following two main use cases, +illustrated in the [diagram herinafter](@ref xkb-keymap-components-diagram): + +- __Server:__ Load a keymap from the keymap configuration database, then handle + input events by updating the keyboard state. The keymap is assembled from + an [RMLVO configuration][RMLVO] and its corresponding + [KcCGST components][KcCGST] files. -@todo general comment on syntax: section, values, etc. + @see xkb_keymap::xkb_keymap_new_from_names -@todo the import mechanism + @see [xkeyboard-config] for the implementation of the standard keymap + configuration database. +- __Client:__ Load the active keymap from the server, then handle update events + sent by the server. The [complete keymap] is directly + available in a _self-contained_ file. -@todo recommended ways to feed xkbcommon + @see xkb_keymap::xkb_keymap_new_from_string + +@anchor xkb-keymap-components-diagram +@dotfile xkb-keymap-components "XKB text format use cases" [C]: https://en.wikipedia.org/wiki/C_(programming_language)#Syntax +[RMLVO]: @ref RMLVO-intro +[KcCGST]: @ref KcCGST-intro +[complete keymap]: @ref keymap-intro -### Keywords +### Keymap and its components {#keymap-components-intro} -@todo keywords, other settings such as “SetMods” +The top level structure of the XKB text format consists of the [xkb_keymap] +block and its various [components][keymap components]. - -The key words are _case-insensitive_, e.g. the following strings denote -the same key word: `SETMODS`, `SetMods`, `setMods` and `setmods`. +
+ +
Keymap component @anchor keymap-components
+
+ A keymap is composed of multiple _components_, referred as [KcCGST]. They are + presented in the [table herinafter][keymap components table]. +
+
Keymap section @anchor keymap-section-def
+
+ A part of the keymap text configuration dedicated to one of the + [keymap components][keymap components table]. +
Component folder
+
+ A folder in the [keymap configuration database][database], containing files + with partial definitions of the same keymap section. +
+ + + + + + +
+ +[keymap components table]: @ref keymap-components-table + +@anchor keymap-components-table + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Keymap components +
Component[Section](@ref keymap-section-def) in a [keymap][xkb_keymap]Folder in a keymap configuration databaseDescription
Key codes[xkb_keycodes]`keycodes` + A translation of the raw [key codes][keycode] from the keyboard into + symbolic names. +
Compatibility[xkb_compat]`compat` + A specification of what internal actions modifiers and various + special-purpose keys produce. +
(Geometry)xkb_geometry`geometry` + A description of the physical layout of a keyboard. + + @attention This legacy feature is [not supported](@ref geometry-support) + by _xkbcommon_. + +
Key symbols[xkb_symbols]`symbols` + A translation of symbolic [key codes][keycode] into actual [key symbols][keysyms] + (keysyms). +
Key types[xkb_types]`types` + Types describe how a pressed key is affected by active [modifiers] + such as Shift, Control, Alt, etc. +
+ +@todo introduce keymap sections +@todo multiple keymaps in one file? + + +### Comments + +Comments are introduced following either `//` or `#` until the end of the line. ### Literals @@ -395,6 +539,78 @@ the same key word: `SETMODS`, `SetMods`, `setMods` and `setmods`. +### Keywords + +The following table presents the keywords used in the format. They are +_case-sensitive_. + + + +| Keyword | Use | +| ----------------------- | ------------------------------ | +| `action` | TODO | +| `alias` | TODO | +| `alphanumeric_keys` | TODO | +| `alternate_group` | TODO | +| `alternate` | TODO | +| `augment` | Mode qualifier for [include] statements | +| `default` | TODO | +| `function_keys` | TODO | +| `group` | TODO | +| `hidden` | TODO | +| `include` | [Include statement][include] | +| `indicator` | TODO | +| `interpret` | TODO | +| `key` | TODO | +| `keypad_keys` | TODO | +| `keys` | TODO | +| `logo` | TODO | +| `mod_map` | Alias of `modifier_map` | +| `modifier_keys` | TODO | +| `modmap` | Alias of `modifier_map` | +| `modifier_map` | TODO | +| `outline` | TODO | +| `overlay` | TODO | +| `override` | Mode qualifier for [include] statements | +| `partial` | TODO | +| `replace` | Mode qualifier for [include] statements | +| `row` | TODO | +| `section` | TODO | +| `shape` | TODO | +| `solid` | TODO | +| `text` | TODO | +| `type` | TODO | +| `virtual_modifiers` | TODO | +| `virtual` | TODO | +| `xkb_compat_map` | Alias of `xkb_compatibility_map` | +| `xkb_compat` | Alias of `xkb_compatibility_map` | +| `xkb_compatibility_map` | Declare a [compatibility section][xkb_compat] | +| `xkb_compatibility` | Alias of `xkb_compatibility_map` | +| `xkb_geometry` | Declare a geometry section (TODO: legacy) | +| `xkb_keycodes` | Declare a [keycodes section][xkb_keycodes] | +| `xkb_keymap` | Declare a [keymap block][xkb_keymap] | +| `xkb_layout` | TODO | +| `xkb_semantics` | TODO | +| `xkb_symbols` | Declare a [symbols section][xkb_symbols] | +| `xkb_types` | Declare a [key types section ][xkb_types] | + +[include]: @ref xkb-include + +### Built-in settings + + + +There are many built-in settings; they are explained in the following relevant +sections. + +These settings are _case-insensitive_, e.g. the following strings denote +the same key word: `SETMODS`, `SetMods`, `setMods` and `setmods`. + +### The include mechanism {#xkb-include} + +@todo the import mechanism, its qualifiers ## The “xkb_keymap” block {#the-xkb_keymap-block} @@ -422,6 +638,10 @@ block, under which are nested the following sections: + + + + Overview of a keymap file: ```c @@ -441,6 +661,12 @@ xkb_keymap { }; ``` +@todo `xkb_semantics`, `xkb_layout`: them seem to be aliases of `xkb_keymap` in +xkbcommon, but they have subtle differences in original `xkbcomp`. + + ## The “xkb_keycodes” section {#the-xkb_keycodes-section} This is the simplest section type, and is the first one to be diff --git a/meson.build b/meson.build index ce17b1d69..b1a91873a 100644 --- a/meson.build +++ b/meson.build @@ -830,6 +830,7 @@ You can disable the documentation with -Denable-docs=false.''') doxygen_input = [ 'README.md', 'doc/diagrams/xkb-configuration.dot', + 'doc/diagrams/xkb-keymap-components.dot', 'doc/doxygen-extra.css', 'doc/introduction-to-xkb.md', 'doc/quick-guide.md',