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)

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

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"

};