doc/user-configuration.md

   1 # User-configuration
   2
   3 This page describes how to add a custom layout or option so that it will be
   4 parsed by libxkbcommon.
   5
   6 **The below requires libxkbcommon as keymap compiler and does not work in X**.
   7
   8 ## Data locations
   9
  10 libxkbcommon searches the following paths for XKB configuration files:
  11 - `$XDG_CONFIG_HOME/xkb/`, or `$HOME/.config/xkb/` if the `$XDG_CONFIG_HOME`
  12   environment variable is not defined
  13 - `$HOME/.xkb/`
  14 - `$XKB_CONFIG_ROOT`
  15 - `<datadir>/X11/xkb/` (path defined by the `xkeyboard-config` package, on most
  16   distributions this is `/usr/share/X11/xkb`)
  17
  18 A keymap created with `xkb_keymap_new_from_names()` will look up those paths in
  19 order until the required data is found.
  20
  21 **Note: Where libxkbcommon runs in a privileged context, only the system
  22 (datadir) path is available.**
  23
  24 Each directory should have one or more of the following subdirectories:
  25 - `compat`
  26 - `geometry` (libxkbcommon ignores this directory)
  27 - `keycodes`
  28 - `rules`
  29 - `symbols`
  30 - `types`
  31
  32 ## RMLVO vs KcCGST
  33
  34 Due to how XKB is configured, there is no such thing as a "layout" in XKB
  35 itself, or, indeed, any of the rules, models, variant, options (RMLVO) decribed
  36 in `struct xkb_rule_names`. RMLVO names are merely lookup keys in the
  37 rules file provided by xkeyboard-config to map to the correct keycode, compat,
  38 geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data
  39 is the one used by XKB and libxbkcommon to map keys to actual symbols.
  40
  41 For example, a common RMLVO configuration is layout "us", variant "dvorak" and
  42 option "terminate:ctrl_alt_bksp". Using the default rules file and model
  43 this maps into the following KcCGST components:
  44
  45 ```
  46 xkb_keymap {
  47         xkb_keycodes  { include "evdev+aliases(qwerty)" };
  48         xkb_types     { include "complete"      };
  49         xkb_compat    { include "complete"      };
  50         xkb_symbols   { include "pc+us(dvorak)+inet(evdev)+terminate(ctrl_alt_bksp)"    };
  51         xkb_geometry  { include "pc(pc105)"     };
  52 };
  53 ```
  54
  55 A detailed explanation of how rules files convert RMLVO to KcCGST is out of
  56 scope for this document. See [the rules file](md_doc_rules-format.html) page
  57 instead.
  58
  59
  60 ## Adding a layout
  61
  62 Adding a layout requires that the user adds **symbols** in the correct location.
  63
  64 The default rules files (usually `evdev`) have a catch-all to map a layout, say
  65 "foo", and a variant, say "bar", into the "bar" section in the file
  66 `$xkb_base_dir/symbols/foo`.
  67 This is sufficient to define a new keyboard layout. The example below defines
  68 the keyboard layout "banana" with an optional variant "orange"
  69
  70 ```
  71 $ cat $XDG_CONFIG_HOME/xkb/symbols/banana
  72 // Like a US layout but swap the top row so numbers are on Shift
  73 default partial alphanumeric_keys
  74 xkb_symbols "basic" {
  75     include "us(basic)"
  76     name[Group1]= "Banana (US)";
  77
  78     key <AE01> { [ exclam,          1]     };
  79     key <AE02> { [ at,              2]     };
  80     key <AE03> { [ numbersign,      3]     };
  81     key <AE04> { [ dollar,          4]     };
  82     key <AE05> { [ percent,         5]     };
  83     key <AE06> { [ asciicircum,     6]     };
  84     key <AE07> { [ ampersand,       7]     };
  85     key <AE08> { [ asterisk,        8]     };
  86     key <AE09> { [ parenleft,       9]     };
  87     key <AE10> { [ parenright,      0]     };
  88     key <AE11> { [ underscore,      minus] };
  89     key <AE12> { [ plus,            equal] };
  90 };
  91
  92 // Same as banana but map the euro sign to the 5 key
  93 partial alphanumeric_keys
  94 xkb_symbols "orange" {
  95     include "banana(basic)"
  96     name[Group1] = "Banana (Eurosign on 5)";
  97     include "eurosign(5)"
  98 };
  99 ```
 100
 101 The `default` section is loaded when no variant is given. The first example
 102 sections uses ``include`` to populate with a symbols list defined elsewhere
 103 (here: section `basic` from the file `symbols/us`, aka. the default US keyboard
 104 layout) and overrides parts of these
 105 symbols. The effect of this section is to swap the numbers and symbols in the
 106 top-most row (compared to the US layout) but otherwise use the US layout.
 107
 108 The "orange" variant uses the "banana" symbols and includes a different section
 109 to define the eurosign. It does not specificially override any symbols.
 110
 111 The exact details of how `xkb_symbols` work is out of scope for this document.
 112
 113 ## Adding an option
 114
 115 For technical reasons, options do **not** have a catch-all to map option names
 116 to files and sections and must be specifically mapped by the user. This requires
 117 a custom rules file. As the `evdev` ruleset is hardcoded in many clients, the
 118 custom rules file must usually be named `evdev`.
 119
 120 ```
 121 $ cat $XDG_CONFIG_HOME/xkb/rules/evdev
 122 ! option = symbols
 123   custom:foo    = +custom(bar)
 124   custom:baz    = +other(baz)
 125
 126 ! include %S/evdev
 127 ```
 128
 129 This rules file maps the RMLVO option "custom:foo" to the "bar" section in the
 130 `symbols/custom` file and the "custom:baz" option to the "baz" section in the
 131 `symbols/other` file. Note how the RMLVO option name may be different to the
 132 file or section name.
 133
 134 The `include` statement includes the system-provided `evdev` ruleset. This
 135 allows users to only override those options they need.
 136
 137 The files themselves are similar to the layout examples in the previous section:
 138
 139 ```
 140 $ cat $XDG_CONFIG_HOME/xkb/symbols/custom
 141 // map the Tilde key to nothing on the first shift level
 142 partial alphanumeric_keys
 143 xkb_symbols "bar" {
 144     key <TLDE> {        [      VoidSymbol ]       };
 145 };
 146
 147 $ cat $XDG_CONFIG_HOME/xkb/symbols/other
 148 // map first key in bottom row (Z in the US layout) to k/K
 149 partial alphanumeric_keys
 150 xkb_symbols "baz" {
 151     key <AB01> {        [      k, K ]       };
 152 };
 153 ```
 154
 155 With these in place, a user may select any layout/variant together with
 156 the "custom:foo" and/or "custom:baz" options.