InternationalKeyboard 0.50
==========================

This document describes version 0.50 of the International Keyboard module.
Version 0.50 is a significant break from previous versions in that:

    1) All keyboard definitions are in terms of the Universal Character Set
       (UCS).
    2) Keyboards with two layers are supported.
    3) All keyboards will work with any alphabet.
    4) Keyboard definitions are now described textually.
    5) Special keys like Caps Lock are now relocatable.
    6) The module understands *Alphabet UTF8.
    7) Unusual Caps Lock pairings are now possible (eg Swiss é key)
    8) Dead key tables much fuller - for example it is now possible to
       generate r-acute on the UK layout, if r-acute is in the current
       alphabet.

From the user's point of view, the new module providing the UK layout should
be identical when the alphabet is Latin-1, but the difference will show when a
different alphabet is selected. The differences can be summarised by the following
table showing the codes inserted into the keyboard buffer for different key
sequences with different *Alphabet settings:

Previous UK keyboard driver:
                                 Current Alphabet
Key sequence      Latin1              Welsh               UTF8
A                 61 = a              61 = a              61 = a
F1                81 = F1             81 = F1             81 = F1
Shift-3           00 A3 = pound       00 A3 = pound       00 A3 = [illegal]
Shift-`           00 AC = not sign    00 AC = Y-grave     00 AC = [illegal]
Alt-' W           00 82 = w-circ      00 82 = [illegal]   00 82 = [illegal]
Alt-[ W           77 = w              77 = w              77 = w
Alt-keypad 1,8,9  00 BD = one-half    00 BD = W-diaeresis 00 BD = [illegal]
Alt-1,2,4,0,2     72 = r              72 = r              72 = r

New UK keyboard driver:
                                 Current Alphabet
Key sequence      Latin1              Welsh               UTF8
A                 61 = a              61 = a              61 = a
F1                81 = F1             81 = F1             81 = F1
Shift-3           00 A3 = pound       00 A3 = pound       00 C2 00 A3 = pound
Shift-`           00 AC = not sign    no output           00 C2 00 AC = not sign
Alt-' W           00 82 = w-circ      00 F0 = w-circ      00 C5 00 B5 = w-circ
Alt-[ W           77 = w              00 BA = w-acute     00 E1 00 BA 00 83 = w-acute
Alt-keypad 1,8,9  00 BD = one-half    00 BD = W-diaeresis 00 C2 00 BD = one-half
Alt-1,2,4,0,2     72 = r              72 = r              00 E3 00 81 00 B2 = hiragana "hi"

The InternationalKeyboard module uses Service_International 8 to read the UCS mapping
for the current alphabet - if unable to find the UCS map for the current alphabet
it maps UCS codes 80-FF to 00 80 - 00 FF.

Layout files
============
Layouts are now described in a textual layout file.

Blank lines and lines beginning with # are ignored. The file is delimited by
directives beginning with $. The first directive should be $Country <n>. This may be
followed by multiple $Layer sections, and optionally a $Keypad section.

$Layer
======

A layer section begins with a $Layer <n> line, and is terminated by $EndLayer.
The primary layer is numbered 0, and a second layer (1) may be supplied. This layer
is used if OS_Byte 202 bit 5 is clear.

The layer section contains a series of key definitions, in any order. A key
definition consists of a 2-digit hex number on the first line, followed by eight
lines giving the character for each part of a key:

<key number> {replace}
<key>
<Shift+key>
<Ctrl+key>
<Ctrl+Shift+key>
<Alt+key>
<Alt+Shift+key>
<Alt+Ctrl+key>
<Alt+Ctrl+Shift+key>

To replace a previously defined character (which may be required when included
files are in use), you must add the word "replace" after the key number.

The 10 standard modifier keys (Left Shift, Right Shift, Left Ctrl, Right Ctrl,
Left Alt, Right Alt, Select, Menu, Adjust, Break) need not, and indeed cannot,
be specified in a layer. However, it is possible to override the behaviour
of any of these keys to act like a standard key.

Any pairs of characters may be tagged as a capital/lower case pair by placing
a bracket symbol in front of each character name. Bracket symbols are [], {},
<> and () - the opening bracket marks the lower-case character and the closing
bracket marks the upper-case character. Keys should be defined with the
characters as if Caps Lock is off - the bracket characters tell the key how
to behave if Caps Lock or Shift-Caps Lock is on.

A character name may take the form of

1) A UCS identifier, such as:

   LATIN CAPITAL LETTER A        (ie U+0041)
   EURO SIGN                     (ie U+20AC)
   CJK UNIFIED IDEOGRAPH-5F24    (ie U+5F24)
   HANGUL SYLLABLE GGAS          (ie U+AE5F)

2) A control code:

   FUNCTION KEY CTRL-Q           (ie &11)
   FUNCTION KEY CTRL-?           (ie &7F)

3) A function key specifier:

   FUNCTION KEY F1               (ie &81)
   FUNCTION KEY CTRL-UP          (ie &AF)
   FUNCTION KEY CTRL-SHIFT-ENTER (ie &0D)
   FUNCTION KEY &FE              (ie &FE)

   Valid code names are:

   08 BACKSPACE
   0D ENTER
   1B ESCAPE
   1E HOME
   7F DELETE
   80 PRINT / F0
   81 F1
   82 F2
   83 F3
   84 F4
   85 F5
   86 F6
   87 F7
   88 F8
   89 F9
   8A BREAK
   8B COPY / END
   8C LEFT
   8D RIGHT
   8E DOWN
   8F UP
   9E PAGE DOWN
   9F PAGE UP
   C0 ACORN
   C1 MENU
   C2 WIDTH
   C3 KANJI
   C4 EISUU
   C5 NO CONVERSION
   C6 CONVERT
   C7 KANA
   C8 ALL CANDIDATES
   C9 KANJI NUMBER
   CA F10
   CB F11
   CC F12
   CD INSERT

   Any of these may be preceded by either or both of "CTRL-" or "SHIFT-"
   (in that order). Under RISC OS, keys above &80 are exclusive ored
   with &10 for Shift, and &20 for Ctrl, so CTRL-SHIFT-F10 is &FA.
   Keys below &80 are not affected by Shift or Ctrl. However, it is
   suggested that the SHIFT- and CTRL- suffixes be put in for future
   compatibility. Likewise, "FUNCTION KEY ESCAPE" and "FUNCTION KEY CTRL-["
   are totally equivalent at the moment, but might not always be - it
   is probably better to use the higher-level description.
   
   Note that there is normally no "FUNCTION KEY BREAK" - the Break key
   is a hard-coded shifting key, and RISC OS inserts code &8A into the
   keyboard buffer after a reset. The Wimp sets up Tab using OS_Byte 219
   to produce code &8A.
   
   Similarly, "FUNCTION KEY DELETE" gives traditional behaviour - there
   is now a CMOS bit that determines whether Delete produces code &08
   or &7F - use "SPECIAL KEY DELETE" to call the code that checks this bit.

4) A special key:

   SPECIAL KEY SCROLL LOCK

   Normally the special key will occupy all 8 shift/ctrl/alt variants, but
   there are some exceptions. For example Caps Lock is only on the
   shifted form of the key on a Japanese keyboard.

   Special keys are those that require specific code to handle them. These
   are:

   CAPS LOCK
   NUM LOCK
   SCROLL LOCK
   TAB
   KANA LOCK
   SHIFT-CAPS LOCK
   DEFAULT KEYBOARD
   CONFIGURED KEYBOARD
   DIAL KEYBOARD
   DELETE

   Most keyboard layouts have the first four keys,
   in their standard places. In these cases, you should not include
   the keys in the layout file - this will save some memory. For each
   key position &0E, &22, &26, &5D, if it is not mentioned in any
   layer, it will perform its normal function in all layers. If it's
   altered in any layer, its function must be explicitly stated in
   all layers.

   TAB must be special because the code it generates can be altered using
   OS_Byte 219.

   SHIFT-CAPS LOCK toggles Shift-Caps on and off, irrespective of
   the Shift key being held down. CAPS LOCK performs the normal
   Caps Lock function, looking at the Shift key to determine whether
   to toggle Caps Lock or enter Shift-Caps.

   DEFAULT KEYBOARD selects the default (UK) keyboard. This is normally
   assigned to Alt+Ctrl+F1.

   CONFIGURED KEYBOARD selects the configured keyboard. This is normally
   assigned to Alt+Ctrl+F2.

   DIAL KEYBOARD allows the user to select a keyboard by entering the
   appropriate international dialling code on the keypad while Alt remains
   held down. This key must be in an Alt position, and is normally
   assigned to Alt+Ctrl+F12.

   DELETE produces either code &7F or &8B depending on the configuration.

5) A dead accent key:

   DEAD KEY ACUTE ACCENT
   DEAD KEY RING ABOVE
   
   Valid dead keys are currently:
   
   GRAVE ACCENT                        U+0300
   ACUTE ACCENT                        U+0301
   CIRCUMFLEX ACCENT                   U+0302
   TILDE                               U+0303
   MACRON                              U+0304
   BREVE                               U+0306
   DOT ABOVE                           U+0307
   DIAERESIS / GREEK DIALYTIKA         U+0308
   RING ABOVE                          U+030A
   DOUBLE ACUTE ACCENT                 U+030B
   CARON                               U+030C
   VERTICAL LINE ABOVE / GREEK TONOS   U+030D
   CEDILLA                             U+0327
   OGONEK                              U+0328
   GREEK DIALYTIKA TONOS               U+0344
   STROKE                              U+0335
   
   Each entry shows the equivalent UCS code, although this is not
   used internally.
   
   These can easily be added to by extending the table generator and
   Source.Accents, but once you get to 31 there will need to be
   a code redesign.

6) Nothing:

   -

$Keypad
=======
This section defines the 17 keypad keys, in order:

                      23  24  25
                  37  38  39  3A
                  48  49  4A  4B
                  5A  5B  5C  ||
                  --65--  66  67

If the section is omitted, the default keypad is used (saving memory):

        $Keypad
        SOLIDUS
        ASTERISK
        NUMBER SIGN
        DIGIT SEVEN;        FUNCTION KEY HOME
        DIGIT EIGHT;        FUNCTION KEY UP
        DIGIT NINE;         FUNCTION KEY PAGE UP
        HYPHEN-MINUS
        DIGIT FOUR;         FUNCTION KEY LEFT
        DIGIT FIVE;         -
        DIGIT SIX;          FUNCTION KEY RIGHT
        PLUS SIGN
        DIGIT ONE;          FUNCTION KEY END
        DIGIT TWO;          FUNCTION KEY DOWN
        DIGIT THREE;        FUNCTION KEY PAGE DOWN
        DIGIT ZERO;         FUNCTION KEY INSERT
        FULL STOP;          FUNCTION KEY DELETE
        FUNCTION KEY ENTER
        $EndKeypad

You need to supply seventeen lines, containing one or two key names
separated by a semicolon. The first is the character with Num Lock on,
the second with Num Lock off. If only one name is supplied, the key
is Num Lock invariant.

Note that it is currently only possible to put UCS codes 00-7F, RISC OS
function keys or nothing on the keypad.

$LeftAltLayerSwitch
===================
This directive, initially added for the Russian layout, enables the ISO
standard mechanism for switching between keyboard layers. If this directive
is included in a layout file, then the left-hand Alt key will can no longer
be used in conjunction with other keys to get extra characters. Instead, its
only function is to switch between the keyboard layers when pressed with
either Shift key.

In the future, if more than two layers are allowed, the left-hand Alt key
will cycle between the layers, in a direction determined by which Shift key
is pressed.

$FNKey
======
This section defines mappings for a FN key, as found on reduced keyboards.
For example:

        $FNKey
        01 0B
        02 0C
        $EndFNKey

One line is provided for each key that represents another key when FN is
pressed. The first number is the key number of the base key, and the second
number is the key number of the key in conjunction with FN.

This mapping only affects generated characters - if FN+F2 is F12, then
pressing FN+F2 will insert the standard F12 code into the keyboard buffer,
but INKEY -30 will not report F12 as being down.

Modifier keys may not be included in the list.

If no FN mappings are defined, FN will be ignored. If any mappings are
defined, then FN plus an unmapped key will generate no output.

It is generally preferable for keyboards with FN to process it in hardware,
as in the A4, but this facility is provided for when this isn't done.

%Include
========
A simple facility for inclusion of other files is available - just
place "%Include <filename>" on any line. The magic filename "@ExtraKeys@"
is the value of the command line parameter "-extra". If no -extra
parameter was specified, the include directive is ignored. In the future,
the @..@ syntax may be extended to a full macro capability.

$Wide
=====
This directive, placed before the first layer definition, is used to indicate
that a key handler which uses the new 'wide' (16bit) internal/low-level key
numbers should be generated. You'll need this if you want to use an internal or
low-level key number which is greater than 127. Attempts to use wide key
numbers without specifying this directive will trigger an error.

$Type
=====
This directive is used to indicate the keyboard type. By default keygen assumes
a layout for a PC keyboard is being generated (making use of
InternationalKeyboard's builtin PC keyboard INKEY reverse lookup table), but by
using this directive you can generate a layout for a different keyboard type
(e.g. "$Type Pandora" for a Pandora keyboard layout)
