/*man-start*********************************************************************


========================================================================
APPENDIX 2 - KEYBOARD HANDLING IN THE
========================================================================

This appendix contains information on how THE handles keystrokes in the
U*ix environment.  One thing that is consistant with PCs is keyboard
handling.  Therefore this explanation is not applicable to the PC
arena.

Keystroke handling is a very complicated business! There are so many
layers between the physical keyboard and the application; in this case
THE. These layers can be best described with the following diagrams:

          +------------------------------------------+
          | Text-mode Version of THE using terminal  |
          +------------------------------------------+
          |                                          |
          |            Physical Keyboard             |
          |                    |                     |
          |                    |                     |
          |           [terminal emulator]            |
          |                    |                     |
          |                    |                     |
          |             Termcap/Terminfo             |
          |                    |                     |
          |                    |                     |
          |                 Curses                   |
          |                    |                     |
          |                    |                     |
          |                   THE                    |
          |                                          |
          +------------------------------------------+

          +------------------------------------------+
          |   Text-mode Version of THE using xterm   |
          +------------------------------------------+
          |                                          |
          |            Physical Keyboard             |
          |                    |                     |
          |                    |                     |
          |               X11 server                 |
          |                [xmodmap]                 |
          |                    |                     |
          |                    |                     |
          |                  xterm                   |
          |              [translations]              |
          |                    |                     |
          |                    |                     |
          |             Termcap/Terminfo             |
          |                    |                     |
          |                    |                     |
          |                 Curses                   |
          |                    |                     |
          |                    |                     |
          |                   THE                    |
          |                                          |
          +------------------------------------------+


                   +-----------------------+
                   |  X11 Version of THE   |
                   +-----------------------+
                   |                       |
                   |  Physical Keyboard    |
                   |          |            |
                   |          |            |
                   |     X11 server        |
                   |      [xmodmap]        |
                   |          |            |
                   |          |            |
                   |       PDCurses        |
                   |    [translations]     |
                   |          |            |
                   |          |            |
                   |         THE           |
                   |                       |
                   +-----------------------+

Each layer is described below

-----------------
Physical keyboard
-----------------

Each keyboard is potentially different from every other.  The similarity
that they do possess is that when a key is pressed, a unique code is
generated. The state of the Shift, Control, Num Lock, Alt modifiers
either alter the unique code generated or a separate code is generated
to identify to the next layer that the key pressed should be modified.

-----------------
terminal emulator
-----------------

This is a required layer if the user is connected to the host via some
emulation software. eg a PC connected to a U*ix host requires a terminal
emulator of one sort or another.

The terminal emulator translates the unique codes generated by the
keyboard usually into physical escape sequences that are passed to
the U*ix shell.  These escape sequences can be seen by running the
U*ix command 'cat -v'.  When you press a key on the keyboard while
in 'cat -v', the escape sequences that the terminal emulator has
generated are displayed. Some systems require the Enter key to be
pressed before the escape sequence is displayed.  The term "escape
sequence" is used because in most cases, the first character
generated is an Escape character (hex 1B).  Following the escape
is any number of other characters, which together form a unique
sequence of characters.

When using a terminal directly, firmware on the terminal does the
generation of the escape sequences. Some terminals allow the user
to specify what escape sequence will be generated when particular
keys are pressed.

----------------
Termcap/Terminfo
----------------

Each terminal that connects to a U*ix host is identified by the value
of the TERM environment variable.  The value of TERM is used to setup
various settings for the terminal.  These settings are stored in a
database; either in a flat file 'termcap' or in a compiled format
'terminfo'. Which one a particular system uses is dependant on the
version of the U*ix Operating System being run.

One of the capabilities of the termcap/terminfo databases is to
translate an escape sequence into a keyboard mnemonic that is used
by the Curses library functions.  This translation can also be
changed by the user.

An example of this is:

    +------------------------------
    Termcap:  ku=\E[A
    Terminfo: kcuu1=\E[A
    +------------------------------

This translates the escape sequence ESC [ A into the mnemonic ku or
kccu1.

------
Curses
------

The Curses library contains definitions of many keys.  These can be
seen by looking in the Curses header file; usually /usr/include/curses.h
Here you will see definitions like:

    +------------------------------
    #define KEY_UP 0403 /* up arrow key */
    +------------------------------

---
THE
---

As THE is a Curses-based application, it recognises the Curses key
definitions defined in curses.h.  As not all escape sequences are
usually defined in the Termcap/Terminfo databases, or are defined in
curses.h, THE also has special code to decipher other escape sequences.

When a key is pressed, and is interpreted by THE, the first action is
to check if the value passed to THE is a 'known' curses key. If it is
THE carries out any command associated with the key.  If the value
is not a 'known' curses key, THE assumes that an escape sequence is
forthcoming.  The module getch.c has code for deciphering many escape
sequences that are not normally defined in the Termcap/Terminfo
database.  Later in this document is a table of escape sequences and
its associated curses key.

----------
X11 Server
----------

When THE is run in a X environment, the X server acts in a similar way
to terminal emulation software.  The principal difference is that there
are more layers within the X server.  The translation of physical
keyboard codes to an X mnemonic is the first layer.  The code generated
is called a keycode.  This keycode is then translated into another
higher level mnemonic; a keysym.  The keysym is usually a name that
resembles the label on the physical keyboard.

The X environment provides a mechanism to assign keycodes to keysyms.
This is done with the xmodmap command, and any assignment of keycode
to keysym is done for all applications within the current X environment.

-----
xterm
-----

The xterm program is a terminal emulation program, and as such has many
of the properties of the terminal emulator described above.
The xterm program takes keysyms from the X11 server and generates
escape sequences, which are defined in the xterm entry in the Termcap/
Terminfo database.

One of the features of xterm is the ability to alter the standard keysym to
escape sequence translation.  Surprisingly this is via a feature called
'translations'.  Not only do these translations enable the user to
specify a different escape sequences to be generated, but internal
xterm commands can also be assigned.  These are beyond the scope of
this description. An example of an xterm translation follows:

    +------------------------------
    *VT100.Translations: #override\n\
     <Key>F1: string(0x1b) string("[192z")\n\
     <Key>F2: string(0x1b) string("[193z")\n
    +------------------------------

This specification is typically part of your own $HOME/.Xdefaults file.
This file is usually read dynamically by the xterm program on startup.
On some systems, the .Xdefaults file is ignored.  To ensure the entries
are incorporated into the X server resource database, run the command:

    +------------------------------
    xrdb -merge .Xdefaults
    +------------------------------

The above example will generate the escape sequence ESC [ 1 9 2 z when
the F1 key is pressed.  The trailing "\" is a continuation character.

So, if you had the above translation in effect, and were running THE in
an xterm, and ran the SHOWKEY command, pressing the F1 key would result
in THE responding with F11.

--------
PDCurses
--------

The actions performed by PDCurses in the X environment combine the
xterm, Termcap/Terminfo and curses actions. This results in fewer
layers to be traversed.

PDCurses takes a keysym from the X server and converts it into a
Curses key code.  PDCurses also has the same translation capabilities
as does xterm.  The xterm example above would look like:

    +------------------------------
    *the.Translations: #override\n\
     <Key>F1: string(0x1b) string("[192z")\n\
     <Key>F2: string(0x1b) string("[193z")\n
    +------------------------------

All the details described in xterm as far as translations are concerned
hold for translations in PDCurses.

Another capability that translations offer is the ability to assign
international characters to alphabetic characters, while still having
the alphabetic characters available.  For example, the translations
below assigns the action of the Shifted Meta key and A, giving a
capital A with a grave accent, and the unshifted Meta key and A giving
a small A with a grave accent.

    +------------------------------
    *the.Translations: #override\n\
     !Shift Meta <Key>a: string(0xc0) \n\
     !Meta       <Key>a: string(0xe0) \n
    +------------------------------

The examples above assume you are using a font with a character set that
is compatible with ISO 8859-1.

---------------------------------------
THE Escape Sequence to Key Name Mapping
---------------------------------------

 +------------------+----------------+----------------+
 | Escape Sequence  |  Curses Key    |  THE Key Name  |
 +------------------+----------------+----------------+
 | (pre) 1 ~        | KEY_Find       | FIND           |
 | (pre) 2 ~        | KEY_InsertHere | INS            |
 | (pre) 3 ~        | KEY_Remove     | DEL            |
 | (pre) 4 ~        | KEY_Select     | SELECT         |
 | (pre) 5 ~        | KEY_PrevScreen | PGUP           |
 | (pre) 6 ~        | KEY_NextScreen | PGDN           |
 | (pre) 1 1 ~      | KEY_F(1)       | F1             |
 | (pre) 1 2 ~      | KEY_F(2)       | F2             |
 | (pre) 1 3 ~      | KEY_F(3)       | F3             |
 | (pre) 1 4 ~      | KEY_F(4)       | F4             |
 | (pre) 1 5 ~      | KEY_F(5)       | F5             |
 | (pre) 1 7 ~      | KEY_F(6)       | F6             |
 | (pre) 1 8 ~      | KEY_F(7)       | F7             |
 | (pre) 1 9 ~      | KEY_F(8)       | F8             |
 | (pre) 2 0 ~      | KEY_F(9)       | F9             |
 | (pre) 2 1 ~      | KEY_F(10)      | F10            |
 | (pre) 2 3 ~      | KEY_F(11)      | F11            |
 | (pre) 2 4 ~      | KEY_F(12)      | F12            |
 | (pre) 2 5 ~      | KEY_F(49)      | F13            |
 | (pre) 2 6 ~      | KEY_F(50)      | F14            |
 | (pre) 2 8 ~      | KEY_F(51)      | F15            |
 | (pre) 2 9 ~      | KEY_F(52)      | F16            |
 | (pre) 3 1 ~      | KEY_F(53)      | F17            |
 | (pre) 3 2 ~      | KEY_F(54)      | F18            |
 | (pre) 3 3 ~      | KEY_F(55)      | F19            |
 | (pre) 3 4 ~      | KEY_F(56)      | F20            |
 | (pre) 3 7 ~      | KEY_F(13)      | S-F1           |
 | (pre) 3 8 ~      | KEY_F(14)      | S-F2           |
 | (pre) 3 9 ~      | KEY_F(15)      | S-F3           |
 | (pre) 4 0 ~      | KEY_F(16)      | S-F4           |
 | (pre) 4 1 ~      | KEY_F(17)      | S-F5           |
 | (pre) 4 2 ~      | KEY_F(18)      | S-F6           |
 | (pre) 4 3 ~      | KEY_F(19)      | S-F7           |
 | (pre) 4 4 ~      | KEY_F(20)      | S-F8           |
 | (pre) 4 5 ~      | KEY_F(21)      | S-F9           |
 | (pre) 4 6 ~      | KEY_F(22)      | S-F10          |
 | (pre) 4 7 ~      | KEY_F(23)      | S-F11          |
 | (pre) 4 8 ~      | KEY_F(24)      | S-F12          |
 | (pre) 4 9 ~      | KEY_F(25)      | C-F1           |
 | (pre) 5 0 ~      | KEY_F(26)      | C-F2           |
 | (pre) 5 1 ~      | KEY_F(27)      | C-F3           |
 | (pre) 5 2 ~      | KEY_F(28)      | C-F4           |
 | (pre) 5 3 ~      | KEY_F(29)      | C-F5           |
 | (pre) 5 4 ~      | KEY_F(30)      | C-F6           |
 | (pre) 5 5 ~      | KEY_F(31)      | C-F7           |
 | (pre) 5 6 ~      | KEY_F(32)      | C-F8           |
 | (pre) 5 7 ~      | KEY_F(33)      | C-F9           |
 | (pre) 5 8 ~      | KEY_F(34)      | C-F10          |
 | (pre) 5 9 ~      | KEY_F(35)      | C-F11          |
 | (pre) 6 0 ~      | KEY_F(36)      | C-F12          |
 | (pre) A          | KEY_UP         | CURU           |
 | (pre) B          | KEY_DOWN       | CURD           |
 | (pre) C          | KEY_RIGHT      | CURR           |
 | (pre) D          | KEY_LEFT       | CURL           |
 | (pre) F          | KEY_END        | END            |
 | (pre) G          | KEY_NextScreen | PGDN           |
 | (pre) H          | KEY_HOME       | HOME           |
 | (pre) I          | KEY_PrevScreen | PGUP           |
 | (pre) L          | KEY_InsertHere | INS            |
 | (pre) M          | KEY_NUMENTER   | NUMENTER       |
 | (pre) N          | KEY_F(2)       | F2             |
 | (pre) O          | KEY_F(3)       | F3             |
 | (pre) P          | KEY_PF1        | PF1            |
 | (pre) Q          | KEY_PF2        | PF2            |
 | (pre) R          | KEY_PF3        | PF3            |
 | (pre) S          | KEY_PF4        | PF4            |
 | (pre) T          | KEY_F(8)       | F8             |
 | (pre) U          | KEY_F(9)       | F9             |
 | (pre) V          | KEY_F(10)      | F10            |
 | (pre) W          | KEY_F(11)      | F11            |
 | (pre) X          | KEY_F(12)      | F12            |
 | (pre) Z          | KEY_BACKTAB    | S-TAB          |
 | (pre) l          | KEY_PadComma   | COMMA          |
 | (pre) m          | KEY_PadMinus   | MINUS          |
 | (pre) n          | KEY_PadPeriod  | NUMSTOP        |
 | (pre) o          | KEY_Pad0       | NUM0           |
 | (pre) p          | KEY_Pad1       | NUM1           |
 | (pre) q          | KEY_Pad2       | NUM2           |
 | (pre) r          | KEY_Pad3       | NUM3           |
 | (pre) s          | KEY_Pad4       | NUM4           |
 | (pre) t          | KEY_Pad5       | CENTER         |
 | (pre) u          | KEY_Pad6       | NUM6           |
 | (pre) v          | KEY_Pad7       | NUM7           |
 | (pre) w          | KEY_Pad8       | NUM8           |
 | (pre) x          | KEY_Pad9       | NUM9           |
 | (pre) y          | KEY_NUMENTER   | NUMENTER       |
 | (pre) 1 z        | KEY_BTAB       | S-TAB          |
 | (pre) 2 z        | KEY_InsertHere | INS            |
 | (pre) 3 z        | KEY_HOME       | HOME           |
 | (pre) 4 z        | KEY_END        | END            |
 | (pre) 5 z        | KEY_PrevScreen | PGUP           |
 | (pre) 6 z        | KEY_NextScreen | PGDN           |
 | (pre) 1 9 5 z    | KEY_UNDO       | UNDO           |
 | (pre) 2 1 4 z    | KEY_HOME       | HOME           |
 | (pre) 2 1 5 z    | KEY_UP         | CURU           |
 | (pre) 2 1 6 z    | KEY_PrevScreen | PGUP           |
 | (pre) 2 1 7 z    | KEY_LEFT       | CURL           |
 | (pre) 2 1 9 z    | KEY_RIGHT      | CURR           |
 | (pre) 2 2 0 z    | KEY_END        | END            |
 | (pre) 2 2 1 z    | KEY_DOWN       | CURD           |
 | (pre) 2 2 2 z    | KEY_NextScreen | PGDN           |
 | (pre) 2 2 4 z    | KEY_F(1)       | F1             |
 | (pre) 2 2 5 z    | KEY_F(2)       | F2             |
 | (pre) 2 2 6 z    | KEY_F(3)       | F3             |
 | (pre) 2 2 7 z    | KEY_F(4)       | F4             |
 | (pre) 2 2 8 z    | KEY_F(5)       | F5             |
 | (pre) 2 2 9 z    | KEY_F(6)       | F6             |
 | (pre) 2 3 0 z    | KEY_F(7)       | F7             |
 | (pre) 2 3 1 z    | KEY_F(8)       | F8             |
 | (pre) 2 3 2 z    | KEY_F(9)       | F9             |
 | (pre) 2 3 3 z    | KEY_F(10)      | F10            |
 | (pre) 2 3 4 z    | KEY_F(11)      | F11            |
 | (pre) 2 3 5 z    | KEY_F(12)      | F12            |
 | (pre) 3 2 4 z    | KEY_F(13)      | S-F1           |
 | (pre) 3 2 5 z    | KEY_F(14)      | S-F2           |
 | (pre) 3 2 6 z    | KEY_F(15)      | S-F3           |
 | (pre) 3 2 7 z    | KEY_F(16)      | S-F4           |
 | (pre) 3 2 8 z    | KEY_F(17)      | S-F5           |
 | (pre) 3 2 9 z    | KEY_F(18)      | S-F6           |
 | (pre) 3 3 0 z    | KEY_F(19)      | S-F7           |
 | (pre) 3 3 1 z    | KEY_F(20)      | S-F8           |
 | (pre) 3 3 2 z    | KEY_F(21)      | S-F9           |
 | (pre) 3 3 3 z    | KEY_F(22)      | S-F10          |
 | (pre) 3 3 4 z    | KEY_F(23)      | S-F11          |
 | (pre) 3 3 5 z    | KEY_F(24)      | S-F12          |
 | (pre) 4 1 4 z    | KEY_C_HOME     | C-HOME         |
 | (pre) 4 1 5 z    | KEY_C_CURU     | C-CURU         |
 | (pre) 4 1 6 z    | KEY_C_PGUP     | C-PGUP         |
 | (pre) 4 1 7 z    | KEY_C_CURL     | C-CURL         |
 | (pre) 4 1 9 z    | KEY_C_CURR     | C-CURR         |
 | (pre) 4 2 0 z    | KEY_C_END      | C-END          |
 | (pre) 4 2 1 z    | KEY_C_CURD     | C-CURD         |
 | (pre) 4 2 2 z    | KEY_C_PGDN     | C-PGDN         |
 | (pre) 4 2 3 z    | KEY_PadComma   | COMMA          |
 | (pre) 4 2 4 z    | KEY_F(25)      | C-F1           |
 | (pre) 4 2 5 z    | KEY_F(26)      | C-F2           |
 | (pre) 4 2 6 z    | KEY_F(27)      | C-F3           |
 | (pre) 4 2 7 z    | KEY_F(28)      | C-F4           |
 | (pre) 4 2 8 z    | KEY_F(29)      | C-F5           |
 | (pre) 4 2 9 z    | KEY_F(30)      | C-F6           |
 | (pre) 4 3 0 z    | KEY_F(31)      | C-F7           |
 | (pre) 4 3 1 z    | KEY_F(32)      | C-F8           |
 | (pre) 4 3 2 z    | KEY_F(33)      | C-F9           |
 | (pre) 4 3 3 z    | KEY_F(34)      | C-F10          |
 | (pre) 4 3 4 z    | KEY_F(35)      | C-F11          |
 | (pre) 4 3 5 z    | KEY_F(36)      | C-F12          |
 | (pre) 1 9 2 z    | KEY_F(49)      | F13            |
 | (pre) 1 9 3 z    | KEY_F(50)      | F14            |
 | (pre) 2 9 2 z    | KEY_F(57)      | S-F13          |
 | (pre) 2 9 3 z    | KEY_F(58)      | S-F14          |
 | (pre) [ A        | KEY_F(1)       | F1             |
 | (pre) [ B        | KEY_F(2)       | F2             |
 | (pre) [ C        | KEY_F(3)       | F3             |
 | (pre) [ D        | KEY_F(4)       | F4             |
 | (pre) [ E        | KEY_F(5)       | F5             |
 | (pre) 0 q        | KEY_PadComma   | COMMA          |
 | (pre) 1 q        | KEY_F(1)       | F1             |
 | (pre) 2 q        | KEY_F(2)       | F2             |
 | (pre) 3 q        | KEY_F(3)       | F3             |
 | (pre) 4 q        | KEY_F(4)       | F4             |
 | (pre) 5 q        | KEY_F(5)       | F5             |
 | (pre) 6 q        | KEY_F(6)       | F6             |
 | (pre) 7 q        | KEY_F(7)       | F7             |
 | (pre) 8 q        | KEY_F(8)       | F8             |
 | (pre) 9 q        | KEY_F(9)       | F9             |
 | (pre) 1 0 q      | KEY_F(10)      | F10            |
 | (pre) 1 1 q      | KEY_F(11)      | F11            |
 | (pre) 1 2 q      | KEY_F(12)      | F12            |
 | (pre) 1 3 q      | KEY_F(13)      | S-F1           |
 | (pre) 1 4 q      | KEY_F(14)      | S-F2           |
 | (pre) 1 5 q      | KEY_F(15)      | S-F3           |
 | (pre) 1 6 q      | KEY_F(16)      | S-F4           |
 | (pre) 1 7 q      | KEY_F(17)      | S-F5           |
 | (pre) 1 8 q      | KEY_F(18)      | S-F6           |
 | (pre) 1 9 q      | KEY_F(19)      | S-F7           |
 | (pre) 2 0 q      | KEY_F(20)      | S-F8           |
 | (pre) 2 1 q      | KEY_F(21)      | S-F9           |
 | (pre) 2 2 q      | KEY_F(22)      | S-F10          |
 | (pre) 2 3 q      | KEY_F(23)      | S-F11          |
 | (pre) 2 4 q      | KEY_F(24)      | S-F12          |
 | (pre) 2 5 q      | KEY_F(25)      | C-F1           |
 | (pre) 2 6 q      | KEY_F(26)      | C-F2           |
 | (pre) 2 7 q      | KEY_F(27)      | C-F3           |
 | (pre) 2 8 q      | KEY_F(28)      | C-F4           |
 | (pre) 2 9 q      | KEY_F(29)      | C-F5           |
 | (pre) 3 0 q      | KEY_F(30)      | C-F6           |
 | (pre) 3 1 q      | KEY_F(31)      | C-F7           |
 | (pre) 3 2 q      | KEY_F(32)      | C-F8           |
 | (pre) 3 3 q      | KEY_F(33)      | C-F9           |
 | (pre) 3 4 q      | KEY_F(34)      | C-F10          |
 | (pre) 3 5 q      | KEY_F(35)      | C-F11          |
 | (pre) 3 6 q      | KEY_F(36)      | C-F12          |
 | (pre) 1 3 9 q    | KEY_InsertHere | INS            |
 | (pre) 1 5 0 q    | KEY_PrevScreen | PGUP           |
 | (pre) 1 4 6 q    | KEY_END        | END            |
 | (pre) 1 5 4 q    | KEY_NextScreen | PGUP           |
 | ESC P            | KEY_PF1        | PF1            |
 | ESC Q            | KEY_PF2        | PF2            |
 | ESC R            | KEY_PF3        | PF3            |
 | ESC S            | KEY_PF4        | PF4            |
 +------------------+----------------+----------------+

 Where (pre) is either:

    +------------------------------
    ESC [ - (0x1B 0x5B) or
    ESC O - (0x1B 0x4F) or
    ESC ? - (0x1B 0x3F) or
    CSI   - (0x9B)
    +------------------------------

**man-end**********************************************************************/
