Delphi Components - A Help File Style Guide

Well, I have not been able to figure out how to make help files which look exactly like Delphi's, but I think that this is close enough.

Style Guide | More on Footnotes - k a + | Example Pages | Class Example | Units
Help Template Generator

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

Style Guide

These are the formatting details that seem to make help files that are fairly consistent with the Delphi help.

The font sizes are the actual number of pixels for a capital 'T' - Arial 10 is actually 10 pixels high.

Use only Arial - except as noted below, all text is Arial 10
Every page gets a Topic ID footnote (#)

Component descriptions
  The no-scroll section consists of 2 lines - Title and Links
    Title - Arial 12 bold
    Links - Arial  8 separated by 1" tabs
            Between the words "Hierarchy" and "Properties" place 2 1/2" tabs
            Between those tabs, place a 'space' formatted as Arial 12
            If the space is placed at the end of the line, then the spacing
            between the Title and the Links changes when the width of the help window
            changes. Be SURE that the space and tabs are not hidden.
    Mark both lines as "Keep with next" (this defines the no-scroll area)
    # (topic id)         TComponentName
    $ (title)            TComponentName
    k (index)            TComponentName
    a (search)           TComponentName_object; TComponentName (both are required)
    + (browse sequence)  UnitName:TComponentName               (the colon is required)
    > (window name)      main

Hierarchy pop-ups

  All text is Arial 10
  The lines with the vertical bars are a problem
    They should be 8 pixels high
    A vertical bar '|' in Arial 10 is 12 pixels high
      But a vertical bar in Arial 6, though 8 pixels high, is 3 pixels too low
    Because Arial is used, a capital 'i' is just a vertical line
      However, Arial 8 is one pixel lower than what Delphi uses
    Arial 10 is a good compromise because, though it is 9 pixels high, it is correctly centered
    Another solution would be to use an image, I prefer text
    Use only # and > footnotes
    # (topic id)         Hierarchy_TComponentName
    > (window name)      main

Lists of Properties, Methods, Events
  All text is Arial 10
  Title - Name of the component followed by - properties, or methods, or events
      notice lower case letters
      I've added actions to this list - they make components easier to select from menus
  Second line - link to the control, Perhaps a link to an alphabetical listing,
      a link to the appropriate legend
  The headings are "In component" and "Derived from component" (in bold, style Help6Heading)
  Use the 3 icons (bitmaps) in accord to the Delphi standard
  Use 2 spaces for missing icons
  Personally, I don't list all the items for the "Derived from" components - too much work
    # (topic id)         TComponentName_Properties (Txyz_Properties)
    > (window name)      pme

Properties, Methods, Events associated with a Component (class)
  The no-scroll section consists of 2 lines - Title and Links
     see Component section for details
  Title - TComponent.PropertyName
    # (topic id)         TComponentName_PropertyName  (Txyz_Text)
    $ (title)            TComponentName.PropertyName  (Txyz.Text)
    k (index)                Text, Txyz; Txyz, Text;Text     (requires all 3)
    a (search)               Txyz_Text; Text_Property; Text  (requires all 3)
    + (browse sequence)  TComponentName_Properties:PropertyName  (Txyz_Properties:Text)
    > (window name)      main

    Each of these is a different browse sequence (+ footnote) - 
      TComponentName_Properties, TcomponentName_Mehtods, TcomponentName_Events
   In the a-footnote, "Property" should be either Property, Method, or Event

Methods not associated with a class
  The no-scroll section consists of 2 lines - Title and Links
     see Component section for details
  The links line only has See also and Example
  Title - MethodName 
    # (topic id)         MethodName
    $ (title)            MethodName function
    k (index)            MethodName
    a (search)           MethodName; MethodName_function
    + (browse sequence)  UnitName:MethodName 
    > (window name)      main

    This is the same browse sequence as the components
  Do not include the Register method - most units have one

  The no-scroll section consists of only 1 line - the Title
  Title - MethodName example
  For examples associated with classes, 
    * Be sure to include the ClassName in the footnote entries
    * The UnitName should not be included
  Key words in code are bold - procedure, var, begin, end,, if..then..else
  Delphi examples never link to anything, Some of mine do
    # (topic id)         MethodName_example  (Txyz_Text_Example, StringFunctions_example)
    > (window name)      example

  I've chosen to include $, k, a, and + footnotes for my examples
  so that they will be listed in the index. Most Delphi examples are
  not listed in the index, but some are. 
  Unit level
    $ (title)            MethodName example
    k (index)            MethodName, Example; UnitName, MethodName example
    a (search)           MethodName_example
    + (browse sequence)  UnitName:MethodName@_example

  Class level
    # (topic id)         TComponentName_PropertyName_example  (Txyz_Text_example)
    $ (title)            TComponentName.PropertyName example  (Txyz.Text example)
    k (index)                Text, Example; Txyz, Text example
    a (search)               Txyz_Text_example
    + (browse sequence)  TComponentName_Properties:PropertyName@_example (Txyz_Properties:)

More on k-Footnotes

Indexes are built off the k-footnote.

The rules for adding a method or property associated with a class are pretty specific. You need 3 entries (their order does not matter)

    k (index)            ParamName, Txyz; Txyz, ParamName; ParamName
These produce 2 entries is the index - one under the parameter (or method) name and the other under the class name. The commas cause the creation of an indented list. If the last "ParamName" (without the comma) is missing, then the entry will be
instead of

Note: The Delphi help specifically says that an extra comma should be used, the Help Workshop help says that it should NOT be used. If it is present, then ONE of your index entries (the first one alphabetically) will be displayed with an extra comma.

    k (index)            ParamName, Txyz; Txyz, ParamName; ParamName  // Good
    k (index)            ParamName, Txyz; Txyz, ParamName; ParamName, // Bad, but in Delphi help

Spaces around the semicolons are ignored. Adding a few may make it easier to edit the files.

Spaces after the commas are NOT ignored. All other things being equal, the entries with spaces after the commas come first in the index.

Don't do this
    k (index)            Txyz,ParamName          // This comes second
    k (index)            Txyz, ParamName example // This comes first

This is better
    k (index)            Txyz, ParamName         // This comes first
    k (index)            Txyz, ParamName example // This comes second

Linking to Windows SDK help

Most of the time A-Links should be used to reference help topics in other *.hlp files. If more than one topic matches the parameter, additional modifiers can be added so that only a single topic is referenced. I had a situation where the following returned a selection list with 2 options - a VCL reference and a win32sdk reference.
    SetPrinter!ALink('SetPrinter', 1, tnf_qref)
I was not able to find a modifier that returned only the win32sdk topic ... but the following worked fine.
    SetPrinter!KLink('SetPrinter', 1, tnf_qref)

Unit Indices

I like to add index entries for the units I write. The standard Delphi help does not do this, but I like the ability to ask "what is the purpose of this unit?"

To do this you need to add a k-footnote similar to this to one of your pages (I use the Overview page)

    k (index)            UnitName
It begins the top level in the index. k-footnotes similar to
    k (index)            UnitName, TClassName
will be listed under it. For Examples,
    k (index)            UnitName, ExampleName; ProcedureName, Example


In order to simplify testing index entries, I suggest using an *.cnt file which does not include any additional indices. Just comment them out with semicolons
    ;:Index Delphi vcl=del5vcl.hlp
This should make it very easy to see all your indices. Be sure to double click all of them - just to be sure.

More on a-Footnotes

See "Making component help context-sensitive" in the Delphi help - the a-footnotes are used to associate pressing F1 with the correct page. The TControl.OnClick example link is attached to this macro

More on +-Footnotes

The +-Footnotes define a browse sequence - this allows you to move between related pages using the browse buttons - "<<" and ">>".

Delphi places all the classes in one sequence, and places each class's Properties, Methods, and Events in their own sequence (one set per sequence). I place all the classes in a unit in one sequence, and each class's Properties, Methods, and Events get their own sequence.

The footnote should be formatted like this.

I originally decided to leave the entry after the colon blank - this is supposed to format the sequence in the same order as the pages appear in the *.rtf file. Well, that basically works ... except that the first page in the sequence is part way through the *.rtf file. When the end of the file is reached, the next page in the sequence is the first page in the *.rtf file. Other than that, they are in the correct sequence.

The only place that the colon is documented is in the Help Workshop under browse sequences / Browse sequences (RTF) ... and even that got it wrong - if you define a browse sequence, the colon is required - the help says that it is not. That help page also says that the identifier after the colon should be a number, but alpha identifiers also work. The Delphi 5 help never mentions browse sequences.

In general, I find the browse sequences useful when browsing through multiple pages of a description, but not very useful when reading about a class. In that case, the pme index is much better.

Example Pages

There is no need for examples for every Property, Method, and Event.

In the help index, Delphi examples are listed under the property or method name - only. The word "Example" should never be an index heading.

Most Delphi examples do not indicate the class name in the title.

If you decide to place examples in the browse sequence, use footnotes that look like this

    + (browse sequence)  TComponentName_Properties:methodName@_example
The extra at-sign (@) keeps things in the correct sort order. Another way to control the order is to use numbers with leading zeroes (006).

Class Example

Properties, Methods, and Events form 3 separate browse sequences.


The Delphi standard is to provide 2 pme pages that document the unit's contents. These are linked to each other and to all the other units in the Delphi help files. Of course, you need to make sure that each page references the correct items.


In addition to these, I like to add a regular page (or two) that describes the overall purpose of the unit. Links to the Overview page are placed in both the unit and routine pme pages. If you place UnitName in this a-footnote, then you should remove it from the pme page above. The help files should have only one UnitName a-footnote.

Help Template Generator

I have written a Delphi program that reads a unit (an *.pas file) and produces an *.rtf file with all the formatting and footnotes suggested above, plus a lot more.

This program has several known design problems (features). I have no plans to fix these.


Once the template is generated, there is still a lot of work to do. For most classes, the template is pretty clean, however,

pme pages - Properties, Methods, Events - these are the yellow pages that list the items associated with a class.


Author: Robert Clemenzi -
URL: http:// / user / clemenzi / technical / Languages / Delphi / ComponentHelpStyleGuide.html