Delphi Components - Help File Table of Contents

Under Help Topics, there are 3 tabs - Contents, Index, and Find This page discusses the issues related to generating the Contents.

Overview | Contents Files | Preparing to Use OpenHelp | Using OpenHelp

Files Used for del5vcl.hlp | mcCommon.cnt and mcCommon.toc Files | Problems | Additional Notes | Trouble Shooting

Related pages
Writing Help Files | Style_Guide | Table of Contents | MS Help Workshop | Checklist | More Tips


Overview

Normally, when you double click on xyz.hlp, Windows first looks to see if there is a file named xyz.cnt. If found, Windows opens it, looks for a :Base filename command, and opens that as the actual help file. The base filename does not need an extension, but the Help Workshop will want one when you run Test / Contents File.... The format used by Delphi help is

According to the Help Workshop, the *.cnt file should contain the contents entries for your help file ... and if your help file is accessed from your application, that is true.

With components, things are a bit more complicated. In order to integrate your help into the existing Delphi help, Borland provides OpenHelp (from the menu, select Help / Customize...). This program produces 3 files which indicate how the help should be displayed. This architecture allows Delphi to display an integrated help package made up of many separate files, and it allows the user to double click an *.hlp file and get all the necessary links without building a monster index of everything in the full help system.


Contents Files

To test your help file, you could start with a simple *.cnt file. However, I suggest that you start with a *.cnt and *.toc combination because that is what you will need to distribute your components.

Both of these files are simple text documents. Neither of them is compiled by the Help Workshop - instead, they are read the first time you open the associated *.hlp file and the data is stored in an *.gid (compiled index) file.

Though the *.cnt file can be built in either notepad or the Help Workshop, I find the Workshop a little cumbersome to use (and extremely involved to explain).

You can not edit *.toc files using the Help Workshop, use notepad instead.

In both files, comments start with semicolons and blank lines are ignored.

Be REAL sure that the :Base directives in both files match the *.hlp file you're testing.


The *.cnt File

Create a new *.cnt file using del5vcl.cnt (or mcCommon.cnt) as an example. In 3 places, replace "DEL5VCL" with the name of your help file. Modify the Title and Index identifier as appropriate.

Title is what is displayed in the title bar of the Help Topics dialog box. It is also used by OpenHelp and is sometimes displayed when viewing the help.

Careful: Be very sure that you place a blank line at the end of the file. If you don't, then the last directive won't be recognized, your *.toc file won't be read, and your file will not have a Contents tab.


The *.toc File

Create a new *.toc file using del5vcl.toc (or mcCommon.toc) as an example.

The *.toc file should not include any directives except :Base. Modify this directive to reference your *.hlp file and be sure that it specifies main as the default window.

As you can see from the examples, the contents entries start with numbers. Increasing the number increases the level of indent. For basic testing, I suggest starting from level-1 (as shown). When you create a final *.toc file, these should be renumbered so that level-1 indicates your company (or yourself) so that you don't clutter up the main Contents display. (Remember, your data will be added to what Delphi is already showing.)

Another approach is to make Add-in Components level-1, your company level-2, and place the additional information below that.

Be sure that none of the entries specifies a destination page, if it does, it won't work.

Delphi provides several lists of its classes - see Delphi5\Help\del5vcl.toc to see how the vcl classes and units are structured and added to the overall help system.

Careful: Be very sure that you place a blank line at the end of the file. If you don't, then the last directive won't be recognized, your *.toc file won't be read, and your file will not have a Contents tab.


Specifying which window to display the page in

The first line of either an *.cnt or *.toc file should be

When individual contents entries do not specify a window type, the one specified in the :Base directive is used.

If you plan to build an *.cnt file in the Help Workshop and then rename it to *.toc - be careful. Be sure to leave the Window type empty. If you set a value, it is included in the file as

(where main is the name of a window). This syntax works as expected in *.cnt files, but causes a failure in *.toc files.


Test It

At this point, double click your *.hlp file and make sure that it works. It should have a Contents tab, and all of the links should work. The Index should also work and should contain only your entries. Once you have displayed the help, additional changes to the *.cnt and *.toc files will not take effect until you delete the *.gid file. (OpenHelp and the Help Workshop will rebuild the *.gid file for you.)

The concept is this


Supporting Different Delphi Versions

When you look at the examples, notice that the Delphi version is always specified in the *.cnt file. As a result, you will either have to supply different versions of these files, or you will have to explain how the users should modify them. (An automated installer could also be used, but that is out of scope.)

My installation packages contain this directory structure

I simply place version specific *.cnt files is the D5, D6, & D7 directories under Help and instruct the users to copy the appropriate files into the Help directory.

Adding links to multiple Delphi versions in a single *.cnt file will work in some cases, but will cause problems on machines containing more than one delphi version. (All the versions would be linked together and cause a general mess.)


Preparing to Use OpenHelp

Before you use OpenHelp, Delphi suggests that you copy your *.hlp and *.cnt files to Delphi5\Help, but I prefer to keep my files separate from the Delphi files. Therefore, I leave them in the Help directory associated with the unit. (The MS Help Workshop allows you to configure an output directory, but since I'm using the same directory as the *.rtf file, I don't use that feature.)


Using OpenHelp

To run OpenHelp from the Delphi 5 menu, select Help / Customize...

OpenHelp provides several tabs - Contents, Index, Link, Project - (we won't use the Project tab). On one of the tabs, expand the Path column so that everything can be read. (You can double click on the vertical bar separating the columns to automatically re-size them.) Notice that Contents entries refer to *.toc files and that Index and Link use *.hlp files.

On each of the 3 tabs - Contents, Index, Link - use Edit / Add files... (or the equivalent toolbar button) to add your *.toc or *.hlp files, as appropriate. (You will be prompted for the correct file in the Add File dialog box.) OpenHelp adds your selection to 3 files, one file per tab. See the next section for examples of each. It also creates 2 registry entries under

one for each file.

After the entries are made, select File / Save Project (or press the Save Project toolbar button). This saves 4 OpenHelp files and updates the help index (delphi5.GID).

And that's all there is to it, your help file should be fully integrated into Delphi.


Files Used for del5vcl.hlp

These files should be located on your system under Delphi5\Help - you can open them in notepad to see the full contents.

del5vcl.cnt

del5vcl.toc delphi5.ohl (OpenHelp Links) delphi5.ohc (OpenHelp Contents) delphi5.ohi (OpenHelp Index) You may have noticed that none of the *.hlp files have a fully qualified path. That is because OpenHelp makes registry entries under Thus, you should not edit the OpenHelp files by hand - without the registry entries, Windows is not able to find the files.


mcCommon.cnt and mcCommon.toc Files

This is the cnt/toc pair used with mcCommon.hlp

mcCommon.cnt

mcCommon.toc - Used for test (less clicking) mcCommon.toc - Shipped with components I suggest the following hierarchy Placing the level 1 and 2 entries after the 3's and 4's makes testing easier (fewer mouse clicks) - you can move them to their correct positions when test is complete. Another approach is to leave them in the correct order and just comment them out (with semicolons) for testing.

When several different help files want to use the same contents tree, only the "first" *.toc file should have levels one and two. "First" is defined by the order that the *.toc files are registered in OpenHelp.

The reference after the equals sign is a Topic ID - not an A-Link or a K-Link.


Problems

When working with the Help Workshop, you might want an *.toc file that is different from the one you distribute with a component. After a while, I got tired of clicking down several layers of contents just to test the help.

Add an extra blank line to the end of your *.cnt and *.toc files. Without it, the last data line may not be processed.


Delphi 6

Believe it or not, a help file that works perfectly with Delphi 5 won't work with Delphi 6 - for that matter, Delphi 6 help does not work correctly with Delphi 6. For example This behavior is pure crap.

To make matters worse (yes it is possible), when I added my component and related help to Delphi 6, F1 did not work on all the properties. It worked perfectly with Delphi 5. (Yes, I re-compiled the source so it would work with Delphi 6.) There were also problems with the Help's Context and Index tabs not showing all the data.

Workaround: The basic problem (there are others) is that sometimes delphi6.hlp is called and othertimes del6vcl.hlp is called. Delphi 5 always calls delphi5.hlp. (This was verified by using RegMon and by deleting *.gid files and seeing which one was re-created.) This is what causes the Index and Contents to have problems.

One "fix" is to modify del6vcl.cnt to include delphi6.ohc (Contents) and delphi6.ohi (Index). (See delphi6.cnt to see how.) With this done, the Contents and Index are now mostly correct (though sometimes still missing) but sometimes F1 still does nothing in the Object Inspector and the Tool Palette. When F1 does nothing, close the current Help window and try again - this appears to work every time.

Delphi 6 and 7 require an *.als file (not used in Delphi 5). One source indicates that several *.als files can be used, another indicates that they should be merged. It would be useful if Borland would comment on this.


Additional Notes

Developing this information took a long time. Along the way, I went down many dead ends. This is just some additional information - it is not needed, but you may find it useful.


Alternate *.cnt Format

This is an alternate header for an *.cnt file which does not have an associated *.toc file. It allows your hyperlinks - similar to !alink(Tcontrol,1) - to display the appropriate Delphi pages. However, it also includes the Delphi vcl index information with your index data and this makes it harder to test your page (just because there was too much data). To remove the extra indices, just comment them out with semicolons
    ;:Index Delphi vcl=del5vcl.hlp
or you can change them to :Link's
    :Link del5vcl.hlp
Either way makes it much easier to see all your indices at one time.

(The toc/cnt pair described above already uses :Link's to avoid this problem.)


Editing *.cnt File with the Help Workshop

Tips for editing the contents file (*.cnt) using the Help Workshop. You can not edit *.toc files using the Help Workshop, use notepad instead.


Linking to the Existing Delphi Help

In the *.cnt file,
    :INCLUDE DELPHI5.OHL
includes all the links available to the Delphi help. Of all the files included, only 2 are really important to component builders.


Do not place :Link's in the *.toc file

Warning:


Help File Limitations

This data is from the Delphi 6 readme.txt file.
Windows Help index limitation on Windows 98/ME

The Windows Help engine on Windows 95, 98, and Millennium uses a 16-bit list box in the Help Topics dialog's Index tab, and can display no more than 32,767 keywords. If this limitation is exceeded, the Index is blank. If you are using one of these operating systems, you may note that the Help Index control file (Delphi6.ohi) has been modified to exclude a number of Help files from the Index. This modification does not affect other Help system functionality- -such as crossfile linking or F1 accessibility--and you can expand the index or modify it further to include or exclude any Help file reference by adding or removing semi-colon comment marks before ":Index" entries. When modifying the .OHI file, however, you must keep the WinHelp viewer limitation in mind to avoid the "blank index" problem.


Trouble Shooting


Author: Robert Clemenzi - clemenzi@cpcug.org
URL: http:// cpcug.org / user / clemenzi / technical / Languages / Delphi / ComponentHelp_toc.html