Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]


Rich-text source file — .rtf

[Top]


Overview

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.

[Top]


RTF file format

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:

Notes:

[Top]


Available styles

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.

[Top]


Character styles

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.

[Top]


Lists

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


Bulleted and numbered lists

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.


Definition lists

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

Definition list styles


Definition list styles

[Top]


Graphics

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.


See also

Project file— .xml