This is PrinterPS, version 2.44 (23-Jul-90)

Introduction
============

Documentation on how to use PrinterPS can be found in Edition 2 of the
Archimedes User Guide, but this version has significant enhancements, so
please read the notes below.

The way in which a file is printed depends upon its type:

    File type:         Printed as:
 ---------------------------------
 Command  (&FFE)     "plain" text - as under original printer drivers
 Obey     (&FEB)     "plain" text - as under original printer drivers
 Text     (&FFF)     "fancy" text - line numbering, titling, highlights etc.
 PoScript (&FF5)     all bytes sent straight to the printer

For anything else, the application checks if other applications know how to
print the file. If this fails it checks with the user whether to print the
file, giving him the choice of printing it as "plain" text, "fancy" text, or
not at all. This is so that 1st Word Plus files can be printed as "fancy"
text. The "fancy" text file format is mainly the same as the 1st Word Plus
file format, and so most of the highlighting is printed correctly by release
2 of the printer drivers. This means you don't have to load 1st Word Plus to
print out your 1st Word Plus files (although there are some restrictions,
described below, including headers, footers and graphics). Note that if you
have already 'seen' 1st Word Plus then it will automatically be loaded when
you try to print.

You can override the application's treatment of a particular type file by
setting system variables of the form Alias$@PrintType_xxx, where xxx is the
appropriate type. If the variable exists, then the application performs
*@PrintType_xxx <filename> before doing anything else. It then checks for
the existence of <Printer$Temp>. If this exists then it is printed (using
plain, fancy or literal printing, depending upon the type of this file). You
can therefore print via a print utility program by using:

    *Set Alias$@PrintType_xxx *PrintUtil %0 -to <Printer$Temp>

Try looking at the !Boot files of !Draw and !Paint for some examples of
this.

Using the printer drivers
=========================

Select
======

Clicking SELECT on the icon produces a window with data about the current
printer driver settings.

Printer:
-------
Clicking on the name field steps through the printers and dump modes
enumerated in the file "PrData" (see below).

Paper feed:
----------
The "manual feed" option causes the printer to take paper from its manual
paper tray.  The "auto feed" option uses the normal internal paper tray.  In
the case of printers which do not have different trays, these options are
not presented.

Title:
-----
Puts file name, time and page number at top of each "fancy" text page.

Number lines:
------------
Prints the number of each line in "fancy" text files.

Scale factor:
------------
The standard sizes of pica, elite, condensed and expanded text are 10, 12,
16 and 6 cpi (characters per inch). PostScript printers have a wide range of
available sizes, however, so you can scale the text from these standard
sizes to suit your taste. The first release of !PrinterPS used 100% for
portrait printing and 70% for landscape printing. 100% gives these standard
sizes, 200% uses twice the size, and 50% gives half the size (i.e. twice as
many characters per inch). The scale factor is in the range 20% to 999%, but
remember that !PrinterPS needs at least 10 characters on a line, so more
than 700% will give an error if used with portrait.

Columns:
-------
Specifies the number of columns of text (plain or fancy) to be printed on
each sheet of paper.  PrinterPS remembers 2 chosen values - one for portrait
and one for landscape printing.

Orientation:
-----------
Allows choice of portrait or landscape orientation when printing "plain" or
"fancy" text.

Control codes:
-------------
This alters the way in which control characters in "fancy" text files are
handled.  For most purposes, it should be set to "standard".  The "display"
option causes all control characters (other than end-of-line characters) and
top-bit-set characters to be expanded to a printable hex representation,
e.g. "[7f]" for the DELETE character.  If "ignore" is chosen, all control
characters (except end-of-line characters) and top-bit-set characters are
ignored, and only the normal printable characters are sent to the printer.

Menu
====

Clicking MENU on the icon produces a menu which allows the print destination
to be set, and the paper size to be altered.

Graphics page size information:
------------------------------
Page size and margins supplied here must reflect the actual printable area
of the page, and cannot be used to alter the format of text printed as a
result of dragging text files onto the printer icon.  The paper limits are
used to ensure correct positioning of graphics on the page, and are also
reported back to applications such as Draw for information purposes. The
values given refer to portrait-orientation paper - the corresponding values
for landscape printing are deduced from these.

Text page size information:
--------------------------
These margins apply to "fancy" and "plain" text printing.  They are measured
relative to the printable area of the page (as defined by the graphics page
size information), not relative to the total size of the paper.  The left
and right margins (measured in characters) and the top and bottom margins
(measured in lines) may be changed.  From these values, PrinterPS determines
the total number of characters-per-line and lines-per-page that may be
printed: this will be different in landscape and portrait orientations.  A
1stWord+ page-layout format line at the start of a document can override the
menu margin and deduced page size settings, provided the page length and
width specified in the file are not greater than the menu values.

NFS printing:
------------
There is a new option on the printer drivers in additions to Serial,
Parallel, Econet and File. This is for NFS printing, for use with the TCP/IP
suite available from Acorn. For more details about the options read your
TCP/IP manual.

Additional notes
================

Multiple file printing:
----------------------
If a file is dragged from a directory viewer on to the printer icon while
the printer is printing or paused, then the file is added to the end of a
queue of files.  When the current print finishes, the printer driver always
looks in its queue, and if it isn't empty starts printing the first entry.
If a selection of files are dragged together on to the printer, then they
are all placed in the queue.

The queue stores names only, and if the queue is full when a file is dropped
on to the printer then this file is rejected with a "Printer queue full"
error message.  When a file name is retrieved from the queue for printing,
the printer driver checks it for readability.  If the file cannot be found,
or cannot be read, then it is discarded from the queue with an error
message.

Files cannot be dragged out of application windows on to the printer while
it is printing.  Any attempt to do so will produce an "Already printing"
error message.  This is because such files would have to be physically
copied rather than remembered by name.

To print all or some of the files in a directory, the directory must be
opened, and a selection of files chosen and dragged on to the printer. It is
not possible to print the contents of a directory by dragging the directory
icon to the printer.

Clicking on the "Stop printing" main menu item while printing aborts
printing completely, i.e. it gives-up printing the current file and flushes
the file queue.  Clicking "No" on the page-prompt window has the same
effect.  Slightly more subtle control is available from the "Stop printing"
sub-menu:

     Stop printing => Abandon all
                      Cancel current
                      Cancel others

Clicking "Abandon all" is the same as clicking "Stop printing".  Clicking
"Cancel current" skips to the end of the current document, tidies-up, and
starts printing of the next queued file (or stops printing if the queue is
empty).  Clicking "Cancel others" allows printing of the current document to
continue, but flushes the rest of the file queue (this option is greyed-out
if the queue is empty).

"Stop printing" and "Abandon all" should be used if your printer gets jammed
up, if, say, the ribbon breaks or the paper gets scrunged. This can leave
the printer in an odd state, so beware! The other two options are for more
delicate handling controls, and they can only leave the printer in a
sensible state.

Fancy text:
----------
The standard control sequences recognised in "fancy" text files are a subset
of those used by 1stWord+.  For instance, Pica/Elite/condensed/expanded,
italics, underline, formfeed, etc.  It is not intended that this feature be
used to print faithfully all possible features that may be included in a
file produced by 1stWord+ (use 1stWord+ to print these!), but rather that
simple features may be included in text files and printed without having to
load a word-processing application.

Plain text:
----------
Control characters (other than end-of-line) in files printed as "plain" text
are sent literally to the printer. To print a PostScript file absolutely
literally, set its type to "PoScript".

'Fancy text' file format:
-------------------------
The 'fancy' text file format is fairly simple. It consists of plain text,
with added special sequences:

Character sequence     Meaning                     Action
      <8>           Backspace character      Backspace if possible
      <9>           Tab character            Tabulate to next 8th column
     <10>           Linefeed character       Possible end-of-line
                                              (depends on options)
     <11><x>        Conditional pagebreak    Page break if less than x-16
                                              lines left on page, else a new
                                              line.
     <12>           Unconditional pagebreak  Go to a new page (i.e. a page
                                              break)
     <13>           Return character         Possible end-of-line
                                              (depends on options)
 <24><x><y>,<n>     Footnote reference       Reference to footnote <n>, so
                                              print <n>.
     <25>           Soft hyphen              Print a hyphen
     <27>           Escape character         Start escape sequence
 <28>,<29> or <30>  Soft space               Discard if precedes a <10>,
                                              <11>, <12> or <13>, else print
                                              a space
     <31>           Format character         Start format sequence
                                              (reserved for Acorn use)
     <127>          Delete character         Ignored

Escape sequence       Meaning
 <27><%11000000>  Start literal escape sequence
 <27><%10fedcba>  If 'a' is 1 then toggle bold style (on=>off, off=>on)
                  If 'b' is 1 then toggle light style (on=>off, off=>on)
                  If 'c' is 1 then toggle italic style (on=>off, off=>on)
                  If 'd' is 1 then toggle underline (on=>off, off=>on)
                  If 'e' is 1 then toggle superscript (on=>off,off=>on)
                  If 'f' is 1 then toggle subscript (on=>off, off=>on)
  <27><other>     Ignored

A literal escape sequence is a sequence of characters which are sent
directly to the printer - and hence are printer specific. The sequence is
ended by a <27><0>. A "||" pair sends a "|" character, a "|?" pair sends a
<127>, and any other "|<x>" sequence sends <x AND 31>. Thus to send an
escape character use "|[".

The file format is almost a subset of the 1st Word Plus file format, the
basic omissions being headers and footers, and an incomplete implementation
of footnotes.

The "PrData" file:
-----------------
This file contains printer configuration information.  It is read when the
application starts, and updated by the "Save choices" menu item. Included in
the file are the printer-specific control sequences used to print "fancy"
text features.  "PrData" is a compressed file containing no comments.  A
commented version is provided as "PrDataSrc", and there is a compression
utility, "PrSquasher".  The printer driver can read uncompressed commented
PrData files, but they cause it to start-up more slowly.  To produce your
own PrData files for different printers, edit a copy of "PrDataSrc", check
it for mistakes (!!), then use "PrSquasher" from the command-line to make a
new "PrData" from it.  If you increase the number of entries in "PrData",
you may also need to increase the "Wimpslot" size in "!Run". To run
PrSquasher you should open the printer application directory (using
shift-SELECT), and double-click on the BASIC program PrSquasher. You must
then type in the absolute path-names of the input (unsquashed PrDataSrc) and
output (squashed PrData) files.

The PrData file supplied with the printer driver provides settings for an
Apple LaserWriter and for a generic colour PostScript printer. The former is
totally accurate for an Apple LaserWriter, but can also be used as a generic
monochrome PostScript printer. The PrData file can be edited to add to the
set of printers if desired.  If you increase the number of entries in the
"PrData" file, you may also need to increase the "Wimpslot" size in "!Run".

Serial output:
-------------
If the output is to the serial line and XON/XOFF protocols are being used
then a small module, SerialRxIgnore, is loaded and used to discard incoming
characters (except XON/XOFF control characters).

The printer driver module:
-------------------------
The following remarks should be noted about this version of the printer
driver module and its documentation.

For each RISC OS font used, the printer driver needs to be told which
PostScript font to use in its place and the character encoding to be used
for it. Near the end of the file !PrinterPS.PSprolog is a list of the font
translations used. This can be added to or modified by the user as desired -
usually, you should add a suitable translation for each new font you
acquire. It is a good idea to ensure that the PostScript font you use has
similar metrics to the RISC OS font: the PostScript code used for text
printing will compensate automatically for differences between the metrics
of the two fonts, but the results are likely to be ugly if these differences
are too large.

The file !PrinterPS.PSprolog also contains two PostScript encoding vectors
(which say what actual character corresponds to each character code). One
has been chosen to conform with the ISO 8859-1 Latin 1 alphabet as far as
possible, though there are some ambiguities (e.g. character code &2D is
defined in the ISO standard to be hyphen or minus, which are usually two
different characters in PostScript fonts). The other is a special character
encoding for the Selwyn font. Both encoding vectors can be edited if
necessary - but make sure you know what you are doing.

Not all PostScript fonts contain all the characters in the encoding vectors.
The PostScript code in !PrinterPS.PSprolog is set up to ignore any character
that you try to print if it doesn't appear in the PostScript font being
used. If you would prefer a PostScript error to be generated instead, there
is a commented single line change you can make to !PrinterPS.PSprolog to
achieve this effect.

Printing RISC OS sprites to PostScript is a rather complicated business and
always generates quite a lot of PostScript output. It may also take quite a
long time to print. Under some circumstances (particularly if there are a
lot of colours in the sprite and/or if the sprite is to occupy a large
amount of space on the printed page), the time taken by the printer and/or
the application to print the sprite may become quite large (of the order of
several minutes or even more). Do not worry unduly about this.
