Add support for pre-commit

[platform/upstream/libxkbcommon.git] / doc / user-configuration.md

diff --git a/doc/user-configuration.md b/doc/user-configuration.md
index 886950a..40f7f77 100644 (file)
--- a/doc/user-configuration.md
+++ b/doc/user-configuration.md
@@ -11,6 +11,8 @@ libxkbcommon searches the following paths for XKB configuration files:
 - `$XDG_CONFIG_HOME/xkb/`, or `$HOME/.config/xkb/` if the `$XDG_CONFIG_HOME`
   environment variable is not defined
 - `$HOME/.xkb/`
+- `$XKB_CONFIG_EXTRA_PATH` if set, otherswise `<sysconfdir>/xkb` (on most
+  distributions this is `/etc/xkb`)
 - `$XKB_CONFIG_ROOT` if set, otherwise `<datadir>/X11/xkb/` (path defined by the
   `xkeyboard-config` package, on most distributions this is
   `/usr/share/X11/xkb`)
@@ -29,6 +31,15 @@ Each directory should have one or more of the following subdirectories:
 - `symbols`
 - `types`
 
+The majority of user-specific configuration involve modifying key symbols and
+this is what this document focuses on. For use-cases where a user may need to
+add new key types or compat entries the general approach remains the same. A
+detailed description for how to add those types or compat entries is out of
+scope for this document.
+
+You should never need to add user-specific keycodes. Where a keycode is missing,
+the addition should be filed in the upstream xkeyboard-config project.
+
 ## RMLVO vs KcCGST
 
 Due to how XKB is configured, there is no such thing as a "layout" in XKB
@@ -154,3 +165,68 @@ xkb_symbols "baz" {
 
 With these in place, a user may select any layout/variant together with
 the "custom:foo" and/or "custom:baz" options.
+
+## Discoverable layouts
+
+**The below requires libxkbregistry as XKB lookup tool and does not work where
+clients parse the XML file directly**.
+
+The above sections apply only to the data files and require that the user knows
+about the existence of the new entries. To make custom entries discoverable by
+the configuration tools (e.g. the GNOME Control Center), the new entries must
+also be added to the XML file that is parsed by libxkbregistry. In most cases,
+this is the `evdev.xml` file in the rules directory. The example below shows the
+XML file that would add the custom layout and custom options as outlined above
+to the XKB registry:
+
+```
+$ cat $XDG_CONFIG_HOME/xkb/rules/evdev.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
+<xkbConfigRegistry version="1.1">
+  <layoutList>
+    <layout>
+      <configItem>
+        <name>banana</name>
+        <shortDescription>ban</shortDescription>
+        <description>Banana</description>
+      </configItem>
+      <variantList>
+        <variant>
+          <configItem>
+            <name>orange</name>
+            <shortDescription>or</shortDescription>
+            <description>Orange (Banana)</description>
+          </configItem>
+        </variant>
+      </variantList>
+    </layout>
+  </layoutList>
+  <optionList>
+    <group allowMultipleSelection="true">
+      <configItem>
+        <name>custom</name>
+        <description>Custom options</description>
+      </configItem>
+      <option>
+      <configItem>
+        <name>custom:foo</name>
+        <description>Map Tilde to nothing</description>
+      </configItem>
+      </option>
+      <option>
+      <configItem>
+        <name>custom:baz</name>
+        <description>Map Z to K</description>
+      </configItem>
+      </option>
+    </group>
+  </optionList>
+</xkbConfigRegistry>
+```
+
+The default behavior of libxkbregistry ensures that the new layout and options
+are added to the system-provided layouts and options.
+
+For details on the XML format, see DTD in `<datadir>/X11/xkb/rules/xkb.dtd`
+and the system-provided XML files in `<datadir>/X11/xkb/rulies/xkb.dtd`.