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 IDE. 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.
We take a slightly different approach in this article to that taken in the others published here. This article is not explicitly about Delphi programming but about using the Delphi system.
My Component Help Installer tool uses the techniques presented here when installing help files into the IDE.
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:
.hlpfile (and any
.tocfiles) to a suitable folder on your computer and note the folder's path.
Now open the Windows RegEdit utility and navigate to the
Create a new string (REG_SZ) value at 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. The following figure provides an example.
Repeat the process for any
.tocfiles in your help project.
Alternatively, create a text file with a
.reg extension and
enter the following into the file:
REGEDIT 4 [HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help] "MyHelpFile.hlp"="C:\\Program Files\\MyCodeFolder\\"
MyHelpFile.hlp is the name of the help file being
C:\\Program Files\\MyCodeFolder\\ 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
etc. files as follows:
REGEDIT4 [HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help] "MyHelpFile.hlp"="C:\\Program Files\\MyCodeFolder\\" "MyHelpFile.cnt"="C:\\Program Files\\MyCodeFolder\\"
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
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.
|Link File||Index File|
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:
:Include <ohi-file-name> :Include <ohl-file-name>
<ohi-file-name> is the name of the
.ohi file and
<ohl-file-name> the name of
.ohl file for the version of Delphi in question. E.g. for
Delphi 7 the required lines will be:
:Include d7.ohi :Include d7.ohl
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
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
Note that, from release 2.2, the Component Help Installer can automatically merge
.als files when installing help
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.:
:Indexstatement you added to Delphi's Index file.
:Linkstatement from the Link file.
:Includestatement(s) referring to your help project's
.tocfiles from the master contents file.
Delete the entries you made in the registry (unless the help files are being used by other programs). You can either use RegEdit to delete the entries or use a
.regfile that does this automatically when run, e.g.:
REGEDIT4 [HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help] "MyHelpFile.hlp"=- "MyHelpFile.cnt"=-
However, do not delete the following lines from the master contents file, since other help files may depend on the presence of these lines.
:Include <ohi-file-name> :Include <ohl-file-name>
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 get in touch.
This article is copyright © Peter Johnson 2004-2005
Licensed under a Creative Commons License.