 |
About CategoriesCategories is one of the concepts of Time2HELP which definitely sets it apart from more "manual" way of writing help files/documentation for source code. Categories is a way to add more structure to your help files/documentation. E.g. you may make a category titled "String Handling Routines" to make a group of all your string handling routines, making it easy for the user to get a list of them all.Defining CategoriesThe categories are defined/stored in a single document, which you open by using the menu item File | Edit Categories Doc. This file is located in your T2H install directory, "GlobalDoc\GlobalCategories.CatDoc". Here you give categories a name, title and a description. The name will not be visible in the output, but the title and description will. Currently all your categories have to be defined in this single file. T2H 1.0 will only support multiple category files when the different ones target different languages, say one category file defining titles and descriptions in english, another file in French, German etc. The "links" to categories are done using the (internal) category name, which means your category "links" will be language independent.The Name of the Category
This name will be the basis for topics id's (in WinHelp output) and similar in other kinds of output. It is also what you refer to when you "add" items to a category (more on this below). Each category must have a unique name, and since these names never will be seen by end users, you may use your favorite cryptic naming convention and favorite natural language.
| You should only use the standard English letters, digits and the underscore character, and the category name should start with a letter (not underscore nor digits). Category names starting with "_" (underscore) is reserved for future internal T2H category names. |
Category names could be like "StringHandling", "DateHandling", "Datamodule" etc.Defining the Content of CategoriesThere are two different ways to associate categories to your code items, depending upon whether you prefer using DocComments or UnitDoc files.Using DocComments
To link to a category (which is the same as saying that a given code item "belongs" to the given category, you use the following syntax: {:This is a nice routine.
@cat StringHandling
@cat DateHandling
}
Function CalculateDay(const i_name: String; const i_date: TDateTime): TDateTime;
Begin
...
End; | @cat is short for @category, you may use both. You may also read this as:
"CalculateDay is both a StringHandling and a DateHandling routine". When Time2HELP processes this, it will list CalculateDay in the category overviews for StringHandling and DateHandling. It will also make a link to these categories in the topic for CalculateDay. (Quite like what the D5 help file does)From UnitDocs
Here you use:
<CatRefs>
<CatRef>StringHandling</CatRef>
<CatRef>DateHandling</CatRef>
</CatRefs>
|
