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 |
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
: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.
Contents Files
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
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.
Specifying which window to display the page in
The first line of either an *.cnt or *.toc file should be
:Base Filename.hlp>mainWhen 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
2 TClassName=TClassName>main(where main is the name of a window). This syntax works as expected in *.cnt files, but causes a failure in *.toc files.
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
:INCLUDE DELPHI5.OHLAs 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
dcl_xxx \ Help \ D5 D6 D7 \ Source \ lib_50 \ lib_60 \ lib_70I 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
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\Helpone 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
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.TOCdel5vcl.toc
:Base del5vcl.hlp>main ; 1 Visual Component Library Reference ; // The actual contents continues from heredelphi5.ohl (OpenHelp Links)
:LINK del5new.hlp :LINK delphi5.hlp :LINK del5prog.hlp :LINK del5dbd.hlp // Followed by many more similar linksdelphi5.ohc (OpenHelp Contents)
:INCLUDE del5new.toc :INCLUDE delphi5.toc :INCLUDE del5prog.toc :INCLUDE del5dbd.toc // Followed by many more similar linksdelphi5.ohi (OpenHelp Index)
: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 linksYou may have noticed that none of the *.hlp files have a fully qualified path. That is because OpenHelp makes registry entries under
HKLM\SOFTWARE\Microsoft\Windows\HelpThus, 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
mcCommon.cnt
:Base mcCommon.hlp>main :Title mcCommon routines :Index mcCommon routines=mcCommon.hlp :INCLUDE DELPHI5.OHL :INCLUDE mcCommon.TOCmcCommon.toc - Used for test (less clicking)
: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 ControlsmcCommon.toc - Shipped with components
: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_mcFileExitI suggest the following hierarchy
Add-in Components / Company ID / Types of Controls / Actual controlsPlacing 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.
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.
Problems
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
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.
Additional Notes
Alternate *.cnt Format
: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 hereIt 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.hlpor you can change them to :Link's
:Link del5vcl.hlpEither 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
Linking to the Existing Delphi Help
:INCLUDE DELPHI5.OHLincludes all the links available to the Delphi help. Of all the files included, only 2 are really important to component builders.
!alink(Tcontrol,1)
function ReadInteger(Section, Name: string): Integer;
Do not place :Link's in the *.toc file
:Link del5vcl.hlpto 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.
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.hlpNot 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.
Help File Limitations
Windows Help index limitation on Windows 98/METhe 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.
:Base filename