The XKB Configuration Guide

                              Abstract

     This document describes how to configure X11R7.2 XKB from a
   user's point of view. It covers basic configuration syntax and
                     gives also a few examples.
           _______________________________________________

   Table of Contents
   Overview
   Selecting XKB Configuration
   Direct XKB Configuration
   Keymap XKB Configuration

Overview

   The XKB configuration is decomposed into a number of
   components. Selecting proper parts and combining them back you
   can achieve most of the configurations you might need. Unless
   you have a completely atypical keyboard you really don't need
   to touch any of the xkb configuration files.
     __________________________________________________________

Selecting XKB Configuration

   The easiest and the most natural way to specify a keyboard
   mapping is to use the rules component. As its name suggests it
   describes a number of general rules to combine all bits and
   pieces into a valid and useful keyboard mapping. All you need
   to do is to select a suitable rules file and then to feed it
   with a few parameters that will adjust the keyboard behaviour
   to fulfill your needs.

   The parameters are:

     * XkbRules - files of rules to be used for keyboard mapping
       composition
     * XkbModel - name of the model of your keyboard type
     * XkbLayout - layout(s) you intend to use
     * XkbVariant - variant(s) of the layout you intend to use
     * XkbOptions - extra xkb configuration options

   The proper rules file depends on your vendor. In reality, the
   commonest file of rules is xorg. For each rules file there is a
   description file named <vendor-rules>.lst, for instance
   xorg.lst which is located in the xkb configuration subdirectory
   rules (for example /etc/X11/xkb/rules).
     __________________________________________________________

Basic Configuration

   Let's say you want to configure a PC-style American keyboard
   with 104 keys as described in xorg.lst. This can be done by
   simply writing several lines from below to your xorg.conf
   configuration file (previously known as /etc/X11/XF86Config-4
   or /etc/X11/XF86Config):
Section "InputDevice"
    Identifier "Keyboard1"
    Driver "kbd"

    Option "XkbModel" "pc104"
    Option "XkbLayout" "us"
    Option "XKbOptions" ""
EndSection

   The values of XkbModel and XkbLayout are really not surprising.
   The XkbOptions has been explicitly set to the empty set of
   parameters. The XkbVariant option has been left out. That means
   the default variant named basic is loaded.

   Of course, this can be also done at runtime using the utility
   setxkbmap. The shell command loading the same keyboard mapping
   would look like:
   setxkbmap -rules xorg -model pc104 -layout us -option ""

   The configuration and the shell command would be very analogous
   for most other layouts (internationalized mappings).
     __________________________________________________________

Advanced Configuration

   You can use multi-layouts xkb configuration. What does it mean?
   Basically it allows to load up to four different keyboard
   layouts at a time. Each such layout would reside in its own
   group. The groups (unlike complete keyboard remapping) can be
   switched very fast from one to another by a combination of
   keys.

   Let's say you want to configure your new Logitech cordless
   desktop keyboard, you intend to use three different layouts at
   the same time - us, czech and german (in this order), and that
   you are used to Alt-Shift combination for switching among them.

   Then the configuration snippet could look like this:
Section "InputDevice"
    Identifier "Keyboard1"
    Driver "kbd"

    Option "XkbModel" "logicordless"
    Option "XkbLayout" "us,cz,de"
    Option "XKbOptions" "grp:alt_shift_toggle"
EndSection

   Of course, this can be also done at runtime using the utility
   setxkbmap. The shell command loading the same keyboard mapping
   would look like:
setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
         -option "grp:alt_shift_toggle"
     __________________________________________________________

Even More Advanced Configuration

   Okay, let's say you are more demanding. You do like the example
   above but you want it to change a bit. Let's imagine you want
   the czech keyboard mapping to use another variant but basic.
   The configuration snippet then changes into:
Section "InputDevice"
    Identifier "Keyboard1"
    Driver "kbd"

    Option "XkbModel" "logicordless"
    Option "XkbLayout" "us,cz,de"
    Option "XkbVariant" ",bksl,"
    Option "XKbOptions" "grp:alt_shift_toggle"
EndSection

   That seems tricky but it is not. The logic for settings of
   variants is the same as for layouts, that means the first and
   the third variant settings are left out (set to basic), the
   second is set to bksl (a special variant with an enhanced
   definition of the backslash key).

   Analogously, the loading runtime will change to:
setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
         -variant ",bksl," -option "grp:alt_shift_toggle"
     __________________________________________________________

Basic Global Options

   See rules/*.lst files.
     __________________________________________________________

Direct XKB Configuration

   Generally, you can directly prescribe what configuration of
   each of basic xkb components should be used to form the
   resulting keyboard mapping. This method is rather "brute
   force". You precisely need to know the structure and the
   meaning of all of used configuration components.

   This method also exposes all xkb configuration details directly
   into xorg.conf configuration file which is a not very fortunate
   fact. In rare occasions it may be needed, though. So how does
   it work?
     __________________________________________________________

Basic Components

   There are five basic components used to form a keyboard
   mapping:

     * key codes - a translation of the scan codes produced by the
       keyboard into a suitable symbolic form
     * types - a specification of what various combinations of
       modifiers produce
     * key symbols - a translation of symbolic key codes into
       actual symbols
     * geometry - a description of physical keyboard geometry
     * compatibility maps - a specification of what action should
       each key produce in order to preserve compatibility with
       XKB-unware clients
     __________________________________________________________

Example Configuration

   Look at the following example:
Section "InputDevice"
    Identifier "Keyboard0"
    Driver "kbd"

    Option "XkbKeycodes" "xorg"
    Option "XkbTypes"    "default"
    Option "XkbSymbols"  "en_US(pc104)+de+swapcaps"
    Option "XkbGeometry" "pc(pc104)"
    Option "XkbCompat"   "basic+pc+iso9995"
EndSection

   This configuration sets the standard X server default
   interpretation of keyboard keycodes, and sets the default
   modifier types. The symbol table is composed of extended US
   keyboard layout in its variant for pc keyboards with 104 keys
   plus all keys for german layout are redefined respectively.
   Also the logical meaning of Caps-lock and Control keys is
   swapped. The standard keyboard geometry (physical look) is set
   to pc style keyboard with 104 keys. The compatibility map is
   set to allow basic shifting, to allow Alt keys to be
   interpreted and also to allow iso9995 group shifting.
     __________________________________________________________

Keymap XKB Configuration

   Keymap configuration is the way formerly used to configure xkb.
   The user included a special keymap file which specified the
   direct xkb configuration. This method has been obsoleted by
   previously described rules files which are far more flexible
   and allow simpler and more intuitive syntax. It is preserved
   merely for compatibility reasons and should be avoided if
   possible.
