--- /dev/null
+# 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.
projects / platform / upstream / libxkbcommon.git / commitdiff