From 5fb2c6769b7259ba647781bc800d6a46d90cf1a9 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 2 Jun 2020 16:18:47 +1000 Subject: [PATCH] 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 --- doc/user-configuration.md | 156 ++++++++++++++++++++++++++++++++++++++ meson.build | 1 + 2 files changed, 157 insertions(+) create mode 100644 doc/user-configuration.md 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` +- `/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 { [ exclam, 1] }; + key { [ at, 2] }; + key { [ numbersign, 3] }; + key { [ dollar, 4] }; + key { [ percent, 5] }; + key { [ asciicircum, 6] }; + key { [ ampersand, 7] }; + key { [ asterisk, 8] }; + key { [ parenleft, 9] }; + key { [ parenright, 0] }; + key { [ underscore, minus] }; + key { [ 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 { [ 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 { [ k, K ] }; +}; +``` + +With these in place, a user may select any layout/variant together with +the "custom:foo" and/or "custom:baz" options. diff --git a/meson.build b/meson.build index 2ea360d..388906a 100644 --- a/meson.build +++ b/meson.build @@ -543,6 +543,7 @@ You can disable the documentation with -Denable-docs=false.''') 'doc/doxygen-extra.css', 'doc/quick-guide.md', 'doc/compat.md', + 'doc/user-configuration.md', 'doc/rules-format.md', 'xkbcommon/xkbcommon.h', 'xkbcommon/xkbcommon-names.h',