In Ubuntu 14.04, keyboard layouts are kept in

/usr/share/X11/xkb/symbols/

Each of the files in this directory contains a series of entries of the following type:

    key <AC01> {[a, A, aacute, Aacute]};

This entry maps a key on the keyboard to a number of specific characters using the following conventions:

1. <A C01> The first letter A indicates we are looking in the alphanumeric key block (other options include KP [for keypad] and FK [for Function Key]);

2. <A C 01> The second letter C indicates the row, counting from the bottom in which the key is found. (In a standard US keyboard, the space bar is in row AA and the number keys are in row AE).

3. <AC 01> The numbers 01 indicates the position of the key, counting from the left and ignoring any specially named key like TAB or ~ (tilde): AC01 is in the third row up, first key over from the left (ignoring Caps Lock, if present); on a standard US keyboard, this is the key marked “a”.

4. The brackets enclose the list of characters assigned to each key. This contains up to four entries, separated by commas:

   1. a - The unmodified key.
   2. A - The Shift character.
   3. á - The Alt Gr character. (aacute)
   4. Á - The Shift+Alt Gr character. (Aacute)

Creating a custom keyboard map is as easy as replacing the characters you don’t want in a given line with the ones you do!

For example:

As an Anglo-Saxonist, I type á and Á much less frequently than I type æ and Æ.

To add the Anglo-Saxon characters to my list, I simply replace aacute and Aacute with the entity names or Unicode code points for æ and Æ (“aelig” or U00E6 and “AElig” or U00C6, respectively):

    key  {[a, A, aelig, AElig]};

or

    key  {[a, A, U00E6, U00C6]};

When I am finished modifying my keyboard layout, I save the file with a new name, "oe" in the same directory.

Adding a new keyboard layout to evdev.xml file.

In order to use new keyboard layout, We need to tell X11 that it exists. In Ubuntu 14.04 X11 keeps track of installed keyboards in /usr/share/X11/xkb/rules/evdev.xml file. Then lets add the new layout in it.

1. Open X11/xkb/rules/evdev.xml in an editor

2. Go to the end of the <layoutList> section (search for </layoutList>). Add the following after the last </layout> tag, where X is the file name of your keyboard layout in /usr/share/X11/xkb/symbols (in my case oe); Y a suitable short name; and Z an appropriate long name in one or more languages and aaa a legal three letter (ISO 639-2) language code (e.g. eng for English):

   <layout>
    <configItem>
      <name> X </name>
      <shortDescription> Y </shortDescription>
      <description> Z </description>
      <languageList>
         <iso639Id> aaa </iso639Id>
      </languageList>
    </configItem>
    <variantList/>
   </layout>
   

Here it is, follow complete introduction

Other related links:
http://ubuntuforums.org/showthread.php?t=188761&p=1092145#post1092145 http://www.charvolant.org/~doug/xkb/html/index.html

Note: Wayland does use xkb, but many xTools have stopped working properly (xdotool for example)

Note: This is a non-exhaustive tutorial. It is most useful for an individual looking to create a new eight level layout and understanding the syntax.

Note: A quick and dirty solution is provided. It includes a spreadsheet which automatically generates the code you need.

Understanding XKB Directory

cd /usr/share/X11/xkb/ && ls

1. types - How produced keys are changed by Active Modifiers. ^{(Shift, Control, Alt~)}
   Important if you want to customize the Modifier Keys.
2. geometry - Used to draw keyboard graphics.
   Important if you are designing a non standard piece of keyboard hardware.
3. rules - Fetching the appropriate configuration for your current setup.
   You will need to define this
4. keycodes - The interpreter of the keycodes for keyboard hardware.
   Example: Macintosh Keyboards understand the spacebar as 57. We write it however as <SPCE>
5. symbols- Which Values are assigned to what Keycodes.
   This is where we will define our custom layout.
6. compat - Short for Compatability.
   Internal behaviour of Modifiers (Shift, Control, Alt...)

Workflow

keycodes > symbols > compat

I only touch symbols: See below for the Quick and Dirty solution.

Symbol Maps

/symbols/us ^{Any file in this directory follows the same structure.}

partial alphanumeric_keys
xkb_symbols "basic" {
    name[Group1]= "US/ASCII";
    key <TLDE> {        [ quoteleft,    asciitilde      ]       };
    key <AE01> {        [         1,    exclam          ]       };
    modifier_map Shift  { Shift_L, Shift_R };
};

partial - Not a complete keyboard map

alphanumeric_keys Section of the keyboard being mapped. ^{Multiple can be used}
Note: If no *_keys are specified, a complete keyboard is assumed.

"basic" - The name of the symbol map

name[Group1]= "US/ASCII"; Gives a unique name to this keyboard group.

modifier_map For editing modifier keys. (ctrl, shift, alt~)

Shift { Shift_L, Shift_R }; Not ordinarily neccessary. It maps both shifts to the shift modifier, aka level 2.

key <TLDE> The Tilde Key - Usually top left key right above Tab

key <AE01> Illustration - Composed of Three Parts, AE01

1. A = alphanumeric key block.
   KP = Keypad
   FK = Function Key

2. E = Row on Keyboard.
   Space Key = A row
   Shift Key = B row
   Caps Lock = C row
   Tab Key = D row

3. 01 = Position of the key on the row.
   AE01 = 1
   AB02 = X
   AC05 = G

[ + ] - In C Languages; Square brackets denotes a list, by which items are split by ,. The Length of the list determines the amount of levels. For example:

key<AE01> { [ Level 1 , Level 2 , Level 3 , Level 4 , Level 5 ] }

Typically, the Levels denote the following keypress with:

1. No Modifier Keys
2. Shift
3. Alt Gr
4. Shift + Alt Gr
5. Custom - Unlikely to see anything beyond level 4.

In short, if you wanted to map a key to shift + altgr, your list would have to be at least four items long.

WARNING - Common Errors

Either of these lines will cause a critical error, and will leave you without a usable keyboard:

key<AE01> { [ Backspace ] }
key<AE02> { [ a, b, , C ] }

• Backspace should be BackSpace : Pay extra careful attention to spelling.
• An empty entry should be VoidSymbol.

Best Safety Measure!

1. Backup your file that you are editting:

   sudo /bin/cp /usr/share/X11/xkb/symbols/us /usr/share/X11/xkb/symbols/usBACKUP

2. Make a script that you can run without root password

Something like:

#!/bin/bash
sudo /bin/cp -rf /usr/share/X11/xkb/symbols/usBACKUP /usr/share/X11/xkb/symbols/us

If anything goes wrong, use your mouse to run that line of code (contained in the bash script which you gave sudoers permission to. Remember to chmod +x to allow running as an executable.)

Backup strategies to recover a broken system

• WARNING: Keyboard & On-Screen keyboard will cease to work with the slightest error.
• Mouse will work. Typing can be done by highlighting characters, and pasting them in using middle click. In Bash, you can return (Pressing Enter) by pasting a linebreak.
• Keyboard will work in recovery mode in root shell. (Accessed from bash)
• You can always use a live environment to fix files.

Quick and Dirty solution

1. Go here
2. File > Make a Copy
3. Mapper Sheet is where you define your layout.
   • Single Character entries are translated into code understood by the program.
     (! becomes U0021). Unicode supported!
   • Strings are not translated and are treated as is. MAKE SURE THERE ARE NO SPELLING or CASE errors!.
   • Empty Squares are automatically filled with VoidSymbol.
4. XKB-Sort Sheet contains key groups, for example:

   key <AE01> { [U0021, U0021, U0021, U0021, U0021, U0021, U0021, U0021] };
   key <AE02> { [U005B, U005B, U005B, U005B, U005B, U005B, U005B, U005B] };
   key <AE03> { [U005D, U005D, U005D, U005D, U005D, U005D, U005D, U005D] };
   key <AE04> { [U0022, U0022, U0022, U0022, U0022, U0022, U0022, U0022] };
   key <AE05> { [U002A, U002A, U002A, U002A, U002A, U002A, U002A, U002A] };
   key <AE06> { [U007B, U007B, U007B, U007B, U007B, U007B, U007B, U007B] };
   key <AE07> { [U007D, U007D, U007D, U007D, U007D, U007D, U007D, U007D] };
   key <AE08> { [U002F, U002F, U002F, U002F, U002F, U002F, U002F, U002F] };
   key <AE09> { [U0027, U0027, U0037, U0027, U0027, U0027, U0027, U0027] };
   key <AE10> { [U0029, U0029, U0038, U0029, U0029, U0029, U0029, U0029] };
   key <AE11> { [U0028, U0028, U0039, U0028, U0028, U0028, U0028, U0028] };
   key <AE12> { [U005C, U005C, U005C, U005C, U005C, U005C, U005C, U005C] };
   

   Changes this on all 8 levels:

   1234567890-= // Physical Keys
   ![]"*{}/')(\ // Changed to these characters

5. XKB Tab also has lines. Every other tab can be ignored (its code).
6. sudo vim /usr/share/X11/xkb/symbols/us
7. Replace a layouts contents. Choose one you wont use. For example: I changed the colemak entry leaving the structure intact, and replaced the keys.

Lines of interest:

key.type[group1]="EIGHT_LEVEL";          // Enables 8 levels
modifier_map Control { <LFSH>, <RTSH> }; // Maps ctrl`s to shift keys.
key  { [Control_R, Control_R, Control_R, Control_R, Control_R, Control_R, Control_R, Control_R] }; 
key  { [Control_L, Control_L, Control_L, Control_L, Control_L, Control_L, Control_L, Control_L] };
include "level3(lalt_switch)" // Hold Left  Alt for Level 3
include "level5(ralt_switch)" // Hold Right Alt for Level 5