% LaTeX source for PSPRINT System Guide.
% Cross references are indicated by the string "XREF".

\documentstyle[11pt]{article}

\nofiles                       % no auxiliary output

% make sure leading/trailing spaces work correctly in \verb
{\obeyspaces\gdef {\leavevmode\null\enskip\null}}

% 1 inch margins at left and right:
\oddsidemargin=0in
\evensidemargin=0in
\textwidth=6.25truein          % A4 paper is 8.25in wide

% 1 inch margins at top and bottom:
\headheight=0pt
\headsep=0pt
\topmargin=0in
\textheight=9.7in              % A4 paper is 11.7in high

\parindent=0pt
\parskip=\medskipamount
\itemsep=0pt

\def\DVItoVDU{DVIto\kern-.15em VDU}
\def\Modula{\hbox{Modula-2}}
\def\aligneddots{\leaders\hbox to .75em{\hss.\hss}\hfill}

\begin{document}

\vspace*{\fill}

\begin{center}
\Huge\bf PSPRINT System Guide\\ [3mm]
\normalsize\bf Version 3.1 for VAX/VMS\\
\bf Andrew Trevorrow, October 1989
\end{center}

\bigskip
\bigskip

This document explains how to install or modify PSPRINT, a PostScript
driver that runs under VAX/VMS\@.
Currently supported printers include the Apple LaserWriter,
the Linotronic~300 and DEC's PrintServer~40.
The PSPRINT command can be used to print a DVI file, a PostScript program,
or an ordinary text file.
The {\sl PSPRINT User Guide\/} has details on how to use the program.

\bigskip
\begin{center}
\bf Contents
\end{center}

                                     % XREF: make sure page #s are up-to-date
Overview               \aligneddots\ 1\\
Installing PSPRINT     \aligneddots\ 2\\
Testing PSPRINT        \aligneddots\ 3\\
Adding a New Device    \aligneddots\ 4\\
Existing Problems      \aligneddots\ 5\\
Changes to Version 1.1 \aligneddots\ 6\\
Changes to Version 2.0 \aligneddots\ 7\\
Changes to Version 3.0 \aligneddots\ 8

\vspace*{\fill}

\thispagestyle{empty}

\newpage
\setcounter{page}{1}

\subsection*{Overview}

PSPRINT is a mixture of \Modula, DCL and PostScript.  All the necessary
files, including documentation and source code, are kept in a directory
referred to by the logical name \verb|tex_ps|.  The file \verb|aaaread.me|
gives a brief description of each file.

The following sequence of events occurs when a user runs PSPRINT:
\begin{enumerate}
\item
\verb|psprint.exe| is invoked.  This \Modula\ program extracts the
file parameter and qualifier values from the command line according
to \verb|psprint.cld|.
If everything seems okay then a device-specific command file is activated:
   \begin{itemize}
   \item [ ]
   \verb|tex_ps:lw_print.com  | --- if \verb|/device=LW|\\
   \verb|tex_ps:lino_print.com| --- if \verb|/device=LINO|\\
   \verb|tex_ps:ps40_print.com| --- if \verb|/device=PS40|
   \end{itemize}
The CLD file specifies the allowed \verb|/device| values and the default
value (currently \verb|LW| for LaserWriter).

\item
These command files handle most of the messy system-dependent details.
Each can process one of five file types:
a DVI file, a PostScript program, or one of three text file types.
(A DVI file is translated into a temporary PostScript file by
PSDVI, another \Modula\ program.
Each command file uses a different set of qualifiers to specify the
printer's resolution, the location and format of bitmapped fonts,
the order in which to translate pages, etc.)

\item
Each type of file is bracketed by device-specific header and trailer
information before being sent to an appropriate print queue.
\end{enumerate}
Note that much of the behaviour of PSPRINT can be changed by simply
editing command files and/or PostScript text files.
Such flexibility is of particular benefit to sites without \Modula.
You'll probably need the {\sl PostScript Language Reference Manual\/} by
Adobe if you run into problems or wish to make substantial changes.

\newpage

\subsection*{Installing PSPRINT}

Let's assume you've dumped all the necessary files into a suitable directory.
Attach yourself to this directory and carry out the following steps:
\begin{enumerate}
\item
Check \verb|psprint.cld| and \verb|psdvi.cld| for any site-dependent changes.
Also check the \hbox{PSDVI} qualifiers in each of the \verb|*_print.com| files.

\item
Examine the file \verb|install.com| and make the necessary changes to suit
your site.  Running this command file will perform the following steps:
\begin{itemize}
   \item
   Set terminal characteristics for a LaserWriter or Linotronic.
   These printers are assumed to be connected to your VAX via a serial line.
   The LaserWriter should have its mode switch set to 9600 baud.
   The PrintServer~40 should be set up as described in the DEC documentation.
   \item
   Define the PostScript form type (used by LaserWriter and Linotronic).
   \item
   Initialize the print queue(s).
   \item
   Define \verb|tex_ps| to be a system logical name pointing to
   the public-access directory.
   \item
   Install the PSPRINT and PSDVI commands.
\end{itemize}
Some of the above steps must be copied into appropriate
system files if you want PSPRINT to work the next time you reboot.

\item
Start the appropriate print queue(s).
Note that print jobs will disappear if the LaserWriter
is switched off or its mode switch is incorrectly set.
Similar warnings apply to the Linotronic~300.
Both these devices use the standard VAX/VMS print symbiont.
The symbiont for the PrintServer~40 is much more intelligent;
it is able to interpret PostScript messages and can even send them
back to the user's terminal (if \verb|/notify| is specified).

\item
Each PostScript printer has a system password that allows you to change
persistent parameters.
In an open-access environment it's probably a good idea to
change the initial password.
Make the appropriate changes to \verb|pass.ps| and then send it to the printer
by typing `\verb|psprint pass.ps|' (with an appropriate \verb|/device| value).
Then delete all reference to the new password!
Note that the PrintServer~40 uses a string for the password;
the other devices use an integer.

\item
\verb|psprint.hlp| is provided as a suitable source for on-line help.
Feel free to make any changes to suit your site.
Changes may also be needed in \verb|userguide.tex|; the likely locations
are flagged by a ``\verb|SYSDEP|'' comment.

\item
Check the installation by logging out, then logging in as a normal user
and trying PSPRINT on various DVI/PostScript/text files.

\end{enumerate}

\newpage

\subsection*{Testing PSPRINT}

There are a number of useful files in \verb|tex_ps| for testing PSPRINT:

\begin{itemize}

\item
Type `\verb|psprint test|'.
The top left corner of the first rule should appear
1~inch in from the top and left paper edges.
If not, then you'll need to modify \verb|tex.ps|.
You should only need to carry out such changes for a LaserWriter.
The last two integers of the \verb|setmatrix| array are pixel values that
adjust the horizontal and vertical position of the origin.
Also type `\verb|psprint test/land|' to test the positioning
of landscaped output.
(Note that the \verb|/hoffset| and \verb|/voffset| qualifiers allow
users to shift the output as well.)

\item
Type `\verb|psprint lines.dat|' and `\verb|psprint lines.dat/land|'
to check the output format of ordinary text files.

\item
Type `\verb|psprint clip.ps|' to produce some lines indicating
the default clipping region; nothing can be printed outside this region.

\item
Type `\verb|psprint psfonts|' to test the use of resident PostScript fonts
in a \TeX\ document (assuming you have the necessary TFM files).
The fonts used in this test should be available in all PostScript printers.

\item
The file \verb|nasty.dvi| is also useful for testing rarely used code
in PSDVI\@.  Try some of these pages:
   \begin{itemize}
   \item [ ]
   \verb|psprint nasty/page=1 | --- empty page\\
   \verb|psprint nasty/page=3 | --- page with \verb|\special| commands\\
   \verb|psprint nasty/page=10| --- tests long verbatim \verb|\tt| strings\\
   \verb|psprint nasty/page=18| --- tests rules in math extension characters
   \end{itemize}

\end{itemize}

\newpage

\subsection*{Adding a New Device}

Here are the steps required to support a new type of PostScript printer:
\begin{enumerate}

\item
Create a new \verb|/device| value by adding a \verb|psprinter| keyword,
say \verb|XXX|, at the bottom of \verb|psprint.cld|.

\item
Modify \verb|psprint.mod| to handle the new device value.
Locate all occurrences of an existing device, say \verb|LW|, and duplicate
the code.  Type `\verb|@build|' to create a new version of PSPRINT\@.
This assumes you have a Modula-2 compiler; if you don't then you could
quite easily translate \verb|psprint.mod| into Pascal.
It is a reasonably small and simple program.
Note that no changes to PSDVI are needed.

\item
Create \verb|xxx_print.com| using one of the existing \verb|*_print.com|
files as a starting point.  This new command file will be activated when
a user types `\verb|psprint/dev=xxx ...|'.

\item
Create \verb|xxx_header.ps|, \verb|xxx_trailer.ps| and \verb|xxx_fonts.ps|
as required.  Again, base these new files on the nearest equivalents for
an existing device.

\item
Make any necessary changes to the job prologues:
\verb|tex.ps|, \verb|ps.ps|, \verb|text.ps|, \verb|two.ps| and \verb|wide.ps|.
Search these files for occurrences of \verb|dev|, \verb|res| and \verb|land|
and add any code needed for the new device.
Note that \verb|xxx_print.com| must make sure the definitions for these
PostScript variables come {\em before\/} the prologue file.

\item
Connect the new printer to the VAX host and create a suitable queue.
See \verb|install.com| for details.

\item
Type `\verb|set command psprint|' and
test the new version of PSPRINT on a variety of files.
% XREF
The previous section describes some useful tests.

\item
Finally, update the user documentation in \verb|userguide.tex|
and \verb|psprint.hlp|.
If you plan to pass on your changes to other people
it would be polite to update the system documentation as well
(in \verb|sysguide.tex| and \verb|aaaread.me|).

\end{enumerate}

\newpage

\subsection*{Existing Problems}

\begin{itemize}

\item
PSPRINT is {\em not\/} a print symbiont.
It cannot, for example, report any LaserWriter problems to an operator.
Jobs will just disappear if the LaserWriter is turned off or
its mode switch is on some setting other than 9600.
The print queue should be started {\em after\/} turning on the LaserWriter
and stopped {\em before\/} turning it off.

\item
Some DVI jobs may exceed PostScript's virtual memory, depending on the
number and size of downloaded characters, and the amount of VM available.
For reasons unknown, early versions of the LaserWriter can crash
(and then restart by printing a test page) rather than show a ``VMerror''
message.  No banner page is printed.
The ``\verb|VMERROR|'' code in \verb|tex.ps|
attempts to overcome this problem by producing an error message if the
VM usage reaches some threshold value.
Enable this code if your LaserWriter suffers from such a problem.

\item
PSPRINT cannot handle FORTRAN carriage-control files nor RUNOFF output.

\item
PostScript printers can get occasional one-pixel rounding errors when
drawing rules.
The problem can sometimes be visible in a \TeX\ document, usually in large
math extension characters containing one or more rules.
The use of device-specific \verb|setmatrix| code in
\verb|tex.ps| minimizes these errors.
Some ``fine-tuning'' of the PostScript rule-drawing code may also be necessary.
For example, in some versions of the LaserWriter I've had to
add 1 to the vertical position of each rule.
Page 18 of \verb|nasty.dvi| is a good test sheet; try printing it
in both portrait and landscape orientation.

\item
To be able to use PostScript fonts with \TeX\ you must have the necessary
TFM files.  PSDVI requires that their names all begin with the
\verb|/psprefix| value.  The default prefix of ``\verb|ps-|''
is set in \verb|psdvi.cld|.  If you decide to use some other prefix then
you'll need to edit \verb|*_fonts.ps| and update the user documentation.

\item
When using a PostScript text font, users need to be aware that
the standard \TeX\ commands for accents and foreign letters must be redefined
(and reinstated when switching back to a Computer Modern text font).
See \verb|psfonts.tex| and \verb|pstext.tex| for one possible solution.

\item
If you are using any CM fonts with 256 characters then
you'll have to change a few numbers appearing in the definition of
\verb|@newfont| in \verb|tex.ps|.
Change the two occurrences of 128 to 256 and the single 127 to 255.
A warning: jobs that used to print okay may now exceed VM.

\item
The \verb|\special| facility provided by PSDVI (i.e., file inclusion with
optional starting text) is quite primitive compared
with other DVI-to-PostScript translators.
The reason is that all \verb|\special| commands on a page are gathered
together and sent all at once, as are all the fonts and rules.
A significant advantage of this method is printing speed: by minimizing the
number of font switches we keep character images in the font cache for as
long as possible.

\end{itemize}

\newpage

\subsection*{Changes to Version 1.1}

\begin{itemize}

\item
These changes were made while I was working in the UK at The Open University.
The current version of PSPRINT (and PSDVI) has leapt to 2.0 to coincide
with the latest version of \DVItoVDU.

\item
PSPRINT now supports a variety of PostScript printers.
The new \verb|/device| qualifier indicates which type of printer to use;
a default device is specified in \verb|psprint.cld|.
A separate command file exists for each device: see \verb|*_print.com|.
Each device also requires slightly different PostScript code
for each type of input file.
The introduction of different devices has meant a major file-renaming exercise.

\item
PSPRINT has a number of new qualifiers --- \verb|/size|, \verb|/lowres| and
\verb|/cutmarks| --- that only take effect if \verb|/device=LINO|.
See the {\sl PSPRINT User Guide\/} for details.

\item
Temporary files are now created in \verb|sys$scratch|.
This can easily be changed by editing the \verb|*_print.com| files.

\item
PSDVI can now handle resident PostScript fonts.
Such fonts must have TFM file names beginning with ``\verb|ps-|''.
The new \verb|/tfm_directory| qualifier specifies the default location of
these TFM files.  For each \verb|/device| value there exists a
\verb|*_fonts.ps| file that maps the TFM names into the PostScript font names
used in that type of printer.
(Each PostScript printer has a different set of resident fonts.)

\item
PSDVI has a new \verb|/conserve_vm| qualifier.  This can be used to conserve
PostScript's virtual memory at the expense of downloading character bitmaps
more often (resulting in a larger output file).
PSPRINT makes \verb|/conserve_vm| the default for the Linotronic~300
and \verb|/noconserve_vm| the default for the LaserWriter and PrintServer~40.

\item
PSDVI now creates an ordinary text file.  Although slightly less efficient
than creating a fixed-length-record file, the advantages of being able
to easily edit/view/transmit a text file were considered more important.

\end{itemize}

\newpage

\subsection*{Changes to Version 2.0}

\begin{itemize}

\item
These changes were made while I was working at Aston University.
The current version of PSPRINT (and PSDVI) is now 3.0.

\item
Added a number of new qualifiers to PSPRINT:
\verb|/queue| allows users at sites with more than one printer of the
same type to override the default queue;
\verb|/output| copies the PostScript code generated by PSPRINT into a
given file rather than sending it to a printer;
\verb|/two| and \verb|/wide| are variants of \verb|/text| that print
two ``pages'' (60 lines by 80/132 columns) on each sheet of paper;
\verb|/nobanner| and \verb|/manualfeed| have been implemented for
the LaserWriter;
\verb|/reverse| and \verb|/noreverse| override the device-specific
order in which pages are printed;
\verb|/resolution|,
\verb|/font_directory|,
\verb|/dummy_font|,
\verb|/tfm_directory|,
\verb|/psprefix|,
\verb|/xsize| and \verb|/ysize|
can be used to override the device-specific default values used by PSDVI
(although most users should never need to use them).

\item
Added \verb|/psprefix| qualifier to PSDVI so that sites can specify the
TFM file name prefix used to indicate PostScript fonts.
(The default prefix is ``\verb|ps-|''.  If you decide to change this then
you'll need to change the various \verb|*_fonts.ps| files; it's also
mentioned in the user documentation.)

\item
Added \verb|/increment| qualifier to PSDVI and PSPRINT to simplify the
printing of documents on both sides of the paper;
see the {\sl User Guide\/} for details.

\item
Added \verb|/hoffset| and \verb|/voffset| qualifiers to PSDVI and PSPRINT
to allow shifting of each page.  This should be useful for sites with many
printers of the same type, each with different margin settings.

\item
Reduced both the size and execution time of the PostScript code generated
by PSDVI when setting resident PostScript fonts.

\item
Modified the \verb|BuildFontSpec| routine in PSDVI's \verb|FontReader| module
to remove the limitation requiring all font files to contain a size substring
of the same length.  Sites that had to include a leading zero
in some font names to overcome this limitation must now
rename them (e.g., \verb|$rename *.0635pk *.635pk|).

\item
PSDVI's \verb|Terminal| module is now called \verb|TermOut| and no longer
calls \verb|SYS$ASSIGN| to assign \verb|TT|.
This change allows terminal output to be captured in a file ---
very important when PSPRINT is used in a batch job!
A side-effect is that page numbers now appear on separate lines.

\item
There is now a single prologue file for each type of job:
\verb|tex.ps|, \verb|ps.ps|, \verb|text.ps|, \verb|two.ps| and \verb|wide.ps|.
They rely on a few PostScript definitions created in \verb|*_print.com| to
handle different devices, landscaping, etc.

\item
The \verb|*_print.com| files now put a single temporary file in the print
queue.  This simplifies the code required in \verb|text.ps| and
overcomes problems caused by print symbionts adding unwanted characters
(such as formfeeds/linefeeds) between files in a multi-file print job.
A side-effect of this change is that the format characters in a
FORTRAN carriage-control file are no longer obeyed
(they will now be printed!).

\item
The CTRL-D sent at the start of each \verb|LW|/\verb|LINO| print job has
been removed to avoid problems (involving the echoing of such characters)
when a PostScript printer is connected to an X.25 pad.

\end{itemize}

\newpage

\subsection*{Changes to Version 3.0}

\begin{itemize}

\item
These changes were made while I was working at Aston University
(for a second time).
The current version of PSPRINT (and PSDVI) is now 3.1.

\item
Any \verb|\special|s on a page are now processed in the order they
appear in the DVI file (instead of in reverse order).

\item
Fixed bug in \verb|FixToDVI| routine in \verb|FontReader.MOD| that
prevented fonts being scaled to more than 128pt.
Thanks to Niel Kempson for spotting this.

\item
Added code to \verb|PSWriter.MOD| to make sure that very long PostScript
strings are correctly broken over multiple lines.
This problem was spotted by Adrian Clark when using halftone fonts.

\item
Added support for Macintosh-generated PostScript files created
by pressing Command-F after clicking OK in the Print dialogue.
A new \verb|/prep=file| qualifier allows users to include a
modified Laser Prep file at the end of the normal prologue.
This is necessary when printing a DVI file that uses \verb|\special| to include
a Command-F PostScript file.
If only \verb|/prep| is given then a default file (specified in
\verb|psprint.cld|) is included.  The current default is
\verb|tex_ps:laserprep70.ps| but other versions are provided in \verb|tex_ps|.
These files contain comments describing how they were created.

\item
Allow \verb|/nobanner| on a Linotronic job.

\item
\verb|*_print.com| no longer append CTRL-D if \verb|/output| is used.

\item
Fixed \verb|*_print.com| so that CTRL-Y won't clobber a user's symbols.

\item
For a DVI job, if a file called \verb|global.ps| exists in the user's
current directory then its contents will be included after the prologue.
The example \verb|global.ps| file in \verb|tex_ps|
shows how to get the word ``DRAFT'' printed in the background on every page.

\item
Added \verb|psnames.tex| and illustrated its use in \verb|psfonts.tex|.
This might be a useful approach for people with access to more
than one set of PostScript TFM files.

\item
\verb|/noreverse| is now the default for all devices.
The default setting for this qualifier (and for \verb|/conserve_vm|)
is now specified in \verb|*_print.com| rather than in \verb|psprint.mod|.

\end{itemize}

\end{document}