country.txt - an overview of i18n issues in EmuTOS
==================================================

EmuTOS supports different countries. The way it does is sometimes
dictated by TOS specifications, and sometimes solved in original
ways.


What can vary
-------------
- language: messages printed by EmuTOS, see doc/nls.txt
- keyboard: the rules to convert from scancodes to characters
- charset: a way of encoding characters
- font: the graphical display of individual characters
- date&time: the way of printing time-related info in text.

In EmuTOS, we shall call 'country' a community having the same value
for all the parameters above. This means that 'Switzerland(German)' and
'Switzerland(French)' are not the same 'country' because the language and
keyboards are different.

Obviously these things are related. For instance, the language,
keyboard and font depend on the charset.


Where is it in the code
-----------------------
- country codes:
  include/ctrycodes.h

- language: this is covered by the 'nls' stuff, in files
  util/langs.[ch], util/nls.c, util/nlsasm.S

- keyboard:
  bios/country.h holds #defines for the keyboard codes;
  bios/keyb_* contain the actual kbd layouts
  bios/country.c contains the logic to choose the keyboard to use.

- charset:
  bios/country.h holds #defines for the charset codes;

- font:
  bios/fnt*6x6.c, bios/fnt*8x8.c and bios/fnt*8x16.c contain the fonts
  bios/country.c contains the logic to choose the fontsets to use.

- date&time:
  the cookie _IDT. Used by EmuDesk and EmuCON2.


How is it set?
--------------
localise.ctl contains the values of language, keyboard, charset and
IDT for each known country.  The 'localise' tool creates bios/ctables.h,
which contains tables derived from this information.  bios/ctables.h is
included in bios/country.c.

Functions detect_akp() and detect_idt() are called early in the boot
sequence (from fill_cookie_jar() in machine.c). See in bios.c:

  cookie_init();  /* sets a cookie jar */
  machine_init(); /* detect hardware features and fill the cookie jar */

There are three basic ways (chosen at compile time) that the country,
language, keyboard, charset, and IDT values are set:
1. For the 192K/256K versions of EmuTOS (expected to run on ST/STe
   systems which have no NVRAM), the country code is stored in the OS
   header, and all parameters are deduced from the country code.
2. For the 512K version of EmuTOS (expected to run on TT/Falcon systems
   with NVRAM), the country code is stored in the OS header and the
   language is derived from that.  Other parameters are obtained from
   NVRAM.
3. For other versions of EmuTOS (including PRG and emulator versions),
   all parameters are deduced from NVRAM if present; otherwise the
   country code is taken from the OS header, and all parameters are
   deduced from the country code.
The values of parameters in the OS header are contained in the file
bios/header.h, itself created by tools/mkheader.awk, depending on
the build date and the value of the Makefile variable $(COUNTRY).

Later, nls is initialised and configured according to the language.
See in bios.c:

  nls_init();         /* init native language support */
  nls_set_lang(get_lang_name());

Here, function get_lang_name() is the method from country.c to obtain
the language name.


New country check list
----------------------
- if the country is not known (in include/ctrycodes.h),
  - get it from tos.hyp:
    https://freemint.github.io/tos.hyp/en/bios_cookiejar.html#Cookie_2C_20_AKP
  - or from FreeMiNT:
    https://github.com/freemint/freemint/blob/master/sys/keyboard.c#L93
  - if there is no code for your country yet, be sure to agree with tos.hyp
    and FreeMiNT people to avoid a number clash.
  - add your new entry in include/ctrycodes.h

- add a suitable line to localise.ctl

- if a specific charset is needed,
  - find a two character name for this charset
  - use it in the added line in localise.ctl
  - provide C source code fonts for this charset (you may use the
    tool fntconv to create the C files, available from Laurent's
    page at http://lvogel.free.fr/misc.htm). The files should be named
    bios/fnt_xx_6x6.c, bios/fnt_xx_8x8.c and bios/fnt_xx_8x16.c,
    where xx is the charset name; each should define a struct
    font_head which has the same name as the file's without extension.
    => IMPORTANT NOTICE: GEM will crash if the values in the
    => font header are not as follow:
    =>    font_id = 1
    =>    flags = F_STDFORM | F_MONOSPACE             (for the 6x6 font)
    =>    flags = F_STDFORM | F_MONOSPACE | F_DEFAULT (for the 8x8 & 8x16 fonts)
  - update localise.c to add the mapping from the two character name to the
    full name that will be used in the .po file for this language
  - check if this charset is known by GNU recode and if not
    - send mail to the GNU recode maintainer (!)
  - see chapter 'charsets' of doc/nls.txt

- if a specific keyboard is needed,
  - provide the keyboard layout in a file bios/keyb_*.h
    (you may use supplied tool dumpkbd.prg to generate such a file from an
    existing Atari ST with the correct keyboard)

- if a specific language is needed,
  - follow the instructions in doc/nls.txt
    (add a new *.po file to the po/ directory and add an entry in localise.ctl)

Note: adding a new charset makes it mandatory to also add a new keyboard
and a new language.


Summary of i18n-related files
-----------------------------
localise.ctl - the table of font,keyboard,language,date&time for countries
tools/localise.c - builds bios/ctables.h, i18nconf.h, po/LINGUAS from localise.ctl
tools/mkheader.awk - builds bios/header.h
tools/bug.c - see nls.txt
po/* - see nls.txt
bios/ctables.h - table generated by localise, usable from C code
bios/header.h - contains the default country for the TOS header
bios/keyb_xx.h - keyboard layout for keyboard 'xx'
bios/fnt_xx_*.c - fonts for charset 'xx'
bios/country.h - defines for keyboard and charset names
include/ctrycodes.h - defines for country names
