doc/introduction-to-xkb.md

   1 # Introduction to XKB {#xkb-intro}
   2
   3 __XKB__ stands for “X Keyboard Extension”. It may refer to either:
   4
   5 - a [protocol](@ref xkb-the-protocol)
   6 - a [keyboard layout configuration](@ref xkb-the-config)
   7 - a [text format](@ref xkb-the-text-format)
   8
   9 ## XKB the protocol {#xkb-the-protocol}
  10
  11 A __protocol__ for the [X Windows System], that extends the core protocol.
  12
  13 _xkbcommon’s_ API is somehow derived from this API, but has been
  14 substantially reworked to function as a library instead of a protocol,
  15 and exposes fewer internal details to clients.
  16
  17 _xkbcommon_ does not depend on a particular windows system; for instance
  18 it is used by the [Wayland] protocol.
  19
  20 _xkbcommon_ provides the <code>[xkbcommon-x11]</code> module to interface
  21 a client with an X server using the XKB protocol. Relevant links:
  22
  23 - [The X Window System Protocol][X Protocol]
  24 - [The X Keyboard Extension: Protocol Specification][XKB Protocol]
  25 - [xkbcommon-x11]
  26
  27
  28 ## XKB the keyboard keymap configuration {#xkb-the-config}
  29
  30 In order to use [the protocol](@ref xkb-the-protocol), one must first load a
  31 [complete keymap]. The keymap usually comes from the OS _layout database_,
  32 which is commonly [xkeyboard-config]. Since keymaps may have definitions in
  33 common, the database actually stores their basic components separately to allow
  34 maximum composability and coherence. A recipe to compose a keymap from its
  35 components is called a _keymap configuration_.
  36
  37 In XKB, there are several ways to define a keymap configuration. They all aim to
  38 produce a [complete keymap]. The following diagram presents an overview.
  39 Then they are presented hereinafter, ordered from end user to low-level
  40 implementation.
  41
  42 @dotfile xkb-configuration "XKB keymap configurations"
  43 <dl>
  44   <dt>
  45     RMLVO: <u>R</u>ules, <u>M</u>odel, <u>L</u>ayout, <u>V</u>ariant,
  46     <u>O</u>ptions @anchor RMLVO-intro
  47   </dt>
  48   <dd>
  49     This is the configuration the end user usually faces in the UI.
  50     The idea is to expose high level concepts such as [keyboard model] and
  51     [keyboard layout] to the user, then to _map_ them to the corresponding set
  52     of low-level configuration files (see [KcCGST]).
  53
  54     @note The RMLVO configurations actually available to the end user is managed
  55     by the `xkbregistry`. It uses an XML file, the _registry_, which exposes and
  56     documents the set of RMLVO settings in the layout database.
  57
  58     The RMLVO configuration consists of the following components:
  59
  60     <dl>
  61       <dt>Rules</dt>
  62       <dd>
  63       The rules define the _mapping_ from high to low level components.
  64       The rules _component_ is the file containing the set of rules to use.
  65       It is usually implicit and set by the system.
  66
  67       See the [rules file format](@ref rule-file-format) for further details.
  68       </dd>
  69       <dt>Model</dt>
  70       <dd>
  71       The name of the model of the keyboard hardware in use.
  72       It may depend on:
  73
  74       - The _location_ and _language_ of the user, because languages may
  75         require [specific keys][language input keys] for their input methods,
  76         such as the _muhenkan_ key on Japanese keyboard and the _Hanja_ key
  77         for Korean keyboards. The keyboard are usually classified by the
  78         [standard][keyboard standard] it is based on, e.g. ANSI, ISO, JIS,
  79         ABNT.
  80       - The keyboard _vendor:_ keyboard may have a set of keys that are not
  81         standard, or may be specific to an OS.
  82       </dd>
  83       <dt>Layout</dt>
  84       <dd>
  85       The identifier of the general layout to use. It usually refers to a
  86       country or a language.
  87       </dd>
  88       <dt>Variant</dt>
  89       <dd>
  90       Any minor variants on the general layout. It may be national variants
  91       </dd>
  92       <dt>Options</dt>
  93       <dd>
  94       Set of extra options to customize the standard layouts.
  95
  96       Examples: switch modifiers keys, location of the compose key, etc.
  97       </dd>
  98     </dl>
  99   </dd>
 100   <dt>
 101     KcCGST: <u>K</u>ey<u>c</u>odes, <u>C</u>ompat, <u>G</u>eometry,
 102     <u>S</u>ymbols, <u>T</u>ypes @anchor KcCGST-intro
 103   </dt>
 104   <dd>
 105     This is the low-level configuration of XKB and how the files are actually
 106     organized in the _layout database_.
 107     It is not really intuitive or straight-forward for the uninitiated.
 108
 109     @note _xkbcommon_ [does not offer an API for KcCGST](@ref KcCGST-support):
 110     it is considered an implementation detail.
 111     Instead, [RMLVO] is the preferred way for the user to configure XKB.
 112
 113     The KcCGST configuration consists of the following components:
 114
 115     <dl>
 116       <dt>Key codes</dt>
 117       <dd>
 118       A translation of the raw [key codes] from the keyboard into
 119       symbolic names.
 120       </dd>
 121       <dt>Compatibility</dt>
 122       <dd>
 123       A specification of what internal actions modifiers and various
 124       special-purpose keys produce.
 125       </dd>
 126       <dt>Geometry</dt>
 127       <dd>
 128       A description of the physical layout of a keyboard.
 129
 130       @attention This legacy feature is [not supported](@ref geometry-support)
 131       by _xkbcommon_.
 132       </dd>
 133       <dt>Key symbols</dt>
 134       <dd>
 135       A translation of symbolic key codes into actual [key symbols] (keysyms).
 136       </dd>
 137       <dt>Key types</dt>
 138       <dd>
 139       Types describe how a pressed key is affected by active [modifiers]
 140       such as Shift, Control, Alt, etc.
 141       </dd>
 142     </dl>
 143   </dd>
 144   <dt>Complete Keymap @anchor keymap-intro</dt>
 145   <dd>
 146   A complete keymap is a _self-contained_ text file with all the [KcCGST]
 147   components needed to configure a keyboard. This is the result of the
 148   _resolution_ of the [RMLVO] and [KcCGST] configurations. This is also the
 149   format used by X11 and Wayland when prompted to _serialize_ the keymap in use.
 150
 151   @note This is a low-level configuration. [RMLVO] is the preferred way for the
 152   end user to configure XKB, but some _power users_ may need it for _avanced_
 153   configurations.
 154
 155   See the [XKB text format] for further details.
 156   </dd>
 157 </dl>
 158
 159 @note Layout making use of dead keys require a [Compose](@ref compose) file. The
 160 same applies when if using a [Compose key].
 161
 162 [key codes]: @ref keycode-def
 163 [key symbols]: @ref keysym-def
 164 [levels]: @ref level-def
 165 [modifiers]: @ref modifier-def
 166 [RMLVO]: @ref RMLVO-intro
 167 [KcCGST]: @ref KcCGST-intro
 168 [complete keymap]: @ref keymap-intro
 169 [Compose key]: https://en.wikipedia.org/wiki/Compose_key
 170 [XKB text format]: @ref xkb-the-text-format
 171
 172
 173 ## XKB the text format {#xkb-the-text-format}
 174
 175 A __text format__ to define keyboard keymaps. XKB 1.0 is the specification
 176 implemented in current X servers. The format supported by _xkbcommon_
 177 is very close to XKB 1.0, with some removals and additions. See the
 178 [compatibility] page for further details.
 179
 180 The format supported by _xkbcommon_ is documented at the page
 181 “[The XKB keymap text format, V1][keymap-text-format-v1]”.
 182
 183 The documentation of the _original_ XKB 1.0 format is much more scarce than
 184 for the protocol. Some priceless resources are:
 185
 186 - [Ivan Pascal's XKB documentation][ivan-pascal]
 187 - [An Unreliable Guide to XKB Configuration][unreliable-guide]
 188 - [ArchWiki XKB page][arch-wiki]
 189
 190 [X Windows System]: https://en.wikipedia.org/wiki/X_Window_System
 191 [X Protocol]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#Keyboards
 192 [XKB Protocol]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html
 193 [xkbcommon-x11]: @ref x11-overview
 194 [Wayland]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard
 195 [compatibility]: @ref xkb-v1-compatibility
 196 [keymap-text-format-v1]: @ref keymap-text-format-v1
 197 [ivan-pascal]: https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/
 198 [unreliable-guide]: https://www.charvolant.org/doug/xkb/html/index.html
 199 [arch-wiki]: https://wiki.archlinux.org/index.php/X_keyboard_extension
 200 [keyboard model]: https://en.wikipedia.org/wiki/Computer_keyboard
 201 [keymap]: https://en.wikipedia.org/wiki/Keyboard_layout
 202 [keyboard layout]: https://en.wikipedia.org/wiki/Keyboard_layout
 203 [xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
 204 [keyboard standard]: https://en.wikipedia.org/wiki/Computer_keyboard#Types_and_standards
 205 [language input keys]: https://en.wikipedia.org/wiki/Language_input_keys
 206
 207 @todo Explain how to configure XKB, with examples