Amiga Developer CD v1.2/amidev_cd_12.iso/devcon/milan_1991/devcon91.2/locale/development/catcomp.doc

Text File | 1992-09-01 | 17KB | 416 lines

                   $VER: CatComp_Documentation 1.3 (30.7.91)
                   =========================================

CatComp is a program to handle locale.library's message catalog creation and
maintenance. Message catalogs are IFF files read by locale.library. They
contain all the text strings used by an application. By providing several of
these catalog files, an application can use locale.library and transparently
adapt itself to the user's preferred language.

CatComp reads and processes two kinds of input files, and produces four types
of output files.

The first kind of file read by CatComp is a catalog description file. That
file describes all the strings used by an application. There is one such file
per localized application. In this file, you assign numbers to all the
application strings as well as specify their minimum and maximum lengths.

The second kind of file read by CatComp is a catalog translation file. That
file contains all strings from the application translated to one language.
There is one catalog translation file per language supported by a localized
application.

CatComp can produce four different kinds of output files. The first is an IFF
catalog. These are regular IFF files. There is one catalog produced for every
catalog text file successfully processed. Catalogs are read directly by
locale.library whenever the OpenCatalog() call is made.

The second type of file output by CatComp is an empty translation file. This
is useful when starting a translation. It lets CatComp convert a catalog
description file into a ready to fill-in translation file.

The third and fourth type of files output by CatComp are C and Assembly
language programming source files. These are used by application writers to
convert catalog description files into source files that can be directly used
in their applications.

Invoking CatComp
----------------

CatComp can only by run from the Shell under Kickstart V37 or beyond. Its
template is:

  DESCRIPTOR/A,TRANSLATION,CATALOG/K,CTFILE/K,CFILE/K,ASMFILE/K,VB=VERBOSITY/N

  DESCRIPTOR/A
  Specifies the name of a catalog description file. Typically, the file
  extension for catalog description files is .cd

  TRANSLATION
  Specifies the name of a catalog translation file. Typically, the
  file extension for catalog translation files is .ct

  CATALOG/K
  Specifies the name of the IFF catalog file to produce. When this option
  is specified, a translation file must have been given in the previous
  argument.

  CTFILE/K
  Specifies the name of the blank catalog translation file to produce. This
  option only requires a catalog descriptor file be provided, there is no need
  for a translation file.

  CFILE/K
  Specifies the name of the C-language source file header to produce. This
  option only requires a catalog descriptor file be provided, there is no need
  for a translation file.

  ASMFILE/K
  Specifies the name of the Assembly-language source file header to produce.
  This option only requires a catalog descriptor file be provided, there is
  no need for a translation file.

  VERBOSITY/N
  Specifies the amount of information CatComp should output while doing some
  processing. The lower this number, the less CatComp will output messages.
  Not providing this option causes CatComp to output every message it could.

Catalog Description Files
-------------------------

Catalog description files completely describe the strings used by an
application. The format for these files is basically a series of two line
entries separated by an arbitrary number of comment lines. The EBNF (Extended
Backus Naur Formalism) specification for catalog description files is:

{# command}
{; comment line}
<string name> "(" [string id] "/" [min string len] "/" [max string len] ")"
[string]

The first line indicates special commands that provide control over the
generation of C and Assembly source files. See the section on C and Assembly
source files below for further information.

<string name> is the symbolic name of the string. Following the name comes
three optional numbers enclosed in parenthesis and separated with slashes. The
first number specifies the string's ID value. This is the ID value used to
request this string when using the GetCatalogStr() call in locale.library. The
second number specifies the minimum length for the string, while the third
number specifies the maximum string length.

The next line of an entry contains the actual string. Within the catalog
description file, the strings are the same as the default strings built into
the application. The strings can use standard C-language backslash ("\")
escape sequences.

Finally, any string entry can be separated from other entries by comment
lines. Comment lines start with a semicolon. There can be any number of
comment lines between two entries. It is not allowed to put comment lines
between the two lines of a same entry.

Here's an example of two strings in a catalog description file:

MSG_HELLO (0/4/50)
This is a test string for the world to see
;
MSG_BYE (1/14/47)
This is another test string

The first string is called MSG_HELLO, has 0 as ID value, can be as short
as 4 characters and as long as 50. The string actually associated with the
name follows on the next line. Then comes a comment line. Following that is
the definition of the second string called BYE_WORLD_STR that has 1 as ID
value, can be as short as 14 characters and as long as 47.

As mentioned above, all three numbers in an entry are optional. If the string
id number is not specified, then the same id as the previous string in the
file plus one is used. If the first string defined has no id value, the
starting id value is 0. If the minimum string length is not specified, it is
assumed to be 0. And finally, if the maximum string length is not specified,
it is assumed to be unlimited.

A note on style here. It is relatively important to choose descriptive
symbolic names for the strings. These names will be viewed by the translators
and should be as meaningful as possible. The following conventions are
suggested:

  - List all names in capital letters. This will make it clear they are
    constants as this is the convention used in all Amiga include files.

  - Prefix each name with the string MSG_. This will make it clear to the
    programmer that a given constant is in fact a string ID value.

  - Append the string _GAD to strings that are used for gadget labels.

  - Append the string _MENU to strings that are used for menu titles. For
    example, MSG_EDIT_MENU.

  - Expand the path leading to a menu item when specifying strings that are
    used for menu items. For example, for the Cut item in the Edit menu
    would be written as MSG_EDIT_CUT.

Catalog Translation Files
-------------------------

Catalog translation files contain all the strings of an application translated
to a different language than the default. The files look very similar to
catalog description files, except they do not include the string id, minimum
string length and maximum string length specifications. The EBNF specification
for catalog translation files is:

{# command}
{; comment line}
<string name>
[string]

The first line indicates special commands that describe attributes of the
catalog file. There are currently three supported commands. "version" lets you
specify a 2.0-style version string for the catalog. "language" lets you list
the language that this catalog is in. This string should itself be in the
given language and not in English.

For example:

MSG_HELLO
Ceci est une chaine test pour être vue
;
MSG_BYE
Ceci est une autre chaine test

On the first line you list the symbolic name of the string, and on the second
line the translated string. The symbolic name is the same as the related entry
in the catalog description file. CatComp uses this name to associate entries
from translation files with entries in description files. It can then validate
the strings in the translation files by ensuring they are of the correct
length, etc.

Escape Sequences Supported
--------------------------

Regular C-language escape sequences can be specified in strings, along with a
few additions:

  \a    inserts an audible bell character (ASCII 7)
  \b    inserts a backspace character (ASCII 8)
  \c    inserts a control sequence introducer (ASCII 155)
  \e    inserts an escape character (ASCII 27)
  \f    inserts a formfeed character (ASCII 12)
  \n    inserts a newline character (ASCII 10)
  \r    inserts a carriage return character (ASCII 13)
  \t    inserts a tab character (ASCII 9)
  \v    inserts a vertical tab character (ASCII 11)
  \xNN  inserts NN, where NN specifies an ASCII code in hexadecimal
  \NNN  inserts NNN, where NNN specifies an ASCII code in octal

Formatted Output Commands
-------------------------

CatComp parses strings for C-language formatting commands as used in the
printf() function. It ensures that the number and type of such commands are
the same in both the description file and the translation files. This
guarantees that the application stack frame will not be misinterpreted due to
incorrect translations of formatting commands.

CatComp warns you if you attempt to use any non-C formatting commands. The
commands that CatComp does understand are:

    %b  %c  %d  %e  %E  %f  %g  %G  %i  %o  %p  %s  %u  %x  %X

CatComp also knows about the ordering formatting command supported by
RawDoFmt() whenever locale.library runs in the system, or by locale's
FormatString() routine. The ordering command lets you specify formatting
commands within a formatting string in a different order than in the original
string, while still accessing the stack frame correctly. CatComp validates the
ordering information and ensures argument types match. See the documentation
locale.library/FormatString().

Specifying the argument position lets the order of the % commands within your
strings without affecting how the program performs. Given a string in a
catalog description file such as:

MSG_AVAIL_MEM (//)
FAST: %lU, GRAPHIC: %lU

This string could be translated in French as:

MSG_AVAIL_MEM (//)
GRAPHIQUE: %2$lU, AUTRE %1$lU

Using the first string, the output of the program might look like:

FAST: 1234, GRAPHIC: 5678

while the translation would output:

GRAPHIQUE: 5678, AUTRE: 1234


Validation
----------

CatComp enforces the syntax of catalog description files and catalog
translation files very strongly. It also ensures that the same number of
C-language % command appear in both the description and the translation file.
This guarantees the integrity of the application stack-frame when using
translated string in printf() statements.

Most errors detected by CatComp are fatal and cause the program to abort.
Errors are reported to the console with a descriptive error message, a
filename, and if needed a line and column number. Non-fatal errors (warnings)
and also sent to the console, but they do not cause the program to abort. The
printing of these warning messages can be suppressed using the VERBOSITY
command-line option.

Possible Errors
---------------

Here is a list of the errors and warnings that CatComp can produce, along with
an explanation of what went wrong. Most errors indicate the file, line and
column where the error occurred to help in solving the problem.

ERROR: string line for token <name> not found
  A given token was not followed by a string

ERROR: token not found
  No token was found on a line in a catalog description file. Comment lines
  must start with ";", any other line must have a valid token definition on
  it.

ERROR: '(' expected
  There was no number section after a token in a catalog description file.
  The number section must start with a (, followed by three optional numbers
  separated by slashes, and terminated by a ).

ERROR: ')' expected
  There was no ) after a number section in a catalog description file.
  The number section must start with a (, followed by three optional numbers
  separated by slashes, and terminated by a ).

ERROR: '/' expected
  There was no slash found within a number section after a token in a catalog
  description file. The number section must start with a (, followed by three
  optional numbers separated by slashes, and terminated by a ). So there
  must always be two slashes specified.

ERROR: garbage characters after token <name>
  There was no number section after a token in a catalog description file,
  and garbage characters were found instead, The number section must start
  with a (, followed by three optional numbers separated by slashes, and
  terminated by a ).

ERROR: <name> is not a valid token
  A token in a catalog description file was composed of invalid characters.
  A token must start with a letter and can be followed by letters, numbers and
  underscores.

ERROR: token <name> not found
  A token specified in a catalog description file was not present in
  a translation file

ERROR: string too short for token <name>
  A string in a translation file is shorter than the minimum length
  specified in the description file.

ERROR: string too long for token <name>
  A string in a translation file is shorter than the minimum length
  specified in the description file.

ERROR: negative value for minimum length
  The minimum string length specified for a token must be positive.

ERROR: negative value for maximum length
  The maximum string length specified for a token must be positive.

ERROR: non-positive value for % ordering
  The position information for a % formatting command must be positive and
  greater than 1.

ERROR: % ordering value too large
  The position information for a % formatting command is greater than the
  number of formatting commands provided

ERROR: % size incorrect
  The size specifier for a % formatting command in a translation file does
  not match the size in the description file.

ERROR: % command does not match
  The type specifier for a % formatting command in a translation file does
  not match the size in the description file.

ERROR: token <name> defined multiple times
  A token was defined multiple times in either a description or a translation
  file.

ERROR: id <number> already used for token <name>
  An attempt was made to reuse an ID value twice within a description file

ERROR: no command found after '#'
  Command lines start with # and are followed by a command.

ERROR: <name> is not a valid command after '#'
  A command specified after # is invalid.

ERROR: <number> is not a valid codeset value
  An incorrect codeset value was specified for a #codeset command.

ERROR: couldn't write catalog <name>
  An error occurred while writing the catalog file

WARNING: <name> is an unknown formatting command
  An unknown % formatting command was specified. CatComp knows only of
  C-language formatting commands, anything else will be flagged
  with this warning.

WARNING: string for token <name> matches string in descriptor
  A string within a translation file matches exactly the original string
  from the description file. This may mean that the string was not
  translated.

C and Assembly Source Files
---------------------------

CatComp has the ability to output C and Assembly language source file headers.
The intent of this is to let application programmers manipulate a single
catalog description file and have source files generated for them
automatically so they can include the strings in their programs.

To generate these files, you need to give CatComp a descriptor file, and
either a C or an ASM output file name using the CFILE/K and ASMFILE/K
command-line options. The resulting files will be standard C and/or ASM
sources file headers that be used easily in application code.

Sample Use
----------

This section presents sample uses of CatComp with example command-lines.

Assume you have a catalog description file for an application called "app.cd".


To test if this file is a valid .cd file, type:

  CatComp app.cd

and CatComp will respond with either some error messages, or with a message
saying that 'app.cd' is a valid descriptor file.


To do a translation of a .cd file, you need a .ct file. Such a file can be
generated by doing:

  CatComp app.cd CTFILE app.ct

This will create a blank translation file called app.ct. You can then load
app.ct in a standard text editor and proceed to translate the strings it
contains.


Once a .ct file is done being translated, it must be converted in an IFF
catalog file. This is done by doing:

  CatComp app.cd app.ct CATALOG app.catalog

This will create a file called app.catalog.