HLP2KWF version 1.2:  Construct MultiHelp .KWF file from .HLP file
Copyright (c) 1995, D.J. Murdoch

Syntax:

    HLP2KWF helpfile[.hlp] [kwffile[.kwf]]

    will read the help file, find all the keywords and topic titles,
    and construct fake context strings to write to the keyword file.

    HLP2KWF is a DOS program, not a Windows program.

Background:

    Borland's Delphi for Windows allows multiple help files to be
    installed, so that a search for a keyword from the IDE will find it
    in any of them.  This is intended to be used for installable
    components, but any help file can be installed --- provided you have
    the .RTF source for it, and can get Borland's KWGEN utility to
    create a .KWF file from it.

    While working on a program (ScanHelp) that generates help files
    automatically, I had a lot of trouble getting KWGEN to work.  I
    don't know if it has bugs in it, or if I was just using it
    improperly, but I couldn't get it to work.

    I took a look at the .KWF files that come with Delphi, and they have
    a very simple format:  they're (almost) just a stream of variable
    length records containing (keyword, indicator of K or B footnote,
    title, context string).  I already had some source for reading .HLP
    files (based on Pete Davis's articles in Dr. Dobb's, Sept/Oct 1993),
    so I figured it would be pretty easy to create a .KWF file directly
    from the .HLP file.  To my surprise, it was, and here's HLP2KWF.

Details:

    I can see two potential uses for HLP2KWF:  installing "foreign" help
    files into Delphi's help system, and creating .KWF files for your
    own components, if you can't get KWGEN to work.  Here are the steps
    for doing your own component help files; for foreign files, just
    start at step 4:

      1.  Create the .RTF version of your help file, following the
      conventions listed in Delphi's Component Writer's Guide for
      creating the special B footnotes.  (The next release of ScanHelp
      will be able to do this automatically.  Look for version 3.4 or
      higher at an ftp site near you.)

      2.  In the [Options] section of the .HPJ project file for your
      help file, include the line

          Multikey=B

      This gets HC31 to put the B footnotes into the .HLP file; normally
      it strips them out.  If you want to really integrate your help
      into Delphi's, you might want to include the macro definitions

          RegisterRoutine("MultiHlp.DLL", "WinHelpEntry", "USS")
          CreateButton("SEARCHALL", "Search &all",
                    "WinHelpEntry(hwndApp, `DELPHI.hlp',`DELPHI.hdx')")
          BrowseButtons()

      in the [Config] section.  This will install a "Search All" button
      and browse buttons.

      3.  Run HC31 to generate the .HLP file, e.g.

          HC31 myhelp

      4.  Run HLP2KWF to generate the .KWF file, e.g.

          HLP2KWF myhelp

      5.  Copy the .HLP file into a directory on your search path, or
      make an entry for it in the WINHELP.INI file.

      6.  Back up your DELPHI.HDX file from your \DELPHI\BIN directory.
      It's fairly easy to make a mistake in the next step and wipe it
      out completely.

      7.  Back in Windows, run the "Keyword Merge" utility from the
      Delphi program group (normally HELPINST.EXE in the \DELPHI\HELP
      subdirectory), and open the DELPHI.HDX file.  If it says that a
      keyword file is not found, use Options|Search directories to point
      to the location of your DELPHI.KWF, CWG.KWF, and WINAPI.KWF files
      (normally \DELPHI\HELP).  Use the big green +, or Alt-I to add
      your new .KWF file to the list, and exit.

    Once you've gone through these steps, your help should be available
    in the Delphi IDE.  Start it up and give it a try!

Known bugs:

    If the help file you're trying to load is too large, HLP2KWF will
    abort, sometimes with an ugly run-time error 203.  There's not much
    you can do about this, other than to clear as much free memory as
    possible, try a smaller .HLP file, or order the source code which
    comes with a version compiled for protected mode.  Sorry.

    On rare occasions HLP2KWF will miss a topic. For example, it misses
    1 keyword out of about 1000 in the CWG.HLP file that comes with
    Delphi.  So far I don't know what causes this bug; I suspect it may
    be caused by errors in the original help file.  If you detect it in
    a help file for which you have source code, I'd appreciate it if you
    sent me a copy so I could try to find what's going wrong.

Release History:

    1.0 - First test release.
    1.1 - First public release.  Uses slightly less memory than 1.0,
          is slightly faster, and fixes minor bugs.
    1.2 - Modified to support keywords pointing to the middle of
          articles.

License:

    HLP2KWF is not public domain.  The copyright belongs to D.J.
    Murdoch.

    You are, however, free to use HLP2KWF without charge.  You may
    distribute HLP2KWF unmodified, together with this documentation
    file, provided that you charge no more than distribution costs, and
    on no account more than $10 per copy.

    In particular, you may not include it on a CD ROM compilation
    without prior permission unless you charge less than $10 per CD ROM.
    The authorized CICA, Simtel20 and Garbo CD ROM compilations have
    permission to include it.

Warranty:

    HLP2KWF comes with no warranty of any kind.  I've tried to get it to
    work, but remember that neither the .HLP nor .KWF file formats are
    documented, and there may well be special cases that cause HLP2KWF
    to fail, perhaps crashing your system.

Source code:

    HLP2RTF is written in Borland Pascal 7.  Source code is available
    for $50.  This includes the general purpose WinHelp reader.  It
    doesn't cover all facets of help files, but it does cover those
    parts that were described in the Dr. Dobb's article, and implements
    them in a native Borland Pascal manner. Some parts of the format are
    certainly not handled properly.

    Recompiling HLP2RTF requires utility routines from the Object
    Professional library by TurboPower Software.

    With any source code orders I'll include a version of HLP2RTF
    compiled for protected mode, together with the necessary support
    files.  I'll fill up the rest of the disk with various utilities.

Comments, orders and bug reports:

    Send any comments or bug reports to D.J. Murdoch at one of the
    following addresses:

      dmurdoch@mast.queensu.ca (Internet)
      DJ Murdoch at 1:249/99.5 (Fidonet)
      71631,122 (Compuserve)

      D. J. Murdoch
      337 Willingdon Ave.
      Kingston, Ontario, Canada
      K7L 4J3

    Orders for source code should be sent to the above address.  Please
    pay in advance by cheque or money order payable to "D. J. Murdoch",
    in the amount of $50CAD (drawn on a Canadian bank), $50USD (drawn on
    a US bank), or 32UKP (drawn on a UK bank).  I'll mail back the
    source code on 3.5" 1.44Meg disk, together with a number of other
    freeware and shareware utilities that I've written (including
    ScanHelp).
