1# @(#)README 8.4 (Berkeley) 11/22/94 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. It would certainly be possible to internationalize all the 7text strings in nvi, but it's unclear that it's the right thing to do. 8 9First, there's no portable way to do message catalogs. The System V 10scheme is a reasonable choice, but none of the 4BSD derived systems 11support it. So, catalogs are completely implemented within nvi, and 12don't require any library support. 13 14Message catalogs in nvi are fairly simple. Every catalog message 15consists of two parts -- an initial number followed by a pipe (`|') 16character, followed by the English text for the message. For example: 17 18 msgq(sp, M_ERR, "001|This is an error message"); 19 20would be a typical message. 21 22When the msgq() routine is called, if the user has specified a message 23catalog and the format string (the third argument) has a leading number, 24then it is converted to a record number, and that record is retrieved 25from the message catalog and used as a replacement format string. If 26the record can't be retrieved for any reason, the English text is displayed 27instead. 28 29Each message format string MUST map into the English format string, i.e. 30it can't display more or different arguments than the English one. 31 32For example: 33 34 msgq(sp, M_ERR, "002|Error: %d %x", arg1, arg2); 35 36is a format string that displays two arguments. It is possible, however, 37to reorder the arguments or to not display all of them. The convention 38nvi uses is the System V printf(3) convention, i.e. "%[0-9]*$" is the name 39of a specific, numbered argument. For example: 40 41 msgq(sp, M_ERR, "002|Error: %2$d %1$x", arg1, arg2); 42 43displays the arguments in reverse order. 44 45If the system supports this convention in its library printf routines 46(as specified by the test #define NL_ARGMAX), nvi uses those routines. 47Otherwise, there is some serious magic going on in common/msg.c to make 48this all work. 49 50Arguments to the msgq function are required to contain ONLY printable 51characters. No further translation is done by the msgq routine before 52displaying the message on the screen. For example, in the msgq call: 53 54 msgq(sp, M_ERR, "003|File: %s", file_name); 55 56"file_name" must contain only printable characters. The routine 57msg_print() returns a printable version of a string in allocated 58memory. For example: 59 60 char *p; 61 62 p = msg_print(sp, file_name); 63 msgq(sp, M_ERR, M("003", "File: %s"), p); 64 FREE_SPACE(sp, p, 0); 65 66makes sure that "file_name" is printable before calling the msgq 67routine. 68 69=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 70 71The message catalogs themselves are maintained in two files. The first 72is the "base file" which contains two fields, a record number and the 73message itself. All base files are named using the convention 74"vi_<language>.base", e.g. the English one is "vi_english.base". For 75example: 76 77 002 "Unable to create temporary file" 78 003 "Warning: %s is not a regular file" 79 004 "%s already locked, session is read-only" 80 005 "%s: remove" 81 006 "%s: close" 82 007 "%s: remove" 83 008 "%s: remove" 84 009 "Read-only file, not written; use ! to override" 85 010 "Read-only file, not written" 86 87are the first few lines of the current vi_english.base file. Note that 88message #1 is missing -- the first message of each catalog is a special 89one, so that nvi can recognize message catalog files. It's added by the 90Makefile script that creates the second version of the message catalog. 91 92The second file is the file used by nvi to access messages, and is a list 93of the messages, one per line: 94 95 VI_MESSAGE_CATALOG 96 Unable to create temporary fileX 97 Warning: %s is not a regular fileX 98 %s already locked, session is read-onlyX 99 %s: removeX 100 %s: closeX 101 %s: removeX 102 %s: removeX 103 Read-only file, not written; use ! to overrideX 104 Read-only file, not writtenX 105 106Note that all messages have had a trailing 'X' character appended. This 107is to provide nvi a place to store a trailing nul for the message so that 108C library routines that expect one won't be disappointed. 109 110These files are named for their language, e.g. "vi_english". The second 111files are automatically created from the first files. 112 113To create a new catalog for nvi: 114 115Copy the file vi_english.base to a file that you can modify , e.g. "cp 116vi_english.base vi_german.base". For each of the messages in the file, 117replace the message with the string that you want to use. To find out 118what the arguments to a message are, I'm afraid you'll have to search 119the source code for the message number. You can find them fairly quickly 120by doing: 121 122 cd ..; egrep '123\|' */*.[chys] 123 124I'm sorry that there's not an easier way, but I couldn't think of 125anything that wasn't a lot of work. 126 127If, for some reason, you don't have the file vi_english.base, or you 128have new sources for which you want to create a new base catalog, you 129can create it by running the command "make english" in the catalog 130directory. 131 132Once you've translated all of the strings, then add your catalog to the 133"CAT=" line of the Makefile, and run the command "make catalog". This 134will create the second (and corresponding) file for each file named 135<language>.base. 136 137Don't worry about missing line numbers, i.e. base files that look like: 138 139 005 Message number 5. 140 007 Message number 7. 141 142This simply means that a message was deleted during the course of nvi's 143development. It will be taken care of automatically when you create 144the second form of the file. 145 146=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 147If you add new messages to the nvi sources, you can check your work by 148doing "make english; make check". The "make check" target lists unused 149message numbers, duplicate message numbers, and duplicate messages. 150Unused message numbers are only useful if you are condensing messages. 151Duplicate message numbers are a serious problem and have to be fixed. 152Duplicate messages are only interesting if a message appears often enough 153that it's worth creating a routine so that the string is only need in 154a single place. 155 156=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 157To select a catalog when running nvi, set the "msgcat" option. If the 158value of this option ends with a '/', it is treated as the name of a 159directory that contains a message catalog "vi_XXXX", where XXXX is the 160value of the LANG environmental variable, if it's set, or the value of 161the LC_MESSAGES environmental variable if it's not. If neither of those 162environmental variables are set, or if the option doesn't end in a '/', 163the option is treated as the full path name of the message catalog to use. 164 165If any messages are missing from the catalog, the backup text (English) 166is used instead. 167