------------------------------------------------------------------------------
KITTEN.TXT         -    Manual for KITTEN.H--    -         Written by CyberRax
------------------------------------------------------------------------------
Section 0   -   Introduction
Section 1   -   Format of message catalogs
Section 2   -   Using the library
Section 3   -   Minimizing size of code (for optimizing freaks only  :)
Section 4   -   Misc. notes
Section 5   -   Greets, credits and legal stuff


------------------------------------------------------------------------------
0.                             Introduction
------------------------------------------------------------------------------
KITTEN.H-- is a SPHINX/Sheker C-- port of Kitten which is a simplified
version of Cats which is a DOS implementation of Unix's catgets() code.
(Phewww... don't you just love code which actually has a family tree   :)
Despite all this re-writing the purpose of the library has stayed the same:
provide a way to add internationalization support to your programs, that is
print messages in the native language of user. The whole thing works on
external language files, so called message catalogs. This way a new language
can be supported by not re-compiling the program but simply creating a
textfile with used messages. It also provides a way to keep the language files
independent, so different versions (or even different programs) can use the
same catalogs.


------------------------------------------------------------------------------
1.                       Format of message catalogs
------------------------------------------------------------------------------
The structure is very simple:

# Comment
x.y: Message 1
x.y: Message 2
...
x.y: Message N

Lines starting with '#' are treated as comments and will be ignored. Lines
containing messages must be preceded by a 'x.y:' combination where 'x'
is the set and 'y' the message number. How exactly these numbers are organized
is up to the user. Set 1 could for example hold informational stuff (1.1 could
be the copyright statement, 1.2 the help screen) while set 2 would carry
errormessages (2.1 "file can't be opened" and 2.3 "not enough memory").
Kitten supports C style escape sequences, so it's possible to break a message
into 2 lines  through '\n' or include non-alphabetic characters through '\???'
(where ??? is the decimal code for the character).


------------------------------------------------------------------------------
2.                          Using the library
------------------------------------------------------------------------------
I assume everyone who's downloading this archive has C-- installed and knows
how to include libraries into programs, so I'll skip that part.
First thing before actually calling functions: global definitions. By default
enough room is reserved for a catalog with size up to 4kB containing max. 64
messages. If more room is needed then it's necessary to define KITTEN_NUM
(number of messages) and/or KITTENBUFLEN (size of buffer for catalog) with
appropriate values before including KITTEN.H--
Now the initializing of library:

   KITTENOPEN(catalog)

where 'catalog' is a literal filename (determined by a directory separator
('\') inside the name) or a relative name. The latter requires two variables
in DOS environment: LANG and NLSPATH. The first is the international two
letter code of language (EN for English, DE for German, ET for Estonian, etc).
The second a semicolon separated list of directories where to find the
language files. Those running FreeDOS should have both set by default (LANG=EN
and NLSPATH=C:\FDOS\NLS if I remember correctly). Kitten tries first to open
%NLSPATH%\%LANG%\catalog and if this fails then %NLSPATH%\catalog.%LANG%
After the initialization all that has to be done is retrieving the needed
message with KITTENGETS():

   KITTENGETS(set,num,message)

where 'set' and 'num' are set and and number of message and 'message' is
string that is to be printed (in practise the message in the main language of
program).
Before parsing another catalog the first one must be closed, like this:

   KITTENCLOSE()


------------------------------------------------------------------------------
3.                       Minimizing size of code
------------------------------------------------------------------------------
Besides the standard way of generating smaller code (by including the compiler
directive 'codesize') there's the possibility of preceding names of dynamic
procedures with '@' in which case they're treated as macros and thus inserted
rather than called. The saving ain't much (usually 3 - 4 bytes per procedure)
but still better than nothing. The problem is that this works when the
procedure is called only once and can't be done automatically. Kitten does
however support several definitions to insert the code so there's no need to
manually alter KITTEN.H-- to include '@'s. These definitions are:

   insertFOPEN
   insertFREAD
   insertFCLOSE
   insertSTRCAT
   insertSTR2WORD
   insertCHARMULTIPLY
   insertADVANCEDSTRCPYFAR
   insertADVANCEDSTRCPYNEAR

Let's for example imagine that the program where Kitten is used doesn't
perform any file manipulations (that is it doesn't read from nor writes to
files). In this case it's safe to assume that procedures FOPEN(), FREAD() and
FCLOSE() are used only by Kitten so one could define insertFOPEN, insertFREAD
and insertFCLOSE to see if the resulting executable is smaller.


------------------------------------------------------------------------------
4.                             Misc. notes
------------------------------------------------------------------------------
Kitten needs following header files to work:
   BYTES.H-- release 20040706 or later
   - functions LOAD_AL(), LOAD_AX(), STORE_AX(), STORE_AL(), STORE(),
               AX2CX(), BX2AX(), DX2AX() and SI2AX()
   STRING2.H-- release 20040705 or later
   - functions ADVANCEDSTRCPYFROMFAR(), ADVANCEDSTRCPYNEAR(), ASCIZ2WORD(),
               STR2WORD() and CHARMULTIPLY()
   STRING.H--
   - functions STRCHR() and STRCAT()
   DOS.H--
   - function ENVSTR()
   NUMBERS.H--
   - numerous definitions
Additionally the internal library is used as functions FOPEN(), FREAD() and
FCLOSE() aren't available in any header file.
The needed versions of BYTES.H--, STRING.H-- and NUMBERS.H-- are included in
this archive (if you've got HMMFILES.ZIP then it also includes NUMBRERS.H--);
STRING.H--, DOS.H-- and internal library (MAINLIB.LDP) are part of the C--
distribution.

Lines read from message catalogs are converted into ASCIZ (terminated by a
zero byte) strings and expected to stay this way. That means if you need DOS
style strings (terminated by '$') then it's necessary to convert them at
runtime or better yet use functions which can deal with ASCIZ strings (like
DWRITESTR()).

Only DOS (0Dh 0Ah) and *NIX (0Ah) line endings in catalogs are supported.

The point about comments in catalogs wasn't 100% correct: actually every line
which starts with *anything* other than a digit is treated as a comment. But
it's advisable to follow the standard and make use of '#'s.

The set and message numbers are converted to type BYTE, this means that
Kitten supports up to 256 messages in 256 sets (0.0...255.255).

By LANG variable besides the form XX also XX-YY is supported (where YY is
the dialect/county code like UK etc.)

Spaces in NLSPATH (like "C:\NLS; C:\FDOS\NLS\ ; ...") aren't supported,

Only standard DOS functions are used for file manipulation which means that
language files can be accessed only through their short names.

When the message catalog is exactly as big as the buffer then an error is
returned by opening. That's because there's no (compact) way to tell if the
file is as large as the buffer *or* bigger. So if you've got a catalog which
is exactly 4096 bytes then it's necessary to define KITTENBUFLEN 4097.

If there are more messages in file than the value of KITTEN_NUM then Kitten
won't return error but parses the file without problem. It will however
overwrite the first entries of the message buffer with the index data.


------------------------------------------------------------------------------
5.                  Greets, credits and legal stuff
------------------------------------------------------------------------------
Greets fly out to Mishel Sheker (author of C--), Jim Hall/Tom Ehlert/Eric Auer
from the FreeDOS project (authors of Cats/Kitten), Stuart Herbert (author of
PC-Man), Spacefly (author of MiniTV), Peter Cellik (creator of C--) and to all
C-- coders (all 6 of us   :) world wide.

This manual is partly based on the layout used by Stuart Herbert in the
documentation of his PC-Man and on the text of "International Support
mini-HOWTO v2.2.3" by Jim Hall.

Cats has been created and copyrighted by Jim Hall and is since version 3.0
  published under GNU Lesser General Public License (LGPL).
Kitten is the work of Tom Ehlert and Eric Auer.
C-- port and this lousy documentation is from CyberRax.

KITTEN.H-- is published under LGPL. You can find the complete license in
LGPL.TXT but in short it says: you can modify and distribute this library as
long as you keep it under LGPL or GPL and include the original copyright
statement, a copy of the license and the (modified) source code.
Programs which use KITTEN.H-- also fall under LGPL, but it's allowed to use a
different license for them as long as it's clearly stated that they use Kitten
which is under LGPL *and* the user can modify the executable for private use
and reverse engineer it for debugging those modifications. There is however
one catch: if I understand the text of LGPL correctly then the only way to use
Kitten in a closed source project is to link it externally, like a DLL.
Otherwise there must exist a way for the user to retrieve the source code of
the program   :(
(As said I'm not 100% sure about this... gotta mail to the guys at FSF and ask
about that   :)

------------------------------------------------------------------------------
       Written by CyberRax in Tootsi, Estonia, Europe on July 30th, 2004
------------------------------------------------------------------------------