Creating and Compiling Custom Keymaps for Linux
Introduction ......................................................................................................................................... 2
Step 1: Retrieve keymap sources ........................................................................................................... 2
Step 2: Modify keymap and symbols ..................................................................................................... 2
Step 3: Compile keymap ...................................................................................................................... 3
Step 4: Install the new keymap .............................................................................................................. 4
More knowledge ................................................................................................................................. 4
Declare symbol using unicode ........................................................................................................ 4
Get key name by keycode ............................................................................................................. 5
Combining keymaps ..................................................................................................................... 5
Extra keys using Alt+Gr ................................................................................................................. 6
Old and new code ....................................................................................................................... 6
For more information ............................................................................................................................ 7
Introduction
HP thin clients running the ThinConnect operating system use compiled keymaps to reduce the amount
of flash disk space required to support a large set of international keyboards. This white paper
describes the basic steps involved in creating custom keymaps for keyboards that are not supported
by default under ThinConnect.
The examples in this white paper are based on Debian Etch and Xorg 7.1. All work should be
completed from a system based on Debian Etch, such as the HP t5735. The resultant keymaps from
the examples have been validated on the HP t5735 and HP t5135 running ThinConnect (S2ST0070).
Step 1: Retrieve keymap sources
1. From the command prompt, execute the following command:
wget http://ftp.de.debian.org/debian/pool/main/x/xkb-data-legacy/xkbdata-legacy_1.0.1.orig.tar.gz
If that URL no longer exists, search http://packages.debian.org for the package xkbdata-legacy and download the .orig.tar.gz file.
2. Go to the directory /home/user and extract the .orig.tar.gz file using tar –xzf <file>.
Step 2: Modify keymap and symbols
In this simple example, you will replace the $ in a US keymap with the sign for yen, ¥.
1. First go to the directory /home/user/xkb-data-legacy-1.0.1. This is the base directory
(<base>) for the remainder of the example.
2. Open the file <base>/keymap/xfree86 for editing.
This file provides declarations for most types of keymaps. In this example, the “us” keymap is
used as a base.
3. Copy the xkb_keymap “us” section and paste it directly below the ‘};’ line that closes out the
“us” keymap. Since there cannot be two default keymaps, remove the “default” header from
the new keymap, and rename it “my_map” as shown below:
xkb_keymap “my_map” {
xkb_keycodes { include “xfree86” };
xkb_types { include “default” };
xkb_compatibility { include “default” };
xkb_symbols { include “us(pc105)” };
xkb_geometry { include “pc” };
};
At this point you have a keymap identical to the us keymap.
4. Now change the xkb_symbols line to match the following:
xkb_symbols { include “us(my_keys)” };
This will change the keymap so that it uses the symbols declaration “my_keys” in the symbols file
“us”. However, this symbols declaration does not exist yet; the next step is to create it.
2
5. Save and exit the xfree86 file and open <base>/symbols/us.
This file contains declarations to map all the keyboard keys to symbols for the us keyboard. Other
files in the <base>/symbols directory will map symbols for other keyboards. For example,
<base>/symbols/de contains declarations for all the German symbols, and
<base>/symbols/jp contains symbol declarations for 106 key Japanese keyboard.
For a simple modification such as this one, you can add a new keyboard declaration to the us symbol
file instead of creating a new symbol file. Go to the end of the us file and add the following lines
directly below the ‘};’ line that closes out the previous symbol declaration:
xkb_symbols “my_keys” {
include “us(pc105)”
key <AE04> { [ 4, yen ] };
};
The include line declares that this symbol definition will inherit all the keys declared by the symbol
definition pc105 in the symbol file us.
If you trace the include lines from the declarations you will see that it inherits most of its keys from
us(basic) which contains all the letters and number keys and us(generic101), which contains
most of the control and auxiliary keys. It can be very helpful when creating a new keymap to look at
existing symbol declarations, such as these, to see what the symbol declarations should look like.
The key line below the include line declares a new key name to symbol mapping. It will take the
key <AE04> and map it to the symbol 4 normally, or yen when the Shift key is pressed.
The alphanumeric section of the keyboard is referred to as <Ax##>, where x is a row letter starting
with the row (A) where the space bar is located, and ## is a number starting from the left side of the
keyboard (ignoring the special keys like the left single-quotation mark/tilde key [` or ~]), Tab, Shift,
etc. Using this convention, the E key is <AD03>, the forward slash (/) key is <AB10> and the numeral
5 key is <AE05>. The special keys all have their own names such as <SPCE> for the spacebar,
<TLDE> for the left single-quotation mark/tilde key key (` or ~) and <L_ALT> for the left alt key.
These keys are all defined in <base>/keycode/xfree86. When a keyboard key is pressed it
generates a integer called a keycode; keycodes are mapped to key names by the keycode file
declared on the line:
xkb_keycodes { include “xfree86” };
in the keymap declaration.
If you are unsure as to what the name for a key is, the best way to find out is to look at a symbol
declaration for a keyboard you know and find where the key is declared. For example, if you did not
know what the key for the backslash was called (usually right above the Enter key on a standard us
keyboard), you could look for ‘backslash’ in the us(basic) symbol declaration, and on line 258 find
that it’s called <BKSL>.
You could also do this in reverse to find what the symbol is called. For example, if you knew that on a
French keyboard the 12
pressed with the Shift key, but didn’t know what to call that symbol, you could look for <AD12> in
<base>/symbols/fr and find that it is called sterling.
th
key on the 4th row from the bottom <AD12> created a £ symbol when
Step 3: Compile keymap
Now that you have created a new keymap and symbol declaration you are ready to compile the
keymap. This is done via this command:
3
xkbcomp –xkm –m <map> <keymap file> <destination file>
For this example, the command is shown below:
xkbcomp –xkm –m my_map /home/user/xkb-data-legacy-1.0.1/keymap/xfree86
/home/user/new_map.xkm
After running the command you’ll likely see many warnings stating “No symbol defined for
<xxx> (keycode yyy)”. Ignore these; xkbcomp will display warnings for any keycodes that were
not declared, even if those keys are not present on the keyboard. Check to make sure there are no
other errors or warnings; warnings other than this one may indicate a syntax error. The error message
should point you to the area where the mistake was made and describe what type of mistake it is.
You can also use this command to compile keymaps that are already declared but not included in the
standard keymaps for the thin client. For example, if you wanted the standard Latvian keyboard, you
could skip step 2 and compile the keymap with the following command:
xkbcomp –xkm –m lv /home/user/xkb-data-legacy-1.0.1/keymap/xfree86
/home/user/lv.xkm
Step 4: Install the new keymap
Once the sample keymap compiles correctly you will have a file called new_map.xkm at
/home/user. Copy this keymap file to a USB key and insert the key into the USB port on the thin
client.
1. Open the Settings menu
2. Click the Experience tab.
3. Click the Keyboard Names button on the right side.
4. Click Add Keymap.
5. In the Language text box enter the display name you want to use for the keymap. For this
example, use US – with Yen
6. Click Import.
7. Browse to usb0, select the new keymap and click Open.
8. Click OK to return to the Keymap configuration menu.
9. Click OK again to return to the Settings menu.
10. Select the new keymap from the Keyboard Language drop-down menu.
11. Click OK and Restart Session and your new keymap will be applied.
With the new keymap applied, whenever we press Shift+4, the ¥ symbol is shown instead of the $
from the normal US keyboard.
More knowledge
This section contains additional information that will help with creating more complex keymaps.
Declare symbol using unicode
If you are having trouble finding the names for special symbols, you can declare the symbols directly
using their Unicode values. For example, you know you’d like your keyboard to produce the | key
when you press the first key on the second row from the bottom (the key just to the right of left shift),
but you don’t know what that key is supposed to be called in your symbols declaration. There are
three ways you can solve this.
4
The first and easiest method is to go to a symbols declaration that you know uses the symbol and see
what name it shows. For example, you know that the us keyboard layout has will display the |
symbol when you press Shift+\. You can look through the symbol declarations in
<base>/symbols/us and see that <BKSL> is set to [ backslash, bar ].
The second method is to refer to the Unicode characters Xorg has predefined. Xorg defines most
Unicode characters in the file /usr/include/X11/keysymdef.h. This file is included in the
debian package x11proto-core-dev. For the most part this will require that you know the
Unicode value of the character you’re looking for, although you can attempt to search or browse the
file to look for the correct declaration line. For example, you’d like to generate the symbol | but are
not sure what it’s called. You search for LINE and find the following declaration:
#define XK_bar 0x007c /* U+007C VERTICAL LINE */
You can then create your symbol declaration as shown below:
xkb_symbols “bar-z” {
key <AB01> { [ bar, z ] };
};
For the third method, rather than try to find the name of the Unicode value in the keysymdef.h file,
you can use the Unicode value directly. Use the official Unicode charts at
http://unicode.org/charts to
look up characters based on what script they are a part of and enter the Unicode value directly into
the symbol declaration. Make sure to precede the Unicode value with 0x100 so that they can be
parsed correctly. For example, the previous keymapping could also be declared like this:
xkb_symbols “bar-z” {
key <AD11> { [ 0x100007c, 0x100007a ] };
};
Get key name by keycode
Suppose you want to set the forward slash (/) key on the keypad of a us keyboard to the less-than (<)
symbol, but cannot find the key name for the / key in any symbol files. You can use the command
xev to find this information.
Run xev from the command line. It will bring up a small GUI with a little white box. Select the title bar
on the GUI and press the key in question. You should get output on the command line like this:
KeyRelease event, serial 29, synthetic NO, window 0x2600001,
root 0x3e, subw 0x0, time 3953390030, (90, -21), root:(754,455),
state 0x10, keycode 112 (keysym 0xffaf, KP_Divide), same_screen YES,
XLookupString gives 1 bytes: (2f) “/”
To find the key name you can search the <base>/keycodes/xfree86 file for the keycode 112
shown on the third line of the xev output. On line 122 of <base>/keycodes/xfree86 we see that
keycode 112 is set to <KPDV>. Once you have the key name you can enter it directly into the symbol
declaration as shown below:
xkb_symbols “sample” {
include “us(pc105)”
key <KPDV> { [ less ] };
};
Combining keymaps
One special case used frequently in the keymap declaration file is combining keymaps. For example,
the standard French keymap is declared:
5
xkb_keymap “fr” {
xkb_keycodes { include “xfree86” };
xkb_types { include “default” };
xkb_compatibility { include “default” };
xkb_symbols { include “en_US(pc105)+fr” };
xkb_geometry { include “pc(pc102)” };
};
This keymap is almost identical to the standard us keymap, except that on the xkb_symbols line it
has the symbol declaration en_US(pc105)+fr. This states that it should take the standard pc105
symbol declaration from the en_US file and add the default fr symbol declaration to it. In the
<base>/symbols/fr file, we can see under the default symbol declaration basic that only the
keys that have been modified from the en_US(pc105) symbol definition are declared.
This is very similar to the includes “<symbol_def>” line that we used in the original samples.
Extra keys using Alt+Gr
In many of the keymaps you will see symbol declarations that declare four symbols per key instead of
two. In most cases the extra symbols are accessed via the Alt+Gr key, which is treated as an extra
mode key like the shift key. For example, the polish keyboard layout, <base>/symbols/pl has
extra symbols declared:
xkb_symbols “basic” {
...
key <AC01> { [ ],
[ agonek, Aogonek ] };
...
};
This symbol declaration states that when the key <AC01> (the a key) is pressed alone or with the shift
key it should behave normally. This is done by leaving the first set of brackets empty. The second set
of brackets states that when the alternate mode key (Alt+Gr) is pressed along with the <AC01> key,
the symbol ơ should be generated, and when Alt+Gr, shift and a are all depressed at the same time,
the Ơ symbol should be generated.
Old and new code
Many older tutorials for creating and compiling keymaps are written for Xfree86. The main difference
between those tutorials and this tutorial will be the location of the xkb base directory. Historically
this was in /usr/X11R6/X11/xkb. In this tutorial, you retrieved the xkb sources directly, so replace
any references to xkb files in other tutorials with the <base> directory declared here.
Many newer tutorials will make references to the rules directory. This is a new interface to the
keymaps that lays out the keymaps in a more logical format. Any references to the rules files will
not work for compiling keymaps using xkbcomp, and any tutorial using the newer rules interface
should not be used to create or compile keymaps for the thin client.
Debian etch by default does not compile its keymaps and uses the newer rules interface. Keymaps for
Debian etch are stored at /usr/share/X11/xkb. Trying to compile keymaps with xkbcomp using
the keymaps in this directory will fail. This is why it is important to download the source to the xkb-
base-legacy package at the start of the tutorial, rather than installing the xkb-data-legacy
package directly or using the xkb-data in /usr/share/X11/xkb.
6
For more information
• http://www.freedesktop.org/wiki/Software/XKeyboardConfig - The official page for xkb
http://www.charvolant.org/~doug/xkb/ --Extensive information about xkb and how it works
•
http://unicode.org/charts - Official Unicode symbol charts
•
http://hektor.umcs.lublin.pl/~mikosmul/computing/articles/custom-keyboard-layouts-xkb.html - A small
•
tutorial on creating a useful custom keymap (out of date)
http://www.linux.com/feature/113715 - A similar tutorial feature on creating a custom keymap (out of
•
date)
http://anakin.ncst.ernet.in/~aparna/consolidated/x1740.html - Some useful information regarding xkb
•
and keymaps (out of date)
© 2008 Hewlett-Packard Development Company, L.P. The information contained
herein is subject to change without notice. The only warranties for HP products and
services are set forth in the express warranty statements accompanying such
products and services. Nothing herein should be construed as constituting an
additional warranty. HP shall not be liable for technical or editorial errors or
omissions contained herein.
510947-001, September 2008
Loading...