Keyboard configuration is a more complicated issue than it might at first appear. There are many different keyboards sold, each with a different number or arrangement of keys. Each of these keyboard models may be sold in different markets, with different key caps installed, and users may want their keyboard to operate in specific ways.

Together, this means that there are thousands of possible keyboard configurations. The XKB extension tries to simplify this by combining a small number of keyboard selection parameters to compose a particular configuration. The final configuration is called a keyboard map.

In addition to keys that type characters or perform actions directly, a keyboard map almost always includes modifiers—such as Alt, Ctrl, and Shift—which change the operation of the other keys. It may also contain dead keys, which don’t actually type anything but cause the following character to be accented, so that pressing’ by itself doesn’t type an apostrophe (unless you type it twice), but pressing’ then A types á.

The keyboard map can also include a compose key, which is pressed before a twokey sequence to generate special characters (for example, pressing Compose-/-C yields the cent symbol [¢]; Compose-O-R yields the registered trademark symbol [®]; and Compose-comma-C yields a C with cedilla [ç]).

In these days of international communication, many users need to communicate in more than one language, so many keymaps have more than one keyboard group defined, with a key or key combination to temporarily switch or to cycle through the groups. Each keyboard group corresponds to one layout. Keyboard LEDs (particularly the ScrollLock LED) may be assigned to indicate the current group.

To load a keymap into the X server, you need to know how to specify that keymap (Sections 12.3 and 12.4), and you need to know how you can use that specification in a file or as command arguments (Sections 12.6, 12.7, and 12.8).

XKB data is stored in a large number of files located in a directory tree. That tree may be located in any one of several different locations, as described next:

XKB keymaps are compiled from five components:

Each component is specified by a filename or by a filename followed by a section name in parentheses. For example, the default keymap for the X.org server is defined as:

	keycodes:    xfree86+aliases(qwerty)
	types:       complete
	compat:      complete
	symbols:     pc(pc105)+latin
	geometry:    pc(pc105)

It’s really tedious to determine which component values should be used, so XKB provides a rule-based system (Section 12.4) that combines more natural criteria determine the components to be used.

Rule-based keymap selection is much easier and more common than component-based selection. Rule-based selection uses five parameter values: Rules, Model, Layout, Variant, and Option.

The Rules value dictates the possible values for each of the other four parameters. For example, if the Rules value is sun, you can specify the Model type4, but that model name is not available if you are using the xorg rules.

The five parameters are described here:

To find available values, look in the .lst file. Here is the top of rules/xorg.lst:

	! model
	  pc101          Generic 101-key PC
	  pc102          Generic 102-key (Intl) PC
	  pc104          Generic 104-key PC
	  pc105          Generic 105-key (Intl) PC
	  dell101        Dell 101-key PC
	  dellm65        Dell Precision M65
	  everex         Everex STEPnote
	  flexpro        Keytronic FlexPro
	  microsoft      Microsoft Natural

The line starting with! identifies the section for a particular parameter: model in this case. The first word on each of the following lines is a possible value for that parameter, and the rest of the line is a comment describing that value. Therefore, a value of pc105 for the XKB model parameter specifies a generic 105-key PC keyboard.

The same data is present in rules/xorg.xml, with translations of the descriptions. This is the top of the file, with some translations removed:

	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
	<xkbConfigRegistry>
	  <modelList>
	    <model>
	      <configItem>
	        <name>pc101</name>
	        <description>Generic 101-key PC</description>
	        <description xml:lang="af">Generies 101-sleutel PC</description>
	        <description xml:lang="fr">PC générique 101 touches</description>
	        <description xml:lang="hu">általános 101 gombos PC</description>
	        <description xml:lang="it">Generica 101 tasti PC</description>
	        <description xml:lang="nl">Algemeen 101-toetsen PC</description>
	...lines snipped...
	          </configItem>

The XML file can be easily parsed by a GUI configuration program, but it is so verbose that it’s hard to browse by hand, so the .lst may be better for direct reading.

In addition to the model values, the .lst and .xml files contain values for the Layout, Variant, and Option parameters. This is the top part of the Layout section:

	! layout
	  us           U.S. English
	  ad           Andorra
	  af           Afghanistan
	  ara          Arabic
	  al           Albania
	  am           Armenia
	  az           Azerbaijan
	  by           Belarus
	  be           Belgium
	  bd           Bangladesh
	  in           India
	  ba           Bosnia and Herzegovina
	  br           Brazil
	  bg           Bulgaria
	  mm           Myanmar
	  ca           Canada
	...lines snipped...

The value in the first line, us, is the default layout. Obviously, there are multiple layouts that may be used in the United States, or Brazil, or Canada; these Layout values specify only the default layout, which is usually the most common. To specify another layout, the Variant parameter is added:

	! variant
	  intl            us: International (with dead keys)
	  alt-intl        us: Alternative international (former us_intl)
	  dvorak          us: Dvorak
	  dvorak-l        us: Left handed Dvorak
	  dvorak-r        us: Right handed Dvorak
	  rus             us: Russian phonetic
	  ps              af: Pashto
	  uz              af: Southern Uzbek
	  azerty          ara: azerty
	  azerty_digits   ara: azerty/digits
	  digits ara:     digits
	  qwerty ara:     qwerty
	...lines snipped...

In this section of the file, the second column specifies the layout with which each variant may be used. For example, the dvorak variant will work with the us layout, but not the af layout.

The variant parameter is optional, and defaults to no variant.

The last section of the .lst file contains possible values for the Option parameter. Here are some common option values from the xorg.lst file:

	!   option
	...lines snipped...
	   ctrl                Ctrl key position
	   ctrl:nocaps         Make CapsLock an additional Ctrl.
	   ctrl:swapcaps       Swap Ctrl and CapsLock.
	   ctrl:ctrl_ac        Ctrl key at left of 'A'
	   ctrl:ctrl_aa        Ctrl key at bottom left
	   ctrl:ctrl_ra        Right Ctrl key works as Right Alt.
	...lines snipped...
	   Compose key         Compose key position
	   compose:ralt        Right Alt is Compose.
	   compose:rwin        Right Win-key is Compose.
	   compose:menu        Menu is Compose.
	   compose:rctrl       Right Ctrl is Compose.
	   compose:caps        Caps Lock is Compose.
	...lines snipped...

Option values can be specified as a comma-delimited list, so ctrl:nocaps, compose: menu would configure the CapsLock key as an additional control key and the Menu key as a compose key.

In today’s globally connected environment, many users need to enter text in two or more languages, and these languages often require different keyboard layouts. XKB accommodates this need by providing up to four keyboard layout groups, along with mechanisms to switch between them and to indicate which group is active. Each group is effectively a keyboard layout that may be selected on-the-fly.

Groups are specified by listing multiple comma-delimited values for the layout and variant parameters. For example, these parameters specify group 1 as the international (intl) variant of the us layout, and group 2 as a ca (Canadian) layout with no variant:

	rules:     xorg
	model:     pc105
	layout:    us,ca
	variant:   intl,

The option parameter is used to specify which keys are used to switch between groups. These are the possible switching keys listed in the xorg.list file:

	grp:switch           R-Alt switches group while pressed.
	grp:lswitch          Left Alt key switches group while pressed.
	grp:lwin_switch      Left Win-key switches group while pressed.
	grp:rwin_switch      Right Win-key switches group while pressed.
	grp:win_switch       Both Win-keys switch group while pressed.
	grp:rctrl_switch     Right Ctrl key switches group while pressed.
	grp:toggle           Right Alt key changes group.
	grp:lalt_toggle      Left Alt key changes group.
	grp:caps_toggle      CapsLock key changes group.
	grp:shift_caps_toggle Shift+CapsLock changes group.
	grp:shifts_toggle    Both Shift keys together change group.
	grp:alts_toggle      Both Alt keys together change group.
	grp:ctrls_toggle     Both Ctrl keys together change group.
	grp:ctrl_shift_toggle Ctrl+Shift changes group.
	grp:ctrl_alt_toggle  Alt+Ctrl changes group.
	grp:alt_shift_toggle Alt+Shift changes group.
	grp:menu_toggle      Menu key changes group.
	grp:lwin_toggle      Left Win-key changes group.
	grp:rwin_toggle      Right Win-key changes group.
	grp:lshift_toggle    Left Shift key changes group.
	grp:rshift_toggle    Right Shift key changes group. 
	grp:lctrl_toggle     Left Ctrl key changes group. 
	grp:rctrl_toggle     Right Ctrl key changes group.

Note that the values marked with switch select group 2 while pressed, switching back to group 1 when the keys are released. This makes them usable only for 2-group configurations where group 1 is in effect most of the time. Entries marked toggle step through the available groups; if only two groups are defined, then toggle keys act like CapsLock—press once to switch, press again to switch back.

There are also options to display the group status on keyboard LEDs:

	grp_led:num         NumLock LED shows alternative group.
	grp_led:caps        CapsLock LED shows alternative group. 
	grp_led:scroll      ScrollLock LED shows alternative group.

Since the ScrollLock LED rarely displays useful information, it is a good candidate for a group indicator.

Unfortunately, the LEDs operate very simply: they are off when group 1 is active, and on when any other group is active—it’s not possible to determine from the LEDs whether the alternative group is 2, 3, or 4.

To select the menu key as the group toggle and the ScrollLock LED as the group indicator, specify both option values in a comma-separated list:

	rules:       xorg
	model:       pc105
	layout:      us,ca
	variant:     intl,
	option:      grp:menu_toggle,group. grp_led:scroll

If you’re using the X.org server, the XKB keymap may be specified in the keyboard InputDevice section of the xorg.conf file, using a series of Option directives. Each options name is a concatenation of Xkb and a component or parameter name.

To specify an XKB keyboard map using rules, any combination of XkbRules, XkbModel, XkbLayout, XkbVariant, and XkbOption options may be specified:

	Section "InputDevice"
	        Identifier  "Keyboard0"
	        Driver      "kbd"
	        Option      "XkbRules"   "xorg"
	        Option      "XkbModel"   "pc105"
	        Option      "XkbLayout"   "us,ca"
	        Option      "XkbVariant"   "intl,"
	        Option      "XkbOption"   "grp:menu_toggle,grp_led:scroll"
	EndSection

You may also specify the keymap using components, using the XkbKeycodes, XkbTypes, XkbCompat, XkbSymbols, and XkbGeometry option names:

	 Section "InputDevice"
	         Identifier  "Keyboard0"
	         Driver      "kbd"
	         Option      "XkbKeycodes" "xfree86+aliases(qwerty)"
	         Option      "XkbTypes"    "complete"
	         Option      "XkbCompat"    "   complete+ledscroll(group_lock)"
	         Option      "XkbSymbols"  "pc(pc105)+us(intl)+ca:2+group(menu_toggle)"
	         Option      "XkbGeometry" "pc(pc105)"
	EndSection

The setxkbmap command enables you to change the keymap at any time. The options -rules, -model, -layout, -variant, and -option are used to specify the parameters:

	$ setxkbmap -rules xorg -model pc105 -layout us,ca -variant intl, 
	     -option grp:menu_toggle,grp_led:scroll

If you specify the -v option, setxkbmap will print a list of the components used:

	$ setxkbmap -rules xorg -model pc105 -layout us,ca -variant intl, 
	     -option grp:menu_toggle,grp_led:scroll
	keycodes:   xfree86+aliases(qwerty)
	types:      complete
	compat:     complete+ledscroll(group_lock)
	symbols:    pc(pc105)+us(intl)+ca:2+group(menu_toggle)
	geometry:   pc(pc105)

If you want only to see the components listed and do not wish to actually set the keyboard map, use the -print option. The output will be formatted for input to xkbcomp, which is the keymap compiler (Section 12.9):

	$ setxkbmap -print -rules xorg -model pc105 -layout us,ca -variant intl, 
	     -option grp:menu_toggle,grp_led:scroll
	xkb_keymap {
	        xkb_keycodes  { include "xfree86+aliases(qwerty)"       };
	        xkb_types     { include "complete" };
	        xkb_compat    { include "complete+ledscroll(group_lock)"        };
	        xkb_symbols   { include "pc(pc105)+us(intl)+ca:2+group(menu_toggle)"   };
	        xkb_geometry  { include "pc(pc105)"
	};

You can also configure the keymap using components. Using the values from the output above, the xkbsetmap command would look like this:

          $ setxkbmap -keycodes "xfree86+aliases(qwerty)" 
	     -types "complete" 
	     -compat "complete" 
	     -symbols "pc(pc105)+us(intl)+ca:2+group(menu_toggle)" 
	     -geometry "pc(pc105)"

One xorg.conf configuration file may be shared between several server instances: for example, on a Linux system, you can start two (or more) X servers running on different virtual terminals and switch between them. You may want to use a common xorg.conf file for both servers, but specify different keyboard configurations.

You can do this by creating a per-server keyboard configuration file. These files are placed in the root of the XKB tree (Section 12.2) and are named d-config.keyboard, where d is the display number—so the configuration file for display :0 would be /etc/X11/xkb/X0-config.keyboard or /usr/share/X11/xkb/X0-config.keyboard.

This file contains name and value pairs, one per line, delimited by equal signs. The names may be component names or parameter names. For example:

	rules = xorg
	model = pc105
	layout = us
	variant = intl

Each keyboard configuration file may also specify how AccessX controls work as well as explain that some parameters are usually adjusted using xset (Section 6.4), such as the bell pitch and volume and the keyboard repeat rate, but these are rarely used.

XKB keyboard maps are compiled before use. Generally, the X server calls the xkbcomp program to compile the map based on information that either is in the server configuration file, in the keyboard configuration file, or passed to the server from set xkbmap.

The manpage for setxkbmap notes that it may fail if it is run on a system that has different XKB components than the server does, because xkbcomp may not find the components specified by setxkbmap. In that case, you may run xkbcomp on the client side:

	$ setxkbmap -layout ca -print | xkbcomp - $DISPLAY

This will automatically upload the keymap to the server after compilation.

It is also possible to save a compiled keymap—but this is depreciated in favor of rules-based configuration.

If you’re using a keyboard layout that doesn’t match they physical keycaps on your keyboard, it may be useful to print (or view) a picture of the layout. The xkbprint program uses the XKB geometry component to generate Postscript or Encapsulated Postscript images of keyboard layouts.

The simplest way to run xkbprint is to provide a displayspec for the keymap source as well as a destination filename:

	$ xkbprint $DISPLAY keyboard.ps

This will generate a single Postscript file containing an image of the first two levels of the first keyboard group, as shown in Figure 12-1.

Figure 12-1. xkbprint output with no options, loading the keymap directly from the X server

If you defined more than two levels, use the -ll option to select the starting level; this is most commonly used to specify that the image should start with level 3, which causes the third and fourth level to be included:

	$  xkbprint -ll 3 $DISPLAY keyboard.ps

In a similar way, you can select the starting group with -lg:

	 $ xkbprint -lg 2 $DISPLAY keyboard.ps

When reading the keymap from the server, xkbprint will show only one keyboard image. However, if you use a compiled keymap as input, xkbprint will draw multiple keyboard groups as separate images, which is usually ideal for a reference sheet. You can obtain the current keymap from the server and place it in a file using xkbcomp:

	$ xkbcomp -xkm $DISPLAY -o keymap.xkm
	$ xkbprint keymap.xkm keyboard.ps

The output is shown in Figure 12-2.

Figure 12-2. xkbprint output from a keyboard map file loaded from the X server

An additional page can be generated, showing the keyboard layout of the third and fourth levels, shown in Figure 12-3.

          $ xkbprint -ll 3 keymap.xkm keyboard.ps

Figure 12-3. xkbprint output from a compiled keymap file, showing levels 3 and 4