Each keyboard definition in GTKeyboard consists of 5 rows of keys. Each row contains multiple keys. Line 1 in the file always tells GTKeyboard how many keys are going to be on each row. In this case, the first line, 14 14 13 12 5 means that there will be 14 keys on the first row, 14 keys on the second row, 13 keys on the third row, 12 keys on the fourth row, and 5 keys on the fifth row. With that laid out, the rest of the file consists of one key definition per line. If you specified that there are 14 keys in the first row, then the first 14 key definitions will be assigned to the first row, from left to right. If you specified that the second row should have 14 keys as well, the next 14 keys will comprise the second row, from left to right.
In the sample file you will notice commentary such as # Begin row 2. GTKeyboard ignores these comments - they are merely there to remind the person writing the file where each row begins.
Now all the file really consists of is a series of key definitions. Key definitions contain up to 5 parts. The first three parts are all KeySyms. KeySyms are the X server's way of keeping track of various symbols. Names for all of the possible KeySyms may be found in /usr/include/X11/keysymdef.h. If this file doesn't exist you may want to consult your local administrator for the location of the X server include files. In that file, you will find lists of KeySyms looking like this:
#define XK_Y 0x059
#define XK_Z 0x05a
#define XK_bracketleft 0x05b
#define XK_backslash 0x05c
In this case, XK_Y refers to the character ``Y'' (upper case). XK_Z refers to the character ``Z'' (upper case). XK_bracketleft refers to ``[``, and XK_backslash refers to the blackslash character. In all of these lists, take the name of the KeySym as listed in /usr/include/X11/keysymdef.h, remove the beginning ``XK_'' and you have a KeySym name for the GTKeyboard keyboard definition file.
Each key definition line starts with three KeySym definitions. For example, in line 37, we see a lower case j, followed by an upper case J, followed by another lower case j. The first KeySym is what the pressed key will do under normal conditions. The second KeySym is what the key will do when pressed in combination with either Shift or Caps Lock. The third KeySym is what the key will do when pressed in combination with the Mode Switch key. Usually this is labeled ``Alt Gr'' on most keyboards. For US keyboard layouts, generally this isn't used, but still must be specified.
Following the three KeySyms is the KeyCode. The KeyCode is an integer assigned to each key on a physical keyboard. This KeyCode is what allows GTKeyboard to do much of its remapping work. While it is not required, it is strongly recommended. Without specifying the KeyCode for each and every key in the keyboard definition file, GTKeyboard will be unable to remap your physical keyboard to the settings you specify in that file.
In order to find the KeyCode for a particular key, use the ``xev'' program that comes with your X server. By placing the mouse in the xev window and pressing a button, xev outputs data about the key to standard out. Example:
KeyPress event, serial 27, synthetic NO, window 0x3800001,
root 0x26, subw 0x0, time 492725957, (100,0), root:(101,521),
state 0x0, keycode 40 (keysym 0x64, d), same_screen YES,
XLookupString gives 1 characters: ``d''
This information tells us that the ``d'' key is bound to KeyCode 40. When trying to find keycodes for particular keys, xev is very helpful. Remember that KeyCodes are bound to particular physical keys on the physical keyboard. KeySyms are not until you use the keyboard remapping feature in GTKeyboard.
The final field is a modifier mask. This field is only used for modifier keys. A modifier key is generally a key that doesn't output a character by itself, it modifies another keystroke. Examples include Caps Lock, Alt, Control, and Shift. Each modifier key may be followed by a modifier mask. There are eight possible modifier masks, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. Modifier masks for modifier keys are mandatory for keyboards which you wish to do remapping with. GTKeyboard cannot successfully remap keyboards whose definitions do not contain modifier masks.
You may specify the mask for each modifier. As the name suggests, ShiftMask is a good choice when specifying the modifier for Shift_L and Shift_R. The keyboard file may specify any modifier mask for any modifier, but the general rule is that Shift_L and Shift_R are assigned to ShiftMask, Control_L and Control_R are assigned to ControlMask, Caps_Lock is assigned to LockMask, Alt_L and Alt_R are assigned to Mod1Mask, and Mode_switch is assigned to Mod2Mask. Keys that perform the same function, (as with Shift_L and Shift_R) should use the same modifier mask. Each modifier mask may hold no more than 2 distinct keys unless you know that your X server can handle more.
Once your keyboard definition file is successfully constructed, there's nothing else to it - you can simply load GTKeyboard, and use the ``Change Layout'' function to load your new keyboard onto the screen.