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.
Related pages
Writing Help Files
| Style_Guide
| Table of Contents
| MS Help Workshop
| Checklist
| More Tips
Overview
Creating Custom Components Making components available at design time Providing help for your componentUse 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
In order to add a footnote, from the Word menu, select
Insert / Footnote... (From the keyboard, use Alt-I-N)The tags (from the following list) are entered in the Custom mark field. (Tags are not case sensitive.)
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. |
Notes on the Browse Sequence
Hyperlinks
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 |
When used as links, macros must start with ! OR : (no spaces)
Link Text!macro(parameters)
Specifying the Target Window
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
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. |
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
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) |
In order to make the file easier to edit, I suggest creating several styles via
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 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
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
Toolbar
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. |
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.
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 |
General | Disable "Keep help on top" |
Buttons | Browse - Enables the Previous/Next buttons |
Color |
[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
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
Not that any of this matters - the help compiler always places the bitmaps
on a separate line.
As far as I can tell, there is no way for component writers to access the relevant
pop-up screens used by
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
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
As far as I can tell,
How could any software be more user hostile than this?
Common Pop-Up Pages
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
ID
Page
3210
Protected, Published, Read-only
6839
Published, Read-only
2818
Published, Read-only
Hyperlink in rtf
{\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
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.
Author: Robert Clemenzi -
clemenzi@cpcug.org
A mirror is available at borland.com.
(I have not used this, and I normally don't advertise non-free info ...
but this looks interesting.)
URL: http:// cpcug.org /
user /
clemenzi /
technical /
Languages /
Delphi /
ComponentHelp.html