Customizing keyboard mapping for X11 revision 7

1. Symbol files

Symbol files are kept in /usr/lib/X11/xkb/symbols/. To modify an existing 
keyboard layout, I recommend editing its symbol file (backing it up first, of 
course) as follows:

To create a new keyboard layout in a symbol file, begin with ... 

	partial alphanumeric_keys
	xkb_symbols "foo" {

... where "foo" is the keyboard name that you'll be giving to the X11 rules 
file later. Don't worry about the name too much -- just keep it short and 
simple, and you'll be fine (e.g., if your keyboard is named "Phonetic Estonian 
layout", call it "ee_phonetic" or "ee_phon").

Note also that comments may be added at any point, delimited by "//" and the 
end of a line.

You'll then add the name of the keyboard as it will appear in programs such as 
Gnome's keyboard properties window:

	name[Group1]="The long title of the keyboard";

Note that all lines within the braces will end with semicolons. The end brace 
itself will be followed by a semicolon, but let's not get ahead of ourselves.

The next step is to figure out where you want to get the keyboard layout that 
you are going to modify. This is done like so:

	include "path(shortname)";

... where path is the path from /usr/lib/X11/xkb/symbols/ to the symbols file 
and "shortname" is the "short name" (using the example above, "foo" would be 
this layout's "short name").

And now you're into the meat of the mapping. Mapping a key takes the following 
format:

	key <NAME> { [lowercase, capital, alt_lowercase, alt_capital] };

The key's "NAME" is the four-letter name assigned to each key. 1, Q, A, and Z 
begin rows AE, AD, AC, and AB respectively; starting from 01, we count from 
left to right for the keys. Thus the QWERTY keyboard's "D" key would be <AC03>.

The "lowercase" and "capital" entries should be obvious as to their nature: the 
standard mapping of the "D" key on a QWERTY keyboard would read:

	key <AC03> { [d,	D ] };

The "alt_lowercase" and "alt_capital" are not used unless a "switch" (e.g., the 
right alt key switch, which will be discussed below) is enabled. In those 
cases, however, the "alt_lowercase" and "alt_capital" keys will correspond to 
holding down the "switch" key and pressing the denoted key, or holding down the 
"switch" and "shift" keys and pressing the denoted key.

To enter the characters matching /[0-9][a-z][A-Z]/ as a keyboard mapping, just 
enter the literal characters. For other characters, there are mnemonics, found 
at $(man keysym). As an example, here is the definition line for my Q key:

	key <AD01> { [q,	Q,	Greek_DELTA,	Greek_OMEGA ] };

"Switches" (or "third-level shift keys") are enabled by adding the line

	include "level3(switchname)";

inside the braces of the xkb_symbols command. The possible switches follow:

	"ralt_switch"		right alt key becomes "third shift"
	"lalt_switch"		left alt key becomes "third shift"
	"alt_switch"		both alt keys become "third shifts"
	"switch"		right control key becomes "third shift"
	"menu_switch"		menu key becomes "third shift"
	"win_switch"		both "windows" keys become "third shifts"
	"lwin_switch"		left "windows" key becomes "third shift"
	"rwin_switch"		right "windows" key becomes "third shift"

Then conclude the xkb_symbols command by a closed brace followed by a 
semicolon. You may also want to check your symbolfile to see if it compiles 
properly by running $(xkbcomp symbolfile) where symbolfile is the name of your
symbolfile.

If you haven't already, now's the time to make another backup of your original 
symbolfile and move the modified one to the original's position.


2. Modifying xorg.xml

For the keyboard layout to show up in keyboard-choosing programs such as 
Gnome's "keyboard properties" window, you will need to edit xorg.xml, which is 
located in the /usr/lib/X11/xkb/rules/ directory. If your keyboard is a variant
of another keyboard (e.g., of the standard US English keyboard), you will want 
to find the entry for that keyboard and look for the opening tag <variantList>.
Then add the following:

	<variant>
		<configItem>
			<name>shortname</name>
			<description>Long title</description>
		</configItem>
	</variant>

You will then want to reboot X and change your keyboard settings to your new 
keyboard file.


apollotiger@nbtsc.org
7 February 2007