How to integrate help files into the Delphi 3-7 IDE

   

Introduction

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

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:

  1. Copy the .hlp file (and any .cnt or .toc files) to a suitable folder on your computer and note the folder's path.
  2. Now open the Windows RegEdit utility and navigate to the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help key.
  3. 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.
    Picture of Edit String dialog in RegEdit
  4. 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\\"

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\\"

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

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>

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

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

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

Updating the index file

Add the following line to the end of the required index (.ohi) file.

:Index A Description=MyHelpFile.hlp

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.

Note that, from release 2.2, the Component Help Installer can automatically merge .als files when installing help files.

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.:

  • Delete the :Index statement you added to Delphi's Index file.
  • Delete the :Link statement from the Link file.
  • Delete any :Include statement(s) referring to your help project's .cnt and .toc files 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 .reg file 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.

Conclusion

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.

Feedback

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.