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