⟦4af975f93⟧

TextFile

%
%   This document describes how to use dvips.  Macros at top cut and
%   slashed from another document.
%
\newif\ifgeneric\genericfalse
\ifx\ntmanloaded Y\else\input dvipsmac \fi % uh oh, no macros, give our own.
%
%   Finally, the document itself.
%
The \.{dvips} program converts a \TeX\ \.{dvi} file into a PostScript file
for printing or distribution.  Seldom has such a seemingly easy programming
task required so much effort.

% Why use dvips?

\sec{Why Use dvips?}

The \.{dvips} program has a number of features that set it apart from other
PostScript drivers for \TeX.  This rather long section describes the advantages
\^{{\tt dvips}}
\^{PostScript}
of using \.{dvips}, and may be skipped if you are just interested in how to
use the program.

The \.{dvips} driver generates excellent, standard PostScript, that can be
included in other documents as figures or printed through a variety of
spoolers.  The generated PostScript requires very little printer memory,
so very complex documents with a lot of fonts can easily be printed even
on PostScript printers without much memory, such as the original Apple
LaserWriter.  The PostScript output is also compact, requiring less disk
space to store and making it feasible as a transfer format.

Even those documents that are too complex to print in their entirety
on a particular printer
can be printed, since \.{dvips} will automatically split such documents
\^{memory}
into pieces, reclaiming the printer memory between each piece.

The \.{dvips} program supports graphics in a natural way, allowing PostScript
graphics to be included and automatically scaled and positioned in a variety
of ways.

Printers with resolutions other than 300 dpi are also supported, even if they
have different resolutions in the horizontal and vertical direction.
High resolution output is supported for typesetters, including an option
that compresses the bitmapped fonts so the typesetter virtual memory is
\^{resolution}
not exhausted.  This option also significantly reduces the size of the
PostScript file and decoding in the printer is very fast.

Missing fonts can be automatically generated if \MF\ exists on the system,
or fonts can be converted from \.{gf} to \.{pk} format on demand.
\^{automatic font generation}
If a font cannot be generated, a scaled version of the same font at a
different size can be used instead, although \.{dvips} will complain
loudly about the poor aesthetics of the resulting output.

Users will appreciate features such as collated copies and support
for \.{tpic}, \.{psfig}, \.{emtex}, and \.{METAPOST};
\^{{\tt tpic}}
\^{{\tt psfig}}
\^{{\tt emtex}}
\^{{\tt METAPOST}}
system administrators will love the support for multiple printers, each
with their own configuration file, and the ability to pipe the output
directly to a program such as \.{lpr}.
Support for MS-DOS and VMS in addition to UNIX is provided in the
\^{MS-DOS}
\^{UNIX}
\^{VMS}
standard distribution, and porting to other systems is easy.

One of the most important features is the support of virtual fonts, which
add an entirely new level of flexibility to \TeX.  Virtual fonts are used to
give \.{dvips} its excellent PostScript font support, handling all the font
remapping in a natural, portable, elegant, and extensible way.  The \.{dvips}
\^{{\tt afm2tfm}}
driver even comes with its own \.{afm2tfm} program that creates the necessary
virtual fonts and \TeX\ font metric files automatically from the Adobe
font metric files.

Source is provided and freely distributable, so adding a site-specific feature
is possible.  Adding such features is made easier by the highly modular
structure of the program.

There is really no reason to use another driver, and the more people use
\.{dvips}, the less time will be spent fighting with PostScript and the
more time spent creating beautiful documents.  So if you don't use \.{dvips}
on your system, get it today.

\sec{Using dvips}

To use \.{dvips}, simply type
\cmd{localhost> dvips foo}
\noindent
where \.{foo.dvi} is the output of \TeX\ that you want to print.  If \.{dvips}
has been installed correctly, the document should come out of your default
printer.

If you use fonts that have not been used on your system before, they
may be automatically generated; this process can take a few minutes.
The next time that document is printed, these fonts will already exist, so
printing will go much faster.

Many options are available; they are described in a later section.

\sec{Landscape Mode}

You may want to design a document that has the long edge of the
\^{landscape}
paper horizontal.  This can be useful when typesetting booklets,
brochures, complex tables, or many other documents.  This type of
paper orientation is called landscape orientation (the `normal'
orientation is portrait).
\^{portrait}

To typeset a document in landscape, simply give the command
\cmd{\ttbackslash special\char123landscape\char125}
\noindent
somewhere on the first page of the document.  This is preferable to giving
the landscape option as a command line argument, since landscape determination
is more a document design issue than it is a printing issue, and you want
to be sure a document intended for landscape printing is always printed in
landscape mode.

If you use landscape mode, be sure to set the horizontal and vertical size
of your document to reasonable values in \TeX.  (For plain \TeX, these are
the parameters \.{hsize} and \.{vsize}.)

\sec{Including PostScript Graphics}

Scaling and including PostScript graphics is a breeze---if the PostScript
\^{graphics}
\^{PostScript graphics}
file is correctly formed.  Even if it is not, however, the file can usually
be accommodated with just a little more work.  The most important feature of
a good PostScript file---from the standpoint of including it in another
document---is an accurate bounding box comment.

\sub{The Bounding Box Comment}

Every well-formed PostScript file has a comment describing where on the
\^{bounding box}
page the graphic is located, and how big that graphic is.  This information
is given in terms of the lower left and upper right corners of a box just
enclosing the graphic, and is thus referred to as a bounding box.
These coordinates are given
in PostScript units (there are precisely 72 PostScript units to
the inch) with respect to the lower left corner of a sheet of paper.

To see if a PostScript file has a bounding box comment, just
look at the first few lines of the file.
(PostScript is standard ASCII, so you can use any text editor to do this.)
If within the first few dozen lines there is a line of the form
\cmd{\%\%BoundingBox:\ 0 1 2 3}
\noindent
(with any numbers), chances are very good that the file is Encapsulated
PostScript and will work easily with \.{dvips}.  If the file contains
instead a line like
\cmd{\%\%BoundingBox:\ (atend)}
\noindent
the file is still probably Encapsulated PostScript, but the bounding
box (that \.{dvips} needs to position the graphic) is at the end of the
file and should be moved to the position of the line above.  This can be
done with that text editor, or with a simple Perl script.

If the document lacks a bounding box altogether, one can be easily added.
Simply print the file.  Now, take a ruler, and make the following measurements.
All measurements should be in PostScript units, so measure it in inches and
multiply by 72.

From the left edge of the paper to the leftmost mark on the paper is
{\it llx}, the first number.  From the bottom edge of the paper to the
bottommost mark on the paper is {\it lly}, the second number.  From
the left edge of the paper to the rightmost mark on the paper is
{\it urx}, the third number.  The fourth and final number, {\it ury}, is
the distance from the bottom of the page to the uppermost mark on the
paper.

Now, add a comment of the following form as the second line of the document.
(The first line should already be a line starting with the two
characters `{\tt \%!}'; if it is not, the file probably isn't PostScript.)
\cmd{\%\%BoundingBox:\ {\it llx lly urx ury}}
\noindent
Or, if you don't want to modify the file, you can simply write these
numbers down in a convenient place and use them when you import the
graphic.

If the document does not have such a bounding box, or if the bounding box
is given at the end of the document, please complain to the authors of the
software package that generated the file; without such a line, including
PostScript graphics can be tedious.

\sub{Using the EPSF Macros}

Now you are ready to include the graphic into a \TeX\ file.  Simply add to
\^{{\tt epsf} macros}
the top of your \TeX\ file a line like
\cmd{\ttbackslash input epsf}
\noindent
(or, if your document is in La\TeX\ or Sli\TeX, add the \.{epsf} style
option, as was done to the following line).
\cmd{\ttbackslash documentstyle[12pt,epsf]\char123article\char125}
\noindent
This only needs to be done once, no matter how many figures you plan to
include.  Now, at the point you want to include the file, enter a line
such as
\cmd{\ttbackslash epsffile\char123foo.ps\char125}
\noindent
If you are using La\TeX\ or Sli\TeX, you may need to add a
\.{leavevmode} command immediately before the
\^{{\tt leavevmode}}
\.{epsffile} command to get certain environments to work
correctly.  If your file did not (or does not currently) have a bounding
box comment, you should supply those numbers you wrote down as in the
following example:
\cmd{\ttbackslash epsffile[100 100 500 500]\char123foo.ps\char125}
\noindent
(in the same order they would have been in a normal bounding box comment).
Now, save your changes and run \TeX\ and \.{dvips}; the output should
have your graphic positioned at precisely the point you indicated, with the
proper amount of space reserved.

The effect of the \.{epsffile} macro is to typeset the figure as a \TeX\
\.{vbox} at the point of the page that the command is executed.
By default, the graphic will have its
`natural' width (namely, the width of its bounding box).
The \TeX\ box will have depth zero and a `natural' height.
The graphic will be scaled by any \.{dvi} magnification in effect at the
\^{magnification}
time.

Any PostScript graphics included by any method in this document (except
\^{{\tt bop-hook}}
\.{bop-hook} and its ilk) are scaled by the current \.{dvi} magnification.
For graphics included with \.{epsffile} where the size is given in \TeX\
dimensions, this scaling will produce the correct, or expected, results.
For compatibility with old PostScript drivers, it is possible to turn
\^{{\tt magscale}}
this scaling off with the following \TeX\ command:
\cmd{\ttbackslash special\char123!/magscale false def\char125}
\noindent
Use of this command is not recommended because it will make the
\.{epsffile} graphics the wrong size if global magnification is used
in a \.{dvi} document, and it will cause any PostScript graphics to
appear improperly scaled and out of position if a \.{dvi} to \.{dvi}
program is used to scale or otherwise modify the document.

You can enlarge or reduce the figure by putting
\cmd{\ttbackslash epsfxsize=<dimen>}
\noindent
right before the call to \.{epsffile}.
Then the width of the \TeX\ box will be \.{<dimen>} and its
height will be scaled proportionately.  Alternatively you can force the
\^{{\tt epsfxsize}}
vertical size to a particular size with
\cmd{\ttbackslash epsfysize=<dimen>}
\noindent
in which case the height will be set and the width will be scaled
proportionally.  If you set both, the figure will be scaled to fit
both, perhaps distorting the aspect ratio.

A more general facility for sizing is available by defining the
\.{epsfsize} macro.   You can redefine this macro
\^{{\tt epsfsize}}
to do almost anything.  This \TeX\ macro is passed two parameters
by \.{epsffile}.  The first parameter is the natural horizontal size of
the PostScript graphic, and the second parameter is the natural vertical
size.  This macro is responsible for returning the desired horizontal size of
the graph (the same as assigning \.{epsfxsize} above).

In the definitions given below, only the body is given; it should be inserted
in
\cmd{\ttbackslash def\ttbackslash epsfsize\#1\#2\char123{\it body}\/\char125}
\noindent
Some common definitions are:

{\options
\.{\ttbackslash epsfxsize}
This definition (the default) enables the default features listed above,
by setting \.{epsfxsize} to the same value it had before the macro was
called.

\.{0pt}
This definition forces natural sizes for all graphics by setting the width to
zero, which turns on horizontal scaling.

\.{\#1}
This forces natural sizes too, only by just returning the first parameter
(which is the natural width) and setting the width to that.

\.{\ttbackslash hsize}
This forces all graphics to be scaled so they are as wide as the current
horizontal size.  (In La\TeX, use \.{textwidth} instead of \.{hsize}.)

\.{0.5\#1}
This scales all figures to half of their natural size.

\.{\ttbackslash ifnum\#1>\ttbackslash hsize\ttbackslash hsize\ttbackslash
else\#1\ttbackslash fi}
This keeps graphics at their natural size, unless the width would be wider
than the current \.{hsize}, in which case the graphic is scaled down to
\.{hsize}.\par}

If you want \TeX\ to report the size of the figure as a message
on your terminal when it processes each figure, give the command
\cmd{\ttbackslash epsfverbosetrue}

\sub{Header Files}

Often in order to get a particular graphic file to work, a certain header
\^{header}
file might need to be sent first.  Sometimes this is even desirable, since
the size of the header macros can dominate the size of certain PostScript
graphics files.  The \.{dvips} program provides support for this with the
\.{header=} special command.  For instance, to ensure that \.{mick.ps}
gets downloaded as part of the header material, the following command
should be added to the \TeX\ file:
\cmd{\ttbackslash special\char123header=mick.ps\char125}
\noindent
The dictionary stack will be at the \.{userdict} level when these header
files are included.

\sub{Literal PostScript}

For simple graphics, or just for experimentation, literal PostScript
\^{literal PostScript}
graphics can be included.  Simply use a special command that starts with
a double quote ({\tt"}).
For instance, the following (simple) graphic:
\vskip\baselineskip
\vbox to 100bp{\vss % a bp is the same as a PostScript unit
\special{" newpath 0 0 moveto 100 100 lineto 394 0 lineto
closepath gsave 0.8 setgray fill grestore stroke}}

\noindent
was created by typing:
\cmd{\ttbackslash vbox to 100bp\char123\ttbackslash vss
 \% a bp is the same as a PostScript unit\\
\ttbackslash special\char123" newpath 0 0 moveto 100 100 lineto 394 0 lineto\\
closepath gsave 0.8 setgray fill grestore stroke\char125\char125}
\noindent
(Note that you are responsible for leaving space for such literal graphics.)

\sub{Literal Headers}

Similarly, you can define your own macros for use in such literal graphics
through the use of literal macros.  Literal macros are defined just like
literal graphics, only you begin the special with an exclamation point
instead of a double quote.  These literal macros are included as part of the
header material in a special dictionary called \.{SDict}.  This dictionary
\^{{\tt SDict}}
is the first one on the PostScript dictionary stack when any PostScript
graphic is included, whether by literal inclusion or through the \.{epsffile}
macros.

\sub{Other Graphics Support}

There are other ways to include graphics with \.{dvips}.  One is to use an
\^{obsolete}
existing package, such as \.{emtex}, \.{psfig}, \.{tpic}, or \.{METAPOST},
all of which \.{dvips} supports.

Other facilities are available for historical reasons, but their use is
discouraged, in hope that some `sane' form of PostScript inclusion shall
become standard.  Note that the main advantage of the \.{epsffile} macros
is that they can be adapted for whatever form of special eventually becomes
standard, and thus only minor modifications to that one file need to be
made, rather than revising an entire library of \TeX\ documents.

Most of these specials use a flexible key and value scheme:
\cmd{\ttbackslash special\char123psfile=filename.ps[ key=value]*\char125}
\noindent
This will download the PostScript file called \.{filename.ps}
such that the current point will be the origin of the PostScript
\^{{\tt psfile}}
coordinate system.  The optional key/value assignments allow you
to specify transformations on the PostScript.

The possible keys are:\vskip\baselineskip

\centerline{\vbox{\halign{\tt#\hfil\quad&#\hfil\cr
hoffset	&The horizontal offset (default 0)\cr
voffset	&The vertical offset (default 0)\cr
hsize	&The horizontal clipping size (default 612)\cr
vsize	&The vertical clipping size (default 792)\cr
hscale	&The horizontal scaling factor (default 100)\cr
vscale	&The vertical scaling factor (default 100)\cr
angle	&The rotation (default 0)\cr}}}

The dimension parameters are all given in PostScript units.
The \.{hscale} and \.{vscale} are given in non-dimensioned percentage
units, and the rotation value is specified in degrees.
Thus
\cmd{\ttbackslash special\char123psfile=foo.ps hoffset=72 hscale=90
vscale=90\char125}
\noindent
will shift the graphics produced by file \.{foo.ps} right by one inch
and will draw it at 0.9 times normal size.
Offsets are given relative to the point of the special command, and are
unaffected by scaling or rotation.  Rotation is counterclockwise about the
origin.  The order of operations is to rotate the figure, then
scale it, then offset it.

For compatibility with older PostScript drivers, it is possible to change
the units that \.{hscale} and \.{vscale} are given in.  This can be
done by redefining \.{@scaleunit}
\^{{\tt scaleunit}}
in \.{SDict}
\^{{\tt SDict}}
by a \TeX\ command such as
\cmd{\ttbackslash special\char123/@scaleunit 1 def\char125}
\noindent
The \.{@scaleunit} variable, which is by default 100, is what \.{hscale}
and \.{vscale} are divided by to yield an absolute scale factor.

All of the methods for including graphics we have described
so far enclose the graphic in
a PostScript save/restore pair, which guarantee that the figure will have
no effect on the rest of the document.
Another type of special command allows literal PostScript instructions to be
inserted without
enclosing them in this protective shield; users of this feature
are supposed to understand what they are doing (and they shouldn't change
the PostScript graphics state unless they are willing to take the
consequences).  This command can take many forms, because it has had a
torturous history; any of the following will work:
\cmd{\ttbackslash special\char123ps:{\it text}\char125\\
\ttbackslash special\char123ps::{\it text}\char125\\
\ttbackslash special\char123ps::[begin]{\it text}\char125\\
\ttbackslash special\char123ps::[end]{\it text}\char125}
\noindent
(with longer forms taking precedence over shorter forms, when they are used).
An exception is the command
\cmd{\ttbackslash special\char123ps:\ plotfile filename\char125}
\noindent
which will copy the commands from \.{filename}
verbatim into the output (but omitting lines that begin with \%).
An example of the proper use of literal specials can be found in the file
\.{rotate.tex} which makes it easy to typeset text turned 90 degrees.

To finish off this section, the following examples are presented without
explanation:
{\vskip0pt\parskip=0pt\begverb{`\$}
\def\rotninety{\special{ps:currentpoint currentpoint translate 90
rotate neg exch neg exch translate}}\font\huge=cmbx10 at 14.4truept
\setbox0=\hbox to0pt{\huge A\hss}\vskip16truept\centerline{\copy0
\special{ps:gsave}\rotninety\copy0\rotninety\copy0\rotninety
\box0\special{ps:grestore}}\vskip16truept$endverb}
\smallskip
{\def\rotninety{\special{ps:currentpoint currentpoint translate 90
rotate neg exch neg exch translate}}\font\huge=cmbx10 at 14.4truept
\setbox0=\hbox to0pt{\huge A\hss}\vskip16truept\centerline{\copy0
\special{ps:gsave}\rotninety\copy0\rotninety\copy0\rotninety
\box0\special{ps:grestore}}\vskip16truept}
\smallskip
{\vskip0pt\parskip=0pt\begverb{`\$}
\vbox to 2truein{\special{ps:gsave 0.3 setgray}\hrule height 2in
width\hsize\vskip-2in\special{ps:grestore}\font\big=cminch\big
\vss\special{ps:gsave 1 setgray}\vbox to 0pt{\vskip2pt
\line{\hss\hskip4pt NEAT\hss}\vss}\special{ps:0 setgray}%
\hbox{\raise2pt\line{\hss NEAT\hss}\special{ps:grestore}}\vss}$endverb}
\smallskip
\vbox to 2truein{\special{ps:gsave 0.3 setgray}\hrule height 2in
width\hsize\vskip-2in\special{ps:grestore}\font\big=cminch\big
\vss\special{ps:gsave 1 setgray}\vbox to 0pt{\vskip2pt
\line{\hss\hskip4pt NEAT\hss}\vss}\special{ps:0 setgray}%
\hbox{\raise2pt\line{\hss NEAT\hss}\special{ps:grestore}}\vss}

Some caveats are in order when using the above forms.  Make sure that
each \.{gsave} on a page is matched with a \.{grestore} on the same
page.  Do not use \.{save} or \.{restore}.  Use of these macros can
interact with the PostScript generated by \.{dvips} if care is not
taken; try to understand what the above macros are doing before
writing your own.  The \.{rotninety} macro especially has a useful
trick that appears again and again.

\sub{Dynamic Creation of PostScript Graphics Files}

PostScript is an excellent page description language---but it does
tend to be rather verbose.  Compressing PostScript graphics files can
often reduce them by more than a factor of five.  For this reason,
if the filename parameter to one of the graphics inclusion techniques
starts with a backtick ({\tt`}), the filename is instead interpreted
as a command to execute that will send the actual file to standard
output.  Thus,
\cmd{\ttbackslash special\char123psfile="`zcat foo.ps.Z"\char125}
\noindent
will include the uncompressed version of \.{foo.ps}.  Since such a
command is not accessible to \TeX, if you use this facility with
the \.{EPSF} macros, you should supply the bounding box parameter
yourself, as in
\cmd{\ttbackslash epsffile[72 72 540 720]\char123
   "`zcat screendump.ps.Z"\char125}
\noindent
to include \.{screendump.ps}.  Of course, the commands to be executed can
be anything, including using a file conversion utility such as \.{tek2ps}
or whatever is appropriate.

This extension is not portable to other \.{dvi2ps} programs.  Yet.

\sec{Using PostScript Fonts}

Thanks to Donald~E.~Knuth,
\^{Knuth, Donald E.}
the \.{dvips} driver now supports PostScript fonts
\^{PostScript fonts}
through the virtual font capability.
PostScript fonts are (or should be) accompanied by font metric files
such as \.{Times-Roman.afm},
which describes the characteristics of the font called Times-Roman.
\^{{\tt afm}}
To use such fonts with \TeX, we need \.{tfm} files that contain similar
\^{{\tt tfm}}
information. These files can be can be generated from the \.{afm} files
by running the program \.{afm2tfm}, supplied with \.{dvips}.
\^{{\tt afm2tfm}}
This program also creates virtual fonts with which you can use normal
plain \TeX\ conventions.

Note that PostScript fonts tend to use a great deal of printer virtual
memory, usually much more than the \TeX\ bitmap fonts.  This is because
the information for the bitmapped fonts is stored in a very dense form
and downloads information for only those characters that are actually used,
while modifying PostScript fonts for use by \TeX\ (by creating a new width
vector, among other things) takes a fair bit of PostScript memory.

\sub{The afm2tfm Program}

The \.{afm2tfm} program can convert an Adobe \.{afm} file into a `raw'
\TeX\ \.{tfm} file with the command
\cmd{localhost> afm2tfm Times-Roman rptmr}
\noindent
This file is `raw' because it does no character remapping; it simply
converts the character information on a one-to-one basis to \TeX\
characters with the same code.

PostScript fonts have a different encoding scheme from that of plain
\TeX. Although both schemes are based on ASCII, special characters such as
ligatures and accents are handled quite differently. Therefore we obtain
\^{ligature}
\^{accents}
\^{virtual fonts}
best results by using a `virtual font' interface, which makes \TeX\ act
as if the PostScript font had a standard \TeX\ encoding. Such a virtual
font can be obtained, for example, by the command
\cmd{localhost> afm2tfm Times-Roman -v ptmr rptmr}
\noindent
This produces two outputs, namely the `virtual property list' file
\.{ptmr.vpl}, and the \TeX\ font metric file \.{ptmr.tfm}.
The latter file describes an `actual font' on which the virtual font is based.

%If you want to specify a different \.{tfm} file name than the default, you
%can use the \.{-t} option; this will override any default \.{tfm} file name
%that would be calculated from the input file name.

To use the font in \TeX, you should first run
\cmd{localhost> vptovf ptmr.vpl ptmr.vf ptmr.tfm}
\noindent
and then install the virtual font file \.{ptmr.vf} in the virtual font
directory (by default, \.{/usr/lib/tex/fonts/vf}) and install \.{ptmr.tfm}
in the directory for \TeX\ font metrics (by default,
\.{/usr/lib/tex/fonts/tfm}).  (This probably has already been done for you for
the most common PostScript fonts.)
You can also make more complex virtual fonts by editing
\.{ptmr.vpl} before running \.{vptovf}; such editing might add the upper-case
Greek characters in the standard \TeX\ positions, for instance.
Once this has been done, you're all set. You can use
code like this in \TeX\ henceforth:
\cmd{\ttbackslash font\ttbackslash myfont=ptmr at 10pt\\
\ttbackslash myfont Hello, I am being typeset in Times-Roman.}

Note that there are two fonts, one actual (`rptmr',
which is analogous to a raw piece of hardware) and one virtual
(`ptmr', which has typesetting know-how added). You could also say
\cmd{\ttbackslash font\ttbackslash TR=rptmr at 10pt}
\noindent
and typeset directly with that, but then you would have no ligatures
\^{ligature}
or kerning, and you would have to use Adobe
\^{kerning}
character positions for special letters like \AE. The virtual font
called \.{ptmr}
not only has ligatures and kerning, and most of the standard
accent conventions of \TeX, it also has a few additional features
not present in the Computer Modern fonts. For example, it includes all
the Adobe characters (such as the Polish ogonek and the French
guillemots). It also allows you to type 58 accented letters
from `Aacute' to `zcaron' as if they were ligatures---namely
as `acute' followed by `A', etc., where you can get `acute'
(\.{\ttbackslash char 19}) by defining a suitable control sequence.
(The 58 constructed characters are found in the \.{afm} file, and constructed
as specified by Adobe; you may want to adjust the spacing and/or
add additional accent combinations by editing the \.{vpl} file.)
The only things you lose from ordinary \TeX\ text fonts are
the dotless j (which can be hacked into the VPL file with
literal PostScript specials if you have the patience) and
uppercase Greek letters (which just don't exist unless you buy
them separately).

When \.{dvips} goes to use a font, it first checks to see if it is one of
the fonts listed in a file called \.{psfonts.map}.  If it is mentioned in
\^{{\tt psfonts.map}}
that file, then it is assumed that the font is a resident PostScript font
and can be found with the PostScript \.{findfont} operator.  This file
resides by default in {\tt /usr/lib/tex/ps}, and consists of a single font
per line.  Note that only the raw PostScript font names should be listed
in this file; the \.{vf} fonts should not be, since they are automatically
mapped to the raw PostScript fonts by the virtual font machinery.
The supplied \.{psfonts.map} file defines the most common PostScript fonts.

As much as possible, the PostScript fonts follow plain \TeX\ conventions
for accents.  The two exceptions to this are the Hungarian umlaut (which
is at position {\tt 0x7D} in {\tt cmr10}, but position {\tt 0xCD} in
{\tt ptmr}) and the dot accent (at positions {\tt 0x5F} and {\tt 0xC7},
respectively).  In order to use these accents with PostScript fonts or in
math mode when {\tt \char92 textfont0} is a PostScript fonts, you will need
to use the following definitions.  Note that these definitions will not work
with normal \TeX\ fonts for the relevant accents.
{\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$}
\def\H#1{{\accent"CD #1}}\def\.#1{{\accent"C7 #1}}
\def\dot{\mathaccent"70C7 }$endverb}

These PostScript fonts can be scaled to any size.  Go wild!
Note, however, that using PostScript fonts does
use up a great deal of the printer's virtual memory and it does take time.
\^{memory}
You may find downloading the Computer Modern fonts to be faster than using
the built-in PostScript fonts.

\sub{Special Effects}

Special effects are also obtainable, with commands such as
\cmd{localhost> afm2tfm Times-Roman -s .167 -v ptmro rptmro}
\noindent
which create \.{ptmro.vpl} and \.{rptmro.tfm}.
To use this, proceed as above but put the line
\cmd{rptmro Times-Oblique "/Times-Roman .167 SlantFont"}
\noindent
into \.{psfonts.map}.  Then \.{rptmro} (our name for Times-Oblique)
will act as if it were a
\^{{\tt psfonts.map}}
resident font, although it is actually constructed from Times-Roman
by PostScript hackery.   (It's an oblique version of Times-Roman, obtained
by slanting everything 1/6 to the right.)
Similarly, you can get an extended font by
\cmd{localhost> afm2tfm Times-Extended -e 1.2 -v ptmrre rptmrre}
\noindent
and by recording the pseudo-resident font
\cmd{rptmrre Times-Expanded "/Times-Roman 1.2 ExtendFont"}
\noindent
in \.{psfonts.map}.

The command line switches to \.{afm2tfm} are:

{\options
\.{-e {\it ratio}}
All characters are stretched horizontally by the stated ratio;
\^{expanded fonts}
if it is less than 1.0, you get a condensed font.

\.{-s {\it slant}}
All characters are slanted to the right by the stated slant;
\^{slanted fonts}
if it is negative, the letters slope to the left (or they might be
upright if you start with an italic font).

\.{-v {\it file}}
Generate a virtual property list \.{vpl} file as well as a \.{tfm} file.

\.{-V {\it file}}
Same as \.{-v}, but the virtual font generated is a small caps font obtained
by scaling uppercase letters by 0.8 to typeset lowercase. This font
handles accented letters and retains proper kerning.\par}

\sub{Non-Resident PostScript Fonts}

If you want to use a non-printer-resident PostScript font for which you have
a \.{pfb} file (an Adobe Type 1 font program), you can make it act like
\^{{\tt pfb}}
resident font by putting a `{\tt <}' sign
and the name of the \.{pfb} file just after the font name in the
\.{psfonts.map}
\^{{\tt psfonts.map}}
file entry. For example,
\cmd{StoneInformal <StoneInformal.pfb}
\noindent
will cause \.{dvips} to include \.{StoneInformal.pfb} in your document as if
it were a header file, whenever the pseudo-resident font StoneInformal is
used in a document.   Similarly, you can generate transformed fonts and
include lines like
\vskip\baselineskip
\centerline{\tt StoneInformal-Condensed <StoneInformal.pfb
"/StoneInformal .8 ExtendFont"}
\noindent
in \.{psfonts.map}, in which case \.{StoneInformal.pfb} will be loaded whenever
StoneInformal-Condensed is used. (Each header file is loaded at most once per
document. The \.{pfb} files should be installed in the \.{dvips} configuration
directory [usually {\tt /usr/lib/tex/ps}] with the other header files.)

\sub{Font Aliases}
Some systems don't handle files with long names well---MS-DOS is
\^{MS-DOS}
a notable example.  For this reason, \.{dvips} will accept an alias for such
fonts.  Such an alias should be the first word in the \.{psfonts.map}
line.  For instance, if we wanted the name \.{rptmr} to be used for the
raw \.{Times-Roman} since our computer can't handle long names or since we
want to follow the standard naming conventions, we would use
the following line in our
\.{psfonts.map} file:
\cmd{rptmr Times-Roman}
\noindent
The \.{tfm} file must have the name \.{rptmr.tfm}.
\^{{\tt tfm}}

The parsing of the \.{psfonts.map}
\^{{\tt psfonts.map}}
file should be explained to eliminate all confusion.  Each line is separated
into words, where words are separated by spaces or tabs.  If a word begins
with a double quote, it extends until the next double quote or the
end of the line.  If a word starts with a less than character, it is treated
as a font header file (or downloaded PostScript font).  If a word starts with
a double quote, it is special instructions for generating that font.
Otherwise it is a name.  The first such name is always the name \TeX\ uses for
the font and is also the name of the \.{tfm} file.  If there is another name
word, that name is used as the PostScript name; if there is only one name word,
it is used for both the \TeX\ name and the PostScript name.

Note that the aliases also register the full PostScript name, so the single line
\cmd{rptmr Times-Roman}
\noindent
would allow \.{dvips} to find the \.{rptmr} font as well as the
\.{Times-Roman} font, if \.{tfm} files exist for both.

Incidentally, many font files (e.g., in the Adobe Type Library) include more
characters internally than you can access directly without making a few
changes.  These characters typically have code $-1$ in the \.{afm} file and
no corresponding `constructed character' ({\tt CC}) specification.
For example, in Adobe Garamond
there are Eth and eth, Thorn and thorn, plus things like copyright and
onehalf, plus 58 accented letters Aacute thru zcaron (with accents over
caps much better looking than you can get from constructed accents). To use
these characters, give them character codes between 0 and 255 in the \.{afm}
file, and build the corresponding EncodingVector (instead of StandardEncoding)
in the \.{pfb} file. Then \.{afm2tfm} will generate a \.{vpl} file that
includes accented characters as ligatures, as explained above;
for example, `Aacute' will be accessible as `acute'
followed by `A' (as well as by its character code in the virtual font).

\sec{Font Naming Conventions}

{\def\journal#1{{\sl #1}}
\def\table{\vbox\bgroup
\vskip\parskip\halign\bgroup\strut\indent\tt ##\hfil\quad
    &\vtop{%
       \advance\hsize by -\parindent % The \indent in the first column.
       \advance\hsize by -1em        % The \quad.
       % One table has two-letter abbreviations.
       \advance\hsize by -2\fontdimen7\tentt
       \rm\noindent ##}\hfil
    \cr}
\def\setuphsize{%
       \advance\hsize by -\parindent % The \indent in the first column.
       \divide\hsize by 2            % double column
       \advance\hsize by -1.5em      % The 3 \quads divided by 2.
       % One table has two-letter abbreviations.
       \advance\hsize by -2\fontdimen7\tentt}
\def\dtable{\vbox\bgroup\vskip\parskip\halign\bgroup\strut
    \indent##&\tt ##\hfil\quad
    &\vtop{\setuphsize\rm\noindent ##}\hfil&\quad\tt ##\hfil\quad
    &\vtop{\setuphsize\rm\noindent ##}\hfil\cr}
\def\endtable{%
  \egroup\egroup % End the \halign.
  \smallskip % I don't know what kind of space you want, but it needs
             %  something here.
}
\def\entry#1#2{#1&#2\cr}
\def\mitem{\item{$\bullet$}}
\def\\{\hfil\break}

This section of the manual has been written by Karl Berry and
specifies a standard for naming of fonts for \TeX.  This standard has
been adopted in \.{dvips}, and it is recommended that it be followed
where possible.

As more typeface families become available for use with \TeX, the need
for a consistent, rational naming scheme for the font filenames
concomitantly grows. Some (electronic) discussion has gone into the
following proposal; I felt it was appropriate now to bring it before a
wider community.  In some respects, it follows and simplifies
Mittelbach's and Sch\"opf's article in \journal{TUGboat}, volume~11,
number~2 (June 1990).

Here are some facts about fonts that went into the hopper when creating
this proposal:

\mitem \TeX\ runs on virtually all computers, under almost as many operating
systems, all with their own idea of how files should be named.  Any
proposal regarding filenames, therefore, must cater to the lowest common
denominator.  That seems to be eight characters in length, not counting any
extension, and with case being insignificant.  Characters other
than letters and numerals are probably unusable.

\mitem Most typefaces are offered by several vendors.  The version
offered by vendor~A is not compatible with that of vendor~B.

\mitem Typefaces typically come in different weights (hairline to extra
heavy), different expansions (ultra condensed to wide), and an
open-ended range of variants (italic, sans serif, typewriter,
shadow,~$\ldots$).  No accepted standards exist for any of these
qualities, nor are any standards ever likely to gain acceptance.

\mitem The Computer Modern typeface family preserves traditional typesetting
practice in at least one important respect: different sizes of the same
font are not scaled linearly.  This is in contrast to most commercial fonts
available.

Here is how I propose to divide up the eight characters:
\cmd{FTTWVEDD}
\noindent
where

\mitem \.{F} represents the foundry that produced the font, and is omitted
if there isn't one.

\mitem \.{TT} represents the typeface name.

\mitem \.W represents the weight.

\mitem \.V represents the variant, and is omitted if both it and the
expansion are ``normal''.

\mitem \.E represents the expansion, and is omitted if it is ``normal''.

\mitem \.{DD} represents the design size, and is omitted if the font is
linearly scaled from a single {\tt tfm} file.

See the section on virtual fonts (towards the end) for an exception to
the above.

The weight, variant, and expansion are probably all best taken from the
original source of the typeface, instead of trying to relate them to
some external standard.

Before giving the lists of abbreviations, let me point out two problems,
to neither of which I have a good solution.  1)~Assuming that only the
English letters are used, two letters is enough for only 676 typeface
families (even assuming we want to use all possible combinations, which
is doubtful).  There are many more than 676 typeface families in the
world.  2)~Fonts with design sizes over 100$\,$pt are not common, but
neither are they unheard of.

On to the specifics of the lists.  If you adopt this proposal at your
own installation, and find that you have fonts with some property I
missed, please write to me (see the end of the article for various
addresses), so I can update the lists.  You can get the
most up-to-date version of these lists electronically, by anonymous ftp
from the host \.{ftp.cs.umb.edu}.  I will also send them to you by
electronic mail, if necessary.

I give the letters in lowercase, which is preferred on systems where
case is significant.  Most lists are in alphabetical order by the
abbreviations.

\sub{Foundry}

This is the current list of foundries.

\table
a&Autologic\cr
b&Bitstream\cr
c&Compugraphic\cr
g&Free Software Foundation ({\tt g} for GNU)\cr
h&Bigelow \& Holmes (with apologies to Chuck)\cr
i&International Typeface Corporation\cr
p&Adobe ({\tt p} for PostScript)\cr
r&reserved for use with virtual fonts; see below\cr
s&Sun\cr
\endtable

\sub{Typeface Families}

The list of typefaces is:

\dtable
&ad&Adobe Garamond&go&Goudy Oldstyle\cr
&ag&Avant Garde&gs&Gill Sans\cr
&ao&Antique Olive&jo&Joanna\cr
&at&American Typewriter&lc&Lucida\cr
&bb&Bembo&lt&Lutetia\cr
&bd&Bodoni&nc&New Century Schoolbook\cr
&bg&Benguiat&op&Optima\cr
&bk&Bookman&pl&Palatino\cr
&bl&Balloon&pp&Perpetua\cr
&bv&Baskerville&rw&Rockwell\cr
&bw&Broadway&st&Stone\cr
&cb&Cooper Black&sy&Symbol\cr
&cl&Cloister&tm&Times\cr
&cr&Courier&un&Univers\cr
&cn&Century&uy&University\cr
&cs&Century Schoolbook&zc&Zapf Chancery\cr
&hv&Helvetica&zd&Zapf Dingbats\cr
&gm&Garamond&&\cr
\endtable

\sub{Weight}

This is a list of the possible weights,
roughly in order from lightest to heaviest.

\dtable
&a&hairline&d&demi\cr
&t&thin&s&semi\cr
&i&extra light&b&bold\cr
&l&light&x&extra bold\cr
&k&book&h&heavy\cr
&r&regular&c&black\cr
&m&medium&u&ultra\cr
\endtable

\sub{Variants}

The variants are:

\dtable
&a&alternate&n&informal\cr
&b&bright&o&oblique (i.e., slanted)\cr
&c&small caps&r&normal (roman or sans)\cr
&e&engraved&s&sans serif\cr
&g&grooved (as in the IBM logo)&t&typewriter\cr
&h&shadow&u&unslanted italic\cr
&i&(text) italic&x&expert\cr
&l&outline&&\cr
\endtable

If the variant is {\tt r}, and the expansion is also normal, both the
variant and the expansion are omitted.  When the normal version of the
typeface is sans serif (e.g., Helvetica), \.{r} should be used,
not \.{s}.  Use \.{s} only when the typeface family
has both serif and sans serif variants.  The ``alternate'' variant
(\.{a}) is used by some Adobe fonts that have oldstyle digits.
The ``expert'' variant (\.{x}) is also used by some Adobe
fonts.

Some fonts have multiple variants; Stone Informal Italic, for example.
The only reasonable approach to these is to list all the letters for all
the variants, choosing one to end with that is not also an expansion
letter.  Of course, it is possible that the name will become too
long if you do this, but $\ldots$ well, I'm open to suggestions.  It's
also possible the name will be ambiguous, if some new letter is used for
expansions in the future.  You can avoid this problem by adding the
expansion \.{r} (if it doesn't make the name too long), and
never using \.{r} for the last variant.

\sub{Expansion}

This is a list of the possible expansions, in order from narrowest to
widest.

\dtable
&o&extra condensed&x&extended (by hand)\cr
&c&condensed (by hand)&e&expanded (automatic)\cr
&n&narrow (automatic)&w&wide\cr
&r&\multispan3{regular, normal, medium (usually omitted)\hfil}\cr
\endtable

Expansion of fonts is sometimes done automatically (as in PostScript
{\bf scale}), and sometimes done by humans.  I chose `narrow' and
`expanded' to imply the former, and `condensed' and `extended' to imply
the latter, as I believe this reflects common usage.

\sub{Naming Virtual Fonts}

In concert with releasing \TeX~3.0 and \MF~2.7, Don Knuth wrote two new
utility programs: \.{VFtoVP} and \.{VPtoVF}, which convert
to and from ``virtual'' fonts.  Virtual fonts provide a general
interface between the writers of \TeX\ macros and font suppliers.
In general, therefore, it is impossible to come up with a general scheme
for naming virtual fonts, since each virtual font is an individual
creation, possibly bringing together many unrelated fonts.

Nevertheless, one common case is to use virtual fonts to map \TeX's
default accent and other character code conventions onto a
vendor-supplied font.  For example, \.{dvips} (by Tom Rokicki)
does this for fonts given in the PostScript ``standard encoding''.
In this case, each font consists of a ``virtual'' tfm file, which is
what \TeX\ uses, a ``raw'' tfm file, which corresponds to the actual
device font, and a vf file, which describes the relationship between the
two.

This adds another dimension to the space of font names, namely,
``virtualness'' (or rather, ``rawness'', since it is the virtual tfm
files that the users want to see).  But we have already used up all
eight characters in the font names.

The best solution I have been able to think of is this: prepend
\.{r} to the raw tfm files; the virtual tfm files should be
named with the usual foundry prefix.  For example, the virtual Times
Roman tfm file is named \.{ptmr}, as usual; the raw Times Roman
tfm file is named \.{rptmr}.  To prevent intolerable confusion, I
promise never to give a foundry the letter \.{r}.

This scheme will work only as long as the virtualized fonts do not have
design sizes; if they do, another foundry letter will have to be
allocated, it seems to me.

A pox upon the houses of those who decided on fixed-length filenames!

\sub{Examples}

In closing, I will give two examples.  First, the fonts in the Univers
typeface family were assigned numbers by its designer, Adrien Frutiger. 
(You can see the scheme on, for example, page~29 of {\sl The Art of
Typo.icon.ography}, by Martin Solomon.)  Naturally, we want to give
them names.

\vskip\baselineskip\vbox{%
\halign to\hsize{\hskip20pt\tt #\hfil\space&#\hfil\quad\tabskip=0pt plus 1in
&\tt #\hfil\space\tabskip=0pt&#\hfil\cr
unl&45 (light)&unmro&59 (medium extra condensed)\cr
unli&46 (light italic)&undrx&63 (demibold extended)\cr
unlrc&47 (light condensed)&und&65 (demibold)\cr
unlic&48 (light condensed italic)&undi&66 (demibold italic)\cr
unlro&49 (light extra condensed)&undrc&67 (demibold condensed)\cr
unmrx&53 (medium extended)&undic&68 (demibold condensed italic)\cr
unm&55 (medium)&unbrx&73 (bold extended)\cr
unmi&56 (medium italic)&unb&75 (bold)\cr
unmrc&57 (medium condensed)&unbi&76 (bold italic)\cr
unmic&58 (medium condensed italic)&unxrx&83 (extra bold extended)\cr}}

Second, here are names for the standard PostScript fonts and their variants:
Fonts marked by an asterisk do not require using virtual fonts; the raw
fonts can be used directly because no remapping is necessary.
\vskip\baselineskip\vbox
{\font\small=cmr8\def\mark{${}^*$}\def\smallcaps{{\small(Small Caps)}}
\hyphenation{Post-Script}
\halign to\hsize{\hskip20pt\tt #\hfil\space&#\hfil\quad\tabskip=0pt plus 1in
&\tt #\hfil\space\tabskip=0pt&#\hfil\cr
pagk  &AvantGarde-Book&pncri &NewCenturySchlbk-Italic\cr
pagkc &AvantGarde-Book {\smallcaps}&pncr  &NewCenturySchlbk\cr
pagko &AvantGarde-BookOblique&pncrc &NewCenturySchlbk {\smallcaps}\cr
pagd  &AvantGarde-Demi&pplb  &Palatino-Bold\cr
pagdo &AvantGarde-DemiOblique&pplbi &Palatino-BoldItalic\cr
pbkd  &Bookman-Demi&pplbu &Palatino-BoldUnslanted\cr
pbkdi &Bookman-DemiItalic&pplrrn&Palatino-Narrow\cr
pbkl  &Bookman-Light&pplrre&Palatino-Expanded\cr
pbkli &Bookman-LightItalic&pplri &Palatino-Italic\cr
pbklc &Bookman-Light {\smallcaps}&pplr  &Palatino\cr
pcrb  &Courier-Bold&pplro &Palatino-Oblique\cr
pcrbo &Courier-BoldOblique&pplru &Palatino-Unslanted\cr
pcrro &Courier-Oblique&pplrc &Palatino {\smallcaps}\cr
pcrr  &Courier&psyr  &Symbol\mark\cr
phvb  &Helvetica-Bold&psyro &Symbol-Oblique\mark\cr
phvbo &Helvetica-BoldOblique&ptmb  &Times-Bold\cr
phvro &Helvetica-Oblique&ptmbi &Times-BoldItalic\cr
phvr  &Helvetica&ptmrrn&Times-Narrow\cr
phvrc &Helvetica {\smallcaps}&ptmrre&Times-Expanded\cr
phvbrn&Helvetica-Narrow-Bold&ptmri &Times-Italic\cr
phvbon&Helvetica-Narrow-BoldOblique&ptmro &Times-Oblique\cr
phvron&Helvetica-Narrow-Oblique&ptmr  &Times-Roman\cr
phvrrn&Helvetica-Narrow&ptmrc &Times-Roman {\smallcaps}\cr
pncb  &NewCenturySchlbk-Bold&pzcmi &ZapfChancery-MediumItalic\cr
pncbi &NewCenturySchlbk-BoldItalic&pzdr  &ZapfDingbats\mark\cr}}

Please contact Karl Berry if you have any comments or additions.  Karl
can be reached at \.{karl@cs.umb.edu}, or at 135 Center Hill Road,
Plymouth, MA~~02360.\par}

\sec{Command Line Options}

The \.{dvips} driver has a plethora of command line options.  Reading
through this section will give a good idea of the capabilities of the
driver.

Many of the parameterless options listed here can be turned off by
immediately suffixing
the option with a zero (0); for instance, to turn off page reversal if it is
turned on by default, use \.{-r0}.  The options that can be turned off in
this way are \.f, \.m, \.q, \.r, \.B, \.F, \.K, \.N, \.U, and \.Z.

{\options
\def\o#1 #2:{{\tt #1} {\it #2}:}
\def\O#1:{{\tt #1}:}
\o-c num: Generate {\it num} copies of every page.
\^{copies}
Default is 1. (For collated copies, see the \.{-C} option below.)

\o-d num:  Set the debug flags.  This is intended only for emergencies
or for unusual fact-finding expeditions; it will work only if
\^{debug}
\.{dvips} has been compiled with the \.{DEBUG} option.
The source file \.{debug.h} indicates what the values of
{\it num} can be, or see the last section of this manual.
Use a value of $-1$ for maximum output.

\o-e num:
Make sure that each character is placed at most this many pixels from its
`true' resolution-independent
position on the page. The default value of this parameter
is resolution dependent (it is the number
of entries in the list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600,
2000, 2400, 2800, 3200, $\ldots$] that are less than or equal to the
\^{maxdrift}
resolution in dots per inch). Allowing individual
characters to `drift' from their correctly rounded positions
by a few pixels, while regaining the true position at the beginning of
each new word, improves the spacing of letters in words.

\O-f: Run as a filter.
\^{filter}
Read the \.{dvi} file from standard input and write the PostScript to
standard output.  The standard input must be seekable, so it cannot
be a pipe.  If you must use a pipe, write a shell script that copies
the pipe output to a temporary file and then points \.{dvips} at this file.

\o-h name:
Prepend file {\it name}
\^{header}
as an additional header file. (However, if the name is simply `\.-',
suppress all header files from the output.)  This header file
gets added to the PostScript \.{userdict}.

\o-l num:
\^{pages}
The last page printed will be the first one numbered {\it num.}
Default is the last page in the document.

\O-m:  Specify manual feed for printer.
\^{manual feed}

\o-n num:
At most {\it num} pages will be printed. Default is 100000.
\^{pages}

\o-o name:  The output will be sent to file {\it name.}
\^{output}
If no file name is given, the default name is \.{{\it file}.ps} where
the \.{dvi} file was called \.{{\it file}.dvi};
if this option isn't given, the default name is \.{!lpr}.
If the first character of the file name is an exclamation mark, then
the remainder will be used as an argument to \.{popen}; thus, specifying
\.{!lpr} as the output file will automatically queue the file for printing.

\o-p num:
\^{pages}
The first page printed will be the first one numbered {\it num.}
Default is the first page in the document.

\O-q: Run in quiet mode.
Don't chatter about pages converted, etc.; report nothing but errors to
\^{quiet}
standard error.

\O-r:
Stack pages in reverse order.  Normally, page 1 will be printed first.
\^{reverse}

\O-s:
Causes the entire global output to be enclosed in a save/restore pair.
This causes the file to not be truly conformant, and is thus not recommended,
but is useful if you are driving the printer directly and don't care too
much about the portability of the output.

\o-t papertype:
\^{paper type}
\^{mode}
\^{letter}
\^{legal}
\^{ledger}
\^{a4}
\^{a3}
\^{landscape}
This sets the paper type to {\it papertype}.
Currently, the only types allowable are
\.{letter}, which selects an 8.5 by 11 inch page,
\.{a3}, which selects an a3 sized page,
\.{a4}, which selects an a4 sized page,
\.{legal}, which selects an 8.5 by 14 inch page,
\.{ledger}, which selects an 11 by 17 inch page, and
\.{landscape}, which rotates a \.{letter} size document by 90 degrees.
The default mode is none.
To rotate a document whose size is not letter, you can use the 
\.{-t} option twice, once for the page size, and once for \.{landscape}.
The upper left corner of each page in
the \.{dvi} file is placed one inch from the left and one inch from the top.
Use of this option does not execute the {\tt letter} or {\tt a4} or other
appropriate option in the printer itself, since use of such PostScript
operators make the document nonconforming and have other bad effects.
If you need to execute such operators, use a small header file and the
{\tt -h} option.  If you are using, for example, {\tt a4} paper, your
printer should automatically recognize the fact from the {\tt a4} paper
cartridge, so an explicit {\tt a4} would be unecessary (although a
{\tt -t a4} would still be, in order to put the origin of the page at
the correct place.)

\o-x num:
Set the magnification ratio to {\it num}/1000. Overrides the magnification
\^{magnification}
specified in the \.{dvi} file.  Must be between 10 and 100000.

\o-C num:
Create {\it num}
\^{copies}
copies, but collated (by replicating the data in the PostScript file).
Slower than the \.{-c} option, but easier on the hands, and faster than
resubmitting the same PostScript file multiple times.

\o-D num:
Set the resolution in dpi (dots per inch) to {\it num.}
\^{resolution}
This affects the choice of bitmap fonts that are loaded and also the positioning
of letters in resident PostScript fonts. Must be between 10 and 10000.
This affects both the horizontal and vertical resolution.  If a high resolution
(something greater than 400 dpi, say) is selected, the \.{-Z} flag should
probably also be used.

\O-F:
Causes Control-D (ASCII code 4) to be appended as the very last character
of the PostScript file.  This is useful when \.{dvips}
\^{EOF}
\^{control-D}
is driving the printer directly instead of working through a spooler,
as is common on extremely small systems.  Otherwise, it is not recommended.

\O-K:
This option causes comments in included PostScript graphics, font files,
and headers to be removed.  This is sometimes necessary to get around bugs
in spoolers or PostScript post-processing programs.  Specifically, the
\.{\%\%Page} comments, when left in, often cause difficulties.
Use of this flag can cause some included graphics to fail, since the
PostScript header macros from some software packages read portions of
the input stream line by line, searching for a particular comment.

\O-N:
Turns off structured comments; this might be necessary on some systems
\^{structured comments}
that try to interpret PostScript comments in weird ways, or on some
PostScript printers.  Old versions of Transcript in particular cannot
handle modern Encapsulated PostScript.

\o-P printername:
Sets up the output for the appropriate printer.  This is implemented
by reading in \.{config.{\it printername}}, which can then set the output pipe
(as in, \.{o !lpr -Pprintername}) as well as the font paths and any other
\^{{\tt config.ps}}
defaults for that printer only.  It is recommended that all standard
defaults go in the one master {\tt config.ps}
file and only things that vary
printer to printer go in the \.{config.{\it printername}}
files.  Note that {\tt config.ps}
is read before \.{config.{\it printername}}.
In addition, another file called \.{\tilde/.dvipsrc}
is searched for immediately after \.{config.ps};
this file is intended for user defaults.  If no \.{-P} command is
given, the environment variable \.{PRINTER} is checked.  If that
variable exists, and a corresponding configuration
file exists, that configuration file is read in.

\O-U:
Disable a PostScript virtual memory saving optimization that stores the
character metric information in the same string that is used to store
the bitmap information.  This is only necessary when driving the Xerox
4045 PostScript interpreter, and it is caused by a bug in that interpreter
that results in `garbage' on the bottom of each character.  Not
recommended unless you must drive this printer.

\o-X num:
Set the horizontal resolution in dots per inch to {\it num.}
\^{resolution}

\o-Y num:
Set the horizontal resolution in dots per inch to {\it num.}
\^{resolution}

\O-Z:
Causes bitmapped fonts to be compressed before they are downloaded,
\^{compression}
thereby reducing the size of the PostScript font-downloading information.
Especially useful at high resolutions or when very large fonts are
used.  Will slow down printing somewhat, especially on early 68000-based
PostScript printers.\par}

\sec{Configuration File Searching}

The \.{dvips} program has a system of loading configuration files such that
\^{{\tt config.ps}}
certain parameters can be set globally across the system, others can be set
on a
per-printer basis, and yet others can be set by the user.  When \.{dvips}
starts up, first the global \.{config.ps} file is searched for and loaded.
This file is looked for along the path for header files, which is by
default \.{.:/usr/lib/tex/ps}.
After this master configuration file is loaded, a file by the name of
\.{.dvipsrc} is loaded from the current user's home directory, if such
a file exists.  This file is loaded in exactly the same way as the global
configuration file, and it can override any options set in the global
file.

Then the command line is read and parsed.  If the \.{-P} option is
encountered, at that point in the command line a configuration file
for that printer is read in.  Thus, the printer configuration file can
override anything in the global or user configuration file, and it can
also override anything seen in the command line up to the point that the
\.{-P} option was encountered.

After the command line has been completely scanned, if there was no
\.{-P} option selected, and also the \.{-o} and \.{-f} command line
options were not used, a \.{PRINTER} environment variable is
searched for.  If this variable exists, and a configuration file for
the printer mentioned in it exists, this configuration file is
loaded last of all.

Note that because the printer-specific configuration files are read
after the user's configuration file, the user cannot override things in
the printer configuration files.  On the other hand, the header path
usually includes the current directory, and can be set to include the
user's home directory (or any other directory of the user), so the user can
always provide his or her own printer-specific configuration files that will
be found before the system global ones.

If your printer uses a different resolution than 300 dpi,
make sure that you
have given a \MF\ mode as well as a resolution in the printer
configuration file.  Also make sure that \MF\ knows about the mode,
by entering it into your local \.{mode\_def} file (typically
\.{waits.mf}; \.{amiga.mf} on the Amiga, \.{next.mf} on the NeXT)
and recreating the \.{plain.base} file for \MF, including the
\.{mode\_def} file.  The most common problem in generating fonts
with \MF\ is that
\^{{\tt mode\_def}}
\^{{\tt plain.base}}
\^{\MF}
this file with the mode definitions is not included when creating
the \.{plain.base} file.

\sec{Configuration File Options}

Most of the configuration file options are similar to the command line
options, but there are a few new ones.

Again, many may be turned off by suffixing the letter with a zero (0).
These options are \.f, \.q, \.r, \.K, \.N, \.U, and \.Z.

Within a configuration file, any empty line or line starting with a space,
asterisk, equal sign, or a pound sign is ignored.

{\options
\def\o#1 #2:{{\tt #1} {\it #2}:}
\def\O#1:{{\tt #1}:}
\o e num:
Sets the maximum drift parameter to {\it num} dots (pixels) as explained above.
\^{maxdrift}

\O f:  Run as a filter by default.
\^{filter}

\o h name:
Add {\it name} as a PostScript header file to be downloaded at the beginning.
\^{header}

\o m num:  The value {\it num} is the virtual memory available for fonts
and strings in the printer.
\^{memory}
Default is 180000.  This value must be accurate if memory conservation and
document splitting is to work correctly.  To determine this value, send the
following file to the printer:
{\parindent=40pt\cmd{\%! Hey, we're PostScript\\
/Times-Roman findfont 30 scalefont setfont 144 432 moveto\\
vmstatus exch sub 40 string cvs show pop showpage}}
\noindent
Note that the number returned by this file is the total memory free;
it is often a good idea to tell \.{dvips} that the printer has somewhat
less memory.  This is because many programs download permanent macros
that can reduce the memory in the printer.  In general, a memory size
of about \.{300000} is plenty, since \.{dvips} can automatically split
a document if required.  It is unfortunate that PostScript printers with
much less virtual memory still exist.
Some systems or printers can dynamically increase the memory available
to a PostScript interpreter, in which case this file might return a
ridiculously low number; the NeXT computer is such a machine.  For these
systems, a value of one million works well.

\o o name:
\^{output}
The default output file is set to {\it name}.  As above, it can be a pipe.
Useful in printer-specific configuration files to redirect the output to
a particular printer queue.

\O q:  Run in quiet mode by default.
\^{quiet}

\O r:  Reverse the order of pages by default.
\^{reverse}

\O s:
Enclose the entire document in a global save/restore pair by default.
Not recommended, but useful in some environments; this breaks the
conformance of the document to the Adobe PostScript structuring
conventions.

\o t papertype:  This sets the paper type to {\it modename}, as above.

\o D num:
Sets the vertical and horizontal resolution to {\it num}
\^{resolution}
dots per inch.  Useful in printer-specific configuration files.

\o E command:
Executes the command listed; can be used to get the current date into a
header file for inclusion, for instance.  Possibly dangerous; in many
installations this may be disabled, in which case a warning message will
be printed if the option is used.

\o H path:
The (colon-separated) path to search for PostScript header 
\^{header}
files is {\it path}.

\O K:
Filters comments out of included PostScript files; see the description
above for more information.

\o M mode: Set {\it mode}
as the \MF\ mode to be used when generating fonts.  This is
\^{{\tt MakeTeXPK}}
\^{{\MF}}
passed along to \.{MakeTeXPK} and overrides mode derivation from the
base resolution.

\O N:  Disable PostScript comments by default.

\o P path:  The (colon-separated) path to search for bitmap \.{pk}
font files is
{\it path}.  The \.{TEXPKS} environment variable will override this.
\^{{\tt TEXPKS}}
\^{{\tt pk}}
If a \.{\%} character is found in {\it path},
the following substitutions will be made, and then a search will
be made for the resulting filenames.
A \.{\%f} is replaced by the font name.
A \.{\%d} is replaced by the font size in dots per inch.
A \.{\%p} is replaced by the font family; this is always \.{pk}.
A \.{\%m} is replaced by the font mode; this is the mode given
in the \.{M} option.

\o R num num $\ldots$:
Sets up a list of default resolutions to search for \.{pk} fonts, if the
\^{{\tt pk}}
requested size is not available.  The output will then scale the font
found using PostScript scaling to the requested size.  Note that the
resultant output will be ugly, and thus a warning is issued.  To turn
this off, use a line with just the \.{R} and no numbers.

\o S path:  The path to search for special illustrations
(Encapsulated PostScript files or psfiles) is {\it path}.
\^{{\tt TEXINPUTS}}
The \.{TEXINPUTS} environment variable will override this.

\o T path: The path to search for the \.{tfm} files is
{\it path}.  The \.{TEXFONTS} environment variable will override this.
\^{{\tt TEXFONTS}}
This path is used for resident fonts and fonts that can't be otherwise found.
It's usually best to make it identical to the path used by \TeX.

\O U:  Turns off a memory-saving optimization; this is necessary for the
Xerox 4045 printer, but not recommended otherwise.  See the description
above for more information.

\o V path:  The path to search for virtual font \.{vf} files is
\^{{\tt vf}}
\^{virtual fonts}
{\it path}.
This may be device-dependent if you use virtual fonts to simulate
actual fonts on different devices.

\o W string:
Sends {\it string} to stderr, if a parameter is given; otherwise it cancels
another previous  message.
This is useful in the default configuration file if you want to require
the user to specify a printer, for instance, or if you want to notify
the user that the resultant output has special characteristics.

\o X num:
\^{resolution}
Sets the horizontal resolution to {\it num} dots per inch.

\o Y num:
\^{resolution}
Sets the vertical resolution to {\it num} dots per inch.

\O Z:  Compress all downloaded fonts by default, as above.\par}

\sec{Automatic Font Generation}

One major problem with \TeX\ and the Computer Modern fonts is the huge
amount of disk space a full set of high resolution fonts can take.  The
\.{dvips} program solves this problem by creating fonts on demand, so only
those fonts that are actually used are stored on disk.  At a typical site,
less than one-fifth of the full set of Computer Modern fonts are used over
a long period, so this saves a great deal of disk space.

Furthermore, the addition of dynamic font generation allows fonts to be
used at any size, including typesetter resolutions and extremely huge
banner sizes.  Nothing special needs to be done; the fonts will be
automatically created and installed as needed.

The downside is that it does take a certain amount of time to create a new
font if it has never been used before.  But once a font is created, it
will exist on disk, and the next time that document is printed it will print
very quickly.

It is the \.{MakeTeXPK} shell script that is responsible for making these
\^{{\tt MakeTeXPK}}
fonts.  The \.{MakeTeXPK} script supplied invokes \MF\ to create the font and
then copies the resultant \.{pk} file to a world-writable font cache area.

\.{MakeTeXPK} can be customized to do other things to get the font.  For
instance, if you are installing \.{dvips} to replace (or run alongside)
an existing PostScript driver, and that driver demanded \.{gf} fonts, you
can easily modify \.{MakeTeXPK} to invoke \.{gftopk} to convert the
\.{gf} files to \.{pk} files for \.{dvips}.  This provides the same space
savings listed above.

Because \.{dvips} (and thus \.{MakeTeXPK}) is run by a wide variety of users,
there must be a system-wide place to put the cached font files.  In order
for everyone to be able to supply fonts, the directory must be world
writable.  If your system administrator considers this a security hole,
\.{MakeTeXPK} can write to \.{/tmp/pk} or some such directory, and
periodically the cached fonts can be moved to a more general system area.
Note that the cache directory must exist on the \.{pk} file search path
in order for \.{MakeTeXPK} to work.

\sec{Path Interpretation}

The \.{dvips} program needs to read a wide variety of files from a large
set of directories.  It uses a set of paths to do this.  The actual
paths are listed in the next section; this section describes how the
paths are interpreted.

All paths variables are the names of directories (path elements),
separated by colons.
Each path element can be either the literal name of a directory or one
of the \.{\tilde} forms common under UNIX.  If a path element is a single tilde,
\^{UNIX}
it is replaced by the contents of the environment variable \.{HOME}, which
\^{{\tt HOME}}
is normally set to the user's home directory.  If the path element is
a tilde followed by anything, the part after the tilde is interpreted as
a user name, and his home directory is fetched from the system password
file and used as the real path element.

Where environment variables can override paths, an additional path
element form is allowed.  If a path element is the empty string, it
is replaced with the system defaults.  Thus, to
search the user's home directory, followed by the system
default paths, assuming the current shell is \.{csh},
the following command would be used:
\cmd{setenv TEXINPUTS \tilde:}
\noindent
This is a path of two elements.  The first is the user's home directory.
The second path element is the empty string, indicating that
the system defaults should be searched.

The `system defaults' as defined here means the strings set in the
\.{Makefile} before compilation, rather than any defaults set in
\.{config.ps} or printer-specific configuration files.  This is to
prevent path blowup, where more and more directories are added to the
path by each level of configuration file.

\sec{Environment Variables}

The \.{dvips} program reads a certain set of environment variables to
configure its operation.  The path variables are read after all
configuration files are read, so they override values in the configuration
files.  (The \.{TEXCONFIG} variable, of course, is read before the
configuration files.)  The rest are read as needed.

\descenv HOME,{\rm no default}
  This environment variable is automatically set by the shell and is
used to replace any occurrences of \.{\tilde} in a path.

\descenv PRINTER,{\rm no default}
  This environment variable is read to determine the default printer
configuration file to read in.  Note that it is the responsibility of
the configuration file to send output to the proper print queue, if such
functionality is desired.

\descenv TEXFONTS,{/LocalLibrary/Fonts/TeXFonts/tfm:/usr/lib/tex/fonts/tfm}
  This is where \.{tfm} files are searched for.  A \.{tfm} file only
\^{{\tt tfm}}
needs to be loaded if the font is a resident (PostScript) font or if
for some reason no \.{pk} file could be found.

\descenv TEXPKS,{/LocalLibrary/Fonts/TeXFonts/pk:/usr/lib/tex/fonts/pk}
  This environment variable is a path on which to search for \.{pk} fonts.
Certain substitutions are performed if a percent sign is found anywhere
\^{{\tt pk}}
in the path; see above for a description of the substitutions performed.

\descenv TEXINPUTS,{.:..:/usr/lib/tex/inputs}
  This environment variable is used to find PostScript figures when they
are included.

\descenv TEXCONFIG,{.:/usr/lib/tex/ps}
  This environment variable sets the directories to search for configuration
files, including the system-wide one.  Using this single environment variable
and the appropriate configuration files, it is possible to set up the program
for any environment.  (The other path environment variables can thus be
redundant.)

\sec{Other Bells And Whistles}

For special effects, if any of the macros
\.{bop-hook}, \.{eop-hook}, \.{start-hook}, or \.{end-hook}
\^{{\tt bop-hook}}
\^{{\tt eop-hook}}
\^{{\tt start-hook}}
\^{{\tt end-hook}}
are defined in the PostScript \.{userdict}, they will be executed at the
beginning of a page, end of a page, start of the document, and end of
a document, respectively.
When these macros are executed, the default PostScript coordinate system
and origin
is in effect.  Such macros can be defined in headers added by the
\.{-h} option or the \.{header=}
special, and might be useful for writing, for instance, DRAFT across the
entire page, or, with the aid of a shell script, dating the document.
These macros are executed outside of the save/restore context of the
individual pages, so it is possible for them to accumulate information,
but if a document must be divided into sections because of memory
constraints, such added information will be lost across section breaks.

As an example of what can be done, the following special will write
a light DRAFT across each page in the document:
{\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$}
\special{!userdict begin /bop-hook{gsave 200 30 translate
65 rotate /Times-Roman findfont 216 scalefont setfont
0 0 moveto 0.7 setgray (DRAFT) show grestore}def end}$endverb}

Several of the above tricks can be used nicely together, and it is not
necessary that a `printer configuration file' be used only to set
printer defaults.  For instance, a \.{-P}
file can be set up to print the date on each page; the particular configuration
file will execute a command to put the date into a header file, which is then
included with a \.{h} line in the configuration file.  Note that multiple
\.{-P} options can be used.

\ifgeneric\else
\sec{MS-DOS}
The MS-DOS version of \.{dvips} differs from UNIX in the following ways.
\^{MS-DOS}
\item{$\bullet$} Path separators are \.{;} not \.{:}.
\item{$\bullet$} Directory separators are \.{\ttbackslash} not \.{/}.
\item{$\bullet$} The user's initialization file is \.{dvips.ini}
  not \.{.dvipsrc}.
\item{$\bullet$} Pipes to printers are not supported.  
  Output must go to a file.
\item{$\bullet$} \.{MakeTeXPk} is a batch file.  
  Since MS-DOS has insufficient memory to run both \.{dvips} and \MF\ 
  at the same time, this batch file will typically write out a set of 
  commands for running \MF\ later.  
  The \.{maketexp.bat} supplied writes out an \.{mfjob} file for em\TeX.
\item{$\bullet$} Limited em\TeX\ specials.  The following ones are supported:
{\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$}
\special{em:message xxx}
\special{em:point n}
\special{em:line a[h|v|p],b[h|v|p] [,width]}
\special{em:linewidth width}
\special{em:moveto}
\special{em:lineto} end$endverb}
\item{}
  The \.{\ttbackslash special{\char123}em:graph xxx{\char125}} 
  is not supported.
  The line cut parameters \.{[h|v|p]} of the
  \.{\ttbackslash special{\char123}em:line ...{\char125}} command are ignored.
  Lines are ended with a rounded cap.
  A maximum of 1613 different point numbers are permitted on each page.

The program \.{dvips} can use em\TeX\ font libraries created with the 
em\TeX\ \.{fontlib /2} option .
If a \.{pxl} font is found within a font library, \.{dvips} will complain,
and then ignore the \.{pxl} font.

The font library names and directory names can be specified with 
this configuration file option.

{\options
\def\o#1 #2:{{\tt #1} {\it #2}:}
\def\O#1:{{\tt #1}:}
\o L path:  The list of \.{fli} font libraries to search for bitmap \.{pk}
  font files is {\it path}.  
\^{{\tt fli}}
  Fonts are sought first in these libraries and then as single files.
  Font libraries can be created with em\TeX 's \.{fontlib}; the usual
  extension is \.{fli}.  Directories as well as file names can be 
  entered here, the files will be searched for in all these directories.
  A directory name must have trailing directory separator
  (\.{/} for UNIX, \.{\ttbackslash} for MS-DOS). \par }
\fi

\sec{Installation}

If \.{dvips} has not already been installed on your system, the
\^{installation}
following steps is all that it takes.

First update the \.{Makefile}---in particular, the paths.  Everything
concerning \.{dvips} can be adjusted in the \.{Makefile}.

Next, check the file name definitions in \.{MakeTeXPK}.  If you don't
\^{{\tt MakeTeXPK}}
have \MF\ installed, you cannot use \.{MakeTeXPK} to automatically
generate the fonts; you can, however, modify it to generate \.{pk}
fonts from \.{gf} fonts if you don't have a full set of \.{pk} fonts
but do have a set of \.{gf} fonts.  If you don't have that, you should
probably not install \.{MakeTeXPK} at all; this will disable automatic
font generation.

Now, check the configuration parameters in \.{config.ps}.  This is the
system-wide configuration file that will be automatically installed.
If you are unsure how much memory your PostScript printer has, print the
following file:
\cmd{\%! Hey, we're PostScript\\
/Times-Roman findfont 30 scalefont setfont 144 432 moveto\\
vmstatus exch sub 40 string cvs show pop showpage}
\noindent
Note that the number returned by this file is the total memory free;
it is often a good idea to tell \.{dvips} that the printer has somewhat
less memory.  This is because many programs download permanent macros
that can reduce the memory in the printer.  In general, a memory size
of about \.{300000} is plenty, since \.{dvips} can automatically split
a document if required.  It is unfortunate that PostScript printers with
much less virtual memory still exist.
Some systems or printers can dynamically increase the memory available
to a PostScript interpreter; for these systems, a value of one million
works well.

Next, run \.{make}.  Everything should compile smoothly.  You may need
to adjust the compiler options in the \.{Makefile} if something goes
amiss.

Once everything is compiled, run \.{make install}.  After this is done,
you may want to create a configuration file for each PostScript printer
at your site.

If the font caching is considered a security hole, make the `cache'
directory be something like \.{/tmp/pks}, and \.{cron} a job to move the
good \.{pk} files into the real directory.  Or simply disable this
feature by not installing \.{MakeTeXPK}.

Don't forget to install the new \.{vf} files or \.{tfm} files.  Note
that the \.{tfm} files distributed with earlier (pre-5.4) versions
of \.{dvips}, and all versions of other PostScript drivers, are different.

\sec{Diagnosing Problems}

You've gone through all the trouble of installing \.{dvips}, carefully
read all the instructions in this manual, and still can't get something
to work.  This is all too common, and is usually caused by some broken
PostScript application out there.  The following sections provide some
helpful hints if you find yourself in such a situation.

In all cases, you should attempt to find the smallest file that causes
the problem.  This will not only make debugging easier, but it will
reduce the number of possible interactions among different parts of the
system.

\sub{Debug Options}

The \.{-d} flag to \.{dvips} is very useful for helping to track down
certain errors.  The parameter to this flag is an integer that tells
what errors are currently being tracked.  To track a certain class of
debug messages, simply provide the appropriate number given below;
if you wish to track multiple classes, sum the numbers of the classes
you wish to track.  The classes are:

$$\vbox{\halign{\hfil #\quad&#\hfil\cr
1&specials\cr2&paths\cr4&fonts\cr8&pages\cr16&headers\cr
32&font compression\cr64&files\cr}}$$

\sub{No Output At All}

If you are not getting any output at all, even from the simplest
one-character file (for instance, \.{\char92~\char92 bye}),
then something is very wrong.  Practically any file sent to a
PostScript laser printer should generate some output, at the very
least a page detailing what error occurred, if any.  Talk to your
system administrator about downloading a PostScript error handler.
(Adobe distributes a good one called \.{ehandler.ps}.)

It is possible, especially if you are using non-Adobe PostScript,
that your PostScript interpreter is broken.  Even then it should
generate an error message.  I've tried to work around as many bugs
as possible in common non-Adobe PostScript interpreters, but I'm
sure I've missed a few.

If \.{dvips} gives any strange error messages, or compilation on your
machine generated a lot of warnings, perhaps the \.{dvips} program
itself is broken.  Carefully check the types in \.{structures.h} and
the declarations in the \.{Makefile}, and try using the debug options
to determine where the error occurred.

It is possible your spooler is broken and is misinterpreting the
structured comments.  Try the \.{-N} flag to turn off the
structured comments and see what happens.

\sub{Output Too Small or Inverted}

If some documents come out inverted or too small, your spooler is not
supplying an end of job indicator at the end of each file.  (This happens
a lot on small machines that don't have spoolers.)  You can
force \.{dvips} to do this with the \.{-F} flag, but note that this
generates files with a binary character (control-D) in them.  You can
also try using the \.{-s} flag to enclose the entire job in a save/restore
pair.

\sub{Error Messages From Printer}

If your printer returns error messages, the error message gives very
good information on what might be going wrong.  One of the most common
error messages is \.{bop undefined}.  This is caused by old versions
of Transcript and other spoolers that do not properly parse the
setup section of the PostScript.  To fix this, turn off structured
comments with the \.{-N} option, but make sure you get your spooling
software updated.

Another error message is \.{VM exhausted}.  (Some printers indicate
this error by locking up; others quietly reset.)  This is caused by telling
\.{dvips} that the printer has more memory than it actually does, and
then printing a complicated document.  To fix this, try lowering the
parameter to \.{m} in the configuration file; use the debug option
to make sure you adjust the correct file.

Other errors may indicate that the graphics you are trying to include
don't nest properly in other PostScript documents, or any of a number of
other possibilities.  Try the output on a QMS PS-810 or other Adobe
PostScript printer; it might be a problem with the printer itself.

\sub{400 DPI Is Used Instead Of 300 DPI}

This common error is caused by not editing the \.{config.ps} file to
reflect the correct resolution for your site.  You can use the debug flags
(\.{-d64}) to see what files are actually being read.

\sub{Long Documents Fail To Print}

This is usually caused by incorrectly specifying the amount of memory
the printer has in \.{config.ps}; see the description above.

\sub{Including Graphics Fails}

The reasons why graphics inclusions fail are too numerous to mention.
The most common problem is an incorrect bounding box; read the section
on bounding boxes and check your PostScript file.  Complain very loudly
to whoever wrote the software that generated the file if the bounding
box is indeed incorrect.

Another possible problem is that the figure you are trying to include
does not nest properly; there are certain rules PostScript applications
should follow when generating files to be included.  The \.{dvips}
program includes work-arounds for such errors in Adobe Illustrator and
other programs, but there are certainly applications that haven't
been tested.

One possible thing to try is the \.{-K} flag, to strip the comments from
an included figure.  This might be necessary if the PostScript spooling
software does not read the structuring comments correctly.  Use of this
flag will break graphics from some applications, though, since some
applications read the PostScript file from the input stream looking for
a particular comment.

Any application which generates graphics output containing raw binary
(not hex) will probably fail with \.{dvips}.

\sub{Can't Find Font Files}

If \.{dvips} complains that it cannot find certain font files, it is
possible that the paths haven't been set up correctly for your system.
Use the debug flags to determine precisely what fonts are being looked
for and make sure these match where the fonts are located on your system.

\sub{Can't Generate Fonts}

This happens a lot if either \.{MakeTeXPK} hasn't been properly edited
and installed, or if the local installation of \MF\ isn't correct.
If \.{MakeTeXPK} isn't properly edited or isn't installed, an error
such as \.{MakeTeXPK not found} will be printed on the console.  The
fix is to talk to the person who installed \.{dvips} and have them fix
this.

If \MF\ isn't found when \.{MakeTeXPK} is running, make sure it is installed
on your system.  The person who installed \TeX\ should be able to install
\MF\ easily.

If \MF\ runs but generates fonts that are too large (and prints out the
name of each character as well as just a character number), then your
\MF\ base file probably hasn't been made properly.  To make a proper
\.{plain.base}, assuming the local mode definitions are contained in
\.{local.mf} (on the NeXT, \.{next.mf}; on the Amiga, \.{amiga.mf}),
type the following command (assuming \.{csh} under Unix):
\cmd{localhost> inimf "plain; input local; dump"}
\noindent
Now, copy the \.{plain.base} file from the current directory to where
the base files are stored on your system.

Note that a preloaded \.{cmbase.base} should never be used when creating
fonts, and a program such as \.{cmmf} should never exist on the system.
The macros defined in \.{cmbase} will break fonts that do not use
\.{cmbase}; such fonts include the La\TeX\ fonts.  Loading the \.{cmbase}
macros when they are needed is done automatically and takes less than a
second---an insignificant fraction of the total run time of \MF\ for a
font, especially when the possibility of generating incorrect fonts is
taken into account.

\bye
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦4af975f93⟧ TextFile

Derivation

TextFile
