1254225Speter# $Id: README,v 9.0 2012/10/19 17:06:15 zy Exp $ 219304Speter 319304SpeterGenerally, all non-system error and informational messages in nvi are 419304Spetercatalog messages, i.e. they can be tailored to a specific langauge. 5254225SpeterCommand strings, usage strings, system errors and other 'known text' 6254225Speterare not. 719304Speter 819304SpeterMessage catalogs in nvi are fairly simple. Every catalog message 919304Speterconsists of two parts -- an initial number followed by a pipe (`|') 1019304Spetercharacter, followed by the English text for the message. For example: 1119304Speter 1219304Speter msgq(sp, M_ERR, "001|This is an error message"); 1319304Speter 1419304Speterwould be a typical message. 1519304Speter 1619304SpeterWhen the msgq() routine is called, if the user has specified a message 1719304Spetercatalog and the format string (the third argument) has a leading number, 1819304Speterthen it is converted to a record number, and that record is retrieved 1919304Speterfrom the message catalog and used as a replacement format string. If 2019304Speterthe record can't be retrieved for any reason, the English text is displayed 2119304Speterinstead. 2219304Speter 2319304SpeterEach message format string MUST map into the English format string, i.e. 2419304Speterit can't display more or different arguments than the English one. 2519304Speter 2619304SpeterFor example: 2719304Speter 2819304Speter msgq(sp, M_ERR, "002|Error: %d %x", arg1, arg2); 2919304Speter 30254225Speteris a format string that displays two arguments. 3119304Speter 3219304SpeterArguments to the msgq function are required to contain ONLY printable 3319304Spetercharacters. No further translation is done by the msgq routine before 3419304Speterdisplaying the message on the screen. For example, in the msgq call: 3519304Speter 3619304Speter msgq(sp, M_ERR, "003|File: %s", file_name); 3719304Speter 3819304Speter"file_name" must contain only printable characters. The routine 39254225Spetermsg_print() returns a printable version of a string; the third argument 40254225Speterindicates whether the string needs to be freed. For example: 4119304Speter 4219304Speter char *p; 43254225Speter int nf; 4419304Speter 45254225Speter p = msg_print(sp, file_name, &nf); 46254225Speter msgq(sp, M_ERR, "003|File: %s", p); 47254225Speter if (nf) 48254225Speter FREE_SPACE(sp, p, 0); 4919304Speter 5019304Spetermakes sure that "file_name" is printable before calling the msgq 5119304Speterroutine. 5219304Speter 5319304Speter=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 5419304Speter 5519304SpeterThe message catalogs themselves are maintained in two files. The first 5619304Speteris the "base file" which contains two fields, a record number and the 5719304Spetermessage itself. All base files are named using the convention 58254225Speter"<language>.base", e.g. the English one is "english.base". For 5919304Speterexample: 6019304Speter 61254225Speter 002 "Line length overflow" 62254225Speter 003 "unable to delete line %lu" 63254225Speter 004 "unable to append to line %lu" 64254225Speter 005 "unable to insert at line %lu" 65254225Speter 006 "unable to store line %lu" 66254225Speter 007 "unable to get last line" 6719304Speter 68254225Speterare the first few lines of the current english.base file. 6919304Speter 70254225SpeterBefore this file being converted to the second file, the POSIX formatted 71254225Spetermessage catalog file, by gencat(1), two lines: 7219304Speter 73254225Speter $set 1 74254225Speter $quote " 7519304Speter 76254225Speterwill be inserted before the base text to setup the set_id and the quote 77254225Spetercharacter. So the double-quote needs to be escaped by a backslash to be 78254225Speterincluded in a message; same as the backslash itself. 7919304Speter 80254225SpeterThese files are named for their language, e.g. "english". However, a 81254225Speterlocale(1) name is also recommended. 8219304Speter 8319304SpeterTo create a new catalog for nvi: 8419304Speter 85254225SpeterCopy the file english.base to a file that you can modify , e.g. "cp 86254225Speterenglish.base german.base". For each of the messages in the file, 87254225Speterreplace the message with the string that you want to use. If you have 88254225Speterdoubts about the meaning of a message, just email me. 8919304Speter 90254225SpeterA latest english.base can be created from source by running the command 91254225Speter"make english" in the catalog/ directory. 9219304Speter 9319304SpeterOnce you've translated all of the strings, then add your catalog to the 9419304Speter"CAT=" line of the Makefile, and run the command "make catalog". This 9519304Speterwill create the second (and corresponding) file for each file named 9619304Speter<language>.base. 9719304Speter 9819304SpeterDon't worry about missing line numbers, i.e. base files that look like: 9919304Speter 10019304Speter 005 Message number 5. 10119304Speter 007 Message number 7. 10219304Speter 10319304SpeterThis simply means that a message was deleted during the course of nvi's 10419304Speterdevelopment. It will be taken care of automatically when you create 10519304Speterthe second form of the file. 10619304Speter 10719304Speter=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 10819304SpeterIf you add new messages to the nvi sources, you can check your work by 10919304Speterdoing "make english; make check". The "make check" target lists unused 11019304Spetermessage numbers, duplicate message numbers, and duplicate messages. 11119304SpeterUnused message numbers are only useful if you are condensing messages. 11219304SpeterDuplicate message numbers are a serious problem and have to be fixed. 11319304SpeterDuplicate messages are only interesting if a message appears often enough 11419304Speterthat it's worth creating a routine so that the string is only need in 11519304Spetera single place. 11619304Speter 11719304Speter=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 11819304SpeterTo select a catalog when running nvi, set the "msgcat" option. If the 11919304Spetervalue of this option ends with a '/', it is treated as the name of a 120254225Speterdirectory that contains a message catalog "$LC_MESSAGES", which is set 121254225Speterthrough the LC_MESSAGES environment variable but returned by setlocale(3). 122254225SpeterCheck the output of locale(1) to validate such a value. If the option 123254225Speterdoesn't end in a '/', the option is treated as the full path name of the 124254225Spetermessage catalog to use. 12519304Speter 12619304SpeterIf any messages are missing from the catalog, the backup text (English) 12719304Speteris used instead. 128