% LaTeX source for PSPRINT User Guide.
% System-dependent details are indicated by the string "SYSDEP".
% Cross references are indicated by the string "XREF".
% Feel free to make modifications applicable to your site.

\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
\renewcommand\labelitemii{ }   % don't use en-dash in nested itemize
\itemsep=0pt

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

\begin{document}

\vspace*{\fill}

\begin{center}
\Huge\bf PSPRINT User Guide\\ [3mm]
\normalsize\bf Version 3.0 for Pyramid/OSx\\
\bf Andrew Trevorrow, October 1988
\end{center}

\bigskip
\bigskip

The PSPRINT command drives a variety of PostScript printers
and can be used to print a DVI file (produced by \TeX\ or \LaTeX),
a raw PostScript file, or an ordinary text file.
The currently supported printers include the Apple LaserWriter,
the Linotronic~300 and DEC's PrintServer~40.

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

                                       % XREF: check that page #s are up-to-date
\TeX\ Output                 \aligneddots\ 1\\
PostScript Output            \aligneddots\ 1\\
Text Output                  \aligneddots\ 1\\
Command Options              \aligneddots\ 2\\
Error Messages               \aligneddots\ 5\\
Using PostScript Fonts       \aligneddots\ 6\\
Using PostScript Graphics    \aligneddots\ 7

\vspace*{\fill}

\thispagestyle{empty}

\newpage
\setcounter{page}{1}

\subsection*{\TeX\ Output}

PSPRINT looks for a DVI file by default.  To print \verb|foo.dvi|, simply type:
\begin{center}
\verb|psprint foo|
\end{center}
PSPRINT will translate \verb|foo.dvi| into
a temporary PostScript file called \verb|foo.tmp|.
The DVI and \TeX\ page numbers are displayed as each page is translated.
(The order in which pages are translated depends on the PostScript
device being used.)
If no errors are found, the temporary file is automatically sent to the
appropriate queue where it is printed (and then deleted).

\subsection*{PostScript Output}

PostScript is a complete programming language with a powerful set of operators
for manipulating text and graphics.  A PostScript program is an ordinary text
file.  If you give it a name like \verb|foo.ps| then sending
it to the printer is simple:
\begin{center}
\verb|psprint foo.ps|
\end{center}
If you decide to use some other file extension you'll have to add the
\verb|-ps| option.
The final section in this document   % XREF
describes how to merge a PostScript file with a \TeX\ source file.
People who want to write PostScript programs will need to get the
{\sl PostScript Language Reference Manual\/} and the
{\sl PostScript Language Tutorial and Cookbook}.  Both books are by
Adobe Systems Incorporated and published by Addison-Wesley.

\subsection*{Text Output}

To print a normal text file, just use any file extension except
\verb|.dvi| or \verb|.ps|:
\begin{center}
\verb|psprint foo.lis|~~~or~~~\verb|psprint foo.dat|~~~or~~~\dots
\end{center}
The output is {\em not\/} collated.
By default you get 66 lines per page, and any lines more than 80
characters long are truncated.  The \verb|-l| option will
rotate the paper so that you can have lines up to 132 characters long
(but only 50 lines per page).

Type `\verb|psprint foo.ps -text|' if you want to print a PostScript file
rather than have it interpreted.  You'll also have to use \verb|-text| if you
want to print a text file called \verb|foo| but \verb|foo.dvi| also exists.

The \verb|-two| and \verb|-wide| options are variants of \verb|-text|
that use a smaller font to fit two logical pages on each sheet of
paper.

These text file facilities may not be available on all types of
printers, especially the Linotronic.


\newpage

\subsection*{Command Options}

The PSPRINT command can be followed by a variety of options:
\begin{itemize}
\item \verb|-device printer_type| ---
tells PSPRINT which type of PostScript printer to use.
The currently supported \verb|printer_type| values are:
   \begin{itemize}
   \item
   \verb|lw  | --- for an Apple LaserWriter (the default)\\  % SYSDEP
   \verb|lino| --- for a Linotronic~300\\
   \verb|ps40| --- for DEC's PrintServer~40
   \end{itemize}
\end{itemize}

These options only take effect if \verb|-device lw|:
\begin{itemize}

\item \verb|-noflag| ---
prevents PSPRINT producing a flag page.

\item \verb|-manual| ---
assumes you want to manually feed paper into the LaserWriter.
As soon as the printer sees your job it will wait for you to feed in each
sheet of paper (it will normally wait up to a minute).

\end{itemize}

These options only take effect if \verb|-device lino|:
\begin{itemize}

\item \verb|-lowres| ---
prints a DVI file at low resolution (635 dots per inch).
By default, \TeX\ output on the Linotronic is printed at 1270 dots per inch.
The temporary file created by PSPRINT will typically be very large.
Using \verb|-lowres| reduces both the size of the temporary file
(by roughly three quarters) and the likelihood of memory problems.
The print quality will of course be poorer but you'll
probably need a magnifying glass to see the difference.

\item \verb|-size page_size| ---
sets the Linotronic page size and orientation.
Possible \verb|page_size| values are
\verb|A4P| (the default), \verb|A4L|, \verb|A5P|, \verb|A5L|,
\verb|B5P|, \verb|B5L| and \verb|A3L|.
The \verb|P| stands for portrait and the \verb|L| for landscape.
(Don't confuse the landscape orientation with \verb|-l| which rotates
the output within the page image, regardless of the \verb|-size| value.)
The portrait orientations are less wasteful of paper.

\item \verb|-cutmarks| ---
produces small cut marks at the corners of the page image
on Linotronic output.
\verb|-cutmarks| is the default; use \verb|-nocutmarks| to suppress them.

\end{itemize}

The following five options override PSPRINT's assumptions
about the format of the input file based on the given file specification:
\begin{itemize}
\item \verb|-dvi | --- for a DVI file.
\item \verb|-ps  | --- for a PostScript program.
\item \verb|-text| --- for an ordinary text file.
\item \verb|-two | ---
like \verb|-text| but the output is formatted so that two ``pages''
(both 60 lines by 80 columns) appear on each sheet of paper.
\item \verb|-wide| ---
like \verb|-text| but the output is formatted so that two wide ``pages''
(both 60 lines by 132 columns) appear on each sheet of paper.
\end{itemize}

\newpage

Some options can only be used with a DVI file:
\begin{itemize}

\item \verb|-p first:final| --- selects a subrange of pages for printing.
\verb|first| and \verb|final| can select either DVI page numbers
(positive integers) or \TeX\ page numbers.

A \TeX\ page specification is of the form \verb|[i0.i1...i9]| where
\verb|i0| to \verb|i9| are integers separated by periods and represent the
10 counter values that \TeX\ stores with each DVI page.
Any number of these integers may be absent and trailing periods may be omitted.
An absent integer will match any value in the corresponding counter.
Many DVI pages may match a particular \TeX\ page specification;
if \verb|first| is a \TeX\ page then the {\em lowest\/}
matching DVI page is selected, and if \verb|final| is a \TeX\ page then
the {\em highest\/} matching page is selected.

Assuming \TeX\ generated the 5 DVI pages `\verb|[0] [1] [2.1] [2.2] [3]|',
here are some examples of how you could use \verb|-p|:
   \begin{itemize}
   \item
   \verb|psprint foo -p 2       | --- prints the 2nd DVI page
                                          (\TeX\ page \verb|[1]|)\\
   \verb|psprint foo -p :4      | --- prints the first four pages\\
   \verb|psprint foo -p 4:      | --- prints the last two pages\\
   \verb|psprint foo -p '[2]'   | --- prints \verb|[2.1]| and \verb|[2.2]|\\
   \verb|psprint foo -p 1:'[2]' | --- prints the first four pages\\
   \verb|psprint foo -p '[2.2]':| --- prints the last two pages
   \end{itemize}
Note that \verb|first| and \verb|final| are optional; they default to
the first and last DVI pages respectively.
Omitting `\verb|:final|' entirely sets \verb|final| equal to \verb|first|.
Note also the need for quote marks around a \TeX\ page specification.

\item \verb|-i i| ---
prints pages $f,f+i,f+2i,f+3i,\ldots,f+ni$, where
$f$ is the first DVI page selected (either 1 or the start
of a \verb|-p| subrange) and $f+ni$ is less than or equal to
the final DVI page selected.

The primary use of \verb|-i| is to simplify the printing of a document
on both sides of the paper.  For example, if \verb|foo.dvi| has 8 pages then the
following steps will produce a double-sided document on a LaserWriter:
   \begin{enumerate}
   \item
   \verb|psprint foo -i 2 -noflag     | --- prints DVI pages 7, 5, 3, 1
   \item
   Remove the 4 pages from the output tray and carefully put them back
   into the input cassette so that page 1 remains face up and its
   top edge goes into the printer first.
   (If \verb|foo.dvi| had 7 pages then you would only need to remove the
   top 3 pages from the output tray.)
   \item
   \verb|psprint foo -i 2 -p 2: -norev| --- prints DVI pages 2, 4, 6, 8
   \end{enumerate}
Note that the use of \verb|-reverse| with \verb|-i| has no effect on
{\em which\/} pages are printed; it simply changes the {\em order\/} in
which they are done.

\item \verb|-reverse| or \verb|-noreverse| ---
forces PSPRINT to print pages in descending or ascending order respectively.
By default PSPRINT prints DVI pages in an order determined by the type of
printer you are using.  The Apple LaserWriter stacks output sheets face up,
so PSPRINT normally prints pages in reverse order so that your output will
be automatically collated.  The PrintServer 40 stacks the output face down,
so PSPRINT normally prints pages in ascending order.  The default order
on the Linotronic is largely irrelevant, since this printer produces pages
on a continuous roll of paper (the default used is ascending order).

\item \verb|-m n| ---
overrides the DVI magnification; \verb|n| is a positive integer 1000 times
the desired magnification and should match one of \TeX's \verb|\magstep|
values (see chapter 4 of {\sl The \TeX book\/}).

\item \verb|-s| ---
shows statistics on the rules, fonts, characters and \verb|\special| commands
used on each page.

\item \verb|-conserve| ---
forces PSPRINT to conserve the printer's virtual memory at the
expense of creating a larger output file (character bitmaps will be
downloaded more often).
If \verb|-device lino| then \verb|-conserve| is the default;
if \verb|-device lw| or \verb|ps40| then \verb|-noconserve| is the default.

\item \verb|-u xx| ---
sets the units of dimensions displayed in some PSPRINT messages
(e.g., if the page is off the paper).
\verb|xx| can be one of:
   \begin{itemize}
   \item
   \verb|in| --- for inches (the default)\\   % SYSDEP
   \verb|cm| --- for centimetres (2.54\,cm = 1\,in)\\
   \verb|mm| --- for millimetres (25.4\,mm = 1\,in)\\
   \verb|pt| --- for points (72.27\,pt = 1\,in)\\
   \verb|pc| --- for picas (1\,pc = 12\,pt)\\
   \verb|bp| --- for big points (PostScript's default units; 72\,bp = 1\,in)\\
   \verb|px| --- for pixels (depends on resolution of printer)
   \end{itemize}

\item \verb|-ho dimen| and \verb|-vo dimen| ---
allow you to shift the printed location of each page.
For example, \verb|-ho -0.5in| would
shift each page half an inch to the left.
A \verb|dimen| is any integer or real number, possibly negative, followed
by a two-letter unit (the same as for \verb|-u|).

\end{itemize}

The remaining options apply to all types of input files:
\begin{itemize}

\item \verb|-l| --- specifies landscaped output
\begin{picture}(10,7)
\put(0,0){\framebox(10,7){}}
\end{picture}\,,
instead of the default portrait output
\begin{picture}(7,10)
\put(0,0){\framebox(7,10){}}
\end{picture}\,.
If~a DVI file, PSPRINT will check each page to make sure it fits
within the rotated paper.

\item \verb|-c n| --- specifies up to 100 copies.
Use of this facility is not encouraged.  Note in particular that
copies of a multiple-page document will {\em not\/} be collated.

\item \verb|-n string| --- includes a note on your flag page.

\item \verb|-q string| --- overrides the default queue used by PSPRINT\@.
(Some sites may have more than one printer of the same type).   % SYSDEP

\item \verb|-o file| --- sends the PostScript code generated by PSPRINT
to a file rather than to a printer.  Since some of this code is device-specific
you should only send the file to a PostScript printer of the type that
PSPRINT intended to use.

\end{itemize}

\newpage

\subsection*{Error Messages}

If PSPRINT detects one or more errors while translating a DVI file then
the temporary PostScript file is automatically deleted and nothing
is printed --- not even a flag page.
The sort of errors you are most likely to see include:
\begin{itemize}
\item
\verb|Page off paper (paper is ...| ---
the current page contains material beyond one or more paper edges.
Use \DVItoVDU\ to see where the problem lies.
\item
\verb|Couldn't open font file: ...| ---
your DVI file uses a font at a non-existent size.
Try a different font magnification in your source file.
\item
\verb|Couldn't open \special file: ...| ---
PSPRINT could not locate the given \verb|\special| file.
Check the file's spelling and/or directory location.
\end{itemize}
Error messages apply to the most recently displayed DVI/\TeX\ page.
Any message that does not make sense probably indicates some sort of bug.
Please save a copy of the input file and report the problem to your
local \TeX nician.

If your DVI file uses a large number of fonts or a few very large fonts then
you might get an error page with the message ``\verb|VMerror|''.
This indicates that PostScript's virtual memory has been exhausted,
and the rest of your job will be flushed.
This problem is unlikely to worry most people, particularly on the
PrintServer~40 which has much more VM than the LaserWriter or Linotronic.
If the problem does occur, there are a few things you can try:
\begin{enumerate}
\item
On a LaserWriter or PrintServer, use \verb|-conserve|
or print a few pages at a time.
\item
On a Linotronic, use \verb|-lowres|.
(\verb|-conserve| is the default for this device.)
\end{enumerate}
If you are sending your own PostScript program then an error should
produce some sort of message on the printed output.

\newpage

\subsection*{Using PostScript Fonts}

PSPRINT allows the use of PostScript fonts within a \TeX\ or \LaTeX\ document.
Such fonts can be used at any desired size and no character bitmaps need
to be downloaded since the shape information is resident in the printer.
The necessary typesetting information required by PSPRINT is extracted
from TFM files (\TeX\ Font Metric files).
A TFM file name beginning with ``\verb|ps-|'' is used to indicate a resident
PostScript font.   % SYSDEP; this prefix is set in psprint

Each type of PostScript printer provides a different set of fonts.
To be able to use a particular PostScript font you need to know the
name of its corresponding TFM file and whether it actually exists in
the printer you want to use.  For each PostScript printer currently
supported there exists a file containing just such information:
\begin{itemize}
\item [ ]
\verb|$tex_ps/lw_fonts.ps  | --- converts TFM names into LaserWriter fonts\\
\verb|$tex_ps/lino_fonts.ps| --- converts TFM names into Linotronic~300 fonts\\
\verb|$tex_ps/ps40_fonts.ps| --- converts TFM names into PrintServer~40 fonts
\end{itemize}
PSPRINT also uses these files, so you can be reasonably confident
about the validity of their contents.
To print a list of the PostScript fonts available in your printer you can type
the command `\verb|psprint $tex_ps/fontlist.ps|'.

(The above file names assume that the environment variable \verb|tex_ps|
points to the public directory in which various PSPRINT-related files reside.
To discover what \verb|tex_ps| is at your site, type `\verb|which psprint|'
and examine the first few lines of the indicated file.)

There are some important differences between PostScript fonts and
the Computer Modern fonts normally used with \TeX:
\begin{enumerate}
\item
When asking for a PostScript font it is best to use an `\verb|at| $dimen$'
size specification (e.g., \verb|\font\helv=ps-helv at 13.5pt|) otherwise you
might end up with a default 1pt font!
\item
PostScript fonts usually contain up to 256 characters, with many
empty locations.  Computer Modern fonts can also contain up to 256 characters
but typically use only the first 128 locations (with very few empty).
\item
When a PostScript font is scaled to the same design size as a CM font
it tends to look darker and larger.  You need to be a bit careful
when mixing the two font designs.
\item
The standard \TeX\ commands for accents and foreign letters need to be
redefined for a PostScript text font.  The file \verb|$tex_ps/pstext.tex|
contains the required macro definitions; note that a few commands
(\verb|\j|, \verb|\aa|, \verb|\AA|, \verb|\t|) cannot be used at all.
Another file, \verb|$tex_ps/psfonts.tex|, inputs these macros and illustrates
the use (and abuse) of PostScript fonts in a \TeX\ document.
\end{enumerate}

\newpage

\subsection*{Using PostScript Graphics}

Creating figures and illustrations with \TeX\ is very difficult.
Although it is theoretically possible to place small dots
anywhere on a page and build up an arbitrarily complex picture,
time and memory limitations make such a scheme impractical.
(\LaTeX\ provides a \verb|picture| environment, but it is very inefficient
and only suitable for small, simple diagrams.)
PSPRINT allows you to merge PostScript graphics with \TeX\ or \LaTeX\@.

Let's assume you have a file called \verb|fig.ps| that contains
suitable PostScript commands for generating some sort of figure.
To include this figure in a \TeX\ or \LaTeX\ document, just type
`\verb|\special{fig.ps}|' after leaving sufficient space:
\begin{verbatim}
    % in a TeX source file                        % in a LaTeX source file
    \midinsert                                    \begin{figure}[ht]
       \vskip 3in                                    \vspace{3in}
       \special{fig.ps}                              \special{fig.ps}
       \centerline{Figure 1: Pie Sales}              \caption{Pie Sales}
    \endinsert                                    \end{figure}
\end{verbatim}
It may take a little practice to position the figure correctly.
When you print a raw PostScript file (e.g., `\verb|psprint fig.ps|')
the default origin is at the bottom left corner of the paper.
However, when you include this file in a \TeX\ document the origin is
automatically moved to the position of the \verb|\special| command.

\verb|\special| can appear almost anywhere in your source file.
It behaves like an invisible box of zero height and width.
\TeX\ simply stores the given argument in the DVI file along with the current
page position.  PSPRINT interprets the argument as a file name and then
includes this file in the information sent to the printer.
(The included file is bracketed by \verb|save| and \verb|restore| commands
to prevent any interference to the surrounding typesetting commands.)

You can move the figure about by shifting the \verb|\special| position,
or by including a \verb|translate| command in the PostScript file.
The latter option is faster because you don't have to run \TeX\ again.
For example, `\verb|72 36 translate|' at the start of \verb|fig.ps| would
move the figure 1\,in right and 0.5\,in up
(PostScript's default units are ``big points'' where 72\,bp = 1\,in).

Alternatively, you may prefer to place your figure at an absolute position
on the paper (i.e., at the same position produced by `\verb|psprint fig.ps|').
Simply include an \verb|initgraphics| command at the start of \verb|fig.ps|.
The position of the \verb|\special| command then becomes irrelevant;
just make sure it's on the right page!

The hardest part of the scheme is creating the PostScript file in the first
place.  You are faced with two possibilities:
\begin{enumerate}
\item
Learn enough PostScript to be able to draw your own figures.
You'll need to get the PostScript books mentioned on page~1.
\item
Use a program to convert an existing graphics file
into a corresponding PostScript file.
This assumes you are able to produce graphics of some sort
(e.g., a Zeta plot file) and have access to a suitable conversion program.
Ask your local graphics wizard whether any such programs are available.
\end{enumerate}
\DVItoVDU\ is unable to preview a PostScript file.  All it can do is
tell you the page position of the \verb|\special| command and display the
given file name.

\newpage

Let's look at a few examples.  The public directory \verb|$tex_ps| contains
the \LaTeX\ source file for this User Guide, as well as a few PostScript
files used to produce the figures below.
These figures were created by calling
\begin{verbatim}
    \special{piechart.ps}
    \special{greybox.ps}
    \special{random.ps}
\end{verbatim}
at appropriate points in the source file.

\begin{figure}[h]   % produce figure here
    \vspace{2.1in}
    \special{piechart.ps}        % origin at left margin of text
    \caption{Pie Sales}
\end{figure}

\begin{figure}[h]   % produce figure here
    \begin{center}
       \begin{minipage}{4in}
          \special{greybox.ps}   % origin at top left of minipage box
          The text in this paragraph box was typeset by \LaTeX\@.
          The shaded rectangle was created by PostScript.
       \end{minipage}
    \end{center}
    \bigskip        % leave additional room for shaded box
    \caption{Shaded Text Box}
\end{figure}

\begin{figure}[h]   % produce figure here
    \begin{center}
       \setlength{\unitlength}{1in}
       \begin{picture}(1.3,1.3)   % dimensions match axis lengths in random.ps
          \put(0,0){\special{random.ps}}   % origin at bottom left corner
       \end{picture}
    \end{center}
    \caption{Random Dots}
\end{figure}

PSPRINT allows arbitrary PostScript text to appear after the file name in a
\verb|\special| command.  At least one space must be used to terminate the file
name; further characters are included as a new line at the {\em start\/} of
the given file.  There is a limit of about 80 characters.
For example, `\verb|\special{fig.ps 2 1 scale}|' could be used to double
the width of the figure in \verb|fig.ps|.
Note that it is possible to include the same PostScript file more than once,
but with a different starting line each time.

\end{document}