
 Adding HyperHelp To Your Own Tcl/Tk Application
 ---------------------------------------------------------------

 To add HyperHelp facilities to your own Tcl/Tk application:

   1) Obtain the BLT toolkit from harbor.ecn.purdue.edu.
      Add it to your favorite "wish" executable, or use
      the "blt_wish" provided with it.  The BLT toolkit
      supplies extra widgets and commands needed by the
      HyperHelp facility.

   2) Copy the "hyperhelp.tcl" source file to your Tcl
      application code directory.  Source it directly into
      your application, or create a "tclIndex" file and
      set up the search path for auto loading.

   3) Modify your application to include a call to
      "hyperhelp_init":

        USAGE:
          hyperhelp_init <application-name> <help-dir>

        EXAMPLE:
          hyperhelp_init "My Application" ./Help

   4) Add hooks into your application to invoke the HyperHelp
      viewer:

        USAGE:
          hyperhelp_file <file> ?<line>?  <== displays file
          hyperhelp_mesg <mesg> ?<line>?  <== displays message

        EXAMPLE:
          button .help -text "Help" \
              -command "hyperhelp_file Intro"


 Writing HyperHelp Documentation
 ---------------------------------------------------------------

 HyperHelp documentation is kept as a series of ASCII files
 in a "help" directory that is registered via the "hyperhelp_init"
 command.  The files are displayed exactly as they are written,
 with the exception of hyperlinks.

 Hyperlinks are added by embedding a statement surrounded by
 special "\%\%" characters.  Statements within the "\%\%"
 characters are interpreted as Tcl commands; white space around
 the commands is ignored.  A Hyperlink is defined using a
 command with the following form:

     hyperhelp_link <link-name> <jump-file> ?<jump-marker>?

 where <link-name> is the text displayed on the hyperlink
 button, <jump-file> is the name of another file in the help
 directory, and the optional <jump-marker> specifies a
 particular entry point for the help file.

 For example, following is an excerpt from the file that brought
 you to this point in the documentation:

     HyperHelp facilities are easily \%\%
    hyperhelp_link integrated HyperHelp.add
    \%\%
    into any Tcl/Tk
     application.

 Markers are defined in a similar manner, using the "hyperhelp_mark"
 command:

     hyperhelp_mark <marker-name>

 For example:

     More information is available in \%\%
    hyperhelp_link "Section A" some.file Section-A
    \%\%
    of this document.

     ...

    \%\%
    hyperhelp_mark Section-A
    \%\%
    This is the start of Section A...

 When the user traverses the link marked "Section A", the HyperHelp
 facility will jump immediately to the sentence "This is the start
 of Section A."
