home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / tools / maktxt30 / maketext.doc next >
Text File  |  1990-12-27  |  7KB  |  154 lines
  1.  
  2.                       MakeText Version 3.0
  3.  
  4.                 A Help File Conversion Utility
  5.  
  6.                 Copyright (c) 1990  J.P. Ritchey
  7.  
  8.                    Compuserve ID: 72537,2420
  9.  
  10.  
  11. MakeText is a file conversion utility that takes as input a
  12. Borland format help file, TURBO.HLP for instance, and creates
  13. text files that are suitable for input to the Turbo Power
  14. Software MAKEHELP utility.
  15.  
  16. MakeText will convert the following Borland Help Files:
  17.  
  18.            Turbo Pascal 4.0, 5.0, 5.5 and 6.0
  19.            Turbo C 2.0
  20.            Turbo C++ 1.0
  21.            Quattro Pro 1.0 and 2.0
  22.            Turbo Assembler 2.0
  23.  
  24. Version 3.0 incorporates changes that enable MakeText to
  25. decompile the TASM, TC++ and Turbo Pascal help files.  There has also
  26. been the addition of a command line switch to enable generation of
  27. a "keyword index" topic.  See the discussion of the /I switch below for
  28. the details.
  29.  
  30.  
  31.  
  32. The syntax of the MakeText Program is:
  33.  
  34.    MAKETEXT  [options] <help file path>  [<text file path>]
  35.  
  36. The following options are supported:
  37.  
  38.      /Txxxx  -  Change starting Topic Number to xxxx.  This
  39.      option will override the default starting topic number
  40.      of 1.
  41.  
  42.      /S      -  Generate all output to a single file.  All of the
  43.      help text will be written to a file with a "TXT" extension.
  44.      No include files will be generated.
  45.  
  46.      /Wxx    -  Override the calculated value for the !WIDTH
  47.      statement with "xx".  If the value is less than the calculated
  48.      value,  it's possible that the generated help screens will
  49.      not look as desired.
  50.  
  51.      /N      -  Generate a "!NOINDEX" after each TOPIC.  See below
  52.     for a further explanation.
  53.  
  54.      /I      -  Generate a file with a "KWI" extension containing a
  55.      list of all keywords in the help file.  It is formatted properly
  56.      for inclusion as a TOPIC in the MAKEHELP input files.
  57.  
  58. As shown in the command line syntax, MakeText only requires one
  59. parameter, which is the of name of the Borland Help file to be
  60. converted. An optional second parameter is the path of the resulting
  61. output file(s).  If no second parameter is given, the output files
  62. will be written to the current directory with the name of the input
  63. help file.  To differentiate between the specification of a directory
  64. only and a directory and name, the entry of a directory only should end
  65. with a backslash.  This can best be shown with a few examples.
  66.  
  67.    C:\>MAKETEXT /T1001 C:\TP\TURBO.HLP
  68.         Input File: C:\TP\TURBO.HLP
  69.        Output File: C:\TURBO.xxx
  70.  
  71.    Include files will be written, with a starting Topic number of 1001.
  72.  
  73.  
  74.    C:\>MAKETEXT /S C:\TP\TURBO.HLP  C:\TPRO\
  75.         Input File: C:\TP\TURBO.HLP
  76.        Output File: C:\TPRO\TURBO.xxx
  77.  
  78.    All output will go to the file "C:\TPRO\TURBO.TXT"
  79.  
  80.  
  81.    C:\>MAKETEXT C:\TP\TURBO.HLP C:\TPRO   <-- No Trailing Backslash
  82.         Input File: C:\TP\TURBO.HLP
  83.        Output File: C:\TPRO.xxx   <-- Probably not what was desired
  84.  
  85. Due to the size of the help files to be converted, the output is
  86. split into multiple files, each approximately 40K bytes long,
  87. unless the /S option is used when executing MakeText.  The
  88. files created will have the extensions .001, .002, .003, etc.
  89. Turbo Pascal 5.5 will create 10 such files (.001 through .010).
  90. If the /I option is specified an additional file with the extension
  91. .KWI will also be generated.  Note than when generated, the .KWI file
  92. will always be a separate file whether the /S option was specified or
  93. not.
  94.  
  95. The final file created will have the extension .TXT. This file
  96. contains a "!WIDTH" and "!NOWRAP" directive and "!INCLUDE"
  97. directives for the files that have been created. A check is made
  98. before each numbered file is opened to see if disk space is
  99. available. Since each numbered file is split at a "!TOPIC"
  100. boundary and a single file could exceed 40K, a check for 45K of
  101. free disk is made. If that amount of free disk is unavailable,
  102. MakeText will pause allowing disks to be changed (if the output
  103. media is floppy disk) or aborting the program. You can instruct
  104. the program to continue, but if in fact the output file exhausts
  105. free disk the program will abort rather unceremoniously, possibly
  106. leaving buffered text in memory and not flushed to disk.
  107.  
  108. The Borland help system allows for "topics" to have multiple
  109. names, while a "topic" in the Turbo Power system can only have
  110. one name.  Since topic names are maintained in alphabetical order
  111. in a Borland Help file, and the first name encountered is assigned to
  112. the topic, it is likely that some topics will not have the
  113. correct name.  For instance the names CRT, BLACK, BLUE, etc. all
  114. refer to the same topic. BLACK will become the topic name,
  115. although CRT is probably more appropriate.
  116.  
  117. For those topics that have multiple names, pseudo-topics are
  118. created by MakeText.  These pseudo-topics are links to the
  119. actual topic text.  The text of the pseudo-topics is "See <topic
  120. name>", where <topic name> is the name selected as described
  121. above.
  122.  
  123. When merging the text generated by MAKETEXT with an existing set
  124. of help texts, the OPRO texts for instance, the resulting index
  125. displayed can be rather large.  If the /N command line is used, a
  126. !NOINDEX will be generated after each !TOPIC.  This will eliminate
  127. the BI topics from the TPRO/OPRO index.  In a Borland help file
  128. there is usually one topic that is identified as the main index
  129. page.  In Turbo Pascal, it's the help screen that is viewed when F1 is
  130. pressed from within the help system.  That topic will be indexed
  131. regardless of the use of the /N switch and be given the topic name of the
  132. help file itself.  In the case of Turbo Pascal, it would be
  133. "Turbo Pascal Help"
  134.  
  135.  
  136. The keyword index file
  137. ----------------------
  138. Certain help files contain an alphabetical list of all of the keywords
  139. contained within the help file (Turbo C++ DOES, TP6.0 doesn't).  The
  140. /I option allows you to create your own "topic" containing these
  141. keywords.  The standard apparently used by Borland is to make this index
  142. topic number 4.  If you inspect the files created by MAKETEXT from the
  143. TP6 help file you'll notice that topic #4 is a "No help available"
  144. topic.  You could insert the .KWI file into the help text as topic #4
  145. and then add a link to topic #4 in topic #3 (the TP main index).
  146.  
  147. Any questions or comments can be addressed to me on Compuserve
  148. to the PPN listed above via EasyPlex or at the following address:
  149.  
  150.                 J. Patrick Ritchey
  151.                 O'Neil Tents, Inc.
  152.                 PO Box 88
  153.                 Canal Winchester, OH  43110
  154.                 614-837-6352