Keyboard definitions

Jump to: navigation, search

The X keyboard files are in /usr/share/X11/xkb/symbols/ on the OLPC (possibly elsewhere such as /etc/X11/xkb/symbols/ depending on your Linux distribution). Most of the keyboard file names are two-letter language codes, or are based on those codes.

The upstream location for these keyboard layouts is at Before starting work on a new keyboard layout, check if there is one already there for you. In general, the country code is used for the name of the keyboard layout file; there are a few exceptions, such as "ar" for Arabic which is spoken in several countries.

Each desktop manager has it own keyboard switching applet.

In GNOME, the Keyboard Indicator applet (gnome-keyboard-applet) shows the currently selected layout on the panel, and also allows to configure different options from the graphical interface. To activate, right-click on an empty space on the panel, then click Add to panel. Then, pick Keyboard Indicator and proceed with the configuration.

In KDE, the kxkb applet places an icon in the toolbar allowing you to select from the keyboards you have configured, or to configure others. You can also access it from the KDE Control Center on the main menu, in order to turn on the toolbar icon, if you don't like setting it up from the command line.

To add a keyboard layout, select a keyboard file similar to what you need, if possible, and copy it to a working directory. Edit the tables and the description, and save with the name you want to use, preferably the language code, or using the form language_version, such as en_US (US English) or fr_CH (Swiss French). As root, place your new keyboard file in the appropriate directory. Add your file name and language name to the keyboard list file /etc/X11/xkb/rules/xfree86.lst or /etc/X11/xkb/rules/xorg.lst, depending whether you are using a version of X from XFree86 or one from

When your keyboard layout is working to your satisfaction, post it to the Freedesktop Bugzilla by adding a report similar to this post The maintainer of the keyboard layouts will have a look at it and when everything is ok, it will be added to the keyboard package. Then, it will propagate to all other distributions.

Notes provided by Pablo Saratxaga of Mandriva Linux. Rewriting needed.

The X11 keyboard layouts are simple text files; in each file there
may be one or more layouts defined.

A layout can include some other one instead of redefining common things.
It has a name:


that is used by some keyboard selection tools.
Then, it defines the needed keys.
For unicode keysyms, you have to add 0x1000000 to the unicode value.
For characters that can be defined with the literal keysyms (all those
in ascii and iso-8859-*) it is better to use them (eg, "space" instead
of "0x1000020").
individual keys are defined like this:

   key <CODE>  { [  normal,  shift, altgr, altgr_shift ] };

the CODE for a key is Axyy with x a letter to identify the row it is in:

E: the row with the digits
D: top row of letters
C: middle row
B: bottom row
A: the row of space bar

and yy is a number (in decimal notation) identifying the column:
01, 02, 03, 04, ...., 09, 10, 11, ...

some keys have special codes: LSGT, TLDE, BKSL, as they change their
position depending on the keyboard models.
and then all the special keys (space, control, function keys, numeric keypad,
etc) have special names too (but most often you don't need to redefine

the best is to just take an existing layout file, and edit it to match
what you need.

To test it without restarting X, just launch: setxkbmap "xx"
or: setxkbmap "xx(yy)"
the first will load the default layout on the file "xx", the second
will load the layout "yy" of the file "xx".

If you need to load a non-latin layout; load also a latin one; otherwise
you are in big trouble :-) (unless you have some other way to change 
keyboards, such as a toolbar menu.)

For example: setxkbmap "fr,tifinagh(extended)" -option "grp:shifts_toggle"
loads both the French (fr) and tifinagh(extended) layouts;
and defines pressing both shift keys to toggle between those layouts.

It is possible to cheat a bit, by sending an unused unicode value,
and having the Compose file redefine that to the wanted string.
I have done it for arabic and tifinagh layouts; it works quite well.

It is not difficult to learn the file format by reading files in /etc/X11/xkb, including the various READMEs, but it is easier if you refer to the complete specification can be found at

A keyboard file usually has a two-letter name, from the IANA Language Subtag Registry, which replaces the obsolete ISO 639 standard for language codes.

When you are satisfied with a keyboard file, you can copy it to /etc/X11/xkb/symbols, where programs like KDE Control Center will pick it up automatically the next time you start X. (Look under Regional & Accessibility for Keyboard Layouts.) You can put any selection of keyboards on a toolbar menu.

We need somebody to comb through the keyboards available in the various Linux distributions, starting with Mandriva, and add them to the Laptop distribution. Anybody? I'll help.--Mokurai 00:00, 13 October 2006 (EDT)

The location of the upstream keyboard layouts is at If you are creating the Greek OLPC, you simply need to take the "gr" file (you can even simplify it by removing ancient Greek support which some students may find confusing)

See also