DOC2RTF 1.014

Documentation by Simon N Goodwin, May 1996.


USAGE

This utility converts files written in Psion Quill word-processor format into
the 'Rich Text' format used on many other platorms. It is based on SuperBASIC
by Mark J Swift, originally written to support the Amiga Qdos emulator, which
includes Psion XCHANGE, the full version of Psion's integrated business suite
for the Qdos operating system.

The program runs from Workbench or CLI. If run from Workbench it uses the ASL
requester to select input and output files.  This became part of the standard 
Amiga system from Workbench 2 onwards,  but is only available as an extension
for older versions of Workbench. DOC2RTF has only been tested from the CLI on
Workbench 1.3. The CLI format is:

			DOC2RTF InFile OutFile

when the program reads InFile (which must be a Quill DOC) and writes OutFile.
If another error occurs, a HiSoft BASIC requester pops up and DOC2RTF aborts.

Users may optionally specify the word TO between the InFile and OutFile name.
If the OutFile name is not specified, DOC2RTF appends .RTF to the InFile name
and creates an output file with that name.

If the input file is not in a valid DOC format, DOC2RTF prints an appropriate
message. If the front-end is being used you get another chance to pick a file
but if using the shell DOC2RTF terminates after displaying the error message.


WHAT IS RICH TEXT FORMAT?

Rich Text is a way of encoding documents using standard ASCII character codes
with ancillary formatting information added so the exact appearance on a page
is preserved  even when the text is moved from one package - or computer - to
another. Rich Text is extensively used on Apple Macintosh systems and is also
recognised by workstations, Amiga Wordworth 5 and many PC programs, including
Microsoft Works and Word for Windows.

Since Rich Text only uses the standard 7-bit ASCII character set, stripped of
control codes apart from line-ends, it can be EMAILed without any requirement
for the document to be UUENCODEd first.


WHAT IS PSION QUILL?
										
Psion is the UK-based computer company responsible for the Organiser portable
computers.  In the mid 1980s Psion wrote a suite of business programs (Quill,
Archive,  Abacus  and  Easel) which was available on many platforms. The four
programs were originally bundled with the  Sinclair QL, the first 68000-based
multi-tasking  home computer  (introduced about a year before the Amiga)  and
later as 'PC Four' for MSDOS machines.  Later all four programs were combined
into one integrated package,  XCHANGE,  built into the ICL/BT  'One Per Desk'
computer, and bundled with the  CST Thor,  a QL-clone produced in England and
Denmark. XCHANGE was also converted to run on MSDOS PC-compatible systems.

The Psion suite  uses its own  proprietary format  for data files, as well as
unformatted ASCII text files for 'import and export'.  The DOC file format is
used by Quill, and it contains formatting information such as margins,  tabs,
pagination  and text  attributes as well as the text itself.  It is useful to
be able to convert DOC files into  Rich Text  because the formatting and page
layout is preserved.  This would not be the case if an ASCII file was printed
out or exported.

The Psion suite was exceptionally powerful in its day, and is still unusually
well-integrated and easy to use.  Its main limitation  - compared with modern
packages -  is that it does not support proportionally-spaced characters,  so
it is not capable of Desktop Publishing effects.  But it's still very usable,
especially if you wish to run an  integrated package on a floppy-based Amiga.
The original package had to run in just 128K RAM,  loading and saving on 100K
Sinclair Microdrive tapes,  so it runs quite comfortably on almost any Amiga.

The Quill word processor does not run under Amigados,  but it works very well
under the freely distributable Amiga Qdos emulator - one of the few emulators
that is substantially  FASTER  than the real thing, even on an old Amiga 500!
Psion generously allows  free distribution of Qdos XCHANGE for 68000 systems,
so it can be bundled with the emulator (currently at version 3.23 - beware of
older ones which are buggy and not AGA compatible). Make sure you get the set
of three disks (or archives); one is the Amiga startup disk, one contains the
full source code, and the third is a Qdos disk holding XCHANGE and utilities.


CREDITS

The original program  was written and tested in  QL SuperBASIC (on his Amiga)
by Mark J Swift.  Version 1.014 is derived from Qdos version 1.01,  converted
to run under Amigados and extended  by Simon N Goodwin.  The inner details of
the  file formats were worked out by Chas Dillon, who also contributed the PC
ASCII to ANSI conversion table.  Testing by Mark J Swift and Simon N Goodwin.


EXTENSIONS

This version has been extended to support the PC version of Quill (sold as PC
FOUR and PC XCHANGE) as well as the original QL/Thor/OPD versions. It detects
the difference between the two types of _DOC file automatically. The PC files
support italics as well as underlining, bold, superscripts and subscripts. In
other respects DOC files are handled identically, although there are internal
differences (for instance, PC files lack some Qdos screen colour options, and
store internal numbers the other way round - in little rather than big endian
order). Examine the HiSoft BASIC source if the differences interest you.

The program also converts character codes from Qdos ASCII or Msdos ASCII into
ANSI, which suits the Amiga and PC clones running Windoze.  This is necessary
because the codes for  accented and other  special characters  differ between
systems.  If characters cannot be translated  (for instance, the  Qdos  arrow
characters, codes 188 to 191,  which do not appear in the ANSI set,  they are
replaced with a question mark.

The QL ASCII characters that cannot be translated to ANSI are: oe/OE ellipsis
QL codes 139, 171), the greek letters  Alpha, Theta, Lambda, Pi and Phi (172,
174, 175, 177, 178),  Backward S (181)  and the arrows  (188, 189, 190, 191).

The MSDOS ASCII translation is not as complete,  but does include the accents
used in French, Spanish and German, and the Beta character (German double S).


Simon N Goodwin, simon@studio.woden.com, May 20th 1996.