
HOW TO DEFINE NEW KEYBOARD TEMPLATES
------------------------------------

If the keyboard you use looks superficially like any of the keyboards that
XKeyCaps already knows about (which is likely) then it's not terribly hard
to define a new keyboard.  You need to know three things: the text actually
printed on the surface of each key; the keycode generated by each key; and
the default keysyms and modifiers generated by that code.

You can get the keysyms and modifiers generated by each keycode in a reasonable
format with the output of "xmodmap -pk" and "xmodmap -pm".  Be sure to run this
before you have ever changed your keyboard mapping with xmodmap: you don't want
to capture your personal modifications within the XKeyCaps configuration!

The easiest way to find the keycodes generated by each key is to run "xev",
and press each key in turn.

The format of each line in the kbd- header files is this:

{ keycode, "top string", "bottom string", w, h, modbits, keysym1, keysym2 ... }

The `code' field is the keycode that the key generates.  If a key doesn't
generate a keycode (that is, X doesn't know about that key at all) its
keycode should be 0.

The strings are what is actually printed on the key, top string first.  
The second string may be 0 if there's only one string on the key.  

The width and height are in arbitrary units; I've found 7 to be the most
convenient.

The `modbits' field should be the modifiers that this key generates by
default, as in

 {106,	"Shift",	0,	16, 7,	ShiftMask,	XK_Shift_L},

The keysyms are the symbols that the key generates by default.  There may be
up to 8 keysyms per key, but most keyboards have no more than 3 (US keyboards
probably don't have more than 2.)  You need specify only as many keysyms as
the key generates; missing keysyms will default to NoSymbol.

The keysyms are in the order that the X server knows them, which means that
the keysyms and keycap-strings are probably in opposite orders.  For example,
the key with "2" and "@" looks like this on a Sun:

 {38,	"@",		"2",	7, 7,	0,		XK_2,	XK_at},

If all the elements in the key description are 0 except for width and height,
then it's not a real key: it's just a blank space.  These "keys" are used to
insert space between the main keyboard and the keypad, for example.

Probably the easiest way to define a new keyboard is to copy the most-similar-
looking existing keyboard file and modify it.  First change the strings and
widths of the keys to match the keyboard you're typing on.  This tends to be a
lot of trial and error to get the widths right, but probably won't take more
than 45 minutes or so.

Be especially careful when entering the default keysyms of function keys and
special-purpose keys like "Break" and "Option".  In a lot of instances, the
keysyms generated by these keys have no obvious relation to what is printed on
the surface of the key.  The output generated by "xmodmap -pm" and "xmodmap
-pk" will be helpful for this.

After you've created your new kbd-*.h file, the next step is to add it to the
two obvious places in "all-kbds.h"; add it to the ALL_KBDS variable in the
Imakefile; and then email your changes to me (please!).

If your server has an unambiguously recognizable vendor-identification string,
you might also want to add an appropriate clause the function choose_kbd() in
the file guess.c.  The vendor id string is the string that XKeyCaps prints when
it starts up if it doesn't recognise your display.  You can also find it by
running the `xdpyinfo' program.  It's a very good idea to make XKeyCaps guess
what keyboard is being used based on the display type, because otherwise it no
doubt pick the wrong keyboard by default, and naive users could get hurt.

If you are defining a keyboard for a type of machine which has multiple
keyboards, you might want to add an OS-specific file for querying the keyboard
hardware directly, as sunOS.c does.  (This only helps when $DISPLAY points to
screen zero of the local machine, of course.)

The easiest way to determine whether you have the correct default configuration
is to execute the "Write Output" command, selecting the "Changed Keys" button.
If none of the lines written begin with "keycode", then you've gotten the
keysyms right.  *** Please do this.  Please please do this. ***  I have no way
of testing keyboard configurations of keyboards I don't have, so it's up to
you.  Make sure you haven't run xmodmap or executed the "Restore Default Map"
command since you started your X server, or your results will be invalid.

When you're done, it would be good if you would execute the "Restore Default
Map" command, and try living with the resulting configuration for the rest of
the day, just to make sure that you didn't inadvertantly cripple some key.

And that's about it!
