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_EXTRA_PATH` if set, otherswise `<sysconfdir>/xkb` (on most
  15   distributions this is `/etc/xkb`)
  16 - `$XKB_CONFIG_ROOT` if set, otherwise `<datadir>/X11/xkb/` (path defined by the
  17   `xkeyboard-config` package, on most distributions this is
  18   `/usr/share/X11/xkb`)
  19
  20 A keymap created with `xkb_keymap_new_from_names()` will look up those paths in
  21 order until the required data is found.
  22
  23 **Note: Where libxkbcommon runs in a privileged context, only the system
  24 (datadir) path is available.**
  25
  26 Each directory should have one or more of the following subdirectories:
  27 - `compat`
  28 - `geometry` (libxkbcommon ignores this directory)
  29 - `keycodes`
  30 - `rules`
  31 - `symbols`
  32 - `types`
  33
  34 ## RMLVO vs KcCGST
  35
  36 Due to how XKB is configured, there is no such thing as a "layout" in XKB
  37 itself, or, indeed, any of the rules, models, variant, options (RMLVO) decribed
  38 in `struct xkb_rule_names`. RMLVO names are merely lookup keys in the
  39 rules file provided by xkeyboard-config to map to the correct keycode, compat,
  40 geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data
  41 is the one used by XKB and libxbkcommon to map keys to actual symbols.
  42
  43 For example, a common RMLVO configuration is layout "us", variant "dvorak" and
  44 option "terminate:ctrl_alt_bksp". Using the default rules file and model
  45 this maps into the following KcCGST components:
  46
  47 ```
  48 xkb_keymap {
  49         xkb_keycodes  { include "evdev+aliases(qwerty)" };
  50         xkb_types     { include "complete"      };
  51         xkb_compat    { include "complete"      };
  52         xkb_symbols   { include "pc+us(dvorak)+inet(evdev)+terminate(ctrl_alt_bksp)"    };
  53         xkb_geometry  { include "pc(pc105)"     };
  54 };
  55 ```
  56
  57 A detailed explanation of how rules files convert RMLVO to KcCGST is out of
  58 scope for this document. See [the rules file](md_doc_rules-format.html) page
  59 instead.
  60
  61
  62 ## Adding a layout
  63
  64 Adding a layout requires that the user adds **symbols** in the correct location.
  65
  66 The default rules files (usually `evdev`) have a catch-all to map a layout, say
  67 "foo", and a variant, say "bar", into the "bar" section in the file
  68 `$xkb_base_dir/symbols/foo`.
  69 This is sufficient to define a new keyboard layout. The example below defines
  70 the keyboard layout "banana" with an optional variant "orange"
  71
  72 ```
  73 $ cat $XDG_CONFIG_HOME/xkb/symbols/banana
  74 // Like a US layout but swap the top row so numbers are on Shift
  75 default partial alphanumeric_keys
  76 xkb_symbols "basic" {
  77     include "us(basic)"
  78     name[Group1]= "Banana (US)";
  79
  80     key <AE01> { [ exclam,          1]     };
  81     key <AE02> { [ at,              2]     };
  82     key <AE03> { [ numbersign,      3]     };
  83     key <AE04> { [ dollar,          4]     };
  84     key <AE05> { [ percent,         5]     };
  85     key <AE06> { [ asciicircum,     6]     };
  86     key <AE07> { [ ampersand,       7]     };
  87     key <AE08> { [ asterisk,        8]     };
  88     key <AE09> { [ parenleft,       9]     };
  89     key <AE10> { [ parenright,      0]     };
  90     key <AE11> { [ underscore,      minus] };
  91     key <AE12> { [ plus,            equal] };
  92 };
  93
  94 // Same as banana but map the euro sign to the 5 key
  95 partial alphanumeric_keys
  96 xkb_symbols "orange" {
  97     include "banana(basic)"
  98     name[Group1] = "Banana (Eurosign on 5)";
  99     include "eurosign(5)"
 100 };
 101 ```
 102
 103 The `default` section is loaded when no variant is given. The first example
 104 sections uses ``include`` to populate with a symbols list defined elsewhere
 105 (here: section `basic` from the file `symbols/us`, aka. the default US keyboard
 106 layout) and overrides parts of these
 107 symbols. The effect of this section is to swap the numbers and symbols in the
 108 top-most row (compared to the US layout) but otherwise use the US layout.
 109
 110 The "orange" variant uses the "banana" symbols and includes a different section
 111 to define the eurosign. It does not specificially override any symbols.
 112
 113 The exact details of how `xkb_symbols` work is out of scope for this document.
 114
 115 ## Adding an option
 116
 117 For technical reasons, options do **not** have a catch-all to map option names
 118 to files and sections and must be specifically mapped by the user. This requires
 119 a custom rules file. As the `evdev` ruleset is hardcoded in many clients, the
 120 custom rules file must usually be named `evdev`.
 121
 122 ```
 123 $ cat $XDG_CONFIG_HOME/xkb/rules/evdev
 124 ! option = symbols
 125   custom:foo    = +custom(bar)
 126   custom:baz    = +other(baz)
 127
 128 ! include %S/evdev
 129 ```
 130
 131 This rules file maps the RMLVO option "custom:foo" to the "bar" section in the
 132 `symbols/custom` file and the "custom:baz" option to the "baz" section in the
 133 `symbols/other` file. Note how the RMLVO option name may be different to the
 134 file or section name.
 135
 136 The `include` statement includes the system-provided `evdev` ruleset. This
 137 allows users to only override those options they need.
 138
 139 The files themselves are similar to the layout examples in the previous section:
 140
 141 ```
 142 $ cat $XDG_CONFIG_HOME/xkb/symbols/custom
 143 // map the Tilde key to nothing on the first shift level
 144 partial alphanumeric_keys
 145 xkb_symbols "bar" {
 146     key <TLDE> {        [      VoidSymbol ]       };
 147 };
 148
 149 $ cat $XDG_CONFIG_HOME/xkb/symbols/other
 150 // map first key in bottom row (Z in the US layout) to k/K
 151 partial alphanumeric_keys
 152 xkb_symbols "baz" {
 153     key <AB01> {        [      k, K ]       };
 154 };
 155 ```
 156
 157 With these in place, a user may select any layout/variant together with
 158 the "custom:foo" and/or "custom:baz" options.
 159
 160 ## Discoverable layouts
 161
 162 **The below requires libxkbregistry as XKB lookup tool and does not work where
 163 clients parse the XML file directly**.
 164
 165 The above sections apply only to the data files and require that the user knows
 166 about the existence of the new entries. To make custom entries discoverable by
 167 the configuration tools (e.g. the GNOME Control Center), the new entries must
 168 also be added to the XML file that is parsed by libxkbregistry. In most cases,
 169 this is the `evdev.xml` file in the rules directory. The example below shows the
 170 XML file that would add the custom layout and custom options as outlined above
 171 to the XKB registry:
 172
 173 ```
 174 $ cat $XDG_CONFIG_HOME/xkb/rules/evdev.xml
 175 <?xml version="1.0" encoding="UTF-8"?>
 176 <!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
 177 <xkbConfigRegistry version="1.1">
 178   <layoutList>
 179     <layout>
 180       <configItem>
 181         <name>banana</name>
 182         <shortDescription>ban</shortDescription>
 183         <description>Banana</description>
 184       </configItem>
 185       <variantList>
 186         <variant>
 187           <configItem>
 188             <name>orange</name>
 189             <shortDescription>or</shortDescription>
 190             <description>Orange (Banana)</description>
 191           </variant>
 192       </variantList>
 193   </layoutList>
 194   <optionList>
 195     <group allowMultipleSelection="true">
 196       <configItem>
 197         <name>custom</name>
 198         <description>Custom options</description>
 199       </configItem>
 200       <option>
 201       <configItem>
 202         <name>custom:foo</name>
 203         <description>Map Tilde to nothing</description>
 204       </configItem>
 205       </option>
 206       <option>
 207       <configItem>
 208         <name>custom:baz</name>
 209         <description>Map Z to K</description>
 210       </configItem>
 211       </option>
 212     </group>
 213   </optionList>
 214 </xkbConfigRegistry>
 215 ```
 216
 217 The default behavior of libxkbregistry ensures that the new layout and options
 218 are added to the system-provided layouts and options.
 219
 220 For details on the XML format, see DTD in `<datadir>/X11/xkb/rules/xkb.dtd`
 221 and the system-provided XML files in `<datadir>/X11/xkb/rulies/xkb.dtd`.