How to integrate help files into the Delphi 3-7 IDE
This article shows how to manually update Delphi's help system files in order to integrate your component etc. help files with the Delphi 3 to 7 IDEs. What the article is not about is how to write those help files in the first place – there is plenty of information about that in the Delphi help.
The Delphi 3 to 7 help system uses the legacy WinHelp help system. WinHelp is an optional download for Windows Vista through to Windows 8.1 and can't be installed at all on Windows 10.
How it's done
In order for a help file to be able to be integrated into the Delphi IDE the help file must conform to the OpenHelp standard. Please see the Delphi help file on component writing for details on how to create a help file that meets this standard.
Registering the help file with Windows
The first thing we need to do is register the help file and any contents files with Windows. To do this:
.hlp file (and any
.toc files) to a suitable folder on your computer and note the folder's path.
Now open the Windows RegEdit utility and navigate to the key:
Create a new string (REG_SZ) value and give the value the same name as your help file (just the file name without the path). Set the value to the path to your help file. Figure 1 below provides an example.
Repeat the process for any
.toc files in your help project.
Alternatively, create a text file with a
.reg extension and enter the following into the file:
MyHelpFile.hlp is the name of the help file being registered and
is the path to the help file. Notice how we've escaped each backslash in the path by preceeding it with another backslash – this is required in
.reg files since the "\" character has special meaning. Note that additional lines can be added for any
.cnt etc. files as follows:
To register these values simply double click the
Registering the help file with Delphi
Now that Windows knows all about the help file, we need to register it with Delphi.
To do this we must modify three of Delphi's master help files: the Link, Index and Contents files. The files are found in the
Help subfolder of a Delphi installation. The file name depends of the version of Delphi being used. Table 1 lists the file names for Delphi 3 to 7.
Updating the contents file
Open the required Delphi contents (
.cnt) file in a text editor and check if the following lines appear somewhere in the file:
<ohi-file-name> is the name of the
.ohi file and
<ohl-file-name> the name of the
.ohl file for the version of Delphi in question. E.g. for Delphi 7 the required lines will be:
If the lines do not appear in the file, add them to it and save the file.
You can also reference any
.toc file that belongs to your help project by adding an
:Include line for each file in the master contents file thus:
If you do this remember that the
.toc file must be registered with Windows.
Updating the link file
Open the required link (
.ohl) file in a text editor. Add the following line to the end of the file and save it.
Updating the index file
Add the following line to the end of the required index (
:Index A Description=MyHelpFile.hlp
A Description" is a brief description of the help file. This description will appear in some help system dialogs when searching for entries, so keep the description brief.
Using A-link keyword files
When using Delphi 6 and 7 there is still one more step to take to fully integrate our help file with the Delphi IDE. We must provide a list of all the A-link keywords used in the help file.
To begin with you need to create a text file containing a list of all the A-link keywords. This file must contain one keyword per line in lower case. The keywords must be sorted. Some help authoring tools should be able to assist with the creation of this list.
Next we must make the list known to Delphi. Some documentation states that the keyword file, with extension
.als, should be placed in the Delphi help directory. I have found this approach to be unreliable. The best way to proceed is to merge the keywords from your file into the master
.als file, preserving the sort order. In Delphi 6 the master file is named
Delphi6.als and in Delphi 7 it is named
d7.als. In both cases the file is located in the Delphi help directory.
This completes the discussion of how to install help files into the Delphi IDE.
Uninstallation is almost a reversal of the installation process discussed above. I.e.:
However, do not delete the following lines from the master contents file, since other help files may depend on the presence of these lines.
When working with Delphi 6 and 7 it is probably best not to delete any a-keywords from the master
.als file since the keywords may also be used by other help files.
In this article we have looked at how to manually register third-party help files with Delphi so that the help files are integrated with the Delphi IDE's help system. We also covered how to register help files with Windows.
What, no demo code?
No demonstration code accompanies this article, but if you want to know how to automate the techniques we use here, please see the Component Help Installer source code.
I hope you found this article useful. If you have any comments or queries, or if you wish to report any errors, please create an issue on GitHub (GitHub account required).