Provided by: xkbsel_0.13-13.3ubuntu3_i386 bug

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