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