Improve documentation

- Add introduction to XKB
- Embrace Doxygen features
- More cross links

10 files changed, 469 insertions, 74 deletions

diff --git a/README.md b/README.md
index 84bbcaa..b36e3cf 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,18 @@
 # libxkbcommon
 
 libxkbcommon is a keyboard keymap compiler and support library which
-processes a reduced subset of keymaps as defined by the XKB (X Keyboard
+processes a reduced subset of keymaps as defined by the [XKB] \(X Keyboard
 Extension) specification.  It also contains a module for handling Compose
 and dead keys and a separate library for listing available keyboard layouts.
 
+[XKB]: doc/introduction-to-xkb.md
+
 ## Quick Guide
 
-See [Quick Guide](doc/quick-guide.md).
+See [Introduction to XKB][XKB] to learn the essentials of XKB.
+
+See [Quick Guide](doc/quick-guide.md) for an introduction on how to use this
+library.
 
 ## Building
 
@@ -29,7 +34,7 @@ using the X11 keyboard configuration resource files thusly:
 ## API
 
 While libxkbcommon's API is somewhat derived from the classic XKB API as found
-in X11/extensions/XKB.h and friends, it has been substantially reworked to
+in `X11/extensions/XKB.h` and friends, it has been substantially reworked to
 expose fewer internal details to clients.
 
 See the [API Documentation](https://xkbcommon.org/doc/current/modules.html).
@@ -47,7 +52,7 @@ data.
 
 ## Relation to X11
 
-See [Compatibility](doc/compat.md) notes.
+See [Compatibility](doc/compatibility.md) notes.
 
 ## Development
 
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 56884ef..cb4937a 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -14,10 +14,12 @@ EXTENSION_MAPPING      = no_extension=md
 
 SORT_MEMBER_DOCS       = NO
 
-QUIET                  = YES
+QUIET                  = $(DOXYGEN_QUIET)
 
 WARN_IF_UNDOCUMENTED   = NO
 
+WARN_AS_ERROR          = $(DOXYGEN_WARN_AS_ERROR)
+
 INPUT                  = @INPUT@
 
 FILE_PATTERNS          = *.c \
@@ -45,3 +47,9 @@ ENUM_VALUES_PER_LINE   = 1
 SEARCHENGINE           = NO
 
 GENERATE_LATEX         = NO
+
+HAVE_DOT               = YES
+
+DOTFILE_DIRS           = doc/diagrams
+
+DOT_IMAGE_FORMAT       = svg
diff --git a/doc/compat.md b/doc/compatibility.md
index 19d7d78..2fb05af 100644
--- a/doc/compat.md
+++ b/doc/compatibility.md
@@ -1,4 +1,8 @@
-# Compatibility
+# Compatibility {#xkbcommon-compatibility}
+
+@tableofcontents{html:2}
+
+## XKB support {#xkb-v1-compatibility}
 
 Relative to the XKB 1.0 specification implemented in current X servers,
 xkbcommon has removed support for some parts of the specification which
@@ -6,14 +10,17 @@ introduced unnecessary complications.  Many of these removals were in fact
 not implemented, or half-implemented at best, as well as being totally
 unused in the standard dataset.
 
-Notable removals:
-- geometry support
+### Notable removals
+
+- geometry support @anchor geometry
+  @anchor geometry-support
   + there were very few geometry definitions available, and while
     xkbcommon was responsible for parsing this insanely complex format,
     it never actually did anything with it
   + hopefully someone will develop a companion library which supports
     keyboard geometries in a more useful format
 - KcCGST (keycodes/compat/geometry/symbols/types) API
+  @anchor KcCGST-support
   + use RMLVO instead; KcCGST is now an implementation detail
   + including pre-defined keymap files
 - XKM support
@@ -37,7 +44,8 @@ Notable removals:
 
 On the other hand, some features and extensions were added.
 
-Notable additions:
+### Notable additions
+
 - 32-bit keycodes
 - extended number of modifiers (planned)
 - extended number of groups (planned)
@@ -45,7 +53,7 @@ Notable additions:
   + such levels are ignored by x11/xkbcomp.
 - key names (e.g. `<AE11>`) can be longer than 4 characters.
 
-## Compose support
+## Compose support {#compose-support}
 
 Relative to the standard implementation in libX11 (described in the
 Compose(5) man-page), some features are not supported:
diff --git a/doc/diagrams/xkb-configuration.dot b/doc/diagrams/xkb-configuration.dot
new file mode 100644
index 0000000..e547f00
--- /dev/null
+++ b/doc/diagrams/xkb-configuration.dot
@@ -0,0 +1,75 @@
+digraph {
+
+    node [shape=box]
+
+    subgraph process {
+        RMLVO [
+            label=<<i>End user configuration</i><br/><b>RMLVO:</b> <b>R</b>ules, <b>M</b>odel, <b>L</b>ayout, <b>V</b>ariant, <b>O</b>ptions>,
+            penwidth=3,
+            href="@ref RMLVO-intro",
+        ];
+        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
+        ];
+        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>,
+            penwidth=3,
+            href="@ref KcCGST-intro"
+        ];
+        KcCGST_resolution [
+            label=<<i>KcCGST resolution</i><br/>Construct the keymap from its components>,
+            style=rounded,
+            color=blue
+        ];
+        Keymap [
+            label=<<i>Window server configuration</i><br/><b>Complete keymap</b>>,
+            penwidth=3,
+            href="@ref keymap-intro"
+        ];
+    }
+
+    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">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>
+        </table>
+    >];
+
+    { rank = same; KcCGST; database }
+
+    edge [
+        color=blue,
+        arrowhead=normal,
+        style=bold
+    ]
+    {
+        rankdir="TB";
+        RMLVO -> RMLVO_resolution -> KcCGST -> KcCGST_resolution -> Keymap
+    }
+
+
+    edge [
+        color=dimgrey,
+        arrowhead=vee,
+        style=solid
+    ]
+    RMLVO:e -> database:rules:e [constraint=false];
+    KcCGST:e -> database:keycodes:w [constraint=false];
+    KcCGST:e -> database:compat:w [constraint=false];
+    KcCGST:e -> database:symbols:w [constraint=false];
+    KcCGST:e -> database:types:w [constraint=false];
+
+    database:rules:w -> RMLVO_resolution:e [constraint=false];
+    database:keycodes:e -> KcCGST_resolution [constraint=false];
+    database:compat:e -> KcCGST_resolution [constraint=false];
+    database:symbols:e -> KcCGST_resolution [constraint=false];
+    database:types:e -> KcCGST_resolution [constraint=false];
+}
diff --git a/doc/doxygen-extra.css b/doc/doxygen-extra.css
index f07617a..104fa0b 100644
--- a/doc/doxygen-extra.css
+++ b/doc/doxygen-extra.css
@@ -8,6 +8,26 @@ div#top, div.header, div.contents {
     display: none;
 }
 
-span.TODO::before {
+dl.todo dt::before {
     content: '🚧 ';
 }
+
+span.todo::before {
+    content: '🚧 ';
+}
+
+/* Append external links with a distinctive icon */
+a[href^="http://"]::after,
+a[href^="https://"]::after
+{
+    content: "";
+    width: 11px;
+    height: 11px;
+    margin-left: 4px;
+    /* Bootstrap icon: https://icons.getbootstrap.com/icons/box-arrow-up-right/ */
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='currentColor' class='bi bi-box-arrow-up-right' viewBox='0 0 16 16'%3E%3Cpath fill-rule='evenodd' d='M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z'/%3E%3Cpath fill-rule='evenodd' d='M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z'/%3E%3C/svg%3E");
+    background-position: center;
+    background-repeat: no-repeat;
+    background-size: contain;
+    display: inline-block;
+}
diff --git a/doc/introduction-to-xkb.md b/doc/introduction-to-xkb.md
new file mode 100644
index 0000000..f7402a4
--- /dev/null
+++ b/doc/introduction-to-xkb.md
@@ -0,0 +1,207 @@
+# Introduction to XKB {#xkb-intro}
+
+__XKB__ stands for “X Keyboard Extension”. It may refer to either:
+
+- a [protocol](@ref xkb-the-protocol)
+- a [keyboard layout configuration](@ref xkb-the-config)
+- a [text format](@ref xkb-the-text-format)
+
+## XKB the protocol {#xkb-the-protocol}
+
+A __protocol__ for the [X Windows System], that extends the core protocol.
+
+_xkbcommon’s_ API is somehow derived from this API, but has been
+substantially reworked to function as a library instead of a protocol,
+and exposes fewer internal details to clients.
+
+_xkbcommon_ does not depend on a particular windows system; for instance
+it is used by the [Wayland] protocol.
+
+_xkbcommon_ provides the <code>[xkbcommon-x11]</code> module to interface
+a client with an X server using the XKB protocol. Relevant links:
+
+- [The X Window System Protocol][X Protocol]
+- [The X Keyboard Extension: Protocol Specification][XKB Protocol]
+- [xkbcommon-x11]
+
+
+## XKB the keyboard keymap configuration {#xkb-the-config}
+
+In order to use [the protocol](@ref xkb-the-protocol), one must first load a
+[complete keymap]. The keymap usually comes from the OS _layout database_,
+which is commonly [xkeyboard-config]. Since keymaps may have definitions in
+common, the database actually stores their basic components separately to allow
+maximum composability and coherence. A recipe to compose a keymap from its
+components is called a _keymap configuration_.
+
+In XKB, there are several ways to define a keymap configuration. They all aim to
+produce a [complete keymap]. The following diagram presents an overview.
+Then they are presented hereinafter, ordered from end user to low-level
+implementation.
+
+@dotfile xkb-configuration "XKB keymap configurations"
+<dl>
+  <dt>
+    RMLVO: <u>R</u>ules, <u>M</u>odel, <u>L</u>ayout, <u>V</u>ariant,
+    <u>O</u>ptions @anchor RMLVO-intro
+  </dt>
+  <dd>
+    This is the configuration the end user usually faces in the UI.
+    The idea is to expose high level concepts such as [keyboard model] and
+    [keyboard layout] to the user, then to _map_ them to the corresponding set
+    of low-level configuration files (see [KcCGST]).
+
+    @note The RMLVO configurations actually available to the end user is managed
+    by the `xkbregistry`. It uses an XML file, the _registry_, which exposes and
+    documents the set of RMLVO settings in the layout database.
+
+    The RMLVO configuration consists of the following components:
+
+    <dl>
+      <dt>Rules</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](@ref rule-file-format) for further details.
+      </dd>
+      <dt>Model</dt>
+      <dd>
+      The name of the model of the keyboard hardware in use.
+      It may depend on:
+
+      - The _location_ and _language_ of the user, because languages may
+        require [specific keys][language input keys] for their input methods,
+        such as the _muhenkan_ key on Japanese keyboard and the _Hanja_ key
+        for Korean keyboards. The keyboard are usually classified by the
+        [standard][keyboard standard] it is based on, e.g. ANSI, ISO, JIS,
+        ABNT.
+      - 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>
+      <dd>
+      The identifier of the general layout to use. It usually refers to a
+      country or a language.
+      </dd>
+      <dt>Variant</dt>
+      <dd>
+      Any minor variants on the general layout. It may be national variants
+      </dd>
+      <dt>Options</dt>
+      <dd>
+      Set of extra options to customize the standard layouts.
+
+      Examples: switch modifiers keys, location of the compose key, etc.
+      </dd>
+    </dl>
+  </dd>
+  <dt>
+    KcCGST: <u>K</u>ey<u>c</u>odes, <u>C</u>ompat, <u>G</u>eometry,
+    <u>S</u>ymbols, <u>T</u>ypes @anchor KcCGST-intro
+  </dt>
+  <dd>
+    This is the low-level configuration of XKB and how the files are actually
+    organized in the _layout database_.
+    It is not really intuitive or straight-forward for the uninitiated.
+
+    @note _xkbcommon_ [does not offer an API for KcCGST](@ref KcCGST-support):
+    it is considered an implementation detail.
+    Instead, [RMLVO] is the preferred way for the user to configure XKB.
+
+    The KcCGST configuration consists of the following components:
+
+    <dl>
+      <dt>Key codes</dt>
+      <dd>
+      A translation of the raw [key codes] from the keyboard into
+      symbolic names.
+      </dd>
+      <dt>Compatibility</dt>
+      <dd>
+      A specification of what internal actions modifiers and various
+      special-purpose keys produce.
+      </dd>
+      <dt>Geometry</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>
+      <dd>
+      A translation of symbolic key codes into actual [key symbols] (keysyms).
+      </dd>
+      <dt>Key types</dt>
+      <dd>
+      Types describe how a pressed key is affected by active [modifiers]
+      such as Shift, Control, Alt, etc.
+      </dd>
+    </dl>
+  </dd>
+  <dt>Complete Keymap @anchor keymap-intro</dt>
+  <dd>
+  A complete keymap is a _self-contained_ text file with all the [KcCGST]
+  components needed to configure a keyboard. This is the result of the
+  _resolution_ of the [RMLVO] and [KcCGST] configurations. This is also the
+  format used by X11 and Wayland when prompted to _serialize_ the keymap in use.
+
+  @note This is a low-level configuration. [RMLVO] is the preferred way for the
+  end user to configure XKB, but some _power users_ may need it for _avanced_
+  configurations.
+
+  See the [XKB text format] for further details.
+  </dd>
+</dl>
+
+@note Layout making use of dead keys require a [Compose](@ref compose) file. The
+same applies when if using a [Compose key].
+
+[key codes]: @ref keycode-def
+[key symbols]: @ref keysym-def
+[levels]: @ref level-def
+[modifiers]: @ref modifier-def
+[RMLVO]: @ref RMLVO-intro
+[KcCGST]: @ref KcCGST-intro
+[complete keymap]: @ref keymap-intro
+[Compose key]: https://en.wikipedia.org/wiki/Compose_key
+[XKB text format]: @ref xkb-the-text-format
+
+
+## XKB the text format {#xkb-the-text-format}
+
+A __text format__ to define keyboard keymaps. XKB 1.0 is the specification
+implemented in current X servers. The format supported by _xkbcommon_
+is very close to XKB 1.0, with some removals and additions. See the
+[compatibility] page for further details.
+
+The format supported by _xkbcommon_ is documented at the page
+“[The XKB keymap text format, V1][keymap-text-format-v1]”.
+
+The documentation of the _original_ XKB 1.0 format is much more scarce than
+for the protocol. Some priceless resources are:
+
+- [Ivan Pascal's XKB documentation][ivan-pascal]
+- [An Unreliable Guide to XKB Configuration][unreliable-guide]
+- [ArchWiki XKB page][arch-wiki]
+
+[X Windows System]: https://en.wikipedia.org/wiki/X_Window_System
+[X Protocol]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#Keyboards
+[XKB Protocol]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html
+[xkbcommon-x11]: @ref x11-overview
+[Wayland]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard
+[compatibility]: @ref xkb-v1-compatibility
+[keymap-text-format-v1]: @ref keymap-text-format-v1
+[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
+[arch-wiki]: https://wiki.archlinux.org/index.php/X_keyboard_extension
+[keyboard model]: https://en.wikipedia.org/wiki/Computer_keyboard
+[keymap]: https://en.wikipedia.org/wiki/Keyboard_layout
+[keyboard layout]: https://en.wikipedia.org/wiki/Keyboard_layout
+[xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
+[keyboard standard]: https://en.wikipedia.org/wiki/Computer_keyboard#Types_and_standards
+[language input keys]: https://en.wikipedia.org/wiki/Language_input_keys
+
+@todo Explain how to configure XKB, with examples
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>&quot;</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`
diff --git a/doc/rules-format.md b/doc/rules-format.md
index f9fe0d9..6348d62 100644
--- a/doc/rules-format.md
+++ b/doc/rules-format.md
@@ -1,24 +1,25 @@
-The rules file
+The rules file {#rule-file-format}
 ==============
 
 The purpose of the rules file is to map between configuration values
 that are easy for a user to specify and understand, and the
 configuration values xkbcomp uses and understands.
 
-xkbcomp uses the xkb_component_names struct, which maps directly to
+xkbcomp uses the `xkb_component_names` struct, which maps directly to
 include statements of the appropriate sections, called for short
-KcCGST (see doc/keymap-format-text-v1.txt; 'G' stands for "geometry",
-which is not supported). These are not really intuitive or straight-
-forward for the uninitiated.
+[KcCGST](@ref KcCGST-intro) (see the [XKB introduction](@ref xkb-intro);
+'G' stands for "geometry", which is not supported). These are not
+really intuitive or straight-forward for the uninitiated.
 
-Instead, the user passes in a xkb_rule_names struct, which consists
+Instead, the user passes in a `xkb_rule_names` struct, which consists
 of the name of a rules file (in Linux this is usually "evdev"), a
 keyboard model (e.g. "pc105"), a set of layouts (which will end up
 in different groups, e.g. "us,fr"), variants (used to alter/augment
 the respective layout, e.g. "intl,dvorak"), and a set of options
 (used to tweak some general behavior of the keyboard, e.g.
 "ctrl:nocaps,compose:menu" to make the Caps Lock key act like Ctrl
-and the Menu key like Compose). We call these RMLVO.
+and the Menu key like Compose). We call these
+[RMLVO](@ref RMLVO-intro).
 
 Format of the file
 ------------------
diff --git a/meson.build b/meson.build
index 57fbc1c..b64427d 100644
--- a/meson.build
+++ b/meson.build
@@ -792,9 +792,11 @@ You can disable the documentation with -Denable-docs=false.''')
 
     doxygen_input = [
         'README.md',
+        'doc/diagrams/xkb-configuration.dot',
         'doc/doxygen-extra.css',
+        'doc/introduction-to-xkb.md',
         'doc/quick-guide.md',
-        'doc/compat.md',
+        'doc/compatibility.md',
         'doc/user-configuration.md',
         'doc/rules-format.md',
         'doc/keymap-format-text-v1.md',
diff --git a/scripts/doxygen-wrapper b/scripts/doxygen-wrapper
index baa7b26..2c2edb5 100755
--- a/scripts/doxygen-wrapper
+++ b/scripts/doxygen-wrapper
@@ -5,4 +5,11 @@
 DOXYGEN="$1"
 DOXYFILE="$2"
 ABS_TOP_SRCDIR="$3"
+# Set environment variables that are unset
+if [ -z "$DOXYGEN_WARN_AS_ERROR" ]
+then export DOXYGEN_WARN_AS_ERROR="NO"
+fi
+if [ -z "$DOXYGEN_QUIET" ]
+then export DOXYGEN_QUIET="YES"
+fi
 cd "$ABS_TOP_SRCDIR" && exec "$DOXYGEN" "$DOXYFILE"