Building Help Files


 Creating help  files is  quite easy;  you need  to have  an ASCII editor to
 create them.   You  should have your editor set to expand tab characters to
 spaces.  The help file can contain many different help categories.  Here is
 an example of several defined help categories:

   :0001:Help Category 1
   Help text help text help text
   Help text help text help text
   Help text help text help text
   :0002:Help category 2
   Help text help text help text
   Help text help text help text
   Help text help text help text
   Also see: ^Help Category 1^0001^

 Each help  category starts  with a  category number.   This  number must be
 written as  four hex  digits, starting  and ending with a colon.  Each help
 category must  have its  own, unique  number.  This number is the number of
 the help  category that  you set  using HlpSet().  You can optionally add a
 name to  the category  number; if you do so, it must immediately follow the
 colon that  terminates the  number.   If there is as much as a single space
 between the  second colon  and the  text on  that line,  the text  will  be
 treated as  part of  the help text.  Text on the following lines is used as
 the text  for the  help category,  until a  new line begins with a new help
 category number.   There is no special symbol to indicate the end of a help
 category.

 TCXL represents  help categories as integers.  When assigning help category
 numbers in  the help  file, you should start at 1 (:0001: in the help file)
 and go  up from there.  The highest available help category number is 61439
 (:EFFF: in the help file).  Help category number 0 is reserved to represent
 an empty  help category.   Help category FFFF is used to include other help
 files (see  below).  Help categories between F000 and FFFE are reserved for
 TCXL internal use.

 In the  definition of  help category 2, you will notice the cross-reference
 to help  category 1.   All  cross-referencing is done by prefixing the help
 category name  with a  caret (^),  suffixing it with another caret (^), and
 adding the  help category  number with  a final caret (^).There are several
 special character  sequences that are recognized inside help category text.
 Each of  these special  sequences begins  with  a  backslash  (\).    These
 sequences fall into two categories: display control and text control.

 The display control sequences are used to embed TCXL window escape codes in
 help text,  so that you can control text attributes and positioning.  There
 are two formats for display control codes:

 \NNN.....................Octal number, where N represents a single octal
                          digit. For example: \033 represent the escape
                          character.

 \xNN.....................Hex number, where N represent a single hex digit.
                          The hex digits A through F are not case-sensitive.
                          For example: \x1B represents the escape character.

 With these  codes, you  can insert  such sequences  as \033F\x15 (i.e., set
 foreground to bright white) directly into the help text.

 The text  control codes  are \r,  \n, \p,  and \c.  Use either \r or \n, or
 both, to  indicate an  end-of-line inside  help  text  (e.g.,  "This  is  a
 line\nThis is  another line").  Use \p at the end of a line, if you want to
 leave out  the carriage-return/line-feed  that terminates the line.  Use \c
 at the end of a line to concatenate the line with the beginning of the next
 line.   You can also use \c to indicate a comment, since all text following
 the \c on that line will be ignored.

 The special  help category  number FFFF  is used to include other help text
 files into  the one in which you are working.  To do this, go to the end of
 your help  file, add a line that contains :FFFF:, and follow that line with
 a list  of help  files to be included, each on a line by itself.  NOTE: You
 MUST include the default TCXL help/message file (TCXLDEF.TXT) into any help
 file you create.

 After you  create the  help text  file, you  will need to compile it into a
 form that  is usable  by the  TCXL Help  System.   The TCXL  help  compiler
 utility, MAKMSG.COM, takes as input your ASCII help text file and outputs a
 compressed and  indexed version  of the  same file.   This  new file is the
 actual help  file that  you specify  with MsgHlpName()  or HlpDef().    The
 MAKEMSG syntax is as follows:

 MAKEMSG <input-file> [<output-file>]

 WHERE:  <input-file>  is the raw .TXT file
         <output-file> is the compiled .MSG file to be written

         If no extension is supplied, .TXT is used for the raw file and .MSG
         is used for the compiled file.  If <output-file> is not specified,
         the <input-file> name is used with the appropriate extension.

 If you  have .ASC  files from version 5.5x of TCXL, you can use the utility
 CVTHELP.COM to convert the files into a form that is acceptable as input to
 MAKEMSG.  The CVTHELP syntax is as follows:

 CVTHELP <input-file> [<output-file>]

 WHERE:  <input-file>  is the raw .ASC file
         <output-file> is the new .TXT file to be written

 If no extension is supplied, .ASC is used for the raw file and .TXT is used
         for the new file.  If <output-file> is not specified, the <input-
         file> name is used with the appropriate extension.