doc: Add debugging page and warning about session restart

doc/debugging.md

@@ -0,0 +1,69 @@
+# Debugging {#debugging}
+
+## Available tools
+
+xkbcommon provides multiple tools for debugging. Please consult the manual pages
+`man xkbcli` for the complete documentation of each tools.
+
+@note These tools may not be installed by default; please ensure you have the
+package `libxkbcommon-tools` installed.
+
+### Basic tools
+
+- Interactive:
+  - `xkbcli interactive-x11` to test your current configuration in a *X11* session.
+  - `xkbcli interactive-wayland` to test your current configuration in a *Wayland*
+    session.
+  You may want to use the flag `--enable-compose` if your layouts uses dead keys.
+- `xkbcli how-to-type`: to find the key combinations to type in order to get a
+  specific character or keysym.
+
+### Advanced tools
+
+- `xkbcli interactive-evdev`: to test a configuration without affecting your
+  current configuration. You may need to add your user to the `input` group.
+- `xkbcli compile-keymap`: to check the resulting compiled keymap for some
+  configuration.
+- `xkbcli compile-compose`: to check the resulting Compose file.
+
+## Testing a custom configuration {#testing-custom-config}
+
+@note An erroneous XKB configuration may make your keyboard unusable. Therefore
+it is advised to try custom configurations safely with the following workflow:
+
+1. Create a directory for the custom configuration, e.g. `~/xkb-test`. Note that
+   in order to test it safely, it should *not* be one of the locations that
+   [xkbcommon searches][user-config-locations].
+2. Create the relevant sub-directories and files, e.g. `~/xkb-test/symbols/my-layout`.
+3. Test if your changes *compile* successfully:
+
+   ```bash
+   xkbcli compile-keymap --include ~/xkb-test --include-defaults --test --layout my-layout
+   ```
+
+   @note The order of the `--include*` arguments is important here.
+
+   If it does not compile, you may add the flag `--verbose` for additional information.
+4. Test if it *behaves* correctly. Note that you may need to add your user to the
+   `input` group.
+
+   ```bash
+   xkbcli interactive-evdev --include ~/xkb-test --include-defaults --enable-compose --layout my-layout
+   ```
+5. Repeat steps 3 and 4 with your *full* keyboard configuration, i.e. all your
+   model, layouts and options.
+6. If everything works as expected, it is time to test in real conditions:
+   - Wayland: , move `~/xkb-test` to one of the [user-configuration locations][user-config-locations],
+     restart your session, update the keyboard configuration using your usual UI
+     and enjoy your XKB customization!
+   - X11: Unfortunately XOrg does not support alternative paths, so the next best
+     option is to use the venerable `xkbcomp` tool.
+
+     ```bash
+     xkbcli compile-keymap --include ~/xkb-test --include-defaults --layout my-layout \
+       | xkbcomp - $DISPLAY
+    ```
+
+Happy hacking!
+
+[user-config-locations]: @ref user-config-locations

doc/user-configuration.md

@@ -9,9 +9,15 @@ parsed by libxkbcommon.
 @warning The below requires libxkbcommon as keymap compiler and
 **does not work in X**.
 
+@important An erroneous XKB configuration may make your keyboard unusable.
+Therefore it is advised to try custom configurations safely using `xkbcli` tools;
+see [debugging] for further details.
+
+[debugging]: @ref testing-custom-config
+
 @tableofcontents{html:2}
 
-## Data locations
+## Data locations {#user-config-locations}
 
 libxkbcommon searches the following paths for XKB configuration files:
 1. `$XDG_CONFIG_HOME/xkb/`, or `$HOME/.config/xkb/` if the `$XDG_CONFIG_HOME`
@@ -53,7 +59,7 @@ the addition should be filed in the upstream [xkeyboard-config] project.
 Due to how XKB is configured, there is no such thing as a "layout" in XKB
 itself, or, indeed, any of the rules, models, variant, options (RMLVO) described
 in `struct xkb_rule_names`. RMLVO names are merely lookup keys in the
-rules file provided by xkeyboard-config to map to the correct keycode, compat,
+rules file provided by [xkeyboard-config] to map to the correct keycode, compat,
 geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data
 is the one used by XKB and libxkbcommon to map keys to actual symbols.
 
@@ -238,3 +244,9 @@ are added to the system-provided layouts and options.
 
 For details on the XML format, see the DTD in `<datadir>/X11/xkb/rules/xkb.dtd`
 and the system-provided XML files `<datadir>/X11/xkb/rules/*.xml`.
+
+@note Depending on the desktop environment, it may require restarting the session
+in order to make the configuration changes effective.
+
+@note It is advised to try the custom configuration *before* restarting the
+session using the various `xkbcli` tools. See [debugging] for further details.

meson.build

@@ -1023,6 +1023,7 @@ You can disable the documentation with -Denable-docs=false.''')
 
     doxygen_input = [
         'README.md',
+        'doc/debugging.md',
         'doc/diagrams/xkb-configuration.dot',
         'doc/diagrams/xkb-keymap-components.dot',
         'doc/diagrams/xkb-types-explanation.dot',