Rich-text source file — `.rtf`

Overview
RTF file format

Topic elements
Paragraph styles
Character styles
Lists

Hypertext anchor
Graphics

EPOC help database
HTML proofing

Overview

This section describes the structure of an aleppo rich-text source file. In particular, it covers the different styles that can be used in the source rich-text file, and how they map text into each element of the final help database.

RTF file format

Section Contents

Topic elements
Paragraph styles
Character styles
Lists

Bulleted and numbered lists
Definition lists

A .rtf source file for EPOC help must have the following structure:

The first paragraph in Heading 1 style: its text will be the application name for all topics in the source file
each topic must begin with a Heading 2 style paragraph, and continue with other paragraphs as described below: the text of the Heading 2 paragraph will be the topic title

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.

Topic elements

The main elements in a topic are

the title: comes from the text of the Heading 2 paragraph which begins the topic
the hypertext anchor name: this is represented by a paragraph in Hypertext Anchor style, which must occur immediately after the Heading 2 paragraph. The hypertext anchor name is used for the topic ordering list. The hypertext anchor need not be translated during localisation. This topic element is only required for those topics that are to appear in a defined order in the help database.
any synonyms: these come from the content of paragraphs in Topic Synonym style. A synonym paragraph may be placed anywhere within the topic, however only one synonym paragraph is allowed in each topic.
the body text: this comes from all other paragraphs in the topic

Paragraph styles

The paragraph styles provided by the epochelp template, and recognised by aleppo, 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
`Hypertext Anchor`	cntl+shift+A	hypertext anchor name
`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`	ctrl+shift+O	a note; perhaps a warning
`Important`	ctrl+shift+I	important information; warning which must be heeded
`Comment`		notes that the author wishes to leave in the file — ignored by `aleppo` when processing the file

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

Character styles

The character styles provided by the epochelp template, and recognised by aleppo, are documented below.

`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 aleppo from an RTF source document.

Lists

Aleppo supports the following kinds of list

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, and optional punctuation, 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 aleppo choose the bullet type for you, and in the case of auto-numbered lists, manages the sequencing. 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.

Aleppo 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: aleppo 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. It is like a two-column table. 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

Hypertext anchor

A hypertext anchor may be defined by marking text below the topic heading in Hypertext Anchor style. The anchor can then be used by the order file to define the display order of the topic in the final database, see Order files. A hypertext anchor need not be defined, and if defined need not be used.

Topics for which it would be appropriate to have a hypertext anchor are those which it would be natural for a user to browse first, e.g. for quick start sections.

Notes

Hypertext anchors must be unique within an entire help database.
Hypertext anchors should be combinations of alphanumeric characters, periods and hyphens. An anchor such as agenda.entering-day-notes relates meaningfully to the application and the topic title, and shows a convention that can easily be adapted and followed.
Topics which are not referred to from the order list do not need hypertext anchors.
Hypertext anchors are unique identifiers for a topic, and need not be translated when the help source is localised.

Graphics

Section Contents

EPOC help database
HTML proofing

Graphics are indicated, in the RTF source, by a directive in Graphic Link character style. The directive is used to locate a graphic. The graphic will appear like a single, potentially large, character in the help database.

The form of the graphic link directive is illustrated in the following sentence: press archive=eikon name=darrow to scroll down. The directive specifies an archive, and a name.

The content of a Graphic Link directive is not subject to localisation.

EPOC help database

For the EPOC help database, the archive refers to an EPOC multi-bitmap file, and the name refers to the name of a bitmap within it. The name must be looked up in a .mbg. The algorithm used is as follows:

the archive is graphics-directory\archive.mbm, with its associated graphics-directory\archive.mbg header file
the name is looked up in the .mbg header file, and used to determine the index of the bitmap
the index is looked up in the .mbm to extract the bitmap data

If the relevant archive and name cannot be found in this way, another check is made:

the archive is a directory, graphics-directory\archive\
the name is looked up as a .mbm in that directory: graphics-directory\archive\name.mbm
the first bitmap from this .mbm is used

The graphics-directory is specified in the aleppo project file: see Project files.

More than one graphics directory may be specified in the project file: each one is searched for the graphic in turn.

HTML proofing

HTML requires JPEG files. These are generated by aleppo from .mbm files, as required. The .mbm bitmaps are found in the same way as for EPOC help databases.