Delphi Components - Writing Help Files with MS Word

No component should be considered complete until it is documented. Using the provided tools, and MS Word, it is possible to generate help files which work with the Delphi IDE - you can click on either a component or a property, press F1, and get context sensitive help.

Unfortunately, Borland does not provide enough information for you to generate help files which look like the Delphi help system. These files help to fill in the gaps.

Overview

The Delphi 5 help provides 5 pages on how to produce help files. (But only 2 of them say very much.) To see the first one, on the help Contents tab, select

Creating Custom Components 
  Making components available at design time
    Providing help for your component

Use the Browse buttons to see the rest (the next 4 pages).

The instructions are pretty lame. That's why I wrote these pages. To start

You can use MS Word to produce an acceptable *.rtf file, but you can NOT use WordPad (under accessories)
The *.rtf files can be compiled using the Microsoft Help Workshop (Delphi5\Help\Tools\hcw.exe)
You can compile *.rtf files while they are still open in Word
You tag the help file by placing footnotes in the Word document (this is one reason why WordPad can not be used)
Hyperlinks (what you click on) are indicated by underlining the part you see and formatting the actual link as hidden
Each help page is a separate page in the Word document (Press Ctrl-Enter), or a separate rtf file
In the Help Workshop, be sure File / Help Author is checked. This allows you to right click any help page (not just yours) and get Topic Information.

Tag	Purpose	Description
#	Topic ID	Can jump to it, place at the top of each topic
$	Title	Displayed in find, bookmark, history
K	K-Link	Displayed in the index Separate multiple entries with a semicolon (;) Extra spaces around the semicolon are ignored Two-level keywords (indented) are entered like this macro, ; macro, library ; macro, automatic Notice the comma after the first "macro", don't forget it
A	A-Link	More keywords - not indexed, used in searches
+	Browse Sequence	Name:Number (both are optional) If "name" is present, then the colon (:) is required You must also enable the browse buttons for this to work
>	Window Type	Allows different types of windows to have different colors and/or buttons. Used when a page is selected via the index or contents. When you click a link or use the browse buttons, this value is ignored.

Hyperlinks

Hyperlinks are those phrases that you click to see more information. Windows Help supports the following

Link Type	Action	How to Specify
Dotted	Opens a pop-up window	Format as underlined
Solid	Displays a new page or executes a macro	Format as double underlined

In each case, follow the link text with the Topic ID (# footnote) of the selected page and format the Topic ID as hidden. You must not place a space between the link and the ID. (Of course, with the MS Word defaults, this means that once you have entered the ID, you won't be able to see or edit it. To display hidden text, see "Show codes" and "Tool options View" in the Toolbar section.)

When used as links, macros must start with ! OR : (no spaces)

Link Text!macro(parameters)

Specifying the Target Window

In the footnotes, you can specify the specific window you want to display a page in. Unfortunately, that specification only applies when you click a selection in the Index, the Contents, and related lists of topics.

Unless you specify a target window in a link, the page opens in the current window. The footnote value is ignored.

Link Code	Comments
TmyControl	This opens in the current window
TmyControl>window	This opens in the specified window
!alink(TmyControl, 1)	This opens in the pages default window
!alink(TmyControl, 1,,window)	This opens in the specified window

With dotted links (those used to pop-up a temporary window), you can not select the window type - it simply defaults to the current type and you can not override it.

Links to Other hlp Files

There are several ways to link to topics in other help files, such as the existing Delphi vcl help (in del5vcl.hlp).

Technique	Link Code	Comments
Explicit	TControl@del5vcl.hlp TControl>main@del5vcl.hlp	This link is not checked when you compile the help file. It works fine until you try to use your component with a different Delphi version. I suggest using an a-link instead.
Implicit	TControl	In most cases, this works once your file is integrated with the Delphi help. (I had a few problems.) Without a properly designed Table of Contents, the help compiler produces an "undefined Topic ID" warning for each link. The help compiler gives instructions on how to fix this ... but they don't work.
a-link macro	!alink(Tcontrol, 1)	This technique does not produce compile time warnings. With a properly designed Table of Contents, this technique works when testing your help file. The Delphi help uses this technique a lot.

Including a destination window does not work for pop-up windows.

When you right click a help page, check Ask on Hotspots to get a dialog box that tells you the link or macro associated with that hotspot (link). (Actually, most of the Delphi vcl links don't display anything. But, all the macros are displayed.)

It should be noted that the names of most components and properties can be used as link IDs. However, most variable types - such as string and integer - need to be linked using an a-link.

String!alink(String_Type,1)
Integer!alink(Integer_Type,1)

You must add "Links" to your Table of Contents (*.cnt file) to get the last 2 links to work with your files.

Many Delphi A-links use one of these

xxx!alink(xxx,1, tnf_qref)
xxx!alink('xxx; yyy',1, tnf_qref)

which produce a standard "topic not found" message. Without tnf_qref you get "No additional information is available".

The second example shows how to provide links to multiple pages (notice the semicolon and single quotes).

Editing Tips

If you use Word 97, creating help files is going to be pretty painful - these hints should help

To edit a footnote, double click its symbol in the main part of the document.
Under Tools / Options..., enable the display of Tabs, Paragraph marks, and Hidden text
To keep a header from scrolling, click anywhere in the text and apply
This will place a small black box in the left margin when Show Details is selected (Tools / Options... / View / All).
If more than 1 paragraph is needed, select parts of each. As long as the cursor is in any part of the paragraph, this option can be set.
Be sure to disable Tools / Auto Correct.... or you won't be able to type TComponent (the brain dead software will convert it to Tcomponent - note the lower case 'c').
Each help page starts with a "hard new-page" (Ctrl-Enter).
In order to look like the Delphi help, all text should be Arial 10. To change the default (Times New Roman on my system), select Format / Font..., set the options you want, and click the Default button.
If you set tab stops, they are recognized in the help compiler.
Be careful, hidden tabs and spaces won't display in the final help but look the same as normal tabs and spaces in MS Word when display Hidden text is enabled. This is another case where "reveal codes" would make a big difference.

Be sure to disable most of the autoformat stuff - Tools / Auto Correct...

Tab
AutoCorrect	Disable everything except Capitalize names of days
AutoFormat As You Type	Disable everything under Replace as you type (6 items)
AutoText	This is not a big problem
AutoFormat	Disable everything under Replace (6 items)

Styles

In order to make the file easier to edit, I suggest creating several styles via

Format / Style... / New...

Style	Format	Usage
Help1Link	Double underlined, green Character style	Links to a new page
Help2DottedLink	Underlined, blue Character style	Opens a pop-up window
Help3TopicID	Hidden, pink Character style	The ID of a new page or pop-up
Help5Title	Arial 12 Bold Paragraph style	The Title at the top of a page
Help6Heading	Arial 10 Bold Paragraph style	Each topic heading on the page
Help7NoScrollLinks	Arial 8 Paragraph style	Links right under the Title (in the "no scroll" region) are smaller Hierarchy Properties Methods Events See also

The colors for the first 3 styles are ignored by the Help Workshop. Coupled with Display Hidden Text (see above), these make it much easier to create help files.

The numbers in the style names are used in order to control their display order in the pick list. Paragraph styles apply to all the text in the paragraph. (Paragraphs are delimited with hard returns.) Character styles apply to selected letters or phrases.

To apply a character style, highlight the desired text and then apply the style.
To apply a paragraph style, click anywhere in the paragraph and then apply the style.

In order to remove a style

Apply Default Paragraph Font to remove a character style.
This also removes Bold, Underline, and similar codes.
In other word, the font options are changed to whatever is in the current paragraph style.
Apply Normal to remove a paragraph style

(It took me several days to figure out how to remove styles. As far as I can tell, it is not documented in the help file.)

DelphiHelp-Classes.dot and DelphiHelp-Properties.dot (both written by me) contain the suggested styles and a toolbar. In addition

DelphiHelp-Classes.dot	Contains template pages for the unit, 2 classes, and the Property, Method, and Event indices.
DelphiHelp-Properties.dot	Contains only the template page for a class Property, Method, or Event.

You should start with one of these. If you want to add one to an existing file, from the MS Word menu, select Tools / Templates and Add-Ins... and change the Document template. Be sure to check Automatically update document styles. Only the toolbar and styles will be added, not all the rest of the text. Both of these templates are included in Help Generator.zip. (If you place these templates in the Add-Ins section, then only the toolbar is added - it does not create the styles.)

Toolbar

Using the style pick list is both clumsy and slow. My solution was to create a DelphiHelp toolbar. The idea was to place common functions where they are easy to access them.

Button	Purpose
Footnote	To create a new footnote, you use Insert / Footnote..., press Alt-I-N, press Alt-Ctrl-F, or click this button. If you just click this, it inserts a numbered footnote (not what we need). This is fixed by placing the first footnote by hand and selecting Custom mark. After that, clicking this button will open the dialog box and allow you to specify the custom mark of your choice.
Show codes	This looks like a paragraph symbol. When depressed, Tabs, spaces, hard returns, and hidden text are displayed.
Tool options View	This opens the dialog box which allows you to select which formatting codes should always be displayed. I suggest that hard returns be always displayed.
Solid Link	This applies the Help1Link style.
Dotted Link	This applies the Help2DottedLink style.
ID	This applies the Help3TopicID style.
Remove Character Styles	When a character style (such as Help3TopicID) is applied, there are problems when you try to add a space or hard return immediately after the style. Basically, MS Word continues the style. Specifically, this tends to format the hard returns after a Topic ID as hidden and this produces a warning in the help compiler. This button implements the Default Paragraph Font style which effectively removes the current style.
Title	This applies the Help5Title style.
Heading	This applies the Help6Heading style.
Small Links	This applies the Help7NoScrollLinks style.
Remove Paragraph Style	This applies the Normal style.

One of the neat things about toolbars is that you can drag them close to where you are working. Then you don't need to move the mouse so far to access the functions.

I placed the toolbar in both template files.

Note: I modified the text that is displayed when you move the mouse over the 8 style buttons. As a result, the names of the underlying styles are no longer available.

Window Styles

You should create 3 window types, each with a different color combination.

Window	Purpose	Features
main	Components, Hierarchy, Properties, Methods, Events	white over white Enable the browse button
pme	A pop-up which lists Properties, Methods, Events, Units	gray over pale yellow No buttons enabled
example	Examples	yellow over pale yellow Enable Print button

To create/edit window definitions, first open the project window, then click the Windows... button. If this is the first time, a dialog box prompts you for the name of your first window. Important Tabs

General	Disable "Keep help on top"
Buttons	Browse - Enables the Previous/Next buttons
Color

The following is from the Windows Help Workshop Project Info report on del5vcl.hlp. You can just copy and paste this into your hpj file to get the same window definitions that Delphi uses.

[WINDOWS]
main="",(,,,),28676,,,f2
example="Example",(360,160,640,320),12292,(r14876671),(r8454143),f2
pme="",(40,320,280,640),4,(r14876671),(r12632256)
proc="",(425,100,578,300),12292,,,f2
gloss="",(425,100,578,300),12292,,(r12632256),f2
(w95sec)="",(425,100,578,300),12292,,(r12632256),f2

(Um, I don't know what the last 3 are for.)

When you right click a help page, select Topic Information to get the name of the window.

Images/Bitmaps

Using MS Word 97, there are several ways to place bitmaps in a document

Insert text similar to - {bmc Filename.bmp}
This is the preferred method for help files - it allows text to wrap around the image. However, it does not display the image in Word.
Select Insert / Picture from the menu
Paste an image from the clipboard

I have created the following 8x8 bitmaps for the property keys.

Bitmap	Description	Tag
Protected.bmp	A yellow square	{bmc Protected.bmp}
Published.bmp	A green square	{bmc Published.bmp}
Abstract.bmp	A red square	{bmc Abstract.bmp}
ReadOnly.bmp	A blue arrow	{bmc ReadOnly.bmp}

Don't think about trying to actually display these bitmaps in an MS Word 97 document - it is a complete pain ... Each time you place a bit map (using Insert / Picture / From File...), you MUST

Set the wrapping style to square
Set the vertical position to 0.05" from paragraph
Set the horizontal position to 0.05" from column

As far as I can tell,

There is no way to define these settings as the default for new images.
There is no way to type characters (like a space or tab) before the image.

How could any software be more user hostile than this?

Not that any of this matters - the help compiler always places the bitmaps on a separate line.

Common Pop-Up Pages

According to the "Delphi standard" (ie, my observation of the existing help files), the help for all components should provide their Hierarchy. In addition, the list of Properties should provide a Legend explaining color symbols (Protected, Published, and/or Read-only).

As far as I can tell, there is no way for component writers to access the relevant pop-up screens used by Delphi 5. Therefore, I wrote my own - this is the index of common pop-ups in mcCommonHelp.rtf.

mcCommonHelp Test Page

This page is used to test the pages contained in this file.

These are the Property Legends - I prefer using mcPropertyLegend_All6 
most of the time. Notice that Delphi 5 only shows the symbols actually used 
in the current property sheet, Delphi 6 always shows 3 symbols (in a different order).
Abstract.bmp is not used in any of the Delphi 5 or 6 help, but is provided in
mcPropertyLegend_All6 if you wish to use it (it is used in the TeeChart help).

mcPropertyLegend_All3
mcPropertyLegend_All5
mcPropertyLegend_All6 - Includes Abstract.bmp
mcPropertyLegend_Protected
mcPropertyLegend_Published
mcPropertyLegend_Abstract
mcPropertyLegend_ReadOnly
mcPropertyLegend_ProPub
mcPropertyLegend_Pro_RO
mcPropertyLegend_Pub_RO

These are some standard Hierarchy pages

mcHierarchy_TObject
mcHierarchy_TPersistent
mcHierarchy_TComponent
mcHierarchy_TControl
mcHierarchy_TWinControl
mcHierarchy_TCustomEdit
mcHierarchy_TCustomControl
mcHierarchy_TCustomComboBox
mcHierarchy_TCustomListBox

mcHierarchy_TGraphicControl

mcHierarchy_TBasicAction
mcHierarchy_TContainedAction
mcHierarchy_TCustomAction
mcHierarchy_TAction

Note: This is page 2 of mcCommonHelp.rtf. Since it does not have a k-footnote, it does not have an index entry.

Note: You should compile this file into your help file. This is worth mentioning because, once they are linked into Delphi, several *.hlp files may contain exactly the same data (especially, pages with the same ID's). At any rate, you can not use A-links to open pop-ups - they are automatically converted to regular links.

You can place mcCommonHelp.rtf and the 3 bitmap files in a single directory and link to it instead of copying them to the current directory.

Link the bitmap files by selecting Bitmaps / Add from the Help Workshop's project dialog box.

I had to write my own versions of these because I could not figure out how to access those provided in the Delphi 5 help. The following table shows some of what I discovered about the Delphi 5 help, but I was never able to have my pages access these.

ID	Page
3210	Protected, Published, Read-only
6839	Published, Read-only
2818	Published, Read-only

Hyperlink in rtf

This is an rtf fragment

{\cs16\uldb\cf11 mcINI_File}{\cs18\v\cf5 unit_mcINI_File>pme}

cf11 and cf 5 are colors
uldb  double underline
v     hidden
cs16  character style rlcHelp1Link
cs18  character style rlcHelp3TopicID

The cs numbers may change.

Design Problems

When the rtf file exceeds about 46kb, MS Word 97 suddenly increases its size to about 84K by adding every font known to your system. (My documents only use Arial.) Unfortunately, one of the fonts has more than 31 characters in its name and the help compiler gives a warning.

I opened a new 160 KB *.rtf file in MS Office XP (it was created using my rtf generator), added about 12 characters to it and resaved it ... 273 KB ... that's an increase of 113 KB. Totally unbelievable. Apparently, every rtf code now contains
\insrsid1321135
which is a Revision Save ID - uh, starting with Word 2002, Microsoft tracks all document changes using these. On the one hand, this is great - you can track who made what changes and when - on the other hand, this adds a lot of garbage to your files.
I took the same file and saved it from MS Word 97 - 151 KB and all the Revision Save ID junk was removed.

There is no way to see or edit the tags - such as font, bold, and color.

The rtf and doc files contain an unacceptable amount of private data that you have no control over. This includes directory path information and the name of the person that the operating system is registered to. (Can anyone say "spyware"?)

Warning: If you attempt to edit rtf files with notepad, be sure to turn off word wrap. If you don't, you get extra returns in the middle of words and MS Word won't be able to read the file. Particularly, in the header section, there are a few very long strings which do not contain any spaces. For instance, the color palette is several lines long. (My files had the wrong colors, were displayed at 10% of their size, and lost footnotes.) It appears that adding hard returns at delimiters (such as the semicolon - ; - and curly braces - { } ) does not cause any problems.

References

Component Building for the Professional - by Ray Konopka - is very good. There are numerous screen shots of MS Word demonstrating various concepts. This is the only source I've found which suggests what font sizes to use. This document also suggests using a single class Inspector link from the main page instead of separate Properties, Methods, and Events links.
Writing Help files for Delphi components provides actual samples.
A mirror is available at borland.com.
Serge Gusev provides Help Expert v 1.1 as shareware ($60).
(I have not used this, and I normally don't advertise non-free info ... but this looks interesting.)
www.helpmaster.info - Wow, this is quite a resource. I wish that I had found this before I started creating help files. There are numerous tutorials, explanations, and free software to help you create help files. Several are even able to parse Delphi units. (I have not tried these.)
- Help Compilers and a Decompiler
Microsoft RTF command guide documents most of the rtf commands not in the Help Compiler's help file. Hopefully, you will never need this, but I used it to track down an MS Word 97 design problem that I had to work around.

Author: Robert Clemenzi - clemenzi@cpcug.org