% $Header: /usr/jjc/dvitops/RCS/dvitops.tex,v 1.2 89/02/02 14:08:01 jjc Rel $
% this is the User Manual for DVITOPS in LaTeX format

% this macro was borrowed from the manual to Beebe's drivers
\newcommand{\namelistlabel}[1]{\mbox{#1}\hfil}
\newenvironment{namelist}[1]{%
\begin{list}{}
    {
      \let\makelabel\namelistlabel
      \settowidth{\labelwidth}{#1}
      \setlength{\leftmargin}{1.1\labelwidth}
    }
  }{%
\end{list}}
\documentstyle [11pt,a4,ps]{article}
\newcommand{\dvitops}{{\tt DVITOPS}}
\newcommand{\ps}{{\sc Post\-Script}}
\title{\dvitops\ User Manual}
\author{James Clark}
\newcommand{\error}[1]{\subsubsection{{\tt #1}}}

\begin{document}
\maketitle
\section{Introduction}
\dvitops\ translates a dvi file output of \TeX\ into \ps. It works with
both bitmap fonts and PostScript fonts. When used with the latter it
produces device-independent output.
\section{Usage}
The syntax for the \dvitops\ command is
\begin{flushleft}
{\tt dvitops} [{\it options}] {\it dvi\_file}
\end{flushleft}
You may omit the extension {\tt .dvi} from {\it dvi\_file}.
Options are delimited by the `{\tt -}' character. On MS-DOS,
they can also be delimited by `{\tt /}'. Options with no arguments
can be grouped behind a single delimiter. Option arguments that contain
white space must be enclosed in double-quotes. Option arguments
may, but need not be preceded by white space. 
The following options are currently supported:

\begin{namelist}{{\tt -h} {\it dimension}}
\item[{\tt -c} {\it ncopies}] 
Print {\it ncopies\/} copies of each page; 
note that the copies will not be collated.
\item[{\tt -h} {\it dimension}]
Horizontal offset. Position the origin {\it dimension} from the left edge
of the page; {\it dimension} must be a number followed by one of the units
of measure used by \TeX, for example {\tt1.5in}.
By default \dvitops\ positions the origin
of each page 1~inch down from and 1~inch to the right of
the upper left corner of the page.
This is the standard behaviour suggested by the Stanford \TeX\ project.
\item[{\tt -v} {\it dimension\/}]
Vertical offset. Position the origin {\it dimension} from the top of the page.
\item[{\tt -m} {\it number\/}]
This replaces the magnification in the
{\tt .dvi} file by {\it number}. This has the same effect as saying
 `\verb|\magnification=| {\it number}' in the \TeX\ file.
\item[{\tt -r}]
Reverse the order of the pages. This is useful if you have a printer
such as the Apple LaserWriter which stacks its output face up. If this
option occurs twice on the command line, pages will be in forward order.
This is useful if you include this option in the {\tt DVITOPS}
environment variable. See Section~\ref{ev}.
\item[{\tt -q}]
Work quietly; \dvitops\ will not print the numbers of pages as it
produces them.
\item[{\tt -f} {\it page}]
Select the first page to be processed;
{\it page} is specified by giving a sequence of 1 to 10 numbers or
asterisks separated by dots. For example, the specification `\verb|1.*.-5|'
can be used to refer to a page output by \TeX{} when \verb|\count0| is 1
and \verb|\count1| is $-5$.
An asterisk matches any number,
so the `\verb|*|' in `\verb|1.*.-5|' means that \verb|\count1| is ignored when
specifying the first page. If several pages match the given specification,
\dvitops\ will begin with the earliest such page in the file. The
default specification is `\verb|*|' which denotes
the page at the beginning of the file, since `\verb|*|' matches any page.
\item[{\tt -n} {\it number}]
Number of pages. Produce at most {\it number} pages.
\item[{\tt -s}]
Sort the pages by their \verb|\count0| value.
Negative numbers precede positive numbers. Negative numbers are sorted
in decreasing order, positive numbers in increasing order. Zero counts
as negative.
\item[{\tt -y} {\it kmem}]
Use at most {\it kmem\/} kbytes of printer memory for
preloading bitmap fonts.
\dvitops\ downloads the fonts that are most frequently used
in the document at the beginning. Other fonts have to be downloaded
on each page that they are used.
By default \dvitops\ will use at most 100k of the printer VM for this.
With this option it will use at most {\it kmem\/}k of VM.
\item[{\tt -p} {\it pagesize}]
This option informs \dvitops\ that {\it pagesize} paper will be used;
{\it pagesize} must be one of letter, legal, a4, b5, corresponding to the
page sizes used by standard \ps\ printers. This option does
not produce any \ps\ code to select this page size.
\dvitops\ needs to know the size of the page 
because the \ps\ origin is at the bottom of the page,
and the \TeX\ origin is at the top of the page. If you are using a
non-standard page size, you should choose the nearest standard page size
and adjust the position of the origin using the {\tt -h} and {\tt -v}
options.
\end{namelist}
See Section~\ref{ev} to find out how you can avoid having to
type in the options that you use frequently.

\section{\ps\ Fonts}
Ordinary \ps\ fonts not in pk format must have an entry in
the font directory file in order to be used with \dvitops.
This file is called {\tt dvitops.fnt}, and should be placed
in the same directory as the macro files used by \TeX.
Comments begin with a \verb|%|. They can start anywhere on the line
and continue to the end of the line.
Blank lines are ignored.
The syntax for each line is
\begin{flushleft}
{\it name} [{\it psname} [{\it encoding}]]
\end{flushleft}
{\it name} is the name of the font as it is known to \TeX, which is the same
as the name of the tfm file (with the extension {\tt .tfm} removed);
{\it psname} is the name of the font as it is known to \ps, for example
{\tt Times-Roman}. If {\it psname} is omitted it will be taken to be the same
as {\it name}.
The {\it encoding} field refers to an encoding file. An encoding file
describes an encoding vector for a font.
It should contain a list of the elements of the encoding vector
(without a preceding \verb|/|) separated by white space.
The file should have an extension of \verb|.enc|, which should be omitted
from {\it encoding}.
This field should be used in two situations:
if you created the tfm  file with the {\tt aftopl} utility,
and you specified an encoding file (with the \verb|-e| option),
or if you wish to use \dvitops\ with tfm files intended for
use with some other driver that automatically reencodes fonts.

\section{Environment variables}
\label{ev}
\dvitops\ needs to be able to find a number of different files.
It uses environment variables to do this. 
The environment variables must be all uppercase.
These environment variables all contain
lists. Elements of the list are separated by \verb|:| under UNIX
and by \verb|;| under MS-DOS.
\begin{namelist}{{\tt TEXINPUTS}}
\item[{\tt TEXFONTS}]
If this is set, it should contain a list of directories in which
\dvitops\ should search for tfm files, and encoding files.
\item[{\tt TEXINPUTS}]
If this is set, it should contain a list of directories in which
\dvitops\ should search for its text input files:
{\tt dvitops.fnt}, {\tt dvitops.pro},
and all the files referenced by \verb|\special| commands.
\item[{\tt TEXPK}]
This should be a list of prototypes of names of pk files.
A \verb|%f| in the prototype will be replaced by the name of the font
being searched for,
and a \verb|%d| by the magnification of the font in dots per inch.
\item[{\tt TEXMAGS}]
This should be a list of all the magnifications in dots per inch for which
there is some pk file.
\end{namelist}
The {\tt DVITOPS} environment variable allows you to avoid having to
type in frequently used options each time you use them.
When \dvitops\ reads its command line arguments, it types in the
value of this variable before any of the other arguments that have been
given. Thus if {\tt DVITOPS} is set to
\begin{verbatim}
-y 200 -r -p a4
\end{verbatim}
and you type
\begin{verbatim}
dvitops -f 1 user
\end{verbatim}
the effect will be the same as if you had typed
\begin{verbatim}
dvitops -y 200 -r -p a4 -f 1 user
\end{verbatim}
with the environment variable {\tt DVITOPS} unset.


\section{{\tt \char'134special} commands}
\TeX\ has a primitive \verb|\special| which allows
arbitrary text to be included in the {\tt .dvi} file.
\dvitops\ uses this to offer a variety of extra facilities.
To be recognised  by \dvitops\ the \verb|\special| must begin
with the `tag' {\tt dvitops:}. This tag is followed by a keyword and
possibly some arguments. The tag and keyword are not case-sensitive,
but the arguments are. White space is optional between the tag and the
keyword, but the keyword and arguments must be separated by white space.
A warning will be given if a \verb|\special| command with an
unrecognised tag is encountered, but it is an error if the keyword
following the {\tt dvitops:} tag is unrecognised.
\subsection{Landscape mode}
The command
\begin{verbatim}
\special{dvitops: landscape}
\end{verbatim}
will cause the page on which it occurs to be printed in landscape mode,
i.e. with the top of the page running along the long edge of the paper.
You must specify the command for each page that you want
printed in landscape mode.
\subsection{Graphics}
\label{graph}
You can include graphics in you document with the {\tt import} command.
The syntax of this command is:
\begin{flushleft}
\verb|\special{dvitops: import |{\it filename width height
{\rm[{\it option}\ldots]}}\verb|}|
\end{flushleft}
This option permits you to include a graphic in \ps\ form into the
document. There are three arguments:
{\it filename} is the name of the file containing the graphic,
{\it width} is the desired width of the graphic.
and {\it height} is the desired height of the graphic,
The {\it width} and {\it height} arguments must be specified as dimensions,
that is as a number with an optional decimal point followed by one
of the units of measure recognised by \TeX. The bottom left hand corner
of the graphic will be located at the point where the \verb|\special|
command was issued.
The graphic will be scaled so that it fits into the desired space,
but it will be scaled by the same factor horizontally
and vertically. It will be centred in any surplus
white space. This means that you do not have to know anything about the
dimensions of the graphic to be imported. \dvitops\ gets this
information from the \ps\ file. For example, Figure~\ref{elephant}
\begin{figure}[hbt]
\vspace{2in}
\special{dvitops: import picture.ps \the\textwidth 2in}
\caption{An Elephant}
\label{elephant}
\end{figure}
was produced by the \LaTeX\ commands
\begin{verbatim}
\begin{figure}[hbt]
\vspace{2in}
\special{dvitops: import picture.ps \the\textwidth 2in}
\caption{An Elephant}
\end{figure}
\end{verbatim}
\TeX\ expands \verb|\the\textwidth| to \the\textwidth, which
is the width of the text on the page. Note that the
graphic has been scaled so as to be 2~inches high and has been
centered horizontally with respect to  the text.
The file {\tt picture.ps} is the unaltered output of the
Macintosh version of Adobe Illustrator.

The \ps\ file containing the graphic should comply
with the Encapsulated Postscript Format
(EPSF) standard. EPSF files come in three flavours. The simplest
is just a text file. The first line of such a file will be:
\begin{verbatim}
%!PS-Adobe-2.0 EPSF 1.2
\end{verbatim}
This is the type of file that \dvitops\ needs. The other two
flavours contain in addition to the \ps\ text a representation
of the image that the \ps\ code will produce; one is intended
for the Macintosh environment, one for the MS-DOS environment.
In order for \dvitops\ successfully to import such a file, the
\ps\ text must be extracted from the file. 
A Macintosh EPSF file contains the \ps\ text in its data fork,
and the graphical representation in its resource fork. If such a
file is transferred to another system as a straight
binary  (not MacBinary) file, only the contents of the data fork
will in fact be transferred. Thus in order to import a Macintosh
EPSF file into \dvitops\ on another computer, it is only
necessary to transfer the file as a binary file. It may also
be necessary to change the carriage-returns which the Macintosh
uses as its line separator to whatever is used as a line separator
on the computer on which \dvitops\ is running
(carriage-return followed by line feed in MS-DOS,
line-feed in UNIX).
This method has been used successfully to import pictures produced with
Adobe Illustrator, Cricket Draw and Aldus Freehand running on a
Macintosh into \dvitops\ running under MS-DOS.

\subsection{\ps\ code}
\label{prolog}
\dvitops\ allows you to include your own \ps\ code in a document.
The \ps\ file that is output by \dvitops\ contains two sections:
a prologue and a script. The prologue contains only procedure
definitions and produces no printed output. The script 
calls the procedures defined in the prologue to generate the printed
pages. The pages of the script are independent of each other
but dependent on the prologue. \ps\ code that is executed within
the script of the document can only affect the page in which it occurs.
The command
\begin{flushleft}
\verb|\special{dvitops: prolog| {\it filename}\verb|}|
\end{flushleft}
will include {\it filename} in the prologue of the output file;
{\it filename}  must contain {\em only} definitions. The command
\begin{flushleft}
\verb|\special{dvitops: inline| {\it anything}\verb|}|
\end{flushleft}
will include {\it anything} in the script of the output file;
{\it anything} should a short piece of \ps\ code
which calls procedures defined in a prologue file. 
All the pieces of code from the {\tt inline} commands on a particular
page are held in memory until the end of the page is encountered.
The pieces of code are then output together after all the other output on
the page. The coordinate system in effect is the same as that used by
\TeX: units are scaled points (there are 65536 scaled points in a point);
y coordinates increase down the page; the origin is 1~inch down from
and 1~inch to the right of the upper left hand corner of the page.
Each \verb|\special| command in the {\tt .dvi} file
has an associated position, namely the reference point that would
have been present if a box of height, depth and width zero had appeared
in place of the \verb|\special| command.
\dvitops\ inserts code to move to that position before it outputs
the code from each {\tt inline} command. 
(This is what makes the {\tt inline} command useful.)
Note that any definitions
that you make in the code using  {\tt inline} commands will only
last until the end of the current page.

\subsection{Regions}
\dvitops\ allows you to select regions of a page and perform
various operations on them. Regions of the page are selected
using the following specials
\begin{flushleft}
\verb|\special{dvitops: begin |{\it region}\verb|}|\\
\verb|\special{dvitops: end}|
\end{flushleft}
Anything bracketed between these two commands will be part of the region
called {\it region}; {\it region} can be any alphanumeric string.
Regions cannot be nested; a {\tt begin}
command automatically terminates any previous {\tt begin} command
not already terminated with an {\tt end} command. All regions
are terminated automatically at the end of a page. The same
region can be the subject of more than one {\tt begin} command.
An {\tt end} command must have a preceding {\tt begin} command
on the same page.
Regions can include inline \ps\ and graphics.

\subsubsection{Transformations}
Once you have selected a region, you can apply a geometrical
transformation to it.
Each transformation is relative to an origin. By default
the origin is \TeX's origin, 1~inch down from and 1~inch to the
right of the upper right hand corner of the page
(unless changed by the {\tt -h} and {\tt -v} options).
This origin can be changed. The command
\begin{flushleft}
\verb|\special{dvitops: origin |{\it region}\verb|}|
\end{flushleft}
makes the current point the origin for {\it region}.
A region can have only one origin. Giving a region an origin
does not alter the position of the region on the page;
it just alters the effect of  transformations on that region.
The {\tt origin} command can be given anywhere on the page.

There are two \verb|\special| commands that perform
transformations:
\begin{flushleft}
\verb|\special{dvitops: rotate |{\it region $\theta$}\verb|}|\\
\verb|\special{dvitops: transform |{\it region a b c d}\verb|}|
\end{flushleft}
The {\tt transform} command performs the affine transformation
represented by the matrix
\[ \left( \begin{array}{cc}
a	&b\\
c	&d\\
\end{array} \right). \]
The {\tt rotate} command rotates the region about the origin of that
region by $\theta$ degrees in a clockwise direction. It is equivalent
to a {\tt transform} command; it is included because it is inconvenient
to calculate the appropriate transformation matrix for a rotation in \TeX.
Any number of transformations can be applied to a region. They will be
applied in the order in which they are given. 
Regions are only affected by transformation commands that appear on the 
same page. Apart from this transformation commands can appear at
any point in the document. For example, the following code
\begin{verbatim}
A \special{dvitops: begin example}%
\special{dvitops: origin example}sloping%
\special{dvitops: end} 
word.
\special{dvitops: rotate example -30}
\end{verbatim}
will produce
\begin{flushleft}
A \special{dvitops: begin example}%
\special{dvitops: origin example}sloping\special{dvitops: end} word.
\special{dvitops: rotate example -30}
\end{flushleft}
\subsubsection{Color}
You can also choose what color a region should be painted with.
\begin{flushleft}
\verb|\special{dvitops: gray| {\it whiteness}\verb|}|\\
\verb|\special{dvitops: hsbcolor| {\it hue saturation brightness}\verb|}|\\
\verb|\special{dvitops: rgbcolor| {\it red green blue}\verb|}|
\end{flushleft}
You should use at most one of these for each region. The arguments must
all be numbers between 0 and 1. A value of 0 for {\it whiteness}
will give black, and a value of 1 white.
You can get interesting effects using the \verb|gray| special.
For example, a macro \verb|\rbox| can be defined like this
\def\rbox#1{%
\leavevmode\setbox0\hbox{\strut#1}\special{dvitops: gray reverse 1}%
\vrule width \wd0 height \ht0 depth \dp0
\llap{\special{dvitops: begin reverse}\box0\special{dvitops: end}}}
\begin{verbatim}
\def\rbox#1{%
  \leavevmode\setbox0\hbox{\strut#1}%
  \special{dvitops: gray reverse 1}%
  \vrule width \wd0 height \ht0 depth \dp0
  \llap{\special{dvitops: begin reverse}%
    \box0
    \special{dvitops: end}}}
\end{verbatim}
Then \verb|\rbox{reverse out}| will produce \rbox{reverse out}.  Note
that objects on a page are not necessarily output in the order in
which they occur in the dvi file; in particular, all the text on a page
is output after everything else on the page.

\section{Errors}
\dvitops\ produces three types of error messages---fatal errors, errors
and warnings. The program will terminate immediately on a fatal error.
Each error message is prefixed by the full pathname of the 
\dvitops\ program, followed by a colon and one of 
``fatal error'', ``error'' and ``warning.'' 
\dvitops\ operates in two passes. On the second pass
\dvitops\ prints an opening bracket followed by the number of a page
just as it is about to start outputting the \ps\ code for that page;
it prints a closing bracket when it's done with a page.
The page number displayed is the values of \verb|\count0| through
\verb|\count9| separated by dots with trailing `.0's suppressed.
\TeX\ does the same.
This enables you to tell on the second pass where \dvitops\ has
encountered the error.

\end{document}