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