doc: Improve rules

- Improved introduction
- Added examples
- Added RMLVO resolution process

doc/diagrams/xkb-configuration.dot

@@ -11,7 +11,8 @@ digraph {
         RMLVO_resolution [
             label=<<i>RMLVO resolution</i><br/>Determine KcCGST using the specified rules file:<br/>match the given model, layout, variant and options fields>,
             style=rounded,
-            color=blue
+            color=blue,
+            href="@ref rmlvo-resolution"
         ];
         KcCGST [
             label=<<i>Layout database configuration</i><br/><b>KcCGST:</b> <b>K</b>ey<b>c</b>odes, <b>C</b>ompat, <b>G</b>eometry, <b>S</b>ymbols, <b>T</b>ypes>,
@@ -24,7 +25,7 @@ digraph {
             color=blue
         ];
         Keymap [
-            label=<<i>Window server configuration</i><br/><b>Complete keymap</b>>,
+            label=<<i>Display server configuration</i><br/><b>Complete keymap</b>>,
             penwidth=3,
             href="@ref keymap-intro"
         ];
@@ -34,12 +35,12 @@ digraph {
         <table border="0" cellborder="1" cellspacing="0" cellpadding="4">
             <tr><td><b>Layout Database</b></td></tr>
             <hr/>
-            <tr><td port="rules">Rules files</td></tr>
-            <tr><td port="keycodes">Keycodes files</td></tr>
-            <tr><td port="compat">Compat files</td></tr>
-            <tr><td port="geometry">(Geometry files)</td></tr>
-            <tr><td port="symbols">Symbols files</td></tr>
-            <tr><td port="types">Types files</td></tr>
+            <tr><td port="rules" href="@ref config-rules-def">Rules files</td></tr>
+            <tr><td port="keycodes" href="@ref config-keycodes-def">Keycodes files</td></tr>
+            <tr><td port="compat" href="@ref config-compat-def">Compat files</td></tr>
+            <tr><td port="geometry" href="@ref config-geometry-def">(Geometry files)</td></tr>
+            <tr><td port="symbols" href="@ref config-symbols-def">Symbols files</td></tr>
+            <tr><td port="types" href="@ref config-types-def">Types files</td></tr>
         </table>
     >];
 

doc/doxygen-extra.css

@@ -12,6 +12,10 @@ dl.todo dt::before {
     content: '🚧 ';
 }
 
+dl.note dd {
+    margin-inline-start: revert;
+}
+
 span.todo::before {
     content: '🚧 ';
 }

doc/introduction-to-xkb.md

@@ -58,15 +58,15 @@ implementation.
     The RMLVO configuration consists of the following components:
 
     <dl>
-      <dt>Rules</dt>
+      <dt>Rules @anchor config-rules-def</dt>
       <dd>
       The rules define the _mapping_ from high to low level components.
       The rules _component_ is the file containing the set of rules to use.
       It is usually implicit and set by the system.
 
       See the [rules file format](doc/rules-format.md) for further details.
       </dd>
-      <dt>Model</dt>
+      <dt>Model @anchor config-model-def</dt>
       <dd>
       The name of the model of the keyboard hardware in use.
       It may depend on:
@@ -80,16 +80,16 @@ implementation.
       - The keyboard _vendor:_ keyboard may have a set of keys that are not
         standard, or may be specific to an OS.
       </dd>
-      <dt>Layout</dt>
+      <dt>Layout @anchor config-layout-def</dt>
       <dd>
       The identifier of the general layout to use. It usually refers to a
       country or a language.
       </dd>
-      <dt>Variant</dt>
+      <dt>Variant @anchor config-variant-def</dt>
       <dd>
       Any minor variants on the general layout. It may be national variants
       </dd>
-      <dt>Options</dt>
+      <dt>Options @anchor config-options-def</dt>
       <dd>
       Set of extra options to customize the standard layouts.
 
@@ -113,28 +113,28 @@ implementation.
     The KcCGST configuration consists of the following components:
 
     <dl>
-      <dt>Key codes</dt>
+      <dt>Key codes @anchor config-keycodes-def</dt>
       <dd>
       A translation of the raw [key codes] from the keyboard into
       symbolic names.
       </dd>
-      <dt>Compatibility</dt>
+      <dt>Compatibility @anchor config-compat-def</dt>
       <dd>
       A specification of what internal actions modifiers and various
       special-purpose keys produce.
       </dd>
-      <dt>Geometry</dt>
+      <dt>Geometry @anchor config-geometry-def</dt>
       <dd>
       A description of the physical layout of a keyboard.
 
       @attention This legacy feature is [not supported](@ref geometry-support)
       by _xkbcommon_.
       </dd>
-      <dt>Key symbols</dt>
+      <dt>Key symbols @anchor config-symbols-def</dt>
       <dd>
       A translation of symbolic key codes into actual [key symbols] \(keysyms).
       </dd>
-      <dt>Key types</dt>
+      <dt>Key types @anchor config-types-def</dt>
       <dd>
       Types describe how a pressed key is affected by active [modifiers]
       such as Shift, Control, Alt, etc.

doc/keymap-format-text-v1.md

@@ -1532,6 +1532,13 @@ 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.
 
+@anchor merge-mode-def
+One can use a **merge mode** *prefix* to specify the merge mode of the file:
+- ‘+’ selects the **override** merge mode.
+- ‘|’ selects the **augment** merge mode.
+
+@todo dedicated section for merge mode
+
 ### Key statement
 
 Statements of the form: