Introduction

This tutorial will introduce you to the basics of modifying and creating custom keyboard layouts for use with the system-standard gnome-keyboard-properties application (usually accessed through System->Preferences->Keyboads).

Background

Quickref

/usr/share/X11/xkb/symbols - key  defs
/usr/share/X11/xkb/keycodes/evdev - defintion of keys on keyboard

/usr/include/X11/keysymdef.h - Xorg keysyms
/usr/share/X11/XKeysymDB - compose-style keysyms

/usr/share/X11/locale/compose.dir - XCompose-style mappings directory
/usr/share/X11/locale/ - XCompose compose keys
~/.XCompose - custom XCompose keys (need to define QT/GTK_IM_MODULE)

Details

The basic keyboard mapping package is XKB. In current Ubuntus, the default directory is not /etc/X11/xkb but rather /usr/share/X11/xkb. Layouts are kept in the symbols directory therein: they are generally named by a two letter country code associated with the language for which the layout is designed.

Editing a layout is as simple as locating the correct file in the symbols directory and editing the file. Adding a new layout requires that you also add the file to rules/evdev.xml. If you use other X11 wms you may want to give your layout to the rest of the xorg system. You can do this by adding the file to the symbols.dir, and adding a line for the file in rules/evdev.lst under the !layouts section. These steps are currently beyond the scope of this document.

The output from layout files can be any Unicode character (see this Wikipedia entry), and are entered with the U and without the leading + sign, as for example U0282. Numbers and the standard alphabet may be entered directly. Dead keys, signs, and a large repertoire or characters, such as the @ "at" sign, have a descriptive name that can be entered in place of finding the Unicode character directly - these are defined in /usr/include/X11/keysymdef.h. Ignoring "XK_" part after each definition, the remainder of the word may be used in your layouts (for the sterling symbol, it says #define XK_sterling ..., so you would use sterling in your layout).

See the External Links section for a general overview of XKB and more.

Editing an existing layout

For example, suppose you have a Spanish language keyboard and want to add a dead key for the tilde accent for chatting with your Brazilian friends. You might then opt to place the tilde accent on the ñ key, because it has that symbol printed right on the key (albeit over the "n").

To do this, first you need to find the keyboard layout file you are using - in this case, it would typically be the /usr/share/X11/xkb/symbols/es file.

symbols/es

partial default alphanumeric_keys
xkb_symbols "basic" {

    include "latin(type4)"

    name[Group1]="Spain";

    key <AE01>  { [         1,     exclam,          bar,   exclamdown ] };
    key <AE03>  { [         3, periodcentered, numbersign,   sterling ] };
    key <AE04>  { [         4,     dollar,   asciitilde,       dollar ] };
    key <AE06>  { [         6,  ampersand,      notsign,  fiveeighths ] };
    key <AE11>  { [apostrophe,   question,    backslash, questiondown ] };
    key <AE12>  { [exclamdown, questiondown, dead_tilde,   asciitilde ] };

    key <AD11>  { [dead_grave, dead_circumflex, bracketleft, dead_abovering ] };
    key <AD12>  { [      plus,   asterisk, bracketright,  dead_macron ] };
...

Each line that starts with key gives a definition for that key. The word after key specifies which key, such that the second letter is A for the bottom row, B for the second row, etc., and the number is how far to the right that key is in that row (starting at zero). So mostly everyone's Q key is AD01 (with AD00 being the tab key). The function keys follow a different naming formulation, FK##, and other keys such as the key to the left of the "1" key, may be called TLDE. These are specified in keycodes/evdev by default.

After that there are blocks of generally 4 or less assignments to each key. Each column specifies a different modifier:

* altgr is the right alt key

In the "basic" section, you will be looking for the line containing the ñ key, which should look something like this:

    key <AC10>  { [    ntilde, Ntilde,   asciitilde, dead_doubleacute ] };

Say you want to replace where it says "asciitilde" to be the dead key for the tilde accent (the same symbol, but as a dead key). Looking in keysymdef.h, you can see that it has the predictable (if somewhat unfortunate) name dead_tilde -- so you substitute it in like so:

    key <AC10>  { [    ntilde, Ntilde,   dead_tilde, dead_doubleacute ] };

Then restart X windows and the change should be applied.

If the change doesn't seem to have any effect, it's possible that you might have edited the basic settings in the symbols/es file. There may be a section for your specific keyboard layout, e.g like this:

partial alphanumeric_keys 
xkb_symbols "mac" {

    // Describes the differences between a very simple mac_US
    // keyboard and a very simple Spanish keybaord

    include "es"
    name[Group1]= "Spain - Macintosh";
    
    key <AC10>  { [    ntilde, Ntilde,   asciitilde, dead_doubleacute ] };
};

Applying the change to the proper section should then make the customization work.

Note that you may also have to clear the pre-compiled keymaps before your modifications work:

cd /var/lib/xkb/
sudo rm *.xkm

Creating a new layout from scratch

For this exercise we're going to create a layout for Haitian Creyole. Kreyòl Asisyen, as it is called, is not supported by default, although oddly Latin American layout for Haitian is supported. I can't find any references for a proper layout so I'm going to be using my personal understanding of haitian to guide the design. - Even though my understanding is certainly basic.

symbols

To create a new layout from scratch we have to create our own symbols file. The two letter country code for Haiti is "ht", so following in the footsteps of all the other layouts that people ahve made in the symbols directory, let's use that name:

cd /usr/share/X11/xkb
sudo cp symbols/es symbols/ht
sudo gedit !$

Okay, so that's cheating. This isn't in school, so get over it. There's a whole section, about half of the entire layout, for dvorak typing. I don't know enough about character frequencies in kreyòl, so I'm just gonna cut that. The "cat" and "ast" sections are for Catalán and Asturian, related languages to Spanish, so I cut them as well. I also don't have an OLPC to work with, so I cut that section.

In what remains I need to rename Spain to Haiti everywhere. I need to replace the country code es with ht. And then, the hard work, I need to actually come up with a good key mapping for the haitian language. This is what the kreyòl alphabet looks like at Wikipedia. You can see there's a lot (a whole lot) of dipthongs and trithongs, they won't have a one-to-one mapping in unicode (I don't think so), so we'll just provide each glyph for those letters. There's no non-latin characters or anything special going on, but we want dead keys for the standard accents: grave, acute, diaresis, and caret. They tend to use quotes much as the italians or french do, with Guilemets for antural quotes and double qoutation marks for short, more formal citations or "quote-words". And they use hyphens and apostrophe's in their text much as in português or english.

symbols/ht

example symbols/ht file

The top name tag there is the filename under the symbols directory. The country list is a list of which countries should house this keyboard layout -- short list in our case. Likewise with the language list we only needed to put "hat" as it's just for haitian creyole. There were segments we defined for sun dead keys and we have to find each xkb_symbols "<name>" and create a <variant> sectio like above for it, if we want to see it in our list of variants for that laguage or that country when we browse to it in the keyboard preferences layout pane.

Close any such preferences and open it (go to System->Preferences->Keyboards), on the layouts tab when we add a layout we should now see our new haitian keyboard defitions under Country: Haiti, and as well under Languages: Haitian (Haitian Creyole).

How to load changes

To load changes to the layouts menu simply close out of gnome-keyboard-preferences and reload, relaunching the windows manager should not be necessary.

There is a change in Ubuntu version (13.10) and later versions which causes the keyboard settings cache to not refresh after files in "/usr/share/X11/xkb/symbols" directory are modified. It looks like changes just don't get applied. To force the cache refreshing a one should delete *.xkm files from "/var/lib/xkb", or enter into the console:

sudo dpkg-reconfigure xkb-data

Notes

Unicode and alt codes

(The Combining characters code blocks are particularly useful references for the following:)

From stylishpants on the forum:

Wikipedia Unicode input methods

Quote:

For example, type Ctrl+Shift+U30AD to type a Katakana letter 'キ' Ki. This means, press and hold Ctrl and Shift, then press and release each of the keys u30ad in turn, then release Ctrl and shift.

In Windows you enter the decimal value, but here you're entering the hexadecimal value (which is good, because it's usually shorter to type.) You can translate between decimal and hexadecimal with the 'calculator' utility (use the 'scientific' setting).

This reveals the following:

Alternatively you can find the hex value just by clicking on the symbol in Character map. (You probably want to choose the 'Common' script from the left-side menu.)

Note that the article also provides special methods to input characters at the Linux terminal and in the Vim editor (as well as other operating systems.)

Further contributions

Further contributions: it would be nice to at least add a section on how to set up media keys as well. Two other sections that would be appreciated if someone wants to write it up would be how to set up multi-second-key dead keys (so you can emulate windows alt+160, etc) and how to spawn more than one glyph from a keypress (so you can get a true ch glyph for, for example, the kreyòl example above).

External Links

• List of Unicode characters - organized by script.

• keysymdef.h - file:/// url to the keysym definitions on your computer.

• XKB configuration files - solid non-Ubuntu-specific tutorial

• X keyboard extension - Wiipedia overview of the XKB system

• Unicode and alt-code input - ubuntu forum thread on unicode input and equivalences to windows style alt codes.

References

• XKB pages - X.org foundations' documentation.

• Creating a custom keyboard layout - recent Ubuntu forums thread

• /etc/X11/xkb/base.xml is ignored - ubuntu bugs thread with some coverage

<!-- test -->