Doc: add introduction to keymap and its components

Add a diagram to explain the relationships between RMLVO and KcCGST.
xkbcommon · Sep 20, 2023 · f925880 · f925880
1 parent b900faf
commit f925880
Show file tree

Hide file tree

Showing 3 changed files with 295 additions and 13 deletions.
diff --git a/doc/diagrams/xkb-keymap-components.dot b/doc/diagrams/xkb-keymap-components.dot
@@ -0,0 +1,55 @@
+digraph {
+    node [shape=box]
+
+    database [shape=none, label=<
+        <table border="0" cellborder="1" cellspacing="0" cellpadding="4">
+            <tr><td><b>Layout Database</b></td></tr>
+            <hr/>
+            <tr><td port="rules" href="@ref rule-file-format">Rules files</td></tr>
+            <tr><td port="keycodes" href="@ref keycode-def">Keycodes files</td></tr>
+            <tr><td port="compat" href="@ref key-action-def">Compat files</td></tr>
+            <tr><td port="geometry">(Geometry files)</td></tr>
+            <tr><td port="symbols" href="@ref keysym-def">Symbols files</td></tr>
+            <tr><td port="types" href="@ref key-type-def">Key types files</td></tr>
+        </table>
+    >];
+
+    server [
+        label=<<b>Server</b>>,
+        style=rounded
+    ];
+
+    client [
+        label=<<b>Client</b>>,
+        style=rounded
+    ];
+
+    { rank="same"; database; server; client }
+
+    database:keycodes -> server [
+        label=<<i>xkb_keycodes</i> section>,
+        labelhref="@ref the-xkb_keycodes-section"
+    ];
+    database:compat -> server [
+        label=<<i>xkb_compat</i> section>,
+        labelhref="@ref the-xkb_compat-section"
+    ];
+    database:symbols -> server [
+        label=<<i>xkb_symbols</i> section>,
+        labelhref="@ref the-xkb_symbols-section"
+    ];
+    database:types -> server [
+        label=<<i>xkb_types</i> section>,
+        labelhref="@ref the-xkb_types-section"
+    ];
+
+    server:n -> database:rules [
+        label=<RMLVO>,
+        labelhref="@ref RMLVO-intro",
+        labeltooltip="Rules, Model, Layout, Variant, Options"
+    ];
+    server -> client [
+        label=<complete keymap:<br/><i>xkb_keymap</i> block =<br/><i>xkb_keycodes</i> +<br/><i>xkb_compat</i> +<br/><i>xkb_symbols</i> +<br/><i>xkb_types</i>>,
+        labelhref="@ref the-xkb_keymap-block"
+    ];
+}
diff --git 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.
+
+<!-- TODO quick guide for modify existing keymaps & creating custom ones -->
 
 @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.
   </dd>
+  <dt>Keymap configuration database @anchor database-def</dt>
+  <dd>
+  <span class="todo">TODO:</span> [xkeyboard-config], the
+    standard database of keyboard configuration data.
+  </dd>
 </dl>
 
 [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
+  <strong>[KcCGST components][KcCGST]</strong> 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 <strong>[complete keymap]</strong> 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].
 
-<!--
-TODO: SetMods is not a keyword, but how call it for using-facing doc?
+[keymap components]: @ref keymap-components
 
-There are many keywords
+<!-- NOTE:
+The XKB protocol (https://www.x.org/releases/current/doc/kbproto/xkbproto.html)
+uses “Keyboard description” and “Keyboard components” rather than “keymap” and
+“keymap components”.
+-->
 
-The key words are _case-insensitive_, e.g. the following strings denote
-the same key word: `SETMODS`, `SetMods`, `setMods` and `setmods`.
+<dl>
+<!--
+  <dt>Keymap</dt>
+  <dd>
+  A mapping of raw keycodes to symbols and actions. It fully defines the
+  behavior of a keyboard. Depending of the context, a keymap may refer to:
+  - the software object defined and managed by libxkbcommon;
+  - the text configuration used to create this software object.
+  </dd>
 -->
+  <dt>Keymap component @anchor keymap-components</dt>
+  <dd>
+  A keymap is composed of multiple _components_, referred as [KcCGST]. They are
+  presented in the [table herinafter][keymap components table].
+  </dd>
+  <dt>Keymap section @anchor keymap-section-def</dt>
+  <dd>
+  A part of the keymap text configuration dedicated to one of the
+  [keymap components][keymap components table].
+  <dt>Component folder</dt>
+  <dd>
+  A folder in the [keymap configuration database][database], containing files
+  with partial definitions of the same keymap section.
+  </dd>
+  <!-- FIXME: not sure of the following -->
+  <!-- <dt>Partial keymap</dt>
+  <dd>
+  A keymap text configuration with one or more keymap sections. Some
+  sections may be missing and [include] statements may not be resolved.
+  </dd> -->
+  <!-- <dt>Complete keymap</dt>
+  <dd> -->
+  <!-- FIXME mandatory sections?? -->
+  <!-- TODO: only one section of each type -->
+  <!-- A keymap text configuration consisting of a `%xkb_keymap` block with all
+  mandatory sections; all [include] statements are resolved so that it is
+  self-contained.
+
+  See the [xkb_keymap] block for further details.
+  </dd> -->
+</dl>
+
+[keymap components table]: @ref keymap-components-table
+
+@anchor keymap-components-table
+<table>
+  <caption>
+    Keymap components
+  </caption>
+  <tr>
+    <th>Component</th>
+    <th>[Section](@ref keymap-section-def) in a [keymap][xkb_keymap]</th>
+    <th>Folder in a keymap configuration database</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <th><u>K</u>ey <u>c</u>odes</th>
+    <td>[xkb_keycodes]</td>
+    <td>`keycodes`</td>
+    <td>
+    A translation of the raw [key codes][keycode] from the keyboard into
+    symbolic names.
+    </td>
+  </tr>
+  <tr>
+    <th><u>C</u>ompatibility</th>
+    <td>[xkb_compat]</td>
+    <td>`compat`</td>
+    <td>
+    A specification of what internal actions modifiers and various
+    special-purpose keys produce.
+    </td>
+  </tr>
+  <tr>
+    <th>(<u>G</u>eometry)</th>
+    <td>xkb_geometry</td>
+    <td>`geometry`</td>
+    <td>
+    A description of the physical layout of a keyboard.
+
+    @attention This legacy feature is [not supported](@ref geometry-support)
+    by _xkbcommon_.
+
+    </td>
+  </tr>
+  <tr>
+    <th>Key <u>s</u>ymbols</th>
+    <td>[xkb_symbols]</td>
+    <td>`symbols`</td>
+    <td>
+    A translation of symbolic [key codes][keycode] into actual [key symbols][keysyms]
+    (keysyms).
+    </td>
+  </tr>
+  <tr>
+    <th>Key <u>t</u>ypes</th>
+    <td>[xkb_types]</td>
+    <td>`types`</td>
+    <td>
+    Types describe how a pressed key is affected by active [modifiers]
+    such as Shift, Control, Alt, etc.
+    </td>
+  </tr>
+</table>
+
+@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`.
   </dd>
 </dl>
 
+### Keywords
+
+The following table presents the keywords used in the format. They are
+_case-sensitive_.
+
+<!-- NOTE: keywords are defined in `src/xkbcomp/keywords.gperf` -->
+
+| Keyword                 | Use                            |
+| ----------------------- | ------------------------------ |
+| `action`                | <span class="todo">TODO</span> |
+| `alias`                 | <span class="todo">TODO</span> |
+| `alphanumeric_keys`     | <span class="todo">TODO</span> |
+| `alternate_group`       | <span class="todo">TODO</span> |
+| `alternate`             | <span class="todo">TODO</span> |
+| `augment`               | Mode qualifier for [include] statements |
+| `default`               | <span class="todo">TODO</span> |
+| `function_keys`         | <span class="todo">TODO</span> |
+| `group`                 | <span class="todo">TODO</span> |
+| `hidden`                | <span class="todo">TODO</span> |
+| `include`               | [Include statement][include]              |
+| `indicator`             | <span class="todo">TODO</span> |
+| `interpret`             | <span class="todo">TODO</span> |
+| `key`                   | <span class="todo">TODO</span> |
+| `keypad_keys`           | <span class="todo">TODO</span> |
+| `keys`                  | <span class="todo">TODO</span> |
+| `logo`                  | <span class="todo">TODO</span> |
+| `mod_map`               | Alias of `modifier_map`                   |
+| `modifier_keys`         | <span class="todo">TODO</span> |
+| `modmap`                | Alias of `modifier_map` |
+| `modifier_map`          | <span class="todo">TODO</span> |
+| `outline`               | <span class="todo">TODO</span> |
+| `overlay`               | <span class="todo">TODO</span> |
+| `override`              | Mode qualifier for [include] statements |
+| `partial`               | <span class="todo">TODO</span> |
+| `replace`               | Mode qualifier for [include] statements |
+| `row`                   | <span class="todo">TODO</span> |
+| `section`               | <span class="todo">TODO</span> |
+| `shape`                 | <span class="todo">TODO</span> |
+| `solid`                 | <span class="todo">TODO</span> |
+| `text`                  | <span class="todo">TODO</span> |
+| `type`                  | <span class="todo">TODO</span> |
+| `virtual_modifiers`     | <span class="todo">TODO</span> |
+| `virtual`               | <span class="todo">TODO</span> |
+| `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 (<span class="todo">TODO: legacy</span>) |
+| `xkb_keycodes`          | Declare a [keycodes section][xkb_keycodes] |
+| `xkb_keymap`            | Declare a [keymap block][xkb_keymap] |
+| `xkb_layout`            | <span class="todo">TODO</span> |
+| `xkb_semantics`         | <span class="todo">TODO</span> |
+| `xkb_symbols`           | Declare a [symbols section][xkb_symbols]   |
+| `xkb_types`             | Declare a [key types section ][xkb_types]  |
+
+[include]: @ref xkb-include
+
+### Built-in settings
+
+<!--
+TODO: SetMods is not a keyword, but how call it for using-facing doc?
+-->
+
+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:
   </dd>
 </dl>
 
+<!-- TODO: there might be several keymaps: explain syntax and how they are selected -->
+<!-- TODO: keymap may be named -->
+<!-- TODO: introduce tags → only “default” MAP_IS_DEFAULT seems to be used; other are just documentation -->
+
 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`.
+<!--
+TODO: See: [xkbcomp] xkbcomp/keymap.c CompileKeymap (XkmSemanticsFile, XkmLayoutFile)
+-->
+
 ## 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
@@ -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',