Chapter {seq chapter}
{seq chapter readword}	Word Processor File Format{tc "{seq chapter readword}	Word Processor File Format"}
This document describes the structure of a Psion word processor document file. The description to a level that allows other software to read and write non-password-protected document files.
Psion word processor document files contain a file header, followed by a number of type-length-value records, from the following list:
	options data
	printer-related data
	printer model data
	page header
	page footer
	style data
	emphasis data
	document text
	document index
Document files created by the word processor will contain records in the order listed above. Each record consists of:
	a two-byte record type 
	a two-byte record length, len
	len bytes of data
Unless stated otherwise, all dimensions are stored in twips (1/1440 inch).
Reserved locations
All locations reserved for future use contain a value of zero.
The document header{tc "The document header" \l 2}
The document header is 40 bytes long. It starts with the 16-byte zero terminated file signature "PSIONWPDATAFILE" followed by a two byte file version number.
Following this is a 20-byte struct, containing password data. For a non-password-protected document there are two bytes of zero followed by eighteen bytes, each containing 0xEA.
The remaining two bytes of the header are reserved for future use.
Record types{tc "Record types" \l 2}
The options data record (type 1, length 10){tc "The options data record (type 1, length 10)" \l 3}
The options data record contains the following items:
UWORD cpos
the saved cursor position

UBYTE symbols
specifies the visibility of screen symbols, as indicated below

UBYTE backup/statzoom
on the MC, a non-zero value indicates that backup files are to be maintained
on the Series 3a this byte stores the current status window and zoom states: the top four bits indicate the current zoom state (0x22 by default) and the lowest four bits indicate the status window size: 0, 1 or 2 for off, small or big respectively
this byte is not used on the Series 3

UBYTE style
TRUE to show style bar at the left of the text
for the OPL program editor, a TRUE value sets the use of a bold typeface

UBYTE mono
TRUE to load text by line, else by paragraph
for the OPL program editor, a TRUE value sets the use of a monospaced typeface

UBYTE outlevel
lowest outline level to display
not used for the OPL program editor

UBYTE spare1
reserved for future use, but may contain the OPL program editor data as follows:
used by the OPL program editor, where a TRUE value specifies the use of auto indentation. Set to TRUE by default

UWORD spare2
reserved for future use, but may contain the OPL program editor data as follows:
used by the OPL program editor, to specify the column spacing for tabs. Set to 2 by default

Displayed screen symbols are determined by any combination of the following bit fields in symbols:
0x01
0x02
0x04
0x08
0x10
show tabs
show spaces
show paragraph end markers
show hyphens
show forced line breaks

Printer-related data record (type 2, length 58){tc "Printer-related data record (type 2, length 58)" \l 3}
This record contains information required to format the document for the printer and to control the printing process. It includes, amongst other items, descriptions of the page size and margins, the page numbering style, header and footer position and alignment.
This record consists of a structure that is used to control the display and WDR printing of formatted text in all applications that require such services. It therefore contains some fields that are not relevant to the word processor.
The following description is in terms of the P_EXTENT, SCRLAY_FONT and PAGES_HEADER structs, defined as:
typedef struct
    {
    WORD x;
    WORD y;
    } P_POINT;
typedef struct
    {
    P_POINT tl;
    WORD width;
    WORD height;
    } P_EXTENT;
typedef struct
    {
    UWORD fid;          /* typeface number */ (1)
    UWORD style;        /* font style */ (2)
    UWORD height;       /* height of font in twips */
    } SCRLAY_FONT;
typedef struct
    {
    SCRLAY_FONT f;      /* font data */
    UBYTE align;        /* header alignment */ (3)
    UBYTE first_page;   /* TRUE to emit on first page */
    } PAGES_HEADER;
In these terms, the content of the printer-related record is:
PAGE DATA
WORD width
WORD height
P_EXTENT body
WORD hdtop
WORD hdbot
WORD pdrflags
WORD docflags
UWORD pgbeg
UWORD pgend
page width
page height
body print region, with respect to top left of page (4)
page header position (5)
page footer position (6)
0 for portrait, 1 for landscape
can be 3 or 0, depending on whether the document has or has not been printed
page number to start printing (first page is 1)
last page number to print (7)

RUNNING PAGE HEADERS
PAGES_HEADER top
PAGES_HEADER bot
page header
page footer

PAGE NUMBERING
WORD offset
WORD last
WORD style
page numbering offset
page count, for %m (always reset by pagination)
page number style (8)

MISCELLANEOUS
SCRLAY_FONT f
UBYTE size_choice
UBYTE wo_control
UWORD spare1
UWORD spare2
base font for body print region (9)
paper size index (10)
TRUE to disable widow and orphan control
reserved for future use
reserved for future use

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

A typeface that is not supported by the current printer will be mapped to a supported typeface. See the later Printer driver font mapping section.
In addition, a typeface number of -1, indicating an inherited font, is allowed in all emphases and in all paragraph styles except Body text. An emphasis inherits its font from the surrounding paragraph; a paragraph style inherits its font from the Body text style.
(2) The font style may be zero, or any sensible combination of the following attributes:
0x01
0x02
0x04
0x08
0x10
underline
bold
italic
superscript
subscript

Styles or style combinations that are not supported by the current printer are ignored.
The value 0x4000 is used internally by the word processor and may or may not be set in the font style data in the document. If set, it can safely be ignored.
(3) The running page header alignment may be any one of:
0
1
2
4
5
left aligned
right aligned
centred
2-column
3-column

(4) In terms of the body struct and the page width and height, the page margins are:
left
top
right
bottom
body.tl.x
body.tl.y
width-body.tl.x-body.width
height-body.tl.y-body.height

(5) The page header position measures the vertical distance between the bottom of the header text and the top edge of the page body print region.
(6) The page footer position measures the vertical distance between the bottom of the footer text and the bottom edge of the page body print region.
(7) To print all pages, the last page number should be set to 0xffff.
(8) The page number style is one of:
0
1
2
Arabic
Roman, upper case
Roman, lower case.

(9) The body area base font data is not used by word processor documents. It should always specify the default font, with font number 0 (Courier) a style of 0 (normal) and a size of 240 (12 points).
(10) The page size choice should correspond with the earlier page width and height. The following (English) page sizes are recognised:
Choice	Page type	Width	Height
  0	 A4	11906	16838
  1	 Custom	-	-
  2	 Executive	10440	15120
  3	 Legal	12240	20160
  4	 Letter	12240	15840
  5	 Monarch	5580	10800
  6	 DL	6236	12472
Note that items 2 to 6 may be different in non-English versions of the software.
Printer model data record (type 3, variable length){tc "Printer model data record (type 3, variable length)" \l 3}
The record consists of a zero terminated string, containing the full path name of the current printer driver file, preceded by a one byte index to the printer model within the file.
The default value is:
0
"ROM::\BJ.WDR"
Page header record (type 4, variable length){tc "Page header record (type 4, variable length)" \l 3}
The record contains the page header text as a zero terminated string. The string may not exceed 80 bytes.
Page footer record (type 5, variable length){tc "Page footer record (type 5, variable length)" \l 3}
The record contains the page footer text as a zero terminated string. The string may not exceed 80 bytes.
Style data record (type 6, length 80){tc "Style data record (type 6, length 80)" \l 3}
The file may contain up to 64 such records, each of which defines a single style.
The following description is in terms of the SCRLAY_FONT struct (described above) and the SCRLAY_MARGINS, SCRLAY_SPACING and SCRLAY_TABSTOP structs, defined as:
typedef struct
    {
    UWORD left;        /* left margin */ (1)
    UWORD right;       /* right margin */
    UWORD indent;      /* left margin for first line of a paragraph */
    UWORD align;       /* alignment */ (2)
    } SCRLAY_MARGINS;
typedef struct
    {
    UWORD line;        /* space between lines in a paragraph */
    UWORD above;       /* space above paragraph */
    UWORD below;       /* space below paragraph */
    UWORD flags;       /* keep together/next and new page */ (3)
    } SCRLAY_SPACING;
typedef struct
    {
    UWORD x;           /* tab position */
    UWORD type;        /* tab type */ (4)
    } SCRLAY_TABSTOP;
In these terms, the content of the style data record is:
TEXT sc[2]
TEXT tag[16]
UWORD sflags
SCRLAY_FONT f
UWORD inherit
SCRLAY_MARGINS marg
SCRLAY_SPACING spc
UWORD olevel
UWORD ntabs
SCRLAY_TABSTOP tab[8]
two-letter short code (5)
style tag name (6)
style control flags (7)
paragraph base font (8)
inherited attributes (9)
margin positions
paragraph vertical spacing
outliner level
number of tabstops in following table
up to 8 tabstops, in ascending position order

Notes
(1) Paragraph margins are relative to the page margins (the left and right edges of the body print region).
(2) The paragraph alignment may be one of:
0
1
2
3
left aligned
right aligned
centred
justified

(3) The spacing flags may be any combination of:
0x01
0x02
0x04
keep on same page as following paragraph
keep whole paragraph on one page
paragraph starts a new page

(4) The tab type may be any one of the following:
0
1
2
left tab
right tab
centred tab

(5) The short code must contain two alphabetic characters and must be unique (it must not be duplicated in either a style or an emphasis). If no meaningful short code can be assigned, it is recommended that unique short codes be generated in the sequence ZA,ZB,...,ZZ,YA,...,YZ,XA,...
(6) Although not currently enforced by the software, the text of the tag name should be unique (it should not be duplicated in either a style or an emphasis). If no meaningful tag name can be assigned, it is recomended that the tag name should duplicate the short code.
(7) The style control flags may contain any combination of:
0x02
0x04
undeletable
default

There must be one default style and at least one undeletable style in every document (in all Psion documents they are the same - style BT). It does not make sense for the default style to be deletable.
The value 0x8000 is used internally by the word processor and may or may not be set in the style control flags data in the document. If set, it can safely be ignored.
(8) In addition to the typeface numbers listed earlier, a typeface number of -1 is used to signify that the typeface and font size are to be inherited from the default style. In such a case the font size is conventionally set to zero.
(9) The inherited attributes field may contain any combination of:
0x01
0x02
0x04

underline
bold
italic

For each bit that is set, the corresponding bit in the style field of the SCRLAY_FONT struct must be clear.
Inherited attributes are taken from the default style.
Emphasis data record (type 7, length 28){tc "Emphasis data record (type 7, length 28)" \l 3}
The file may contain up to 16 such records, each of which defines a single emphasis.
The following description is in terms of the SCRLAY_FONT struct (described above). In these terms, the content of the emphasis data record is:
TEXT sc[2]
TEXT tag[16]
UWORD sflags
SCRLAY_FONT f
UWORD inherit

two-letter short code (1)
emphasis tag name (2)
emphasis control flags (3)
emphasis font (4)
inherited attributes (5)

Notes
(1) The short code must contain two alphabetic characters and must be unique (it must not be duplicated in either a style or an emphasis). If no meaningful short code can be assigned, it is recommended that unique short codes be generated in the sequence ZA,ZB,...,ZZ,YA,...,YZ,XA,...
(2) Although not currently enforced by the software, the text of the tag name should be unique (it should not be duplicated in either a style or an emphasis). If no meaningful tag name can be assigned, it is recomended that the tag name should duplicate the short code.
(3) The emphasis control flags must contain the value 0x01, together with any combination of:
0x02
0x04
undeletable
default

There must be one default emphasis and at least one undeletable emphasis in every document (in all Psion documents they are the same - emphasis NN). It does not make sense for the default emphasis to be deletable.
(4) In addition to the typeface numbers listed earlier, a typeface number of -1 is used to signify that the typeface and font size are to be inherited from the enclosing paragraph style (which may itself inherit from the default style). In such a case the font size is conventionally set to zero.
(5) The inherited attributes field may contain any sensible combination of:
0x01
0x02
0x04
0x08
0x10
underline
bold
italic
superscript
subscript

For each bit that is set, the corresponding bit in the style field of the SCRLAY_FONT struct must be clear.
Inherited attributes are taken from the enclosing paragraph style (which may itself inherit from the default style).
Document text record (type 8, variable length){tc "Document text record (type 8, variable length)" \l 3}
This record contains the entire text of the document. Each paragraph, except for the final one, is terminated by a zero.
The content conforms with the IBM Code Page 850 symbol set, together with the following additional symbols:
Symbol	          ASCII
END_PARAGRAPH	0x00
HARD_HYPHEN 	0x07
TAB 		0x09
LINE_FEED	0x0a
SOFT_HYPHEN 	0x0e
HARD_SPACE  	0x0f
Meaning
paragraph terminator
unbreakable hyphen, not a word delimiter
tab character
forced line break
optional, or potential, hyphen
unbreakable space, not a word delimiter

Document index record (type 9, variable length){tc "Document index record (type 9, variable length)" \l 3}
This record contains a number of six byte entries which are used to apply style and emphasis to the document text. Each entry consists of:
	a length (word)
	the two character short code of a style
	the two character short code of an emphasis
The entries conform to the following rules:
	the sum of their lengths is one more than the length of the document text record (i.e. the document size, including the final paragraph terminator that is not contained in the document text record). 
	there is at least one index entry for each paragraph in the document
	the final index entry for each paragraph includes the zero that terminates the paragraph 
	the short codes must correspond with styles and emphases contained in the earlier style data and emphasis data records
It must be stressed that a single index entry may not apply to text that is contained in more than one paragraph.
Template files{tc "Template files" \l 2}
Word processor template files have exactly the same structure as normal word processor files. The only differences are that they:
	have a .wrt extension, rather than .wrd;
	are stored in a \wdr directory.
Template files for program editor aliases of the word processor contain only:
	a 40 byte header, as for other word processor files;
	a type 1 options data record;
	a type 8 document text record.
The meanings of some items in the options data record differ from those of a normal word processor file:
UWORD cpos
the saved cursor position, as for normal word processor files

UBYTE symbols
the visibility of screen symbols, as for normal word processor files

UBYTE backup/statzoom
backup state or status window and zoom settings, as for normal word processor files

UBYTE style
TRUE to set the use of a bold typeface

UBYTE mono
TRUE to set the use of a monospaced typeface

UBYTE outlevel
always TRUE for program editor aliases, to enable the use of templates

UBYTE spare1
TRUE to specify the use of auto indentation

UWORD spare2
the spacing, in column units, for tabs

Printer driver font mapping{tc "Printer driver font mapping" \l 2}
The font ID associated with a particular emphasis or paragraph style is determined by a selection from the fonts available from the current printer driver at the time the emphasis or style was created. When a different printer driver is installed, the font IDs associated with emphases and styles do not change (so that the exact appearance of the document will be restored when the original printer driver is reinstalled).
The actual font to use when printing the document is determined by mapping each fixed font ID to one of the available fonts supplied by the current printer driver. A perfect match occurs when the font ID matches the font number of one of the fonts supported by the printer driver. Otherwise, an attempt is made to make a simple fixed mapping, by font characteristics, onto a basic set of COURIER (mono), HELVETICA (proportional, sans serif) or TIMES_ROMAN (proportional, serif).
If the current printer driver does not contain fonts with font numbers HELVETICA or TIMES_ROMAN, thease are also mapped to COURIER (font number zero). This is assumed always to be set for the printer's default font - usually a 10 or 12 point font - whatever it is called.

Additional system information

	{seq chapter readword}  Word Processor File Format

{page|1}

	{page|1}

	{page|1}


