home *** CD-ROM | disk | FTP | other *** search
/ Shareware Supreme Volume 6 #1 / swsii.zip / swsii / 104 / HLP2TPH.ZIP / HLP2TPH.DOC < prev    next >
Text File  |  1993-10-28  |  7KB  |  154 lines
  1. HLP2TPH v. 1.0 - Convert TurboPower .HLP files to Borland .TPH files
  2.  
  3. Copyright (c) 1993, D.J. Murdoch.  This program is *not* public domain;
  4. see the license description below.
  5.  
  6. SYNTAX:
  7.  
  8.     Syntax:  HLP2TPH Infile[.HLP] [Outfile[.TPH]] [/Option]
  9.  
  10.              Will convert the TurboPower POPHELP help file Infile to
  11.              Borland .TPH format (suitable for the version 7.0 IDE or
  12.              the Pascal THELP 3.0).  By default, the filename of the
  13.              output file is the same as the input file, with extension
  14.              changed to .TPH.
  15.  
  16.     Option:  /F  Toggle automatic wrapping.  By default, HLP2TPH will
  17.                  produce help files with most paragraphs automatically
  18.                  wrapped to fit the display window.  Paragraphs
  19.                  containing lines starting with a blank stay fixed.
  20.                  With this option, all paragraphs stay fixed with the
  21.                  original line breaks.
  22.  
  23. DESCRIPTION:
  24.  
  25.     TurboPower Software distributes the help compiler MAKEHELP and the
  26.     TSR help viewer POPHELP with several of their toolkits.  (For
  27.     details on how to get them, see below.) The Borland Pascal 7.0 IDE
  28.     allows you to load multiple help files, but the file format is
  29.     different from the TurboPower format.  I found that I wanted to
  30.     switch between the Borland help and the TurboPower help so
  31.     frequently that I wanted everything in a single viewer.
  32.  
  33.     Unfortunately, Borland charges $50 for their Open Architecture
  34.     Handbook, which comes with their help compiler.  I already had my
  35.     own code to produce Borland .TPH files (as part of my update to
  36.     TurboPower's SCANHELP program), so I decided it wouldn't be hard to
  37.     write a file convertor that went from binary format to binary
  38.     format.  It wasn't, and HLP2TPH was born.
  39.  
  40. DETAILS:
  41.  
  42.     There are several differences between the Turbopower and Borland
  43.     help files that HLP2TPH has to work around.  First, Borland help
  44.     files are written to work in the resizable windows of the IDE, while
  45.     TurboPower help files have all the word wrapping done by the
  46.     compiler.  I've found that most files work well with automatic
  47.     wrapping, but have provided the /F option to turn it off.
  48.  
  49.     The automatic wrapping works like this:  HLP2TPH scans the help file
  50.     a paragraph at a time.  (It considers any group of non-blank lines
  51.     to be a paragraph.)  If any line in the paragraph is indented from
  52.     the left margin, then the whole paragraph will be left in fixed
  53.     format.  If not, HLP2TPH will allow the IDE to reformat the
  54.     paragraph to fit the current size of the window.
  55.  
  56.     The wrapping isn't perfect; there are several topics in OPRO.HLP
  57.     with paragraphs that HLP2TPH won't recognize as fixed, for instance.
  58.     If this is a problem, the only remedy is to alter the source for
  59.     that screen to insert blanks at the start of some of the lines, and
  60.     to recompile the file using MAKEHELP and then convert it again.
  61.  
  62.     Another difference between the help formats is the indexing
  63.     strategy.  TurboPower help files have essentially two indices:
  64.     a short one that you're supposed to look at, and a hidden one that's
  65.     used for context searches.  (Topics are put in the short index if
  66.     you don't specify !NOINDEX, and they're put in the long index if you
  67.     don't specify !NOSEARCH.)  Borland help files have only one index,
  68.     which may be merged by the IDE with the indices from other files.
  69.     In case of a collision (two help screens with the same index entry),
  70.     POPHELP cycles among the various possibilities, whereas Borland's
  71.     IDE presents all choices in the index, with a subtitle used to
  72.     distinguish among them.
  73.  
  74.     I've chosen to adopt the following strategy to deal with this. I
  75.     create Borland index entries for all topics in the hidden index, and
  76.     try to guess at subtitles that will be appropriate to distinguish
  77.     collisions.  I also create an index topic, and name it according to
  78.     the output filename.  For example, OPRO.TPH would get a topic called
  79.     "OPRO index", which contains all the entries in the .HLP file short
  80.     index.
  81.  
  82.     The subtitle guessing algorithm is to use the first highlighted word
  83.     on the first line as the subtitle.  In the OPRO.HLP help file, this
  84.     guessing algorithm almost always finds the appropriate subtitle. In
  85.     some topics, there's no highlighted word on the first line; in that
  86.     case, I give no subtitle, and the Borland IDE will fall back to the
  87.     default subtitle, the help file filename.
  88.  
  89.     Another difference between the formats is that the TurboPower format
  90.     has 3 levels of highlighting, while the Borland format has only one,
  91.     and uses it to mark code examples for pasting.  HLP2TPH translates
  92.     all TurboPower highlighting into the single Borland highlight
  93.     method.  Nested highlighting will switch back to normal text.
  94.  
  95.     Finally, the Borland format doesn't provide any way to enter control
  96.     characters, while the TurboPower format uses a ^F to mark the next
  97.     character as a literal.  HLP2TPH will insert the literal character,
  98.     unless it's a special control character for the Borland help system
  99.     (^A, ^B, ^E, or #0).  There's no way to get those characters to
  100.     appear in a help topic.  Unprefixed control characters will always be
  101.     translated by prefixing a "^" symbol.
  102.  
  103. GETTING MAKEHELP:
  104.  
  105.     TurboPower Software distributes MAKEHELP and POPHELP with their
  106.     Object Professional, B-Tree Filer and Async Professional toolkits.
  107.     (They also distribute a help compiler with Turbo Professional, but
  108.     it is not compatible with HLP2TPH.)  For information on these,
  109.     contact them at
  110.  
  111.        TurboPower Software
  112.        P.O. Box 49009
  113.        Colorado Springs, CO 80949-9009
  114.  
  115.        719-260-6641 (voice, Monday-Friday 9AM-5PM)
  116.        719-260-7151 (fax)
  117.        Compuserve: 76004,2611
  118.  
  119. ACKNOWLEDGMENTS:
  120.  
  121.     Thanks to Kim Kokkonen of TurboPower Software for helpful comments
  122.     on HLP2TPH.  HLP2TPH is written in Borland Pascal 7.0, using the
  123.     Object Professional toolkit from Turbopower.
  124.  
  125. LICENSE:
  126.  
  127.     This program is not public domain. It was created by and is
  128.     copyrighted by Duncan Murdoch.
  129.  
  130.     You are licensed to use HLP2TPH at no charge. You are also licensed
  131.     to distribute it unchanged, provided you charge no more than
  132.     reasonable distribution costs, and in no case more than $10 (US). In
  133.     particular, without prior written permission you may not include it
  134.     in a CD ROM compilation if you charge more than $10 (US) for the
  135.     collection.
  136.  
  137.     Source code to HLP2TPH is available for $25 (US dollars drawn on a
  138.     US bank, or Canadian dollars drawn on a Canadian bank).  As an
  139.     additional benefit, if you order the source code I'll also send you
  140.     a disk containing other Turbo Pascal utilities that I've written.
  141.  
  142.     Comments and orders should be sent to
  143.  
  144.        Duncan Murdoch
  145.        337 Willingdon Ave.
  146.        Kingston, Ontario, Canada
  147.        K7L 4J3
  148.  
  149.     Email addresses:
  150.  
  151.        Compuserve:   71631,122
  152.        Internet:     dmurdoch@mast.queensu.ca
  153.        Fidonet:      DJ Murdoch at 1:249/99.5
  154.