                          OPL FORMATTING UTILITY
                          ----------------------

                        Written by: John W Dawson.

                           V1.0, December 1994.

Introduction
------------

This utility formats OPL source code for printing in a more useful and 
readable format. It generates an RTF file which can be imported into a 
compatible word processor (e.g. Microsoft Word) and then printed without 
further manipulation.

Special features of the layout are:

  * Code is printed in multiple columns, allowing more to be squeezed
    onto each page.

  * Procedure headings stand out by being printed in a distinct style.

  * Page headers show filename and date.

The utility has been written for the Psion Series 3A, but it should be 
possible to adapt it for the Series 3 (see below).

Customising
-----------

The utility is distributed as source code, allowing you to customise the 
layout to suit your preferences and the capabilities of your printer. 
There are a number of variables defined to control the formatting, which 
are initialised at the beginning of the code. The initialisation values 
can be changed to create the required effects.

The following characteristics can be controlled. Values in brackets are 
the defaults already set up in the code, which I use myself. These work 
well with Microsoft Word V4.0 on the Macintosh and an Apple Laserwriter:

Paper Width/Height (A4);

Left/Right/Top/Bottom Margins (0.5"/0.5"/0.75"/0.75");

Number of columns (2);

Spacing between columns (0.125");

Tab Spacing (0.125");

Indentation for continuation of long lines which are wrapped (0.0625");

Font for procedure headings (9 point Helvetica bold);

Font for rest of code (9 point Courier);

Space before/after procedure headings (9 point/9 point).

DEST$ should be set to the pathname for the default directory or folder 
where you want the RTF file to be written (normally on the remote PC).

PCTYPE$ should be set to the type of PC you are using: IBM (pca) or 
Apple Macintosh (mac). This is only significant when printing non-ASCII 
characters. If an RTF file indicates that it was written on a machine 
with a different character set to the reader, then the reader will 
attempt to translate characters into its own character set.

Unfortunately the RTF translator for Word V4.0 on the Mac does not 
appear to translate correctly the IBM character set used by the Psion. 
Therefore I have adopted a different strategy for transferring RTF files 
from Psion to Mac. This involves using Mclink to do the translation, and 
then fooling Word into thinking the file originated on the Mac, so that 
it will not attempt further translation.

When you have customised the source you should then translate it to 
produce FRMATOPL.OPA. This can then be installed on the System screen in 
the normal way.

Using the Utility
-----------------

Connect the Psion to your PC, run Mclink, and establish the serial 
connection in the normal way. Then run the Utility in the 'usual' way, 
by highlighting one of the .OPL files listed under its icon. A dialog 
box is then displayed, for selection of the destination directory/folder 
on the PC; the default shown will be the value assigned to DEST$.

While formatting and transfer is in progress a bar showing percentage 
completed is displayed.

On completion the .RTF file generated can be opened using the Word 
Processor on the PC. The file should be correctly formatted and ready to 
print.

Adaption for Series 3
---------------------

I believe the only code which is Series 3A specific is in the routines 
which display the 'percentage complete' bar. These are PCINIT%:, 
PCSHOW:, PCEND:, and FILLBAR:. To produce a Series 3 version these would 
have to be rewritten, or removed all together.

Distribution
------------

This software is distributed as freeware. It can be used and distributed 
freely, provided that no charge is made (other than to cover reasonable 
costs of distribution), and that this note is distributed with it. If 
this code is incorporated into another program then the same conditions 
must apply to that program as a whole.

While I have taken reasonable care in producing this software, I cannot 
be held responsible for any loss or damage resulting from its use. 
However I will be very pleased to receive any comments, queries, or 
problems. I can be contacted on:

Email:     jdawson@cix.compulink.co.uk

           100415.370@compuserve.com

Phone:     +44 1734 666185

Snailmail: 19, St Edward's Rd, Reading, England, RG6 1NL
