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