Writing Help Files | Style_Guide | Table of Contents | MS Help Workshop | Checklist | More Tips
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:)
More on k-Footnotes
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; ParamNameThese 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
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
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)
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) UnitNameIt begins the top level in the index. k-footnotes similar to
k (index) UnitName, TClassNamewill be listed under it. For Examples,
k (index) UnitName, ExampleName; ProcedureName, Example
;:Index Delphi vcl=del5vcl.hlpThis 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
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
!alink('TCheckBox_OnClick_Example', 1, '', 'Example')
More on +-Footnotes
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.
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@_exampleThe extra at-sign (@) keeps things in the correct sort order. Another way to control the order is to use numbers with leading zeroes (006).
(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 ...Properties, Methods, and Events form 3 separate browse sequences.
|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) pmeOf course, you need to make sure that each page references the correct items.
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) mainIf 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
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,