Delphi Components - Writing Help Files - Checklist
The other pages in this series give extremely specific instructions on
how to create Delphi component help files.
This page provides a checklist of how to create, compile, and link
help file templates automatically generated from your existing *.pas files.
Download and Install
| Generate
| Create Support Files
| Compile
| Link
| Test
| Add Content
Related pages
Writing Help Files
| Style_Guide
| Table of Contents
| MS Help Workshop
| Checklist
| More Tips
Download and Install
The Delphi Help Template Generator
-
Download the zip file
- Un-zip the file
- Install the program in the Delphi tools menu
Use Tools / Configure Tools...
Give it the name Help Generator
- Configure HelpParse.ini
This is not required, but it is useful
In [input], set directory to the path
where your projects are located
In [Output], set directory to the
default output path (currently set to help)
- Copy (or move) the *.dot files to the MS Office template directory -
the default is
C:\Program Files\Microsoft Office\Templates
Common help files -
Several images
and
a file containing several common hierarchies
Microsoft Help Workshop (compiler) -
it is located at
C:\Program Files\BORLAND\Delphi5\Help\Tools\hcw.exe
-
Install
the compiler in the Delphi Tools menu
Use Tools / Configure Tools...
Give it the name Help Workshop (Compiler)
Generate
This procedure automatically generates help templates (as *.rtf files)
from existing *.pas files.
- In Windows Explorer, create a directory named Help
under your project directory
This is where the templates (*.rtf files) will be saved
- From the Delphi menu, select Tools / Help Generator
- From the Help Generator menu, select File / Open...
- Navigate to the appropriate directory and select an *.pas file
- From the Help Generator menu, select File / Save
This automatically saves the data in the Help directory created above
- Repeat the previous 3 steps for all the *.pas files in that directory
- Close the Help Generator
- In Windows Explorer, rename the *.rtf filenames to remove the _gen.
- At this point, we will NOT edit the *.rtf files
If your source code is named xyz.pas, then the ouput is named
xyz_gen.rtf. You should manually rename these as xyz.rtf.
This may seem like a hassel, but it is the only way I know to protect your
valuable work (other than backups).
In real life,
- I build the help file as I create a component.
This way, I can use (and test) the help from day one.
- I run the Help Generator whenever I add a new
method or property.
- Then I copy the new section from the new template and paste it
in the live *.rtf file - I would be REAL upset if I accidentally
over wrote the live file.
Writing a program to automatically update the live file is more work than I
want at this point.
Create the Help support files
You need to create several support files - place these
in the same directory as your *.rtf files
(normally in your project's Help directory)
-
A help project file (*.hpj)
- This tells the help compiler which files to include,
what colors the windows should be,
and related information.
- Modify TITLE as appropriate
- HLP is the name of the file the compiler generates
- BMROOT needs to point to the image files you downloaded above
- Modify the [FILES] section to point to your *.pas files - one line each
-
The *.cnt *.toc files
- You will need these before the help is installed in Delphi.
Creating them now makes testing the files a lot easier.
- Once it is created, the *.cnt will never change
- You can build the *.toc file a little at a time
- Both files must end with a blank line
Compile
- From the Delphi menu, select Tools / Help Workshop (Compiler)
- Open your *.hpj file
- From the menu, select File / Compile, check the
Automatically display Help file in WinHelp when done box,
and compile the help file
- For all subsequent compiles, simply press the Save and Compile button
Link
Use
OpenHelp
to link your new *.hlp file into the Delphi IDE.
- From the Delphi menu, select Help / Customize...
- Add your *.toc file to the Contents tab
- Add your *.hlp file to the Index and Link tabs
- From the menu, select File / Save Project
Test
It is assumed that your component is already installed.
Each time F1 is pressed, verify that the appropriate help
page is displayed.
- On the Component Palette, click on your component and press F1
- Place your component on a form
- While it is selected, press F1 and verify that the same page is displayed
- Open the Property Inspector
- On each property and event, click to select it and press F1
- If you have multiple components associated with the help file,
repeat the above procedure with each one.
The following steps also apply to classes that are not a part of a component.
- In a code window, enter all associated properties, methods, and events
- Click on each one, press F1, and verify that the correct help page is displayed
Add Content
At this point, the help file template should be fully functional.
Now it is time to use MS Word 97 (or another tool you trust) to add
real content.
During this process, I frequently recompile and view the help.
The general procedure is to
- Make a few edits in MS Word
- Save the changes with Alt F S (in sequence, not at the same time)
- Alt Tab (pressed together) to switch to the Workshop window (which I leave open)
- Click the Workshop's Save and Compile button
- View the changes in the Help window
- Make more changes in MS Word
Some changes you will need to make
- Configure MS Word
so that you get what you type
By default, MS Word will "fix" your "typing errors"
- Create a new hierarchy page
Each class has a link to a Hierarchy listing.
many of the common Delphi classes are already included in mcCommonHelp.rtf.
You can copy that file (or a page from it) and use it as a template to add more hierarchies
as appropriate - be sure to modify the
footnotes as appropriate.
I strongly suggest not editing the existing file.
Be sure to provide a link to your new file in your *.hpj file.
- Combine related overloaded functions onto a single page
This is pretty straight forward - cut and paste the related function prototypes
to a single page and delete the empty pages. The help compiler will generate
Topic ID "xyz" has already been defined warnings on any you miss.
- Add actual content to each page
This is fairly straight forward - you can even use bold and italic if you want.
Add links to other pages as appropriate.
Do not place a blank line between Description and the
text placed under it.
- Add your
examples
Don't skimp here.
By default, the examples are placed in the browse sequence
immediately following the associated property or method.
- Remove any unused example templates and links
- Modify or remove the See Also links
Place links to related items here. Use the A-foornote values.
- Add pages for any Records the developer needs to know about
- Actions - Remove any links and pages not used
- Be sure to document your Types
If they are used lots of places, they should have their own page.
Otherwise, I place them with the property or method that uses them.
- On pme pages, clean up the properties that start with **
These properties are defined in some base class and published in this class.
You need to move them to the appropriate heading and fix their links.
(pme pages - Properties, Methods, Events -
these are the yellow pages that list the items associated with a class.)
- Retest every link in the help file and verify that it works
Author: Robert Clemenzi -
clemenzi@cpcug.org