README revision 19304
119304Speter# @(#)README 8.4 (Berkeley) 11/22/94 219304Speter 319304SpeterGenerally, all non-system error and informational messages in nvi are 419304Spetercatalog messages, i.e. they can be tailored to a specific langauge. 519304SpeterCommand strings, usage strings, system errors and other "known text" 619304Speterare not. It would certainly be possible to internationalize all the 719304Spetertext strings in nvi, but it's unclear that it's the right thing to do. 819304Speter 919304SpeterFirst, there's no portable way to do message catalogs. The System V 1019304Speterscheme is a reasonable choice, but none of the 4BSD derived systems 1119304Spetersupport it. So, catalogs are completely implemented within nvi, and 1219304Speterdon't require any library support. 1319304Speter 1419304SpeterMessage catalogs in nvi are fairly simple. Every catalog message 1519304Speterconsists of two parts -- an initial number followed by a pipe (`|') 1619304Spetercharacter, followed by the English text for the message. For example: 1719304Speter 1819304Speter msgq(sp, M_ERR, "001|This is an error message"); 1919304Speter 2019304Speterwould be a typical message. 2119304Speter 2219304SpeterWhen the msgq() routine is called, if the user has specified a message 2319304Spetercatalog and the format string (the third argument) has a leading number, 2419304Speterthen it is converted to a record number, and that record is retrieved 2519304Speterfrom the message catalog and used as a replacement format string. If 2619304Speterthe record can't be retrieved for any reason, the English text is displayed 2719304Speterinstead. 2819304Speter 2919304SpeterEach message format string MUST map into the English format string, i.e. 3019304Speterit can't display more or different arguments than the English one. 3119304Speter 3219304SpeterFor example: 3319304Speter 3419304Speter msgq(sp, M_ERR, "002|Error: %d %x", arg1, arg2); 3519304Speter 3619304Speteris a format string that displays two arguments. It is possible, however, 3719304Speterto reorder the arguments or to not display all of them. The convention 3819304Speternvi uses is the System V printf(3) convention, i.e. "%[0-9]*$" is the name 3919304Speterof a specific, numbered argument. For example: 4019304Speter 4119304Speter msgq(sp, M_ERR, "002|Error: %2$d %1$x", arg1, arg2); 4219304Speter 4319304Speterdisplays the arguments in reverse order. 4419304Speter 4519304SpeterIf the system supports this convention in its library printf routines 4619304Speter(as specified by the test #define NL_ARGMAX), nvi uses those routines. 4719304SpeterOtherwise, there is some serious magic going on in common/msg.c to make 4819304Speterthis all work. 4919304Speter 5019304SpeterArguments to the msgq function are required to contain ONLY printable 5119304Spetercharacters. No further translation is done by the msgq routine before 5219304Speterdisplaying the message on the screen. For example, in the msgq call: 5319304Speter 5419304Speter msgq(sp, M_ERR, "003|File: %s", file_name); 5519304Speter 5619304Speter"file_name" must contain only printable characters. The routine 5719304Spetermsg_print() returns a printable version of a string in allocated 5819304Spetermemory. For example: 5919304Speter 6019304Speter char *p; 6119304Speter 6219304Speter p = msg_print(sp, file_name); 6319304Speter msgq(sp, M_ERR, M("003", "File: %s"), p); 6419304Speter FREE_SPACE(sp, p, 0); 6519304Speter 6619304Spetermakes sure that "file_name" is printable before calling the msgq 6719304Speterroutine. 6819304Speter 6919304Speter=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 7019304Speter 7119304SpeterThe message catalogs themselves are maintained in two files. The first 7219304Speteris the "base file" which contains two fields, a record number and the 7319304Spetermessage itself. All base files are named using the convention 7419304Speter"vi_<language>.base", e.g. the English one is "vi_english.base". For 7519304Speterexample: 7619304Speter 7719304Speter 002 "Unable to create temporary file" 7819304Speter 003 "Warning: %s is not a regular file" 7919304Speter 004 "%s already locked, session is read-only" 8019304Speter 005 "%s: remove" 8119304Speter 006 "%s: close" 8219304Speter 007 "%s: remove" 8319304Speter 008 "%s: remove" 8419304Speter 009 "Read-only file, not written; use ! to override" 8519304Speter 010 "Read-only file, not written" 8619304Speter 8719304Speterare the first few lines of the current vi_english.base file. Note that 8819304Spetermessage #1 is missing -- the first message of each catalog is a special 8919304Speterone, so that nvi can recognize message catalog files. It's added by the 9019304SpeterMakefile script that creates the second version of the message catalog. 9119304Speter 9219304SpeterThe second file is the file used by nvi to access messages, and is a list 9319304Speterof the messages, one per line: 9419304Speter 9519304Speter VI_MESSAGE_CATALOG 9619304Speter Unable to create temporary fileX 9719304Speter Warning: %s is not a regular fileX 9819304Speter %s already locked, session is read-onlyX 9919304Speter %s: removeX 10019304Speter %s: closeX 10119304Speter %s: removeX 10219304Speter %s: removeX 10319304Speter Read-only file, not written; use ! to overrideX 10419304Speter Read-only file, not writtenX 10519304Speter 10619304SpeterNote that all messages have had a trailing 'X' character appended. This 10719304Speteris to provide nvi a place to store a trailing nul for the message so that 10819304SpeterC library routines that expect one won't be disappointed. 10919304Speter 11019304SpeterThese files are named for their language, e.g. "vi_english". The second 11119304Speterfiles are automatically created from the first files. 11219304Speter 11319304SpeterTo create a new catalog for nvi: 11419304Speter 11519304SpeterCopy the file vi_english.base to a file that you can modify , e.g. "cp 11619304Spetervi_english.base vi_german.base". For each of the messages in the file, 11719304Speterreplace the message with the string that you want to use. To find out 11819304Speterwhat the arguments to a message are, I'm afraid you'll have to search 11919304Speterthe source code for the message number. You can find them fairly quickly 12019304Speterby doing: 12119304Speter 12219304Speter cd ..; egrep '123\|' */*.[chys] 12319304Speter 12419304SpeterI'm sorry that there's not an easier way, but I couldn't think of 12519304Speteranything that wasn't a lot of work. 12619304Speter 12719304SpeterIf, for some reason, you don't have the file vi_english.base, or you 12819304Speterhave new sources for which you want to create a new base catalog, you 12919304Spetercan create it by running the command "make english" in the catalog 13019304Speterdirectory. 13119304Speter 13219304SpeterOnce you've translated all of the strings, then add your catalog to the 13319304Speter"CAT=" line of the Makefile, and run the command "make catalog". This 13419304Speterwill create the second (and corresponding) file for each file named 13519304Speter<language>.base. 13619304Speter 13719304SpeterDon't worry about missing line numbers, i.e. base files that look like: 13819304Speter 13919304Speter 005 Message number 5. 14019304Speter 007 Message number 7. 14119304Speter 14219304SpeterThis simply means that a message was deleted during the course of nvi's 14319304Speterdevelopment. It will be taken care of automatically when you create 14419304Speterthe second form of the file. 14519304Speter 14619304Speter=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 14719304SpeterIf you add new messages to the nvi sources, you can check your work by 14819304Speterdoing "make english; make check". The "make check" target lists unused 14919304Spetermessage numbers, duplicate message numbers, and duplicate messages. 15019304SpeterUnused message numbers are only useful if you are condensing messages. 15119304SpeterDuplicate message numbers are a serious problem and have to be fixed. 15219304SpeterDuplicate messages are only interesting if a message appears often enough 15319304Speterthat it's worth creating a routine so that the string is only need in 15419304Spetera single place. 15519304Speter 15619304Speter=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 15719304SpeterTo select a catalog when running nvi, set the "msgcat" option. If the 15819304Spetervalue of this option ends with a '/', it is treated as the name of a 15919304Speterdirectory that contains a message catalog "vi_XXXX", where XXXX is the 16019304Spetervalue of the LANG environmental variable, if it's set, or the value of 16119304Speterthe LC_MESSAGES environmental variable if it's not. If neither of those 16219304Speterenvironmental variables are set, or if the option doesn't end in a '/', 16319304Speterthe option is treated as the full path name of the message catalog to use. 16419304Speter 16519304SpeterIf any messages are missing from the catalog, the backup text (English) 16619304Speteris used instead. 167