<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
<!ENTITY % defs SYSTEM "X11/defs.ent"> %defs;
]>

<Article>

<articleinfo>

<Title>The XKB Configuration Guide</Title>
<AUTHOR
>
<FirstName>Kamil Toman, Ivan U. Pascal</FirstName>
</AUTHOR
>
<PubDate>25 November 2002
</PubDate>

<Abstract>

<Para>
This document describes how to configure X11R&relvers; XKB from a user's point
of view. It covers basic configuration syntax and gives also a few examples.
</Para>

</Abstract>

</articleinfo>

<Sect1>
<Title>Overview</Title>

<Para>
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.
</Para>

</Sect1>

<Sect1>
<Title>Selecting XKB Configuration</Title>

<Para>
The easiest and the most natural way to specify a keyboard mapping is to use
the <Literal remap="tt">rules</Literal> 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.
</Para>

<Para>
The parameters are:

<ItemizedList>
<ListItem>

<Para>
<Literal remap="tt">XkbRules </Literal>- files of rules to be used for keyboard mapping
composition
</Para>
</ListItem>
<ListItem>

<Para>
<Literal remap="tt">XkbModel </Literal>- name of the model of your keyboard type
</Para>
</ListItem>
<ListItem>

<Para>
<Literal remap="tt">XkbLayout </Literal>- layout(s) you intend to use
</Para>
</ListItem>
<ListItem>

<Para>
<Literal remap="tt">XkbVariant </Literal>- variant(s) of the layout you intend to use
</Para>
</ListItem>
<ListItem>

<Para>
<Literal remap="tt">XkbOptions </Literal>- extra xkb configuration options
</Para>
</ListItem>

</ItemizedList>

</Para>

<Para>
The proper rules file depends on your vendor. In reality, the commonest
file of rules is <Literal remap="tt">xorg</Literal>. For each rules file there is a description
file named <Literal remap="tt">&lt;vendor-rules&gt;.lst</Literal>, for instance <Literal remap="tt">xorg.lst</Literal>
which is located in the xkb configuration subdirectory <Literal remap="tt">rules</Literal>
(for example <Literal remap="tt">/etc/X11/xkb/rules</Literal>).
</Para>

<Sect2>
<Title>Basic Configuration</Title>

<Para>
Let's say you want to configure a PC-style American keyboard with 104
keys as described in <Literal remap="tt">xorg.lst</Literal>.  This can be done by simply writing
several lines from below to your xorg.conf configuration file (previously known
as <Literal remap="tt">/etc/X11/XF86Config-4</Literal> or <Literal remap="tt">/etc/X11/XF86Config</Literal>):

<Screen>
Section "InputDevice"
    Identifier "Keyboard1"
    Driver "kbd"

    Option "XkbModel" "pc104"
    Option "XkbLayout" "us"
    Option "XKbOptions" ""
EndSection
</Screen>

The values of <Literal remap="tt">XkbModel</Literal> and <Literal remap="tt">XkbLayout</Literal> are really
not surprising. The <Literal remap="tt">XkbOptions</Literal> has been explicitly set to
the empty set of parameters. The <Literal remap="tt">XkbVariant</Literal> option has been left out.
That means the default variant named <Literal remap="tt">basic</Literal> is loaded.
</Para>

<Para>
Of course, this can be also done at runtime using the utility setxkbmap.
The shell command loading the same keyboard mapping would look like:

<Screen>
setxkbmap -rules xorg -model pc104 -layout us -option ""
</Screen>

The configuration and the shell command would be very analogous
for most other layouts (internationalized mappings).
</Para>

</Sect2>

<Sect2>
<Title>Advanced Configuration</Title>

<Para>
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.
</Para>

<Para>
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 <Literal remap="tt">Alt-Shift</Literal> combination for switching among them.
</Para>

<Para>
Then the configuration snippet could look like this:

<Screen>
Section "InputDevice"
    Identifier "Keyboard1"
    Driver "kbd"

    Option "XkbModel" "logicordless"
    Option "XkbLayout" "us,cz,de"
    Option "XKbOptions" "grp:alt_shift_toggle"
EndSection
</Screen>

Of course, this can be also done at runtime using the utility setxkbmap.
The shell command loading the same keyboard mapping would look like:

<Screen>
setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
         -option "grp:alt_shift_toggle"
</Screen>

</Para>

</Sect2>

<Sect2>
<Title>Even More Advanced Configuration</Title>

<Para>
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:

<Screen>
Section "InputDevice"
    Identifier "Keyboard1"
    Driver "kbd"

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

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 <Literal remap="tt">basic</Literal>), the second is set to
<Literal remap="tt">bksl</Literal> (a special variant with an enhanced definition of the backslash
key).
</Para>

<Para>
Analogously, the loading runtime will change to:

<Screen>
setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
         -variant ",bksl," -option "grp:alt_shift_toggle"
</Screen>

</Para>

</Sect2>

<Sect2>
<Title>Basic Global Options</Title>

<Para>
See rules/*.lst files.
</Para>

<!--
  TODO: More detailed descriptions of options. Users often get confused.
-->

</Sect2>

</Sect1>

<Sect1>
<Title>Direct XKB Configuration</Title>

<Para>
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.
</Para>

<Para>
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?
</Para>

<Sect2>
<Title>Basic Components</Title>

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

<ItemizedList>
<ListItem>

<Para>
<Emphasis>key codes</Emphasis> - a translation of the scan codes produced by the
keyboard into a suitable symbolic form

</Para>
</ListItem>
<ListItem>

<Para>
<Emphasis>types</Emphasis> - a specification of what various combinations of
modifiers produce

</Para>
</ListItem>
<ListItem>

<Para>
<Emphasis>key symbols</Emphasis> - a translation of symbolic key codes into actual
symbols

</Para>
</ListItem>
<ListItem>

<Para>
<Emphasis>geometry</Emphasis> - a description of physical keyboard geometry

</Para>
</ListItem>
<ListItem>

<Para>
<Emphasis>compatibility maps</Emphasis> - a specification of what action should
each key produce in order to preserve compatibility with XKB-unware clients
</Para>
</ListItem>

</ItemizedList>

</Para>

</Sect2>

<Sect2>
<Title>Example Configuration</Title>

<Para>
Look at the following example:

<Screen>
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
</Screen>

</Para>

<Para>
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 <Literal remap="tt">Caps-lock</Literal> and <Literal remap="tt">Control</Literal> 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.
</Para>

<!--
    TODO: add information about layout shifting:
    TODO: us+ru(winkeys):2+de:3
-->

</Sect2>

</Sect1>

<Sect1>
<Title>Keymap XKB Configuration</Title>

<Para>
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.
</Para>

</Sect1>

</Article>