home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / i18nv102.zip / DOC / CVTMSG.DOC next >
Text File  |  1995-08-28  |  8KB  |  209 lines
  1.  
  2. ===============================================================================
  3.       CVTMSG Utility                                       January 1995
  4. ===============================================================================
  5.  
  6.  
  7. /************************/
  8. /***     Contents     ***/
  9. /************************/
  10.  
  11. 1.  Overview
  12. 2.  Command parameters
  13. 3.  Input file
  14. 4.  Output file
  15. 5.  Function
  16.  
  17.  
  18. 1.  Overview
  19. ============
  20.  
  21. Convert Message (CVTMSG) is used to convert the source for an OS/2 message file
  22. (Make Message File (MKMSGF) format) into the source for an XPG/4 message file
  23. (Internationalization (I18N) Generate Catalog (GENCAT) format).
  24.  
  25.  
  26. 2.  Command Parameters
  27. ======================
  28.  
  29. CVTMSG is an OS/2 program which expects these parameters:
  30.  
  31.      CVTMSG   input_OS2_file   output_XPG4_file   [options]
  32.  
  33. where:
  34.  
  35.      input_OS2_file     This parameter indicates the name of the input file
  36.                         which contains the message source for the MKMSGF
  37.                         utility (from the OS/2 Toolkit).
  38.  
  39.      output_XPG4_file   This parameter indicates the name of the output file
  40.                         to which the converted message source will be written
  41.                         in a format compatible with the GENCAT utility (from
  42.                         the I18N package).
  43.  
  44.      options            /C   Include the text from all OS/2 source comments
  45.                              in the generated XPG/4 message source.  Otherwise,
  46.                              OS/2 comment text is not included in the output
  47.                              file.
  48.  
  49.                         /P   Prompt at the beginning of execution to ensure
  50.                              that the passed parameters were correctly defined.
  51.                              The user will have the option to terminate
  52.                              processing before any conversion is performed.
  53.  
  54.                         /S   Generate symbolic XPG/4 message IDs which are the
  55.                              same as the OS/2 message ID (3 character component
  56.                              plus the 4 digit number, i.e. MSG0001). Otherwise,
  57.                              the XPG/4 message ID will consist of only the
  58.                              numeric part of the OS/2 message ID (i.e. 0001).
  59.  
  60.  
  61.  
  62. 3.  Input file
  63. ==============
  64.  
  65. The input file (which is specified by the first parameter) must contain
  66. source which is compilable by the MKMSGF utility from the OS/2 Toolkit.  The
  67. input file will not be modified by this process.
  68.  
  69. For example:
  70.  
  71.      ; comment record.  Semicolon must be in column 1.
  72.      ; The next line defines the message component value.
  73.      MSG
  74.      ;
  75.      MSG0001E: Message text for message number one, which is an
  76.      error message.  %1 %2 %3 %4 %5 %6 %7 %8 %9 indicate
  77.      replacement variables.
  78.      ;
  79.      ;  Message number two is not used because of "?" after the number.
  80.      MSG0002?:
  81.      ;
  82.      MSG0003I: Message text for message number three, which is an
  83.      informational message.
  84.      ;
  85.      MSG0004I: This shows a special variable: %0
  86.      ;
  87.      MSG0005I: This is the last message in this example.
  88.  
  89.  
  90. Special conversion considerations:
  91.  
  92.      A.  Comments are lines which have a semicolon ";" in column 1.  The
  93.          entire line is considered part of the comment text.
  94.  
  95.      B.  Replacement variables are defined as: %1 %2 %3 %4 %5 %6 %7 %8 %9.
  96.          All replacement variables are considered to be character string
  97.          values.
  98.  
  99.      C.  The value %0 indicates that a new line character is NOT to be
  100.          added to the end of this text line;  it is NOT a replacement variable.
  101.          Any text which follows the %0 is ignored and discarded.
  102.  
  103.      D.  Messages defined with a type of "?" are place-holders and do not
  104.          really define a usable message.
  105.  
  106.  
  107.  
  108. 4.  Output file
  109. ===============
  110.  
  111. The output file (which is specified by the second parameter) will contain
  112. the converted message source which is compilable by the GENCAT utility.
  113.  
  114. For example, the OS/2 message source shown in the "Input File" section above
  115. will create the following XPG/4 message source when the default options are
  116. used (the /C option was specified to include the converted comment text):
  117.  
  118.      $  comment record.  Semicolon must be in column 1.
  119.      $  The next line defines the message component value.
  120.      $
  121.      $quote "     (Define message text delimiter)
  122.      $set 1       (Message component: MSG)
  123.      $
  124.      0001    "MSG0001: Message text for message number one, which is an\n\
  125.      error message.  %1$s %2$s %3$s %4$s %5$s %6$s %7$s %8$s %9$s indicate\n\
  126.      replacement variables.\n"
  127.      $
  128.      $   Message number two is not used because of "?" after the number.
  129.      $
  130.      0003    "Message text for message number three, which is an\n\
  131.      informational message.\n"
  132.      $
  133.      0004    "This shows a special variable: "
  134.      $
  135.      0005    "This is the last message in this example.\n"
  136.  
  137. For example, the OS/2 message source shown in the "Input File" section above
  138. will create the following XPG/4 message source when the /S option was specified
  139. to create symbolic message IDs:
  140.  
  141.      $  comment record.  Semicolon must be in column 1.
  142.      $quote "     (Define message text delimiter)
  143.      $set 1       (Message component: MSG)
  144.      $
  145.      MSG0001 "MSG0001: Message text for message number one, which is an\n\
  146.      error message.  %1$s %2$s %3$s %4$s %5$s %6$s %7$s %8$s %9$s indicate\n\
  147.      replacement variables.\n"
  148.      MSG0003 "Message text for message number three, which is an\n\
  149.      informational message.\n"
  150.      MSG0004 "This shows a special variable: "
  151.      MSG0005 "This is the last message in this example.\n"
  152.  
  153.  
  154. Special conversion considerations:
  155.  
  156.      A.  Comments are lines which have "$" in column 1 and a blank in column 2.
  157.          Comment text can also be defined on the "$quote" and "$set" statements.
  158.  
  159.      B.  The "$set " line defines the delimiter character which is used to
  160.          identify the text of the message.
  161.  
  162.      C.  Replacement variables are defined as "%n$s", where "n" is a one digit
  163.          number (1-9) and "s" identifies the replacement text is a string of
  164.          characters.
  165.  
  166.  
  167.  
  168. 5.  Function
  169. ============
  170.  
  171. The conversion is performed as follows:
  172.  
  173.      A.  OS/2 comments are lines which have a semicolon ";" in column 1, with
  174.          comment text starting in column 2.  The conversion default is that
  175.          comments are not included in the output source.  When the "/C" option
  176.          is specified, OS/2 comments are converted to XPG/4 comments and are
  177.          included in the output source.  XPG/4 comments have a "$" in column 1,
  178.          a blank in column 2, with comment text starting in column 3.
  179.  
  180.      B.  Converted message text will always be delimited with double quotes.
  181.          This tool will add a   $quote "   statement for this purpose.
  182.  
  183.      C.  All converted messages will always be added to be XPG/4 message set
  184.          number 1.  This tool will add a "$set 1" statement for this purpose.
  185.  
  186.      D.  The formatting of the OS/2 message text will be preserved in the
  187.          converted XPG/4 message text.  New line characters "\n" will be added
  188.          to maintain formatting.
  189.  
  190.      E.  A new line character will be added at the end of the XPG/4 message
  191.          text when "%0" is not defined at the end of the OS/2 message text.
  192.  
  193.      F.  OS/2 replacement variables are defined as: %1 %2 %3 %4 %5 %6 %7 %8 %9,
  194.          and are always considered to be character string values.  Each
  195.          variable is converted to an equivalent XPG/4 variable format:
  196.          %1$s %2$s %3$s %4$s %5$s %6$s %7$s %8$s %9$s.  The one digit number
  197.          remains the same (to insure proper sequencing) and each variable
  198.          must be a character string replacement variable.
  199.  
  200.      G.  OS/2 messages defined with a type of "?" are place-holders and do not
  201.          really define a usable message.  These messages are not included in
  202.          the output XPG/4 message file.
  203.  
  204.      H.  OS/2 messages which have a message type of "E" (error) or "W" (warning)
  205.          will have the message identifier added to the beginning of the message
  206.          text (see MSG0001 in the above example).  This will simulate the
  207.          function provided by DosGetMessage for these types of messages.
  208.  
  209.