Created by: gwideman, Jun 7, 2013 5:36 pm
Revised by: gwideman, Jun 13, 2013 5:33 pm (28 revisions)

Overview

This page captures some notes regarding configuration of keyboard and keyboard layout, using the xkb apparatus, which is part of XOrg, X11 apparatus. This is for Mint 15 Cinnamon.
Note:
  • Mint 15 is based on Ubuntu 13.04 (Raring Ringtail), which in turn is based on Debian code freeze of some date before 2013.04.
  • Cinnamon desktop manager is based on Muffin, a fork of GNOME 3 Mutter.
So, configuration details for Mint 15 Cinnamon may or may not be derived from the way things are done in these upstream projects.
At the same time, there is a huge body of documentation about how to configure linux keyboards that doesn't apply, because it's obsolete, or applies to some other linux variant.
So, in this doc I've recorded notes that I believe apply to the xkb apparatus as it now stands, and the GUI configuration tool for keyboard layout and behavior variations.

Principles

  • System-wide default rule-input XKB variables set in /etc/default/keyboard
    • Doc here: http://wiki.debian.org/Keyboard, though "# Consult the keyboard(5) manual page." is a red herring.
    • Variables: XKBMODEL, XKBLAYOUT, XKBVARIANT, XKBOPTIONS
      • These do not appear to become environment variables for user sessions.
    • /etc/default/keyboard takes effect after reboot. Not sure about after logout-login.
  • XKB data is defined at /usr/share/X11/xkb/ ...
    • keycodes
    • keymap (obsolete)
    • rules
      • rules test the input variables, and if enabled, invoke other things defined in the other files.
      • rules files have a "source" version (no extension), a lst version, and an xml version. I assume the lst and xml versions are compiled from the source version. Tool? xkbcomp?
    • compat
    • symbols
    • types
    • semantics (obsolete, I think)
    • geometry
    • Could use an E-R diagram of these data sets. Ah, see the xkb library doc!
  • By default setxkbmap gets invoked at startup
    • rules/evdev gets applied to the /etc/default/keyboard rule input values to...
    • invoke other sections defined in the other xkb files, to...
    • construct a "keymap" file,
      • stored at /var/lib/xkb, and...
      • sent to the (which, if several) X11 client and server
    • This map controls how
      • the X server interprets shift and modifier keys to change shift and group state
      • the X client library's translation functions translate (raw) keycodes and keyboard state into keysyms and strings.
  • Prior to invoking the XKB rules, the XKB rule-input variables can be overridden or augmented by per-user values specified in dconf
    • dconf means database of configuration values
      • the per-user database is located at: ~/.config/dconf/user.
    • It's that data that is edited by:
      • dconf-editor
      • Desktop Menu > Preferences > Region and Language > Layouts [ > Options]
        • Options offered are from evdev.xml (as can be demonstrated by editing that file).
  • By some mechanism, the settings are transformed into a compiled map in /var/lib/xkb, with name server-<SHA1>.xkm.
    • See tool setxkbmap, also possibly xkbcomp.

Related components

  • udev: en.wikipedia.org/wiki/Udev
  • HAL: Hardware Access Layer (wikipedia): The idea was for HAL to detect hardware of all kinds. For keyboards it could feed variables to xkb. Database of info to support detection in "device info files" (xxx.fdi). Quite a few docs discuss this, around 2008, but it seems HAL has been deprecated and removed. Duties purportedly taken over by udev, which was formerly a lower layer below HAL. But if so, where's the data corresponding to fdi files?
  • hotplug

View current keyboard configuration

  • setxkbmap -print > filename
    • prints top level application of rules. Example:
  • xkbcomp $DISPLAY filename
    • Dumps effective expansion of rules showing all details invoked.
  • dconf dump / > filename
    • Dumps contents of user's dconf file.

Modify keyboard layout or behavior

  • If desired modification is defined in xkb/rules, then:
    • Apply systemwide: Edit /etc/default/keyboard
    • Apply for a user: Use Preferences > Region and Language > Layouts to select it.
  • If desired modification is NOT defined in xkb/rules, then
    • Define such a modification in rules/evdev or included file, possibly requiring additions to subsidiary keycodes, symbols, compat or other files.
      • Manually modify lst and xml versions of the rules file to match.
    • Apply
      • for system user using /etc/default/keyboard
      • for user using Preferences > Region and Language > Layouts

Example

Implement three-key swap:
Keyboard key
Make it act as
Caps Lock
Control
Control
Alt
Alt
Caps Lock

Directory usage

List of locations, some of which are used in Linux Mint 15 (/Ubuntu 13.04/Debian something).
/
dir
dir
dir
dir
file
Description
etc





Historically, sub dirs would contain lots of scripts which implemented config and startup. Recently, these dirs tend toward only including system-wide non-default config files (aside from the "default" directory).

default



keyboard
Specifies default values for:XKBMODEL, XKBLAYOUT, XKBVARIANT, XKBOPTIONS

udev



udev.conf
trivial


rules.d



Very few files. README: Local rules; only to override main rules found in /lib/udev/rules.d

X11
xkb



Empty


Xsession.d



Numerous scripts launched by /etc/X11/Xsession script (number-names so they are invoked in order).







(home ~/))
.config
dconf


user
Per-user dconf database. Edited with Preferences, or dconf-editor. Supersedes gconf apparatus in most respects?

.gconf
desktop
gnome
keybindings/
custom0
%gconf.xml
Possible special functions for keys.







lib
udev



keymap
Executable that does something related to keymaps?


rules.d



90+ rules files. Several pertain to keyboard input.
64-xorg-xkb-rules IMPORTs /etc/default/keyboard. Is this THE spot that includes default/keyboard's variables? Or is this udev making use of default/keyboard independent of xkb?
95-keymap.rules: Set model-specific hotkeys.


keymaps



Bunch of keyboard or computer-specific (particularly laptops) files giving translation from keycode to function name for unusual keys. Not sure which number and name series these are using. How do these relate to xkb?







usr
lib
modules
input

evdev_drv.so
mouse_drv.so


share
X11
xkb
compat
geometry
keycodes
keymap
rules
semantics
symbols
types

The xkb "database".
Source appears to be:
cgit.freedesktop.org/xkeyboard-config/
Scriptsin xkeyboard-config generate the distributed xkb files from smaller ones.
In xkb/rules, the xxxx.lst and xxxx.xml files provide string descriptions for the corresponding xxxx file. These are used by tools such as the gnome config UI tool.



xorg.conf.d


Some conf files.
var
lib
xkb



compiled keymap files (xxx.xkb). Most recent one was last one applied?

Tools

xkbcomp

Handles several translations:
From
To
Comments
Configuration files
xkb "source" (xxx.xkb

xkb "source"
xkb compiled (xxx.xkm)

Display
xkb "source" (xxx.xkb)

xkm
xkb "source"




setxkbmap

Instates a particular keyboard map for a particular device. Builds the map ("compiling" components as needed to xkm file). Input args can include specs for each of the kinds of component found in /usr/share/X11/xkb/.

Distractions

  • xmodmap apparatus
    • Confuses things relative to xkb apparatus (what is relationship? Don't exactly know. Do these programs operate through xkb apparatus, or directly on active keymap, or?)
    • Quirky operation due to the sequence in which it interprets then executes a series of commands
    • Vocabulary doesn't expose all the properties of keysyms.
  • Config file locations did not follow XOrg docs, example: http://www.x.org/archive/X11R7.5/doc/man/man5/xorg.conf.5.html
  • Difficult to know which settings files (or dconf... or gconf databases) are authoritative vs which ones are copies for compatibility, nor when such copies are made.
  • libxkbcommon: "xkbcommon is a keymap compiler and support library which processes a reduced subset of keymaps as defined by the XKB specification. Primarily, a keymap is created from a set of Rules/Model/Layout/Variant/Options names, processed through an XKB ruleset, and compiled into a struct xkb_keymap, which is the base type for all xkbcommon operations."
    • Seems to be a replacement for xorg xkb. Possibly for Wayland rather than x11?
    • Mentions contrast between two approaches:
      • libxkbcommon API excludes: KcCGST (Keycodes, Compat, Geometry, Symbols Types), also no predefined keymap files
      • Instead, use RMLVO: Rules, Models, Layouts (languages), Variants, Options. (This seems to correspond with /usr/X11/xkb/rules.)
      • But xkb already uses RMLVO. So contrast must be at more detailed level.

References

Note: Because of the evolution of xkb, and the evolution of how/where settings are maintained by linux (and differences between distros), older docs likely do not cover currently-applicable systems, and can be thoroughly misleading.

Miscellaneous Other Topics

Gnome, uses GTK
  • App API: GTK+ Overview
  • GTK+ components:
    • GDK: (GIMP Drawing Kit) is a computer graphics library that acts as a wrapper around the low-level drawing and windowing functions provided by the underlying graphics system.
    • Pango: layout and rendering of text with an emphasis on internationalization
    • ATK: a set of interfaces providing accessibility
    • GIO: Gnome IO (file) system
  • Underlying libs
    • GLib: provides data structure handling for C (including GObject), portability wrappers and interfaces for such run-time functionality as an event loop, threads, dynamic loading and an object system
    • Cairo: 2D graphics with support for multiple output devices (including the X Window System, Win32)

Download

One of the most crucial docs for understanding xkb is the X Keyboard Extension: Library Specification [PDF] However, all xorg versions of this docs are undermined by poor formatting, unreadably large or small diagrams, and missing section numbering. I have tried to remedy this by extensive detailed reformatting (but no edits to actual content).
Download: XKeyboardExtensionLib_GWToWord-20130613-b6.pdf

.
.