$VER: CatComp_Documentation 38.11 (19.11.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 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. 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. If a string ends with a backslash character, this means that the next line in the file should be considered a continuation of the current line. 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] 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: ## version 38.12 (25.11.91) ## codeset 0 ## language francais ; MSG_HELLO Ceci est une chaine test pour être vue ; MSG_BYE Ceci est une autre chaine test The first three lines are command lines. The following line is a comment line as it starts with a semicolon. The following line you list the symbolic name of the string, and on the second line the translated string. If a string ends with a backslash character, this means that the next line in the file should be considered a continuation of the current line. 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 As well, when any string line within a description or translation file ends with a backslash ("\"), it means that the following line within the file is to be considered a continuation of the current line. 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 %N %T 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. Note that when using strings with the line continuation character ("\"), the line numbers printed will refer to the last line of the strings, even though the error may be in the first line. ERROR: string line for token 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 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: 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 not found A token specified in a catalog description file was not present in a translation file ERROR: string too short for token A string in a translation file is shorter than the minimum length specified in the description file. ERROR: string too long for token 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 defined multiple times A token was defined multiple times in either a description or a translation file. ERROR: id already used for token 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: is not a valid command after '#' A command specified after # is invalid. ERROR: is not a valid codeset value An incorrect codeset value was specified for a #codeset command. ERROR: couldn't write catalog An error occurred while writing the catalog file WARNING: 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 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 source file headers that can be used easily in application code. Special commands can be imbedded in catalog description files to provide control over the generation of header files. These commands are introduced by a # symbol within the catalog description file. The supported commands are: #header
This lets you indicate the base name of the header files being produced. The base name is then used as the top of header files. For example: #header TEXTTABLE would cause the following to be added at the start of the C header file: #ifndef TEXTTABLE_H #define TEXTTABLE_H #ifdef Causes CatComp to enclose the following identifiers within a conditional compilation block. #endif Causes CatComp to terminate the current conditional compilation block. #lengthbytes Causes CatComp to precede every following strings with 'n' bytes of length information. The default number of bytes is 0. The locale.library/GetCatalogStr() function will then return a pointer to the length bytes, followed by the actual string. The length indicated does NOT include the length bytes themselves. 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.