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