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?
--------------
country.mk contains the values of language, keyboard, charset and
IDT for each known country. Tables derived from this information are
generated by tools/genctables.awk into bios/ctables.h, the latter file
being 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 */

If NVRAM is found, then the time&date, keyboard, language and
country are taken from it, and the charset is deduced from the
language. Else 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 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 inited 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 suitable lines to the tables in country.mk

- if a specific charset is needed,
  - find a two character name for this charset
  - add a line in the charset table in bios/country.h
  - 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 the font table in country.mk
  - 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,
  - add its name in bios/country.h
  - 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 po/LINGUAS)

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


Summary of i18n-related files
-----------------------------
country.mk - the table of font,keyboard,language,date&time for countries
tools/genctables.awk - builds bios/ctables.h from country.mk
tools/mkheader.awk - builds bios/header.h
tools/bug.c - see nls.txt
po/* - see nls.txt
bios/ctables.h - table from country.mk 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
