Contents		A list of topics, from a text file
Index		An alphabetical list of k-footnote entries
Find		An alphabetical list of all the words in the help file

:Base filename.hlp>main

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.

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.

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

:Base Filename.hlp>main

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.

2 TClassName=TClassName        // Good
2 TClassName=TClassName>main   // Won't work in *.toc, ok in *.cnt

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.

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

:Base Filename.hlp>main

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

2 TClassName=TClassName>main   

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

• The *.cnt file is automatically called when you double click the associated *.hlp file. In that case, you want to link in the Delphi help but show only your Contents and your Index.
• However, when the help file is opened via Delphi, you must not link in the other Delphi files. Therefore, you provide an *.toc file without any links.

:INCLUDE DELPHI5.OHL

My installation packages contain this directory structure

dcl_xxx \ Help    \ D5
                    D6
                    D7
        \ Source
        \ lib_50
        \ lib_60
        \ lib_70

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

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

HKLM\SOFTWARE\Microsoft\Windows\Help

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.

del5vcl.cnt

:Base del5vcl.hlp>main
:Title Visual Component Library Reference Help
:Index Visual Component Library Reference Help=DEL5VCL.HLP
:INCLUDE DELPHI5.OHL
:INCLUDE DEL5VCL.TOC

:Base del5vcl.hlp>main
;
1 Visual Component Library Reference
;
  // The actual contents continues from here

:LINK del5new.hlp
:LINK delphi5.hlp
:LINK del5prog.hlp
:LINK del5dbd.hlp
  // Followed by many more similar links

:INCLUDE del5new.toc
:INCLUDE delphi5.toc
:INCLUDE del5prog.toc
:INCLUDE del5dbd.toc
  // Followed by many more similar links

:INDEX What's New in Delphi=del5new.hlp
:INDEX Delphi Help=delphi5.hlp
:INDEX Programming with Delphi=del5prog.hlp
:INDEX Developing Database Applications=del5dbd.hlp
  // Followed by many more similar links

HKLM\SOFTWARE\Microsoft\Windows\Help

mcCommon.cnt

:Base mcCommon.hlp>main
:Title mcCommon routines
:Index mcCommon routines=mcCommon.hlp
:INCLUDE DELPHI5.OHL
:INCLUDE mcCommon.TOC

:Base mcCommon.hlp>main

3 String Functions
4 Left_mc=Left_mc 
4 Right_mc=Right_mc
4 Mid_mc=Mid_mc 
4 ExtractSubstring_mc=Mid_mc 
4 InStr_mc=InStr_mc 
4 ParseString_mc=ParseString_mc 

4 AddDoubleQuotes_mc=AddDoubleQuotes_mc 
4 RemoveDoubleQuotes_mc=RemoveDoubleQuotes_mc 

3 Other
4 LoadCursor_mc=LoadCursor_mc 

4 TAction_mcFileExit=TAction_mcFileExit

1 Add-in Components 
2 mc Controls

:Base mcCommon.hlp>main

1 Add-in Components 
2 mc Controls
3 String Functions
4 Left_mc=Left_mc 
4 Right_mc=Right_mc
4 Mid_mc=Mid_mc 
4 ExtractSubstring_mc=Mid_mc 
4 InStr_mc=InStr_mc 
4 ParseString_mc=ParseString_mc 

4 AddDoubleQuotes_mc=AddDoubleQuotes_mc 
4 RemoveDoubleQuotes_mc=RemoveDoubleQuotes_mc 

3 Other
4 LoadCursor_mc=LoadCursor_mc 

4 TAction_mcFileExit=TAction_mcFileExit

Add-in Components / Company ID / Types of Controls / Actual controls

1 Add-in Components 
;2 mc Controls
;3 String Functions
4 Left_mc=Left_mc 

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.

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

• Place a button on a form
• Click on the button and press F1
• In the dialog box, select either of the provided help options (if offered)
• The first error is that sometimes options are offered and other times they are not
• On the Help toolbar, click Help Topics
• Sometimes a Contents tab is available and other times it is not
• When the Contents tab is present, click it - Only help on VCL components will be available
• In the Index tab, notice that the first line is Release

• In the Delphi object inspector, click on one of the button's properties and press F1
• In the dialog box, select one of the provided options (select the one associated with TControl if available)
• On the Help toolbar, click Help Topics
• In the Contents tab, notice that many more options are available (my system has 11 top level options, the VCL component help was option 8)
• In the Index tab, notice that the first line is '(apostrophe)

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.

delphi6.hlp	From the menu F1 on TButton.Cursor in the Object Inspector
del6vcl.hlp	F1 on a form F1 on a TButton F1 in the Object Inspector on a component I created

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.

:Base mcCommon.hlp>main
:Title mcCommon routines
:Index Delphi vcl=del5vcl.hlp
:Index xx=del5op.hlp
:Index xx=E:\DelphiProjects\CommonHelpFiles\mcCommonHelp.hlp

1 The actual contents continue here

    ;:Index Delphi vcl=del5vcl.hlp

    :Link del5vcl.hlp

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

• These files are not compiled, just save them after you edit them
• Title is what is displayed in the title bar of the Help Topics dialog box
• Help file refers to the name of the associated hlp file not the rtf file that the topic is defined in. Leave this blank if it is the same as the help file (different extension, of course)
• For each contents entry, there is a field to enter a window name (type). Do not set this. It works ok in an *.cnt file, but fails in an *.toc file (ie, when used inside Delphi).

    :INCLUDE DELPHI5.OHL

• del5vcl.hlp contains the help pages for the Delphi 5 vcl, needed to test commands like

  !alink(Tcontrol,1)
  

• del5op.hlp contains the help pages for String, Integer, and the like. As in

  function ReadInteger(Section, Name: string): Integer;
  

If you add

:Link del5vcl.hlp

to your *.toc file, then del5vcl.hlp will not be included in the resulting Index. Specifically, when help is opened from inside Delphi, none of the vcl components will be available via the Index - for example, TButton will not be in the Index, but if you highlight a button on the form and pressed F1, the correct help page is displayed. delphi5.GID (the compiled help index) is 600k smaller when the link was included.
• 1,020 Kb with the link
• 1,649 Kb without the link
(You need to delete the current *.gid file for the *.toc changes to take effect. When you do this, the help viewer will automatically create a new one. In fact, that is how you trouble shoot this type of problem. Be sure to make some small change to a contents entry so that you can be sure that the modified *.toc file is actually read.)

The Help Workshop suggests using :Links in the *.cnt files to include other help files. Before I learned to use toc files, I had an *.cnt file with

:Link del5vcl.hlp

Not knowing any better (because there is absolutely no documentation), I added the *.cnt file to the OpenHelp Contents tab. That's how I discovered the problem, and how I learned about *.toc files.

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.

• Every time you modify one of the help files - *.hlp, *.cnt, *.toc - you must delete the associated *.gid file (compiled index) before all the changes take effect. Most of the time, this happens automatically.

• Once the help file pointers are placed in the registry (ie, once you've run OpenHelp), you can not view another *.hlp file with the same name. If you edit and try to display a help file with the same name, but in a different directory, you will never see the changes - only the files pointed to by the registry are read. That is the main reason that I left the help files in the Help directory associated with the unit.

• In the Contents files (*.cnt and *.toc), be sure that the base file is the same as the Help file (*.hlp). I made the mistake of renaming some *.hlp and *.cnt files without changing

  :Base filename

  It took several hours to find the problem.

URL: http:// cpcug.org / user / clemenzi / technical / Languages / Delphi / ComponentHelp_toc.html