Creating keymaps for keyboard internationalization in *MoviX*
=============================================================

Balázs Bárány <balazs@tud.at>

Different languages and countries have different keyboard layouts for
historical reasons and to support national-language characters that don't exist
on US (= standard IBM PC) keyboards.

When a PC boots up, the IBM-PC keyboard layout is active. This means that, for
example, a German user has to type "-" to get the "/" character, and "ß" for
"-" etc. This is really hard for novice users who rightfully assume that a key
press will produce the same symbol on the keyboard.
For English users, this is a non-issue as their keyboard is already generating
the right codes.

To fully support international keyboards, so-called keymaps are used. They
define the assigment of keys (key codes, to be exact) to characters. For
additional complexity, the boot loader can use a keymap but the Linux kernel
will then load another, so for each keyboard, we need to define two keymaps:
one for the boot loader (ISOLINUX) and one for the Unix shell.

The first keymap is loaded by ISOLINUX with the "kbdmap" parameter in
isolinux.conf. The second one is loaded with the "loadkmap" utility of busybox
after the basic Linux system was started.

Generating keymap files for *MoviX*
===================================

1. ISOLINUX keymap
------------------
Documentation: http://syslinux.zytor.com/faq.php#config
You need the utility "keytab-lilo.pl" from the LILO source. 
You can get LILO from http://www.ibiblio.org/pub/Linux/system/boot/lilo/ .
Just call "/path/to/keytab-lilo.pl /path/to/keyboardfile > bootkey.map".

An example:

/usr/local/bin/keytab-lilo.pl /usr/share/keymaps/i386/qwertz/hu.kmap.gz > hu/bootkey.map

Output of this command: 
Loading /usr/share/keymaps/i386/qwerty/us.kmap.gz
Loading /usr/share/keymaps/i386/qwertz/hu.kmap.gz

In the hu/ subdirectory, there is now a bootkey.map file with 256 bytes. (The
size could vary according to the keyboard's complexity.)

2. Linux shell keymap
---------------------
Documentation: http://www.8ung.at/spblinux/doc/loadkmap.html
On the booted *MoviX* system, the loadkmap utility of the Busybox project is
used. Keymaps for loadkmap can be generated on a Linux system using Busybox'
"dumpkmap" utility.
If you don't have it installed, you need to get the source of busybox
and compile it with #define BB_DUMPKMAP in Config.h. (Just remove the //
comment signs from the line.)
dumpkmap reads the current keymap from the console. You need to be root to be
able to load and dump keymaps. 
If you are working under X Window, switch to a console e.g. with CTRL+ALT+F2
and login there as root.

First, the new keymap is loaded, in the following example again for Hungarian.
Then, dumpkmap is used for dumping it into hu/shellkey.map. One can then load 
the "good" keymap again in order to be able to use the PC correctly. ;-)

Example (best entered on one line):

loadkeys hu; /usr/local/bin/dumpkmap > hu/shellkey.map; loadkeys de-latin1

Of course, you should switch to *your* keyboard layout instead of "de-latin1".

On my system, the generated keymap files are 2823 bytes each.

3. TODO: Keymap for X (for MoviX2)
----------------------------------
This is probably not more than copying the appropriate file from some XFree86
directory to keyboard-i18n/<lang>/ but I haven't tested it because I don't use
MoviX2.
