# Rich-text source file — `.rtf`

## Contents

- 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.