# SGML file format

## Contents

- Overview
- Source files
- epochelp doctype

- Topic structure
- Body
- Paragraph text

- Graphics

## Overview

This chapter is superfluous to the needs of most help authors. It defines the `epochelp` SGML doctype, for the following purposes:

- to act as a reference for the capabilities of `aleppo`
- to define implicitly the functions of the RTF-to-SGML converter
- to define implicitly the input data used by the SGML-to-target database converters

The specification attempts to be exhaustive.

  Example SGML pipeline

For information about how to interpret the syntax, see BNF grammars.

## Source files

The `epochelp` SGML source comprises

- one or more files of the `epochelp` SGML doctype, each of which contains a list of topics
- one or more `.mbm` files
- an auxiliary file which lists all `.mbm` files used by the SGML-to-target converter

## epochelp doctype

Section Contents

- Topic structure
- Body
- Paragraph text

A file in the `epochelp` doctype has one or more help topics in it. Each topic has title, application name, synonyms, possibly order information, and a body.

### Topic structure

Each help topic contains the following tags:

  `<topic application=`appname [ `order=`number ] `>`
  `<topic-title>`paragraph-text`</topic-title>`
  topic-body
  [ `<synonyms>`words`</synonyms>` ]
  `</topic>`

The `<topic>` tag and its end-tag delimit a topic. The topic must begin with a title.

The `application=` attribute specifies the application name.

If the `order=` attribute is specified, then the topic is among the ordered topics as specified by the order file. Otherwise, the topic is unordered — i.e., it is ordered alphabetically with all other unordered topics, after all the ordered topics.

The `<synonyms>` tag and its content may occur anywhere within the body.

### Body

The body consists of a number of paragraphs. Some paragraphs may be in lists. Definition lists are supported. Tables are not supported.

  `<p` [ `style=`style-name ] `>`paragraph-text`</p>`
  |
  `<ul>` | `<ol>`
  `<li` [ `seq=`number ] `>`paragraph-text`</li>`
  [ `<p>`paragraph-text`</p>` ... ]
  ...
  `</ul>` | `</ol>`
  |
  `<dl>`
  `<dt>`paragraph-text`</dt>`
  `<dd>`paragraph-text`</dd>`
  [ `<p>`paragraph-text`</p>` ... ]
  ...
  `</dl>`

If style-name is not specified, it defaults to `normal`. Other allowable values are `tip`, `note`, `important`.

There are two types of itemised list: unordered (automatically bulleted), and ordered (auto-numbered). Each of them consists of a sequence of items which, in addition to a head paragraph, may have continuation paragraphs — which would have been `List Continue` style in the original RTF.

The `seq=` attribute is only valid for ordered lists, and allows a sequence number for an item to be explicitly specified. In the absence of a `seq=` attribute, the item’s number is one greater than the previous number, or 1 for the first item.

A definition list contains entries of the form term, definition. The term may have only a single paragraph. The definition may have an arbitrary number of paragraphs. The converter may convert a definition list into either a two-column table, or some suitable list format with a small hanging indent for the definition.

Lists may be nested. Numbering in an enclosing list is not affected by a numbered nested list.

### Paragraph text

Paragraph text consists of a sequence of characters. The sequence may contain whitespace, SGML entities, character formatting tags, or graphics directives. Supported entities are

`&amp;` | ampersand
`&lt;` | less-than sign
`&gt;` | greater-than sign
`&nbspace;` | non-breaking space
`&nbhyphen;` | non-breaking hyphen
`&break;` | forced line break
`&tab;` | tab

Supported tags are

`<b>` | bold
`<i>` | italic
`<sup>` | superscript
`<sub>` | subscript
`<cs style=`style-name`>` | character style
`<graphic index=`index-number`>` | graphic from EPOC MBM

Supported character styles are `app text`, `key name`.

Graphics are looked up by index from the graphics auxiliary file: see below.

## Graphics

During conversion of source RTF into `epochelp` SGML, `aleppo` processes all graphics directives and identifies the `.mbm` file and the bitmap number of each graphic referred to. It also identifies the `.mbm` files and bitmap numbers of graphics defined in the customisation file, if any, for important, note and tip effects. The locations of the graphics are noted in a graphics auxiliary file which is, essentially, a part of the SGML help database.

This graphics auxiliary file is a text file which contains lines of the form

  `<graphic` `index=`index `archive=`archive `name=`name `bitmapfile=`bitmap-file-name `bitmapindex=`bitmap-index`>`

In each such line,

- the `archive=` and `name=` attributes match the attributes specified in the `Graphic Link` directive in the RTF source
- the `bitmapfile=` attribute gives the full path to the EPOC `.mbm` file containing the graphic bitmap
- the `bitmapindex=` attribute gives the index to the bitmap, within the `.mbm` file
- the `index=` attribute is allocated from 1, and is the key to the entry, enabling it to be looked up efficiently from the SGML source when a `<graphic>` tag is processed

This information is sufficient to allow the SGML-to-target converter to process graphics without any further searching.