XKBSEL(5)

NAME
xkbsel - XKB keyboard selection tool files

DESCRIPTION
xkbsel is a framework for defining, selecting and indicating XKB keyboard mappings. It allows to attach additional data to the XKB source files and to select (per-system and per-user) the subset of the mappings presented to the user in a GUI or command-line interface.

This manual page describes the syntax of the configuration files and the extensions of the XKB syntax used for attaching the additional data.

CONFIGURATION FILES
The configuration files are named xkbsel.conf and contain configuration entries divided into sections. Section names are enclosed in square brackets and the entries can be qualified by an optional qualifier. An entry can have zero or more values:

    # comment
    // comment
    [section]
    entry1 = value
    entry2[qualif] = val1 "special-val2" val3

The section names, entry names, qualifiers and unquoted values start with letter, slash or underscore; the remaining characters can include numbers and parentheses. Anything other in the value part must be quoted (there is no possibility yet to get the double quotes in the value itself). The files are generally case-sensitive and the ordering of the sections matters.

If the user configuration file exist, it is used as a whole - no merging with system configuration file occurs.

Presently there are two sections:

  shortcut
Shortcuts define a mapping between short names used for convenient naming of maps in command-line and GUI tools and full XKB keymap names. The XKB keymap name consists of a relative path to a file (often there is no directory part) and a name of a map in this particular file in parentheses.

An example of a shortcut section defining american, german and french keyboards (from the X11 distribution) and slovak one (from the xkbsel distribution) is:

    [shortcut]
    us = xfree86(us)
    de = xfree86(de)
    fr = xfree86(fr)
    sk = czsk(sk)

  mapset
The shortcuts defined in the previous section are used to build an ordered selection list, used by GUI selectors to present a menu of choices to the user. There is a possibility to define lists according to language part of the locale definition (in small letters), territory part (in caps) and/or a default list when no specific list matches. An example:

    [mapset]
    map[sk] = sk us
    map[de] = de us
    map[fr] = fr us
    map = us sk de fr

  ADDITIONAL XKB DATA
It is assumed you know how to create a XKB keyboard mapping. This section only explains how to add the xkbsel data to the new mappings and to the mappings already present in the X distribution.

The xkbsel package mirrors the XKB directory structure (normally residing in /usr/X11R6/lib/X11/xkb) in the xkbsel's system directory (normally /usr/share/xkbsel) and eventually user's directory (~/.xkbsel).

The only directory from the original XKB structure that matters for xkbsel is the keymap subdirectory. This is the starting point where the package searches for the mappings and passes them for compilation and installation to the xkbcomp(1).

xkbsel adds another two directories to the hierarchy. redef contains files that add additional xkbsel data to the mappings already defined, without needing to change the mappings themselves in any way. pixmap contains small icons that can be referenced by the GUI tools (this is not yet implemented).

When there are conflicting data, the priority from the highest to lowest is:
    1. redef directory in the user hierarchy
    2. files from the user hierarchy
    3. redef directory in the xkbsel hierarchy
    4. files from the xkbsel hierarchy
    5. original X11 distribution
The files from the user's directories other than keymap or redef (e.g. symbols) are only used when the mapping itself is mentioned in some file in these two directories - otherwise the xkbsel does not know about them.

The data for xkbsel is added to the XKB files using specially formatted comments in the scope of the particular keymap definition. The format of the comment is
    %xkb_keyword% "value"
Presently there are two such data entries:

description
    defines a description of the keyboard mapping in the GUI tools

pixmap
    defines a pixmap for the GUI tools (not yet implemented)

An example of such keymap definition is:
    xkb_keymap "sk" {
        // %xkb_description% "Slovenska klavesnica"
        // %xkb_pixmap% "slovak.xpm"
        xkb_keycodes { include "xfree86" };
        xkb_types { include "default" };
        xkb_compatibility { include "default" };
        xkb_symbols { include "czsk_ibm(sk)" };
        xkb_geometry { include "pc" };
    };
The descriptions can use characters in a local character encoding, but remember that a GUI tool runs in a specific locale and won't neccessarily display all selected map descriptions correctly.

It is possible to add these data into existing mappings. As it is practical to do this only in several files instead of matching redefinition files to keymap files, there is a possibility to define file name for the following definitions. This works only for files in redef directories and is specified as
    %xkb_file% "value"
outside of keymap definitions. So you can do something like this:
    // %xkb_file% "xfree86"
    xkb_keymap "us"
    {
      // %xkb_description% "US layout"
      // %xkb_pixmap% "us.xpm"
    };
    // %xkb_file% "sun/xfree86"
    xkb_keymap "type4_us"
    {
      // %xkb_description% "US layout for Sun"
      // %xkb_pixmap% "us.xpm"
    };

FILES

/usr/X11R6/lib/X11/xkb
    XKB hierarchy of the X11 distribution

/usr/share/xkbsel
    system data directory

/etc/xkbsel.conf
    system configuration file

~/.xkbsel
    user data directory

~/.xkbsel/xkbsel.conf
    user's configuration file

SEE ALSO
xkbseldb(1), xkbsel(1), xkbsel-aw(1), xkbsel(5)

AUTHOR
Stanislav Meduna <stano@trillian.eunet.sk>