XKBSEL(5)

📦 version 0.13, in arch rolling

💅 NAME 💅

okay so this is the manual for xkbsel — the XKB keyboard selection tool files. yes bestie, it's a manual page (section 5, iykyk) and it's all about the files 💖

✨ DESCRIPTION ✨

so xkbsel is basically a whole framework for defining, selecting and indicating XKB keyboard mappings. it lets you attach extra data to the XKB source files, and it lets you select — per-system and per-user — the subset of the mappings that actually gets shown to the user in a GUI or command-line interface. iconic behavior honestly 👑

this manual page describes two things: the syntax of the configuration files, and the extensions of the XKB syntax used for attaching that additional data. slay.

🎀 CONFIGURATION FILES 🎀

the configuration files are named xkbsel.conf and they contain configuration entries divided into sections. section names get 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

okay so the rules for names, bestie, pay attention: the section names, entry names, qualifiers and unquoted values all start with a letter, slash or underscore. the remaining characters can include numbers and parentheses. anything other in the value part must be quoted (and ngl 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. fr fr, don't reorder them.

if the user configuration file exists, it's used as a whole — no merging with the system configuration file occurs. like, none. zero. the user file ate and left no crumbs.

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's also a possibility to define lists according to the language part of the locale definition (in small letters), the territory part (in caps) and/or a default list for 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 🔥

okay so this whole section assumes you already know how to create an XKB keyboard mapping. this part only explains how to add the xkbsel data to the new mappings, and to the mappings already present in the X distribution. no gatekeeping, just facts 💜

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. that's the starting point where the package searches for the mappings and passes them for compilation and installation to the xkbcomp(1). periodt.

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. like, it literally doesn't know they exist 💀

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 necessarily display all selected map descriptions correctly 🫶 (just a little heads up, not a vibe killer)

it's possible to add these data into existing mappings too. and since it's practical to do this only in several files instead of matching redefinition files to keymap files, there's a possibility to define the 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>

and that's the whole thing, bestie! go forth and keyboard-map your heart out 🎀 this was xkbsel, from the XKBSEL(5) manual, dated 23 Jul 1999 — yeah she's vintage and she still serves 💖✨

📦 where this page comes from