How it's done
Preliminaries
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:
- Copy the
.hlp file (and any .cnt or .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:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help
-
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
.cnt or .toc files 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\\"
Listing 1
where MyHelpFile.hlp is the name of the help file being registered and
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 .cnt etc. files as follows:
REGEDIT4
[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help]
"MyHelpFile.hlp"="C:\\Program Files\\MyCodeFolder\\"
"MyHelpFile.cnt"="C:\\Program Files\\MyCodeFolder\\"
Listing 2
To register these values simply double click the .reg file.
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.
| Compiler |
Master
Contents File |
Link File |
Index File |
| Delphi 3 |
Delphi3.cnt |
Delphi3.ohl |
Delphi3.ohi |
| Delphi 4 |
Delphi4.cnt |
Delphi4.ohl |
Delphi4.ohi |
| Delphi 5 |
Delphi5.cnt |
Delphi5.ohl |
Delphi5.ohi |
| Delphi 6 |
Delphi6.cnt |
Delphi6.ohl |
Delphi6.ohi |
| Delphi 7 |
d7.cnt |
d7.ohl |
d7.ohi |
Table 1
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>
Listing 3
where <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:
:Include d7.ohi
:Include d7.ohl
Listing 4
If the lines do not appear in the file, add them to it and save the file.
You can also reference any .cnt or .toc file that belongs to your help project by adding an :Include line for each file in the master contents file thus:
:Include MyHelpFile.cnt
Listing 5
If you do this remember that the .cnt or .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.
:Link MyHelpFile.hlp
Listing 6
Updating the index file
Add the following line to the end of the required index (.ohi) file.
:Index A Description=MyHelpFile.hlp
Listing 7
Here "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 Delphi .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.
Uninstalling
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.
:Include <ohi-file-name>
:Include <ohl-file-name>
Listing 9
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.