• Use Arial - but be careful, for a while, every time I pasted plain text, it was inserted as Times Roman. (How to change the default font.)
• I was not able to match the top and bottom margins.
• The Line spacing in the pme files is different.

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)
  Footnotes
    # (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
  Footnotes
    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
  Footnotes
    # (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
  Footnotes
    # (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 
  Footnotes
    # (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

Examples
  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, for..to..do, if..then..else
  Delphi examples never link to anything, Some of mine do
  Footnotes
    # (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:)

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

    ParamName,Txyz

    ParamName
        Txyz

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

    SetPrinter!ALink('SetPrinter', 1, tnf_qref)

    SetPrinter!KLink('SetPrinter', 1, tnf_qref)

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

    k (index)            UnitName, TClassName

    k (index)            UnitName, ExampleName; ProcedureName, Example

    ;:Index Delphi vcl=del5vcl.hlp

For a class item      TClassName_ItemName; ItemName_Type; ItemName
For the class         TClassName_Object; TClassName

Examples              SomeName_example
                      TClassName_ItemName_example; ItemName_Type_example; ItemName_example

                      UnitName_unit
                      UnitName_routine
                      UnitName_overview

• "ItemName" is the name of a Property, Method, or Event
• "Type" should be either "Property", "Method", or "Event"
• There are 3 a-footnotes for the unit, each one on a separate page
• Give some thought as to how you name an Example's a-footnote. The second example above will cause a selection list to be displayed when you press F1 (I need to actually test this), normally, Delphi immediately opens the help page.

!alink('TCheckBox_OnClick_Example', 1, '', 'Example')

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.

SequenceName:SortControl

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.

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

(Show the Icon here) TButton (Bold, Font Arial 12)
Hierarchy     Properties     Methods     Events     See also 
        (Arial 8, place a space formatted as Arial 12 after Hierarchy)
----------------------------------
TButton is a push button control.

Unit (Bold)

stdctrls (Normal Link)

Description (Bold)
text starts here ...

Help Page
UnitName unit	This contains a list of all the classes defined in the unit
UnitName routine	This contains a list of all the Functions, Procedures, and Constants defined in the unit

  Title
    UnitName unit
  Links
    UnitName routines!alink('UnitName_routine', 1, 'tnf_qref', 'PME')
    Other objects and components, by unit!alink('Units_all', 1, 'tnf_qref', 'PME') 

  Footnotes
    # (topic id)         UnitName_unit
    $ (title)            UnitName unit
    a (search)           Units_all; UnitName_unit; UnitName
    > (window name)      pme

  Title
    UnitName routines
  Links
    UnitName objects/components!alink('UnitName_unit', 1, 'tnf_qref', 'PME')
    Other routines, by unit!alink('Routines_all', 1, 'tnf_qref', 'PME')


  Footnotes
    # (topic id)         UnitName_routine
    $ (title)            UnitName routines
    a (search)           Routines_all; UnitName_routine; UnitName
    > (window name)      pme

Unit description
  The no-scroll section consists of 2 lines - Title and Links
    Title - Arial 12 bold - UnitName unit overview
    Links - Arial  8 separated by 1" tabs
            Between the words "See Also" and "Examples" place 2 1/2" tabs
            Between those tabs, place a 'space' formatted as Arial 12
    Mark both lines as "Keep with next" (this defines the no-scroll area)
  Footnotes
    # (topic id)         UnitName_Overview
    $ (title)            UnitName unit overview
    k (index)            Overview,UnitName; UnitName,Overview; Overview,; UnitName,
    a (search)           UnitName_Overview; UnitName
    + (browse sequence)  UnitName:                             (the colon is required)
    > (window name)      main

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

• Comments are assumed to be the only item on that line.
• Multi-line comments are supported, but the last line must contain only a curly brace - "}".
• Functions and procedures are assumed to end on the first line to have a semicolon after a closing parentheses. Directives on additional lines are not formatted (included).

• The pme files and the browse sequences are sorted alphabetically. (The unit's browse sequence is not alphabetical, it appears to be a help design problem.)
• Example pages are created for every Property, Method, and Event. I obviously don't expect you to create that many - combine and delete these as appropriate.
• Most of the *.rtf file templates are stored as text files. Two templates are in the *.ini file. However, there are a few short strings which are hardcoded.

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

• The See also links need to be modified or deleted
• Any un-used Example links and pages need to be deleted
• Overloaded methods need to combined on a single page
• You need to create new Hierarchy pages for any base classes you created and for any Delphi base classes not already in mcCommonHelp.hlp
• For Actions, I delete all the properties and methods that I override. Make sure the pme pages are ok - delete the ones you don't use. (Be sure to keep the properties you add.)
• On pme pages, clean up the properties that start with ** - they are defined in some base class.
• And finally, add the text that actually describes your creation.

• 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 Delphi Help Expert v 2.1 as shareware ($69).
  (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 / ComponentHelpStyleGuide.html