HOW TO DEFINE NEW KEYBOARD TEMPLATES
====================================

First, make sure you have absolutely the latest version!  Someone may have
defined the keyboard you're interested in already, or, more importantly, the
data format may have changed (this has happened once, and converting from
the old format to the new format was non-trivial.)  You can get the latest
version of xkeycaps by FTP to LUCID.COM or FTP.X.ORG.

XKeyCaps needs to know four pieces of information about each keyboard:

  -  The physical layout of the keyboard, meaning the size and position
     of each key and the blank spaces between them;
  -  The text that is physically printed on the surface of each key;
  -  The KeyCodes by which the X server knows each key;
  -  The contents of the default KeyCode->KeySym map which is in effect
     just after X starts up and before any user customizations.

Since any subset of these four data may be shared among different keyboards,
they are specified independently, each in its own file.  If the keyboard you
use has keys shaped exactly like another keyboard that xkeycaps already knows
about, then you can use the existing data; for example, pc101-geom.h is used
by a number of keyboards (RS6K, SGI, etc.)

If you're defining a template for a non-US version of a keyboard which xkeycaps
already knows about, you will probably only need to change two things: the
default keymap, and the text that is physically printed on the key surfaces.
The geometry and keycodes are generally the same (and often the keycaps are
very similar.)

Geometry:
=========
  If your keyboard is not shaped exactly like one that is already present,
  you will need to create a new -geom.h file for it.  Start with the one that
  is closest to the shape of your keyboard, and modify it.  The "rows" of a
  keyboard are defined in the -geom.h file as a set of { width, height }
  pairs of each key on the keyboard in some arbitrary units.  If the height
  is specified as 0, then this means that this area is a blank space between
  keys instead of a key itself.

  If your keyboard uses the same (or very similar) geometry as another
  keyboard, there is a good chance you can reuse an existing -caps.h file as
  well.  This file defines the strings which are physically printed on the key
  surfaces.  There may be up to three strings on each key: upper left, lower
  left, and upper right.  If there is no string, then 0 should be used.  This
  file must have exactly one entry for each actual key on the keyboard (and
  should not have entries for the "blank" spaces.)  The keys should appear in
  the same order as in the -geom.h file, that is, left-to-right, top-to-bottom.

KeyCodes:
=========
  The -codes.h files define the keycodes which the X server sees for this
  keyboard hardware.  The entries should be in the same order as in the other
  two files, and there must be exactly the same number of entries in the
  -codes.h and the -caps.h files (which is the total number of keys on the
  keyboard.)

  If a key on the keyboard is not recognised by the X server at all (that is,
  it is intercepted locally without clients getting a KeyPress event at all)
  then its keycode should be specified as 0.

  The easiest way to find the keycodes for the various keys is to run the `xev'
  program and type each key in turn.  But be careful of window managers which
  intercept certain keys for their own purposes.

KeyMaps:
========
  The -map.h files contain the default keymaps which the X servers use for the
  various keyboards.  It's very easy to generate these files: the enclosed
  shell script called `build-map.sh' will parse the output of the `xmodmap'
  program, and write a -map.h file to standard output.  This generated file
  will encode the current state of the keymap.

  It is VERY IMPORTANT that you run the build-map script before you have ever
  changed your keyboard mapping with xmodmap: you don't want to capture your
  personal modifications within the XKeyCaps configuration!  If you make any
  changes to your keyboard, find the place where your init files do this, and
  comment it out.  Then restart the X server (this may mean logging out and
  then back in again.)  Then build the -map.h file.

Installation:
=============
  After creating the various files, add them to the obvious two places in the
  file kbds/all-kbds.h -- #include them at the top, and add a call to KBD() at
  the bottom.  The arguments to the KBD() call are the "short" name of this
  keyboard (for the -kbd command-line argument); the long, descriptive name,
  the vendor ID string which identifies this keyboard, or 0; and then pointers
  to the various data defined in the geom, caps, codes, and map files.

  It's a good idea to specify a vendor ID string if possible, because
  otherwise it will 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' and `hpux.c' do.  (This only helps
  when $DISPLAY points to screen zero of the local machine, of course.)

Debugging:
==========
  If you have mis-specified some data, then when you select your new keyboard,
  xkeycaps will print "DATA ERROR" messages to stderr describing what it thinks
  is wrong with your input files.

  An easy mistake to make is leaving entries out of either the -caps or -codes
  files; these will be flagged with messages like "101 keycaps vs 100
  keycodes", meaning that a keycode is missing somewhere.  It should be easy to
  figure out which one is missing by simply pressing the keys in turn, and
  seeing when the wrong one lights up in the xkeycaps display.

  A message containing "reached end of caps/codes tables with keys left over"
  means that the -kbd file defined more real keys than there are entries in the
  -caps and -codes files.  This could mean that there are entries missing from
  both the -caps and -codes files, or it could mean that there is a key where
  there should be a blank space in the -geom file.

  A message containing "couldn't find keymap entry" means that some key on the
  keyboard generates a keycode which is not mentioned in the -map file.  This
  is not necessarily an error on your part: some vendors' default maps do not
  assign all existant keycodes.  In that case, you should suppress this warning
  by adding a dummy entry to the -map file; see kbds/sun5-map.h for an example.

  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!  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.

  Type each key on the keyboard in turn, and verify that the corresponding key
  in the xkeycaps display lights up.

  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!  Once you've added a new keyboard definition, please send
your changes to me, and I will include them in the next release.