ADVANCED RTF FONT AND STYLE TRANSFER
------------------------------------

You can more accurately control the way that fonts and style names
are transferred in RTF by using an RTF map file, which is a plain
text file, with the name 'rtfmap.txt', in any \WDR subdirectory of
the root directory of a local drive (the drive search order is
M:, A:, B:). 

The contents of a typical map file could be:

:STYLES
 BT      9       Normal;
 HA      1       heading 1;
 HB      2       heading 2; 
:FONTS
 00      fmodern;        pica;
 24      froman;         Times New Roman;

The keywords :STYLES and :FONTS introduce style and font mappings
respectively. They may occur in any order and may be repeated.

Whitespace before an item is generally ignored, as is any text
following the final semicolon (;). Long labels are truncated to 15
(style labels) or 19 (font names) characters, not counting the
terminating semicolon. Illegal entries are ignored, without
generating any error notification.

Style mapping

Each line represents the correspondence between the shortcode,
outline level and a style label. The style labels should correspond
with those used by Microsoft Word (or any other word processor that
understands the RTF format). You can determine these names from the
stylesheet section of an RTF file generated by the word processor
(see the later 'RTF files' section).

There is no checking for duplicate shortcodes or labels, so be
warned. Total duplicates are wasteful of memory but otherwise
harmless. Pairs of entries that match in either their shortcode or
their label, but not both, should be avoided.

To prevent any possibility of error in bi-directional mapping, one-
or two-character labels (particularly if they start with X, Y or Z)
should be avoided.

Font mapping

Each line represents the correspondence between a font ID, the RTF
font class and a font name.

The font IDs should be unique and must lie in the range 0 to 63
inclusive. The font IDs used by the Psion word processor vary from
printer to printer. You can find which font IDs are used in a
particular printer driver by examining the font table in an RTF file
that was saved from the Psion word processor with that printer driver
installed, and with no font mapping (see the later 'RTF files'
section).

There is no harm in mapping a font to an ID that is not supported by
a particular printer driver, but it will be displayed and printed in
the printer's default (monospaced) font. The following table
indicates the preferred general allocation scheme for font IDs used
in Psion printer drivers:

  0 COURIER            22 OPTIONAL_SB          44 RUSSIAN
  1 PICA               23 OPTIONAL_SC          45 OPTIONAL_B
  2 ELITE              24 TIMES_ROMAN          46 OPTIONAL_C
  3 PRESTIGE           25 CENTURY              47 OPTIONAL_D
  4 LETTER_GOTHIC      26 PALATINO             48 NARRATOR
  5 GOTHIC             27 SOUVENIR             49 EMPHASIS
  6 CUBIC              28 GARAMOND             50 ZAPF_CHANCERY
  7 LINEPRINTER        29 CALEDONIA            51 OPTIONAL_DA
  8 HELVETICA          30 BODONI               52 OLD_ENGLISH
  9 AVANT_GARDE        31 UNIVERSITY           53 OPTIONAL_DB
  10 SPARTAN           32 SCRIPT               54 OPTIONAL_DC
  11 METRO             33 SCRIPT_PS            55 COOPER_BLACK
  12 PRESENTATION      34 OPTIONAL_SCA         56 SYMBOL
  13 APL               35 OPTIONAL_SCB         57 LINE_DRAW
  14 OCR_A             36 COMMERCIAL_SCRIPT    58 MATH_7
  15 OCR_B             37 PARK_AVENUE          59 MATH_8
  16 STANDARD_ROMAN    38 CORONET              60 DINGBATS
  17 EMPEROR           39 OPTIONAL_SCC         61 EAN
  18 MADELEINE         40 GREEK                62 PC_LINE
  19 ZAPF_HUMANIST     41 KANA                 63 OPTIONAL_SYA
  20 CLASSIC           42 HEBREW
  21 OPTIONAL_SA       43 OPTIONAL_A

The RTF font class must be one of:
     fnil            Unknown or default
     froman          Roman; proportional serif
     fswiss          Swiss; proportional sans serif
     fmodern         Monospaced serif and sans serif
     fscript         Script
     fdecor          Decorative
     ftech           Technical, symbol and mathematical

The font names should be those present in the font table of a
Microsoft Word (or other word processor) RTF file and do not need to
match the names of Psion printer driver fonts.

Open (RTF)

If a map file is located, and contains valid style entries, the list
is scanned for a match with an incoming label and, if found, the
style is given the corresponding shortcode and outline level. This
style will overwrite any existing style with the same shortcode.

Styles with non-matching labels have their style labels preserved.
They are given an outline level of 9 and a shortcode consisting of
the first two letters of the label (a preceding X is added if the
label contains only one character). If this shortcode is illegal or
matches an existing style, a unique shortcode is generated. These
styles, therefore, never overwrite existing styles.

If there are no valid style map entries, incoming style labels
"Normal" and "heading n" (1 <= n <= 8) are handled explicitly,
generating shortcodes of BT, and HA to HH, with outline levels of 9
for BT and 1 to 8 for the headings. These styles always overwrite any
existing style of the same shortcode.


All incoming fonts whose names match an entry in the map file are
allocated the corresponding ID, regardless of whether this is
supported by the current printer driver.

Non-matching incoming fonts are converted to those supported by the
current printer driver. Fonts are preserved only if they are an exact
match, by both name and RTF font family (the Psion word processor
currently only supports fonts in the fmodern, fswiss and froman
families - see above). Otherwise an attempt is made to convert the
font to a supported font in the same family. If this is not possible,
the font is converted to the current default (monospaced) font.

Save as (RTF)

If a map file is located, and contains valid entries, the list is
scanned for a match with an outgoing shortcode and, if found, the
style is given the corresponding label. Styles with non-matching
shortcodes are given labels equal to their shortcodes, irrespective
of the text of their current labels.

If there are no style map entries, the first style of outline level 9
to be saved (usually BT) is saved with the label "Normal". Similarly,
the first styles of outline level 1 to 5 (usually HA etc.) are saved
with labels from "heading 1" to "heading 5". All other styles are
saved with labels consisting of their shortcodes, irrespective of the
text of their current labels.

The font table includes all fonts listed in the map file, together
with any additional fonts supported by the current printer driver
(provided their font IDs do not match with IDs present in the map
file).

In the absence of any font mappings, only those fonts supported by
the current printer driver are included in the RTF file.

RTF files

An RTF file is a plain text file containing the text of a document,
together with plain text encoding of style and formatting
information.

A Psion map file affects the content of the RTF file font table and
stylesheet sections which can be found near the beginning of the RTF
file.

The font table contains a list of font entries, enclosed by:

        { \fonttbl                      }

Each font entry consists of a font number (ID), a font family and a
font name, for example:

        { \f0  \fmodern  pica; }

The stylesheet section contains a list of stylesheet entries,
enclosed by:

        {  \stylesheet                  }

Each stylesheet entry consists of a variety of style instructions,
terminated by the style label, for example:

        { \s244 \li270 \f3 \fs20 \ul heading 4; }

In this example the label is "heading 4".
