1# $Id: README,v 9.0 2012/10/19 17:06:15 zy Exp $ 2 3Generally, all non-system error and informational messages in nvi are 4catalog messages, i.e. they can be tailored to a specific langauge. 5Command strings, usage strings, system errors and other 'known text' 6are not. 7 8Message catalogs in nvi are fairly simple. Every catalog message 9consists of two parts -- an initial number followed by a pipe (`|') 10character, followed by the English text for the message. For example: 11 12 msgq(sp, M_ERR, "001|This is an error message"); 13 14would be a typical message. 15 16When the msgq() routine is called, if the user has specified a message 17catalog and the format string (the third argument) has a leading number, 18then it is converted to a record number, and that record is retrieved 19from the message catalog and used as a replacement format string. If 20the record can't be retrieved for any reason, the English text is displayed 21instead. 22 23Each message format string MUST map into the English format string, i.e. 24it can't display more or different arguments than the English one. 25 26For example: 27 28 msgq(sp, M_ERR, "002|Error: %d %x", arg1, arg2); 29 30is a format string that displays two arguments. 31 32Arguments to the msgq function are required to contain ONLY printable 33characters. No further translation is done by the msgq routine before 34displaying the message on the screen. For example, in the msgq call: 35 36 msgq(sp, M_ERR, "003|File: %s", file_name); 37 38"file_name" must contain only printable characters. The routine 39msg_print() returns a printable version of a string; the third argument 40indicates whether the string needs to be freed. For example: 41 42 char *p; 43 int nf; 44 45 p = msg_print(sp, file_name, &nf); 46 msgq(sp, M_ERR, "003|File: %s", p); 47 if (nf) 48 FREE_SPACE(sp, p, 0); 49 50makes sure that "file_name" is printable before calling the msgq 51routine. 52 53=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 54 55The message catalogs themselves are maintained in two files. The first 56is the "base file" which contains two fields, a record number and the 57message itself. All base files are named using the convention 58"<language>.base", e.g. the English one is "english.base". For 59example: 60 61 002 "Line length overflow" 62 003 "unable to delete line %lu" 63 004 "unable to append to line %lu" 64 005 "unable to insert at line %lu" 65 006 "unable to store line %lu" 66 007 "unable to get last line" 67 68are the first few lines of the current english.base file. 69 70Before this file being converted to the second file, the POSIX formatted 71message catalog file, by gencat(1), two lines: 72 73 $set 1 74 $quote " 75 76will be inserted before the base text to setup the set_id and the quote 77character. So the double-quote needs to be escaped by a backslash to be 78included in a message; same as the backslash itself. 79 80These files are named for their language, e.g. "english". However, a 81locale(1) name is also recommended. 82 83To create a new catalog for nvi: 84 85Copy the file english.base to a file that you can modify , e.g. "cp 86english.base german.base". For each of the messages in the file, 87replace the message with the string that you want to use. If you have 88doubts about the meaning of a message, just email me. 89 90A latest english.base can be created from source by running the command 91"make english" in the catalog/ directory. 92 93Once you've translated all of the strings, then add your catalog to the 94"CAT=" line of the Makefile, and run the command "make catalog". This 95will create the second (and corresponding) file for each file named 96<language>.base. 97 98Don't worry about missing line numbers, i.e. base files that look like: 99 100 005 Message number 5. 101 007 Message number 7. 102 103This simply means that a message was deleted during the course of nvi's 104development. It will be taken care of automatically when you create 105the second form of the file. 106 107=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 108If you add new messages to the nvi sources, you can check your work by 109doing "make english; make check". The "make check" target lists unused 110message numbers, duplicate message numbers, and duplicate messages. 111Unused message numbers are only useful if you are condensing messages. 112Duplicate message numbers are a serious problem and have to be fixed. 113Duplicate messages are only interesting if a message appears often enough 114that it's worth creating a routine so that the string is only need in 115a single place. 116 117=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 118To select a catalog when running nvi, set the "msgcat" option. If the 119value of this option ends with a '/', it is treated as the name of a 120directory that contains a message catalog "$LC_MESSAGES", which is set 121through the LC_MESSAGES environment variable but returned by setlocale(3). 122Check the output of locale(1) to validate such a value. If the option 123doesn't end in a '/', the option is treated as the full path name of the 124message catalog to use. 125 126If any messages are missing from the catalog, the backup text (English) 127is used instead. 128