git.oblomov.eu Git - xorg/xkeyboard-config/blob - docs/README.config

   1                          The XKB Configuration Guide
   2
   3                          Kamil Toman, Ivan U. Pascal
   4
   5                               25 November 2002
   6
   7                                   Abstract
   8
   9      This document describes how to configure XFree86 XKB from a user's
  10      point a few. It converts basic configuration syntax and gives also
  11      a few examples.
  12
  13 1.  Overview
  14
  15 The XKB configuration is decomposed into a number of components. Selecting
  16 proper parts and combining them back you can achieve most of configurations
  17 you might need. Unless you have a completely atypical keyboard you really
  18 don't need to touch any of xkb configuration files.
  19
  20 2.  Selecting XKB Configuration
  21
  22 The easiest and the most natural way how to specify a keyboard mapping is to
  23 use rules component. As its name suggests it describes a number of general
  24 rules how to combine all bits and pieces into a valid and useful keyboard
  25 mapping. All you need to do is to select a suitable rules file and then to
  26 feed it with a few parameters that will adjust the keyboard behaviour to ful-
  27 fill your needs.
  28
  29 The parameters are:
  30
  31    o XkbRules - files of rules to be used for keyboard mapping composition
  32
  33    o XkbModel - name of model of your keyboard type
  34
  35    o XkbLayout - layout(s) you intend to use
  36
  37    o XkbVariant - variant(s) of layout you intend to use
  38
  39    o XkbOptions - extra xkb configuration options
  40
  41 The proper rules file depends on your vendor. In reality, the commonest file
  42 of rules is xfree86. For each rules file there is a description file named
  43 <vendor-rules>.lst, for instance xfree86.lst which is located in xkb configu-
  44 ration subdirectory rules (for example /etc/X11/xkb/rules).
  45
  46 2.1  Basic Configuration
  47
  48 Let's say you want to configure a PC style America keyboard with 104 keys as
  49 described in xfree86.lst. It can be done by simply writing several lines from
  50 below to you XFree86 configuration file (often found as /etc/X11/XF86Config-4
  51 or /etc/X11/XF86Config):
  52
  53      Section "InputDevice"
  54          Identifier "Keyboard1"
  55          Driver "Keyboard"
  56
  57          Option "XkbModel" "pc104"
  58          Option "XkbLayout" "us"
  59          Option "XKbOptions" ""
  60      EndSection
  61
  62 The values of parameters XkbModel and XkbLayout are really not surprising.
  63 The parameters XkbOptions has been explicitly set to empty set of parameters.
  64 The parameter XkbVariant has been left out.  That means the default variant
  65 named basic is loaded.
  66
  67 Of course, this can be also done at runtime using utility setxkbmap.  Shell
  68 command loading the same keyboard mapping would look like:
  69
  70      setxkbmap -rules xfree86 -model pc104 -layout us -option ""
  71
  72 The configuration and the shell command would be very analogical for most
  73 other layouts (internationalized mappings).
  74
  75 2.2  Advanced Configuration
  76
  77 Since XFree86 4.3.x you can use multi-layouts xkb configuration.  What does
  78 it mean? Basically it allows to load up to four different keyboard layouts at
  79 a time. Each such layout would reside in its own group. The groups (unlike
  80 complete keyboard remapping) can be switched very fast from one to another by
  81 a combination of keys.
  82
  83 Let's say you want to configure your new Logitech cordless desktop keyboard,
  84 you intend to use three different layouts at the same time - us, czech and
  85 german (in this order), and that you are used to Alt-Shift combination for
  86 switching among them.
  87
  88 Then the configuration snippet could look like this:
  89
  90      Section "InputDevice"
  91          Identifier "Keyboard1"
  92          Driver "Keyboard"
  93
  94          Option "XkbModel" "logicordless"
  95          Option "XkbLayout" "us,cz,de"
  96          Option "XKbOptions" "grp:alt_shift_toggle"
  97      EndSection
  98
  99 Of course, this can be also done at runtime using utility setxkbmap.  Shell
 100 command loading the same keyboard mapping would look like:
 101
 102      setxkbmap -rules xfree86 -model logicordless -layout "us,cz,de" \
 103               -option "grp:alt_shift_toggle"
 104
 105 2.3  Even More Advanced Configuration
 106
 107 Okay, let's say you are more demanding. You do like the example above but you
 108 want it to change a bit. Let's imagine you want the czech keyboard mapping to
 109 use another variant but basic.  The configuration snippet then changes into:
 110
 111      Section "InputDevice"
 112          Identifier "Keyboard1"
 113          Driver "Keyboard"
 114
 115          Option "XkbModel" "logicordless"
 116          Option "XkbLayout" "us,cz,de"
 117          Option "XkbVariant" ",bksl,"
 118          Option "XKbOptions" "grp:alt_shift_toggle"
 119      EndSection
 120
 121 That's seems tricky but it is not. The logic for settings of variants is the
 122 same as for layouts, that means the first and the third variant settings are
 123 left out (set to basic), the second is set to bksl (a special variant with an
 124 enhanced definition of the backslash key).
 125
 126 Analogically, the loading runtime will change to:
 127
 128      setxkmap -rules xfree86 -model logicordless -layout "us,cz,de" \
 129               -variant ",bksl," -option "grp:alt_shift_toggle"
 130
 131 2.4  Basic Global Options
 132
 133 See rules/*.lst files.
 134
 135 3.  Direct XKB Configuration
 136
 137 Generally, you can directly prescribe what configuration of each of basic xkb
 138 components should be used to form the resulting keyboard mapping.  This
 139 method is rather "brute force". You precisely need to know the structure and
 140 the meaning of all of used configuration components.
 141
 142 This method also exposes all xkb configuration details directly into XFree86
 143 configuration file which is a not very fortunate fact.  In rare occasions it
 144 may be needed, though. So how does it work?
 145
 146 3.1  Basic Components
 147
 148 There are five basic components used to form a keyboard mapping:
 149
 150    o key codes - a translation of the scan codes produced by the keyboard
 151      into a suitable symbolic form
 152
 153    o types - a specification of what various combinations of modifiers pro-
 154      duce
 155
 156    o key symbols - a translation of symbolic key codes into actual symbols
 157
 158    o geometry - a description of physical keyboard geometry
 159
 160    o compatibility maps - a specification of what action should each key pro-
 161      duce in order to preserve compatibility with XKB-unware clients
 162
 163 3.2  Example Configuration
 164
 165 Look at the following example:
 166
 167      Section "InputDevice"
 168          Identifier "Keyboard0"
 169          Driver "Keyboard"
 170
 171          Option "XkbKeycodes" "xfree86"
 172          Option "XkbTypes"    "default"
 173          Option "XkbSymbols"  "en_US(pc104)+de+swapcaps"
 174          Option "XkbGeometry" "pc(pc104)"
 175          Option "XkbCompat"   "basic+pc+iso9995"
 176      EndSection
 177
 178 This configuration sets the standard XFree86 default interpretation of key-
 179 board keycodes, sets the default modificator types. The symbol table is com-
 180 posed of extended US keyboard layout in its variant for pc keyboards with 104
 181 keys plus all keys for german layout are redefined respectively. Also the
 182 logical meaning of Caps-lock and Control keys is swapped.  The standard key-
 183 board geometry (physical look) is set to pc style keyboard with 104 keys. The
 184 compatibility map is set to allow basic shifting, to allow Alt keys to be
 185 interpreted and also to allow iso9995 group shifting.
 186
 187 4.  Keymap XKB Configuration
 188
 189 It is the formerly used way to configure xkb. The user included a special
 190 keymap file which specified the direct xkb configuration. This method has
 191 been obsoleted by previously described rules files which are far more flexi-
 192 ble and allow simpler and more intuitive syntax. It is preserved merely for
 193 compatibility reasons. Avoid using it if it is possible.
 194
 195      Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/XKB-Config.sgml,v 1.4 dawes Exp $