Process of Creating Windows Help Files (Long)

["R. Darren Carlton" <wk06248 -at- WORLDLINK -dot- COM>]

Purpose
-----------------------
I've had a couple of requests to briefly explain the process of creating
an on-line help file for a MS Windows application. While you can buy tools
to automate this process, you might find it interesting to "look under the
hood" (Doc-To-Help's phrase) of the process of creating a help file.
Microsoft's Windows Help Authoring Guide (WHAG) provides an excellent,
comprehensive, explanation of this process.


Intended Audience
-----------------------
This posting assumes that readers have at least a foggy idea about creating
on-line help files (for any system) and that readers understand such
terms as "compiling" and "rtf."


Disclaimer & Plea for Mercy
-----------------------
I'm posting this on my own time, so the text will _not_ be finely, or even
roughly, edited. All of this information should be technically correct
(although I'm fudging here and there for brevity's sake)--but no
guarantees.


How This Posting Is Organized
------------------------
In order to move from simple to complex, I'm going to explain the process
of creating a help file in reverse: I'll start by explaining the result of
the process (i.e., a file that can be shipped with the application), and
I'll finish by explaining the myriad ways writers can produce a word
processing file that can eventually be converted into an on-line help
file.


Overview of the Process of Creating a MS Windows Help File
------------------------
In reverse order,the steps are as follows:
> Copy the compiled help file (designated with the .hlp extension) into
  the application's directory
> Compile .rtf file(s) to create the .hlp file
> Create the Help Project file (designated with the .hpj extension)
> Convert a word processor file into the .rtf format
> Create a word processor file; encode the text to create hypertext links,
  etc.


Copying the Compiled Help (.hlp) File
------------------------
The following is an explanation of why you must copy the .hlp file into
the application's directory:
        When a user asks for help (by pressing F1 or selecting
        a menu option), the application opens another application
        called  "WinHelp.exe". WinHelp.exe looks for and opens a file
        with the extension ".hlp". The actual help text is contained in
        this .hlp file.


Compiling the .rtf File(s)
------------------------
The .hlp file is created by compiling .rtf file(s).

Background:
        Most of you are familiar with how SGML works: you tag text
        with codes and then run the tagged text through an application
        that formats the text based on the SGML tags. The Windows
        help compiler works like the SGML formatting application.

The Windows help compiler uses certain .rtf tags to format the help text
and to create hypertext links, keyword search terms, browse sequences,
etc.

To run the compiler, you need
> at least one .rtf file
> one help project (.hpj) file


Creating the .hpj File
------------------------
The help project (.hpj) file is an ascii text file that tells the compiler
everything it needs to know to create the .hlp file:
> Which .rtf file(s) to compile
> Which graphic file(s) to compile
> The size, color, and location of the help window that WinHelp.exe
  displays
> Instructions for making the help context sensitive


Converting a Word Processor File to .rtf
--------------------------
Since the compiler uses .rtf tags to format the help text, you must convert
the files containing the help text into the .rtf format. In theory, you can
write your help text in any kind of text editor that will export text as .rtf.


Creating and Encoding in the Word Processor
--------------------------
The goal of working in the word processor is to produce an .rtf file with
the proper tags for the Windows help compiler. (Unfortunately,it seems that
each word processor produces different .rtf tags.) The following chart shows
an example of the text attributes that, when converted into .rtf tags, will
create certain aspects of the help file:

Text with
This Attribute:                 Converts into:
______________________________________________
Double Underline                hot text

Hidden text                     instructions
                                on where to jump

Footnote with the               a title for the
# reference                     help topic



Any Questions?
--------------------
Dare I ask? Just send them my way and I'll try to respond. :-)