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 | Tags | Hyperlinks | Editing Tips | Toolbar
Window Styles | Images/Bitmaps | Common Pop-Up Pages | Hyperlink in rtf
Design Problems
References

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


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


Tags

Tags are added to the rtf file as footnotes. In normal documents, footnotes are numbered - 1 2 3 ... However, tags are marked using special symbols.

In order to add a footnote, from the Word menu, select

The tags (from the following list) are entered in the Custom mark field. (Tags are not case sensitive.) Notes

Notes on the Browse Sequence


Hyperlinks

Hyperlinks are those phrases that you click to see more information. Windows Help supports the following 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)


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.

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

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

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

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


Styles

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

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.

In order to remove a 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

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

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 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. (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 I have created the following 8x8 bitmaps for the property keys.


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

As far as I can tell, 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.

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.


Hyperlink in rtf

This is an rtf fragment 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 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


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