Rich-text source file .rtf

This section describes the structure of a CS Help rich-text source file. In particular, it covers the different styles that can be used in the source rich-text file.

In order to use CS Help successfully, it is important to know something about how rich-text files are used in the conversion process. The conversion is based on styled markup. It conveys no formatting information from the rich-text file, except for bold, italic, subscript and superscript, and the style names of paragraphs and characters. It does not convey tabs, hard line breaks (shift+enter), or any other formatting information such as fonts, underline, margin settings, borders etc. This means that character and paragraph styles must be used to convey all formatting information to CS-Help.

A .rtf source file for CS Help must have the following structure in the order presented:

1. Category name in Heading 1 style. A unique name for all the topics in the help file.

2. UID of the application in category UID style. There can only be a single occurrence of category UID style in the source .rtf file. The UID can be entered as a decimal or hex value. A hex value is entered as 0xXXXXXXX (leading and trailing spaces are ignored).

3. Topic title in Heading 2 style paragraph. There may be any number of topic titles.

The following classifications are associated with the topic that precedes them. They are implemented in the following order and are all optional:

• Synonyms in synonym style. An alternative name for the topic. Synonyms are limited to a maximum of 120 chars.

• Context in context style. Identifies a context that the help topic is linked to, entered as a series of paragraphs. Contexts can be any length but only the first 30 characters are significant. A topic may have any number of contexts but each context must be unique within a help file—the compiler will check for uniqueness. A context may optionally be followed by text in context comment character style. This text forms a program language comment in the generated header file.

• Indexes in index style. Each index should be specified in a separate paragraph and is limited to 120 characters maximum. An index is a string associated with a topic and is used in the help application's index view. Because an index phrase may relate to more than one topic, indexes need not be unique within a help project. A topic may have any number of indexes.

• Body text in Normal and other cshelp.dot styles.

Notes:

• Comment style can be used anywhere within the source file to indicate author, date, or other such notes which should not be converted into the target format.

• The CS Help compiler does not allow the styles named above, except Normal, in the body text of the topic. All other cshelp.dot styles are allowed.

The paragraph styles provided by the cshelp template, and recognised by the CS Help compiler, are documented below.

Style Keyboard shortcut Description Heading 1 ctrl+alt+1 application name Heading 2 ctrl+alt+2 topic title Synonyms ctrl+shift+S words in this paragraph form a synonym list Normal ctrl+shift+N normal body text List Bullet bulleted list item List Number auto-numbered list item List Manual manually-numbered list item List Continue continuation paragraph for a list item List Bullet 2 second-level bulleted list item List Number 2 second-level auto-numbered list item List Manual 2 second-level manually-numbered list List Continue 2 continuation paragraph for a second-level list item Definition Term an item to be defined Definition Definition defines an item Tip ctrl+shift+T a tip Note a note; perhaps a warning Important ctrl+shift+I important information; warning which must be heeded Context identifies a context Comment notes that the author wishes to leave in the file— ignored by the CS Help compiler when processing the file

Apart from the names of these paragraph styles, no paragraph formatting information is conveyed from an RTF source document by the CS Help compiler.

The character styles provided by the cshelp template, and recognised by the CS Help compiler, are documented below.

Style Keyboard shortcut Description App Text ctrl+shift+P Application text, used for text on menus, dialogs, buttons, application views Key Name ctrl+shift+K Used for keys which must be pressed by the user. This is not for entire strings entered by the user: see App Text for that. Graphic Link ctrl+shift+G contains a directive which will be replaced by a graphic in the help database

Apart from the names of these character styles, and manually-applied bold, italic, subscript and superscript attributes, no character formatting information is conveyed by CS Help from an RTF source document.

CS Help supports the following kinds of list

List Type Description. auto-bulleted a suitable bullet character, e.g. blob or dash, picks out the head paragraph in each list item auto-numbered an auto-generated number picks out the head paragraph in each list item manually numbered a manually entered number picks out the head paragraph in each list item definition a special kind of list used for a series of terms and their definitions

Auto-bulleted and auto-numbered lists are supported directly by Microsoft Word, and RTF. Use the List Bullet and List Number styles for the head paragraphs of each item. Word and the CS Help compiler manage the sequencing of auto-numbered lists. This makes it easy to produce consistent and correct lists.

An item in an auto-bulleted list may have continuation paragraphs, in List Continue style, or nested lists, in one of the List ... 2 styles. This is not possible in Word, because the numbering on the head paragraphs is lost.

CS Help also supports manually numbered lists. To enter a head paragraph in a manually numbered list, use the paragraph style List Manual; type the number, a tab, and then the text of the paragraph. Type the number in Roman format only, and do not type any punctuation: CS Help will generate the correct numbering and punctuation.

A definition list is used when a number of items need to be defined or explained. The list is made up of two columns. The first column is a sequence of terms to be defined; the second is a sequence of definitions. The terms are quite short, and cannot be more than a single paragraph. The definitions are potentially long, containing multiple paragraphs. The table of list types above, for instance, would be a natural use of a definition list.

To enter a definition list, use paragraphs with style sequences of the form

Figures are inserted into a help topic by placing the following in graphic link style in the source .rtf file:

archive=archivename name=picture

The archivename refers to the graphic sub directory within the project directory. It is specified in the project file using the graphics tag. The picture refers to the filename of the graphic (mbm) to place into the help file. The mbm may only contain one bitmap.

Project file— .xml