NAME

xarmkeymap − keyboard map file generator for Xarm

SYNOPSIS

xarmkeymap [ -v ] [ -q ] [ -kfile output file ] [ input file ]

DESCRIPTION

Xarmkeymap is a utility program which will generate a keyboard mapping file for use by Xarm(1).

The output is a binary file which can be used as an argument to the -kfile option to Xarm(1).

The input to xarmkeymap is a text file, and so can be read using any editor.  The output contains binary data, however the indentification fields can be extracted using strings(1). This will display the file header, the name of the keyboard description, a drawing number (of an Acorn specification which describes the keyboard) and finally the file trailer - a copyright message.

OPTIONS

-v Verbose output − the program outputs a few messages about what it is doing. 

-q Quiet output − no error messages are output.  The only indication of success is the program return code. 

-kfile output
Specifies the name of the output file.  The name may contain a %d escape which is replaced by the keyboard id (from the input file).  Because sprintf(3) is used to produce the output file name other numeric escapes may be used - see the documentation of sprintf. No checks are made to ensure that the argument to -kfile contains a sensible escape sequence.  Use of invalid (non-numeric) escape sequences will cause the program to crash. 

INPUT FORMAT

Input to xarmkeymap consists of lines of text each of which may be a blank line, a tagged parameter or a key definition.  All lines may also contain comments, a comment starts with the first # character in the line and continues to the end of the line.  Blank lines (including lines which consist solely of space or tab characters and comments) are ignored.  Tagged parameters consist of the parameter name, terminated with a : character, white space (space or tab characters) then the value of the parameter - all the remaining characters up to the end of the line or the start of a comment.  Space characters are included in the value.  The following tags are recognised:-

ID: The value is a (decimal) number giving the keyboard id to which this description applies.  This tag must occur in the file. 

NAME:
The name of the keyboard.  Normally the name of a country for which the keyboard definition is intended.  The first fifteen characters of the value are stored in the output file.

DRAWING:
A 14 character drawing number with format XXXX,XXX/Yy-Ii with these characters replaced as follows:-

XA digit (0-9)
,A comma
/A forwards slash
YA capital letter (A-Z)
yA capital letter or a space
-A hyphen
IA digit or a capital letter
iA digit, captial letter or space

If the NAME: or DRAWING: parameters are not specified the relevant fields of the output are replaced by <undefined>.  The ID: field must be given, but it is only used when generating the output file name from the -kfile parameter. 

All other lines of the file are interpreted as key definitions.  These have the format:-

[shift]keykeysym {keysym} [XTestCommandKey]

Items enclosed in [] are optional.  Items enclosed in {} are optional and may be repeated.  The shift item, if given, specifies that the key is a standard X modifier.  It must be one of Shift Lock Control Mod1 Mod2 Mod3 or Mod5.  The keysym items specify up to four keysyms which are mapped to the key.  The keysyms are interpreted exactly as in the ChangeKeyboardMapping protocol request.  A single keysym has the same format as a (valid) argument to the function XStringToKeysym(3X11). The value NoSymbol may also be used. 

The optional XTestCommandKey argument may be appended to one definition.  It indicates that this key is to be used for the XTESTEXT1 input synthesis extension as the command key. 

The key item specifies the key (KeyCode) to be defined.  It must either be an A series keyboard key position or a scan row/column digit pair identifying the keyboard.  The easiest way to find the valid key positions is to examine the file /usr/lib/X11/XKeyboard/UK.key which defines the key positions for the UK national variant of the A series keyboard.  There are 112 valid key codes, in the range 8-119 (inclusive).  Each code is obtained by adding 8 (to leave space for the mouse buttons) to the hex value RC where R is the scan row (0-6) and C is the scan column (0-F).  Key positions relate directly to the position of the key on the keyboard.  A valid key position has the format Xn or Xnx where X is a capital letter from the set A, B, C, D, E, F, n is a number in the range 1-22 and x is one of a or b.  (This latter form is used to name key positions which change with national variants).  All the valid key positions are contained in /usr/lib/X11/XKeyboard/UK.key. The initial letter is the row of the keyboard, starting at the bottom (space bar row) with A and going up to the function keys (F).  The number is a count of the key position from the leftmost key on the keyboard (1).

FILES

/usr/lib/X11/XKeyboard/KB%d - files used by the server

SEE ALSO

Xarm(1)

AUTHORS

JB, Acorn Computers Ltd

Acorn Computers Ltd  —  Revision 1.1 of 19/04/90