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