doc: add documentation for user configuration

Most of this is currently hidden in the commit message for ca033a29d2ca, let's
make it a bit more public so we have a link to point users to.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 156 insertions, 0 deletions

diff --git a/doc/user-configuration.md b/doc/user-configuration.md
new file mode 100644
index 0000000..ed450fd
--- /dev/null
+++ b/doc/user-configuration.md
@@ -0,0 +1,156 @@
+# User-configuration
+
+This page describes how to add a custom layout or option so that it will be
+parsed by libxkbcommon.
+
+**The below requires libxkbcommon as keymap compiler and does not work in X**.
+
+## Data locations
+
+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_ROOT`
+- `<datadir>/X11/xkb/` (path defined by the `xkeyboard-config` package, on most
+  distributions this is `/usr/share/X11/xkb`)
+
+A keymap created with `xkb_keymap_new_from_names()` will look up those paths in
+order until the required data is found.
+
+**Note: Where libxkbcommon runs in a privileged context, only the system
+(datadir) path is available.**
+
+Each directory should have one or more of the following subdirectories:
+- `compat`
+- `geometry` (libxkbcommon ignores this directory)
+- `keycodes`
+- `rules`
+- `symbols`
+- `types`
+
+## RMLVO vs KcCGST
+
+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) decribed
+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,
+geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data
+is the one used by XKB and libxbkcommon to map keys to actual symbols.
+
+For example, a common RMLVO configuration is layout "us", variant "dvorak" and
+option "terminate:ctrl_alt_bksp". Using the default rules file and model
+this maps into the following KcCGST components:
+
+```
+xkb_keymap {
+	xkb_keycodes  { include "evdev+aliases(qwerty)"	};
+	xkb_types     { include "complete"	};
+	xkb_compat    { include "complete"	};
+	xkb_symbols   { include "pc+us(dvorak)+inet(evdev)+terminate(ctrl_alt_bksp)"	};
+	xkb_geometry  { include "pc(pc105)"	};
+};
+```
+
+A detailed explanation of how rules files convert RMLVO to KcCGST is out of
+scope for this document. See [the rules file](md_doc_rules-format.html) page
+instead.
+
+
+## Adding a layout
+
+Adding a layout requires that the user adds **symbols** in the correct location.
+
+The default rules files (usually `evdev`) have a catch-all to map a layout, say
+"foo", and a variant, say "bar", into the "bar" section in the file
+`$xkb_base_dir/symbols/foo`.
+This is sufficient to define a new keyboard layout. The example below defines
+the keyboard layout "banana" with an optional variant "orange"
+
+```
+$ cat $XDG_CONFIG_HOME/xkb/symbols/banana
+// Like a US layout but swap the top row so numbers are on Shift
+default partial alphanumeric_keys
+xkb_symbols "basic" {
+    include "us(basic)"
+    name[Group1]= "Banana (US)";
+
+    key <AE01> { [ exclam,          1]     };
+    key <AE02> { [ at,              2]     };
+    key <AE03> { [ numbersign,      3]     };
+    key <AE04> { [ dollar,          4]     };
+    key <AE05> { [ percent,         5]     };
+    key <AE06> { [ asciicircum,     6]     };
+    key <AE07> { [ ampersand,       7]     };
+    key <AE08> { [ asterisk,        8]     };
+    key <AE09> { [ parenleft,       9]     };
+    key <AE10> { [ parenright,      0]     };
+    key <AE11> { [ underscore,      minus] };
+    key <AE12> { [ plus,            equal] };
+};
+
+// Same as banana but map the euro sign to the 5 key
+partial alphanumeric_keys
+xkb_symbols "orange" {
+    include "banana(basic)"
+    name[Group1] = "Banana (Eurosign on 5)";
+    include "eurosign(5)"
+};
+```
+
+The `default` section is loaded when no variant is given. The first example
+sections uses ``include`` to populate with a symbols list defined elsewhere
+(here: section `basic` from the file `symbols/us`, aka. the default US keyboard
+layout) and overrides parts of these
+symbols. The effect of this section is to swap the numbers and symbols in the
+top-most row (compared to the US layout) but otherwise use the US layout.
+
+The "orange" variant uses the "banana" symbols and includes a different section
+to define the eurosign. It does not specificially override any symbols.
+
+The exact details of how `xkb_symbols` work is out of scope for this document.
+
+## Adding an option
+
+For technical reasons, options do **not** have a catch-all to map option names
+to files and sections and must be specifically mapped by the user. This requires
+a custom rules file. As the `evdev` ruleset is hardcoded in many clients, the
+custom rules file must usually be named `evdev`.
+
+```
+$ cat $XDG_CONFIG_HOME/xkb/rules/evdev
+! option = symbols
+  custom:foo    = +custom(bar)
+  custom:baz    = +other(baz)
+
+! include %S/evdev
+```
+
+This rules file maps the RMLVO option "custom:foo" to the "bar" section in the
+`symbols/custom` file and the "custom:baz" option to the "baz" section in the
+`symbols/other` file. Note how the RMLVO option name may be different to the
+file or section name.
+
+The `include` statement includes the system-provided `evdev` ruleset. This
+allows users to only override those options they need.
+
+The files themselves are similar to the layout examples in the previous section:
+
+```
+$ cat $XDG_CONFIG_HOME/xkb/symbols/custom
+// map the Tilde key to nothing on the first shift level
+partial alphanumeric_keys
+xkb_symbols "bar" {
+    key <TLDE> {        [      VoidSymbol ]       };
+};
+
+$ cat $XDG_CONFIG_HOME/xkb/symbols/other
+// map first key in bottom row (Z in the US layout) to k/K
+partial alphanumeric_keys
+xkb_symbols "baz" {
+    key <AB01> {        [      k, K ]       };
+};
+```
+
+With these in place, a user may select any layout/variant together with
+the "custom:foo" and/or "custom:baz" options.