PROTOTYPE 4 KEY FILES
=====================

This document describes briefly how to create KEY files to be compiled with
the prototype 4 KEY-compiler (KEYCOMP).

To learn how to use each version of the compiler, type

  KEYCOMP /?

as this file affects only the format of the KEY files.

NOTE: KEY files described in this document may be incompatible with the KEY
      files used for xKEYB and for prototypes 1-3 of KEYB2.

NOTE: KEY files described in this document are definitely incompatible with
      the KEY files that will be user with the standard compiler, to appear
      in the prototype 5.

In this document, we will refer to prototype 4 KEY files simply as KEY files,
unless stated otherwise.


GENERAL FORMAT
==============

A KEY file is a normal text file, which the compiler takes as input. Any blank
line, or any line starting with the ; character is ignored by the compiler
(and can be used for comments).

The KEY file is composed of three sections, being the first one mandatory, and
the later two optional.

Each section begins with the name of the section between sqare brackes: [] 

NOTES:
(1) The order of the sections MUST be preserved. 
(2) In the names of the sections, the compiler does not make any distinction
    on case.

The sections are, on this order,

[KEYS]
[COMBI]
[XSTRINGS]


KEYS Section
============

This section is mandatory. Each line in this section represents a key whose
behaviour is affected. The general format of a line is:

  S  [T] [C] ...

where
     S    scancode specifier with flags
     C    effect

the line can be up to 5 effects long, and at least one effect must be
specified, unless the flag X is used (in which case, 0 characters may be
specified).

The scancode specifier is of the form:

  [E]n[C][N][Sm][X]

where

     [E]n   scancode number (makecode). The E is optional, and indicates that
            the key has the E0 prefix. For a map of all the keys, see

http://panda.cs.ndsu.nodak.edu/~achapwes/PICmicro/keyboard/scancodes1.html
http://www.geocities.com/SiliconValley/Program/6366/keyboard/keyboard002.htm


     CNSmX  are the flags. The order of them is irrelevant, PROVIDED if S is
            specified, a number must mandatorily follow it.

              C    The key is affected by CapsLock
              N    The key is affected by NumLock
              Sm   The key changes its returned scancode to m
              X    The key is completely locked and ignored (used to disable
                   keys on a keyboard)


An effect is either a character (see section below), or of the form

     [![l]]n

The later form is used to specify a COMMAND (see the command document).

In this version, the number of effects is limited to 5, where the columns
correspond to the following combinations

   -    SHIFT    CTRL    ALT    ALTGr

If a character is specified under certain column, then when the appropriate
character is released, otherwise the corresponding command is executed.

In the command format, n is the number of the column, and l is an optional
letter that specifies a constant to be added, to make the commands more
readable. The letters are:


      Letter    Constant   Meaning
     ============================================================
       !C       199        COMBI
       !L        99        Change layout
       !S       119        Change submapping
       !A       169        Alternative character introduction
       !O       179        User defined locks
       !H        89        user defined shifts
     ============================================================

EXAMPLE:  !S1 is equivalent to !120

HINT: 0's compress better, so try to use !0 if the character is already
      produced by the preceding KEYB handler (probably BIOS).

HINT: If less than 5 columns are described, missing ones are interpreted
      as !0, although some space is saved. For example:

         12  '  ?  !0  !0  !0
         12  '  ?

      are equivalent, but the former produces a smaller .KC file. Try to
      avoid trailing !0's


Specifying a character
======================

A character is specified on one of the following forms

     c         a character of code>33, other than #
     #!        specifies the character !
     ##        specifies the character #
     #n        specifies the character n on the current codepage


COMBI section
=============

The COMBI section describes how to combine characters. The first line
describes how to create the combined character for the first COMBI
command, the second line for the second COMBI command, etc.

The line has the format

C0  C1C2  C3C4  C5C6 ...

where Ci's are characters (except for C0, they can be specified as
mentioned in the preceding section). Up to 254 pairs can be
specified.

C0 is the mark which is added to the letter (such as '), and each pair is a
marked/unmarked pair, (such as a).

NOTE: In order for the layout section to work properly, the KEYS section MUST
      have all the non-combined characters (and they shouldn't be chained to
      the previous handler with !0). For example, include the letter a if you
      want to produce  with COMBIs.

HINT: It is convenient to add the space in each line (such as #32') to make
      it possible to get the mark character alone.


XStrings
========

The last section contains the XStrings, sequentially, and one per line.
The contents of the XStrings are free, except for the fact that special
effects may be used if preceded by the character \

The following effects are possible:
	   \Axxx         Produces the character of code xxx
	   \Kxxx,yyy     produces the character code yyy with scancode xxx
	   \Sxxx	 Produces the character 0 with scancode S
	   \n		 Produces a carriage return
	   \\		 Produces the \ character
	   \[key]        Simulates the pressing of a key

The simulated keys can be:

     HOME
     END
     PGUP
     PGDN
     UP
     DOWN
     LEFT
     RIGHT
     DEL
     INS
     Fx  (function)
     SFx (shift+function)
     CFx (control+function)
     AFx (alt+function)

=========== END OF DOCUMENT ===============
