\input texinfo
@setfilename dvips.info
@settitle Dvips: A DVI driver

@set version 5.58f
@set month-year January 1995

@c Define a new index for filenames and options.
@defcodeindex fl
@defcodeindex op

@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fl cp
@syncodeindex fn cp
@syncodeindex op cp
@syncodeindex pg cp
@syncodeindex vr cp

@titlepage
@title Dvips: A DVI-to-PostScript Translator
@subtitle for version @value{version}
@subtitle @value{month-year}
@author Tomas Rokicki
@author (edited for Dvipsk by @samp{kb@@cs.umb.edu})

@page
@vskip 0pt plus 1filll
This document is based on @file{dvips.tex} by Tomas Rokicki.  It is
in the public domain.
@end titlepage

@ifinfo 
@format
START-INFO-DIR-ENTRY
* Afm2tfm: (dvips)Using afm2tfm.  Making Type 1 fonts available to TeX.
* DVIps: (dvips).	 	DVI-to-PostScript translator.
END-INFO-DIR-ENTRY
@end format

@node Top
@top Dvips

This manual documents Dvips, a program to translate a DVI file into
PostScript.  It corresponds to version @value{version} of the Dvipsk
distribution, a slightly modified variant of the original Dvips
progam with path searching rules consistent with @TeX{}, the GNU font
utilities, and Xdvik.  Tom Rokicki wrote and maintains Dvips;
@samp{kb@@cs.umb.edu} made the Dvipsk modifications.

@menu
* Why dvips::                   Why use dvips?
* Using dvips::                 Minimal usage information.
* Paper size and landscape::    Changing the paper dimensions.
* Including PostScript::        Including PostScript graphics.
* PostScript fonts::		Installing and using PostScript fonts.
* Color::                       Using color with dvips.
* Invoking Dvips::              Command-line options, etc.
* Bells and Whistles::          Other nifty things
* Installation::                How to compile and install dvips.
* Index::                       
@end menu
@end ifinfo


@node Why dvips
@chapter 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 of using dvips, and may be skipped if you are just
interested in learning how to use the program.  @xref{Installation}, for
details of compilation and installation.

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 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
directions.  High resolution output is supported for typesetters,
including an option that compresses the bitmapped fonts so that
typesetter virtual memory is 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 @sc{metafont} exists on
the system, or fonts can be converted from @samp{gf} to @samp{pk} format
on demand.  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
@file{tpic}, @file{psfig}, @file{emtex}, and @file{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 @file{lpr}.  Support for MS-DOS, OS/2, and
VMS in addition to UNIX is provided in the 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.  Dvips 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 will be available to create beautiful documents.
So if you don't use dvips on your system, get it today.


@node Using dvips
@chapter Introduction to Dvips

To use dvips, simply type

@example
dvips foo
@end example

@noindent
where @file{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 (@pxref{Dvips options}).  For a brief summary
of available options, just type

@example
dvips
@end example


@node Paper size and landscape
@chapter Paper size and landscape orientation

@cindex paper size
@cindex landscape orientation

Most @TeX{} documents at a particular site are designed to use the
standard paper size (letter size in the United States,
A4 in Europe.)  The dvips program defaults to these paper
sizes and can be customized for the defaults at each site or on
each printer.

But many documents are designed for other paper sizes.  For instance,
you may want to design a document that has the long edge of the 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).
Alternatively, a document might be designed for ledger or A3 paper.

Since the intended paper size is a document design decision, and not a
decision that is made at printing time, such information should be given
in the @TeX{} file and not on the dvips command line.  For this
reason, dvips supports a @samp{papersize} special.  It is hoped
that this special will become standard over time for @TeX{} previewers
and other printer drivers.

The format of the @samp{papersize} special is

@example
\special@{papersize=8.5in,11in@}
@end example

@noindent
where the dimensions given above are for a standard letter sheet.
The first dimension given is the horizontal size of the page, and
the second is the vertical size.  The dimensions supported are
the same as for @TeX{}; namely, in (inches), cm (centimeters), mm
(millimeters), pt (points), sp (scaled points), bp (big points, the
same as the default PostScript unit), pc (picas), dd (didot points),
and cc (ciceros).

For a landscape document, the @samp{papersize} comment would be given as

@example
\special@{papersize=11in,8.5in@}
@end example

@noindent
An alternate specification of @samp{landscape} is to have a special
of the form

@example
\special@{landscape@}
@end example

@noindent
This is supported for backward compatibility, but it is hoped that
eventually the @samp{papersize} comment will dominate.

Of course, using such a command only informs dvips of the desired
paper size; you must still adjust the @samp{hsize} and @samp{vsize} in
your @TeX{} document to actually use the full page.

The @samp{papersize} special must occur somewhere on the first page of
the document.


@node Including PostScript
@chapter Including PostScript Graphics

@cindex graphics
@cindex PostScript graphics

Scaling and including PostScript graphics is a breeze---if the PostScript
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.

@menu
* Bounding Box::                The Bounding Box Comment
* EPSF Macros::                 Using the EPSF Macros
* Header files::                Header files
* Literal PS::                  Literal PostScript
* Literal headers::             Literal Headers
* Graphics Support::            Other Graphics Support
* Dynamic Creation of Graphics::  
@end menu


@node Bounding Box
@section The Bounding Box Comment

@cindex bounding box
Every well-formed PostScript file has a comment describing where on the
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 the 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

@example
%%BoundingBox: 0 1 2 3
@end example

@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

@example
%%BoundingBox: (atend)

@end example
@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 same text editor, or with a simple Perl script.

If the document lacks a bounding box altogether, one can easily be 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.  Alternatively, the @samp{bbfig} program distributed with
dvips in the @file{contrib} directory can be used to automate
this process.

From the left edge of the paper to the leftmost mark on the paper is
@var{llx}, the first number.  From the bottom edge of the paper to the
bottommost mark on the paper is @var{lly}, the second number.  From
the left edge of the paper to the rightmost mark on the paper is
@var{urx}, the third number.  The fourth and final number, @var{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 @samp{%!}; if it is not, the file probably isn't PostScript.)

@example
%%BoundingBox: @var{llx} @var{lly} @var{urx} @var{ury}
@end example

@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.


@node EPSF Macros
@section Using the EPSF Macros

@cindex epsf macros
@cindex macros for epsf inclusion

Now you are ready to include the graphic into a @TeX{} file.  Simply add to
the top of your @TeX{} file a line like

@flindex epsf.tex
@example
\input epsf
@end example

@noindent
(or, if your document is in La@TeX{} or SliTeX, add the @samp{epsf} style
option, as was done to the following line).

@example
\documentstyle[12pt,epsf]@{article@}
@end example

@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

@findex \epsffile
@example
\epsffile@{foo.ps@}
@end example

@noindent
If you are using La@TeX{} or Sli@TeX{}, you may need to add a
@samp{\leavevmode} command immediately before the
@findex \leavevmode
@samp{\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:

@example
\epsffile[100 100 500 500]@{foo.ps@}
@end example

@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 @samp{epsffile} macro is to typeset the figure as a @TeX{}
@samp{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 @samp{dvi} magnification in effect at the
@cindex magnification
time.

Any PostScript graphics included by any method in this document (except
@cindex @samp{bop-hook}
@samp{bop-hook} and its ilk) are scaled by the current @samp{dvi} magnification.
For graphics included with @samp{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
@cindex magscale
this scaling off with the following @TeX{} command:

@example
\special@{! /magscale false def@}
@end example

@noindent
Use of this command is not recommended because it will make the
@samp{epsffile} graphics the wrong size if global magnification is used
in a @samp{dvi} document, and it will cause any PostScript graphics to
appear improperly scaled and out of position if a @samp{dvi} to @samp{dvi}
program is used to scale or otherwise modify the document.

You can enlarge or reduce the figure by putting

@example
\epsfxsize=@var{dimen}
@end example

@noindent
right before the call to @samp{epsffile}.
Then the width of the @TeX{} box will be @var{dimen} and its'
height will be scaled proportionately.  Alternatively you can force the
@cindex epsfxsize
vertical size to a particular size with

@example
\epsfysize=@var{dimen}
@end example

@noindent
in which case the height will be set and the width will be scaled
proportionally.  If you set both, the aspect ratio of the included
graphic will be distorted but both size specifications will be
honored.

By default, clipping is disabled for included EPSF images.  This is
because clipping to the bounding box dimensions often cuts off a
small portion of the figure, due to slightly inaccurate bounding
box arguments.  The problem might be subtle; lines around the boundary
of the image might be half their intended width, or the tops or
bottoms of some text annotations might be sliced off.  If you want to
turn clipping on, just use the command

@example
\epsfclipon
@end example

@noindent
and to turn clipping back off, use

@example
\epsfclipoff
@end example

A more general facility for sizing is available by defining the
@samp{epsfsize} macro.   You can redefine this macro
@cindex epsfsize
to do almost anything.  This @TeX{} macro is passed two parameters
by @samp{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 @samp{epsfxsize} above).

In the definitions given below, only the body is given; it should be inserted
in

@example
\def\epsfsize#1#2@{@var{body}@}
@end example

@noindent
Some common definitions are:

@table @samp

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

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

@item #1
This forces natural sizes too, by returning the first parameter only
(the natural width) and setting the width to it.

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

@item 0.5#1
This scales all figures to half of their natural size.

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

@end table

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

@example
\epsfverbosetrue
@end example


@node Header files
@section Header files

@cindex header files

Often in order to get a particular graphic file to work, a certain 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
@samp{header=} special command.  For instance, to ensure that @file{foo.ps}
gets downloaded as part of the header material, the following command
should be added to the @TeX{} file:

@example
\special@{header=foo.ps@}
@end example

@noindent
The dictionary stack will be at the @samp{userdict} level when these header
files are included.

For these and all other header files (including the headers required
by dvips itself and any downloaded fonts), the printer VM budget is
debited by some value.  If the header file has, in its first 1024 bytes,
a line of the form

@vindex VMusage
@example
%%VMusage: @var{min} @var{max}
@end example

@noindent
then the maximum value is used.  If it doesn't, then the total size of
the header file in bytes is used as an approximation of the memory
requirements.


@node Literal PS
@section Literal PostScript

@cindex literal PostScript

For simple graphics, or just for experimentation, literal PostScript
graphics can be included.  Simply use a @samp{\special} beginning with
a double quote (@samp{"}) (no closing @samp{"}).

For instance, the following (simple) graphic:
@iftex 
@tex
\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}}
@end tex
@end iftex
@noindent
was created by typing:

@example
\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@}@}
@end example

@ifinfo
[ There is a picture of a triangle on hardcopy printouts and in the
PostScript file generated by @file{dvips}.
@end ifinfo
(You are responsible for leaving space for such literal graphics.)
Literal graphics are discouraged because of their nonportability.


@node Literal headers
@section Literal Headers

@cindex 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
@samp{SDict}.  This dictionary
@cindex SDict
is the first one on the PostScript dictionary stack when any PostScript
graphic is included, whether by literal inclusion or through the
@samp{epsffile} macros.


@node Graphics Support
@section Other Graphics Support

@cindex graphics support

There are other ways to include graphics with dvips.  One is to use an
existing package, such as @file{emtex}, @file{psfig}, @file{tpic}, or
@file{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.  The main advantage of the @samp{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:

@example
\special@{psfile=@var{filename.ps}[@var{key}=@var{value}]*@}
@end example

@noindent
This will download the PostScript file called @file{filename.ps} such
that the current point will be the origin of the PostScript
@cindex psfile
coordinate system.  The optional key/value assignments allow you to
specify transformations on the PostScript.

The possible keys are:

@table @samp

@item hoffset
The horizontal offset (default 0)

@item voffset
The vertical offset (default 0)
@item hsize	
The horizontal clipping size (default 612)
@item vsize	
The vertical clipping size (default 792)
@item hscale	
The horizontal scaling factor (default 100)
@item vscale	
The vertical scaling factor (default 100)
@item angle	
The rotation (default 0)
@item clip    
Enable clipping to the bounding box
@end table

The dimension parameters are all given in PostScript units.
The @samp{hscale} and @samp{vscale} are given in non-dimensioned percentage
units, and the rotation value is specified in degrees.
Thus

@example
\special@{psfile=foo.ps hoffset=72 hscale=90 vscale=90@}
@end example

@noindent
will shift the graphics produced by file @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, scale it, then offset it.

For compatibility with older PostScript drivers, it is possible to change
the units that @samp{hscale} and @samp{vscale} are given in.  This can be
done by redefining @samp{@@scaleunit}
@vindex scaleunit
in @samp{SDict}
@vindex SDict
by a @TeX{} command such as

@example
\special@{! /@@scaleunit 1 def@}
@end example

@noindent
The @samp{@@scaleunit} variable, which is by default 100, is what
@samp{hscale} and @samp{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, guaranteeing 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:

@example
\special@{ps:@var{text}@}
\special@{ps::@var{text}@}
\special@{ps::[begin]@var{text}@}
\special@{ps::[end]@var{text}@}
@end example

@noindent
(with longer forms taking precedence over shorter forms, when they are
used).  Note that @samp{ps::} and @samp{ps::[end]} do not do any
positioning, so they can be used to continue PostScript literals started
with @samp{ps:} or @samp{ps::[begin]}.  There is also the command

@example
\special@{ps: plotfile @var{filename}@}
@end example

@noindent
which will copy the commands from @var{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 @samp{rotate.tex} which
makes it easy to typeset text turned 90 degrees.

To finish off this section, the following examples are presented without
explanation:

@example
\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
@end example

@iftex
@tex
\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
@end tex
@end iftex
@ifinfo
[ There are 4 @samp{A} characters, each rotated 90 degrees about a
  common center point ]
@end ifinfo


@example
\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@}
@end example

@iftex
@tex
\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}
@end tex
@end iftex
@ifinfo
[ There is a big gray box with the word @samp{NEAT} inside in big letters ]
@end ifinfo

Some caveats are in order when using the above forms.  Make sure that
each @samp{gsave} on a page is matched with a @samp{grestore} on the
same page.  Do not use @samp{save} or @samp{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.  
@findex \rotninety
The @samp{\rotninety} macro especially has a
useful trick that appears again and again.


@node Dynamic Creation of Graphics
@section Dynamic Creation of PostScript Graphics Files

@cindex dynamic creation of graphics
@cindex compressed PostScript
@cindex uncompressing PostScript

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 (@samp{`}), the filename is instead interpreted
as a command to execute that will send the actual file to standard
output.  Thus,

@example
\special@{psfile="`zcat foo.ps.Z"@}
@end example

@noindent
will include the uncompressed version of @file{foo.ps}.  Since such a
command is not accessible to @TeX{}, if you use this facility with
the @samp{EPSF} macros, you need to supply the bounding box parameter
yourself, as in

@example
\epsffile[72 72 540 720]@{"`zcat screendump.ps.Z"@}
@end example

@noindent
to include @file{screendump.ps}.  Of course, the commands to be executed
can be anything, including using a file conversion utility such as
@file{tek2ps} or whatever is appropriate.

This extension is not portable to other DVI-to-PostScript translators.


@node PostScript fonts
@chapter PostScript fonts

@cindex installing PostScript fonts
@cindex PostScript fonts, installing and using

Dvips supports the use of PostScript fonts in @TeX{} documents.  To use
a PostScript font conveniently, you need to prepare a corresponding
virtual font; the program Afm2tfm, supplied with Dvips, helps
with that.

All the necessary support for the standard 35 PostScript fonts
(@samp{AvantGarde-Book} through @samp{ZapfDingbats}), plus other freely
or commonly available PostScript fonts, comes with Dvips.  To use those
fonts, you need do nothing beyond the normal Dvips installation
(@pxref{Installation}).  This chapter is therefore relevant only if you
are installing new PostScript fonts not supplied with Dvips. (Or if
you're curious.)

(In fact, some the fonts supplied with Dvips contain a few modifications
to make them work as well as possible with @TeX{}.  So don't expect that
following the steps in ths manual will necessarily generate identical
files to those in the distribution.)

@menu
* Font concepts::               Metrics, glyphs, virtual fonts, and encodings.
* Making a font available::     Installing and using a PostScript font.
* Invoking afm2tfm::            Creating TFM and AFM files for a virtual font.
* psfonts.map::                 Associating fonts with their files.
@end menu


@node Font concepts
@section Font concepts

@cindex font concepts
All the information about an ordinary font that's needed to typeset the
font is contained in two files: a @dfn{metric file} that contains
shape-independent information and a @dfn{glyph file} that contains the
actual shapes of the font's characters.

A @dfn{virtual font} is an additional file that specifies where the
characters in the font come from, or how they are constructed.  @TeX{}
itself (and La@TeX{}) only look at the metric file, but DVI drivers
such as Dvips look at all three of these files.

An @dfn{encoding file} records the correspondence between the code
numbers of the characters in a font and their descriptive names.  Two
encoding files used together can describe a reencoding that rearranges,
i.e., renumbers, the characters of a font.

@menu
* Metric files::                Shape-independent font information.
* Glyph files::                 Character shapes.
* Virtual fonts::               Constructing one font from others.
* Encodings::                   Character codes and character names.
* PostScript typesetting::      How PostScript typesets a character.
@end menu


@node Metric files
@subsection Metric files

@cindex metric files

A @dfn{metric file} describes properties of the font that are
independent of what the characters actually look like.  Aside from
general information about the font itself, a metric file has two kinds
of information: information about individual characters, organized by
character code, and information about sequences of characters.

The per-character information specifies the width and height of each
character in the font.  It also specifies each character's depth and
italic correction if those are nonzero.

@cindex kerning
@cindex ligatures
In addition to information on individual characters, the metric file
specifies @dfn{kerning}, i.e., adding or removing space between
particular character pairs.  It further specifies @dfn{ligature}
information: when a sequence of input characters should be typeset as a
different character, namely, the ligature character.  For example, it's
traditional for the input @samp{fi} to be typeset as `fi', not as
`@r{f}@r{i}'.  (In English, the only common ligatures are fi, fl, ff,
ffi, and ffl.)

Different typesetting systems use different formats for their metrics
files:

@itemize @bullet

@item
@cindex afm files
Each Postscript font has an @dfn{Adobe font metrics} (@samp{.afm})
file. These files are plain text, so you can inspect them easily. The
AFM files for most of Adobe's fonts are publicly available and
redistributable, but the files defining the actual shapes are not
publicly available (you have to buy those from Adobe).  You can get
Adobe's AFM files by ftp from @samp{ftp.mv.us.adobe.com}.

@item 
@cindex tfm files
@TeX{} uses @dfn{@TeX{} font metrics} (@samp{.tfm}) files. When you say
@samp{\font = @var{font}} in your @TeX{} document, @TeX{} looks for a
file named @samp{@var{font}.tfm}.  @TeX{} uses that file to calculate
the space occupied by characters from the font. In addition, the DVI
drivers you use to print or view the DVI file produced by @TeX{} may
need to look at the TFM file.

@cindex property list files
@pindex tftopl
@pindex pltotf
TFM files are binary (and hence are typically much smaller than AFM
files). You can use the @code{tftopl} program that comes with @TeX{} to
transform a TFM file into a human-readable ``property list''
(@samp{.pl}) file.  You can also edit a PL file and transform it back to
a @TeX{}-readable TFM with the companion program @code{pltotf}. (Editing
metrics by hand is not something you're likely to want to do often, but
the capability is there.)

@cindex pfm files
@item
ATM and other typesetting systems use @dfn{printer font metric}
(@samp{.pfm}) files. These are binary files. They are irrelevant in the
@TeX{} world, and not freely available, so we will not discuss them
further.

@end itemize

The Afm2tfm program distributed with Dvips converts an AFM file
to a TFM file and performs other useful transformations as well.


@node Glyph files
@subsection Glyph files

@cindex glyph files

Although a metric file (see the previous section) contains information
about the spatial and other properties of the character at position 75,
say, it contains nothing about what the character at position 75
actually looks like. The @dfn{glyphs}---the actual shapes of the
letterforms in a font---are defined by other files. @TeX{} itself reads
only the TFM file for a font; it does not need to know what the glyphs
of the characters are.

A @dfn{glyph file} is a file that defines the shapes of the characters
in a font.  The shapes can be defined either by outlines or by bitmaps.

@cindex outline fonts
@cindex arcs
@cindex splines
PostScript fonts are defined as @dfn{outline fonts}: Each character in
the font is defined by giving the mathematical curves (lines, arcs, and
splines) that define its contours.  Different sizes of a character are
generated by linearly scaling a single shape. For example, a 10-point
`A' is simply half the size of a 20-point `A'.  Nowadays, outline fonts
usually also contain @dfn{hints}---additional information that modifies
the outline slightly to improve the appearance of the font at small
sizes or low resolutions.

@cindex Type 1 fonts
@cindex pfa files
@cindex pfb files
Although there are various kinds of PostScript outline fonts, by far the
most common is @dfn{Type 1} fonts.  For our purposes, the differences
between the types are unimportant.  The glyph files for Postscript Type
1 fonts typically have names ending in @samp{.pfa} (``printer font
ascii'') or @samp{.pfb} (``printer font binary'').

@cindex bitmapped fonts
In contrast, Computer Modern and the other standard @TeX{} fonts are
defined as @dfn{bitmapped fonts}, generated from Metafont (@samp{.mf})
descriptions.  The Metafont program distributed with @TeX{} generates
bitmapped fonts from these descriptions, which are essentially outlines.

@cindex pk files
The glyph files for @TeX{} bitmapped fonts are usually stored in
@dfn{packed font} (PK) files.  The names of these files end in
@samp{.pk@var{n}}, where @var{n} is the resolution of the font in dots
per inch.  For example, @file{cmr10.300pk} contains the bitmap for the
@samp{cmr10} font at 300 dpi resolution.

@cindex gf files
@pindex gftopk
Metafont actually outputs @dfn{generic font} (GF) files, e.g.,
@file{cmr10.300gf}, but the GF files are usually converted immediately
to PK format (using the @code{gftopk} utility that comes with @TeX{})
since PK files are smaller and contain the same information. (The GF
format is a historical artifact.)


@node Virtual fonts
@subsection Virtual fonts

@cindex virtual fonts

A @dfn{virtual font} is constructed by extracting characters from one or
more existing fonts and rearranging them, or synthesizing new characters
in various ways.  The explanation in this manual is intended to suffice
for understanding enough about virtual fonts to use them with Dvips. It
isn't a reference manual on virtual fonts.

@cindex vf files
@cindex vpl files
A virtual font (@samp{.vf}) file specifies, for each character in the
virtual font, a recipe for typesetting that character.  A VF file, like
a TFM file, is in a compressed binary format.  The @code{vftovp} and
@code{vptovf} programs convert a VF file to a human-readable VPL
(virtual property list) format and back again.

@cindex base fonts
In the case of a PostScript font @var{f} being used in a straightforward
way, the recipe says: ``character @var{i} in the VF font is character
@var{j} in font @var{f}''.  The font @var{f} is called a @dfn{base
font}. Here, the only function of the VF file is to remap the characters
of the PostScript font to the positions where @TeX{} expects to find
them.  @xref{Encodings}.

Since @TeX{} reads only TFM files, not VF's, each VF must have a
corresponding TFM for use with @TeX{}.  This corresponding TFM is
created when you run @code{vptovf}.

For more information: The primary document on virtual fonts is Donald
E. Knuth, @cite{TUGboat} 11(1), Apr.@: 1990, pp.@: 13--23, ``Virtual
Fonts: More Fun for Grand Wizards''.  (Unfortunately, the subtitle of
that article alone would intimidate almost anyone.)


@node Encodings
@subsection Encodings

@cindex encodings

Every font, whatever its type, has an @dfn{encoding}, that specifies the
correspondence between ``logical'' characters and character codes.  For
example, the ASCII encoding specifies that the character numbered 65
(decimal) is an uppercase `A'.  The encoding does @emph{not} specify
what the character at that position looks like; there are lots of ways
to draw an `A', and a glyph file (@pxref{Glyph files}) tells how.  Nor
does it specify how much space that character occupies; that information
is in a metric file (@pxref{Metric files}).

@TeX{} implicitly assumes a particular encoding for the fonts you use
with it.  For example, the plain @TeX{} macro @code{\'}, which typesets
an acute accent over the following letter, assumes the acute accent is
at position 19 (decimal). This happens to be true of the standard @TeX{}
fonts, as you might expect, but it is @emph{not} true of normal
PostScript fonts.

It's possible but painful to change all the macros that assume
particular character positions.  A better solution is to create a new
font with the information for the acute accent at position 19, where
@TeX{} expects it to be.  @xref{Making a font available}.

@cindex PostScript encoding
@cindex encoding files
@cindex encoding vectors
One particular way to represent an encoding is as a sequence of 256
character names called an @dfn{encoding vector}.  An @dfn{encoding file}
(@samp{.enc}) stores this vector, together with ligature and kerning
information (with which we are not concerned at the moment).  These
encoding files are used by the Afm2tfm program.  Encoding files are also
downloaded to the PostScript interpreter in your printer if you use one
of them in place of the default encoding vector for a particular
PostScript font.

@flindex dvips.enc
@flindex texmext.enc
@flindex texmital.enc
@flindex texmsym.enc
Examples of encodings: the @file{dvips.enc} encoding file that comes
with Dvips is a good (but not perfect) approximation to the @TeX{}
encoding for @TeX{}'s Computer Modern text fonts.  The distribution also
includes three other encoding files corresponding to the @TeX{}
mathematics fonts: @file{texmext.enc} for math extensions,
@file{texmital.enc} for math italics, and @file{texmsym.enc} for math
symbols.


@node PostScript typesetting
@subsection How PostScript typesets a character

@cindex typesetting in PostScript
@cindex character lookup procedure in PostScript

The output of Dvips is a program in the PostScript language that
instructs your (presumably PostScript-capable) printer how to typeset
your document by transforming it into toner on paper.  Your printer, in
turn, contains a PostScript interpreter that carries out the
instructions in this typesetting program.

Part of the program is the definition of any PostScript fonts that you
use in your document.  Fonts that come with your printer (probably the
``standard 35'', including @samp{Times-Roman}, @samp{Symbol}, @dots{})
are always defined.  Other fonts must be downloaded as pfa or pfb files
(@pxref{Glyph files}) from your computer.  (The one on which you're
running Dvips.)

You may be wondering exactly how a PostScript interpreter figures out
what character to typeset, with this mass of metrics, glyphs, encodings,
and other information.  If you're not wondering, skip this section @dots{}

@findex show @r{PostScript operator}
The basic PostScript operator for imaging characters is
@code{show}. Suppose you've asked @TeX{} to typeset an `S'. This will
eventually wind up in the Dvips output as something equivalent to this:

@example
(S) show
@end example

@noindent Here is how PostScript typesets the S:

@enumerate

@cindex ASCII, used by PostScript
@item PostScript interpreters use ASCII; therefore `S' is represented as the
integer 83. (Any of the 256 possible characters representable in a
standard 8-bit byte can be typeset.)

@cindex current font, in PostScript
@cindex dictionaries, in PostScript
@item
A PostScript @dfn{dictionary} is a mapping of names to arbitrary values.
A font, to the interpreter, is a dictionary which contains entries for
certain names.  (If these entries are missing, the interpreter refuses
to to do anything with that font.)

PostScript has a notion of ``the current font''---whatever font is
currently being typeset in.

@cindex encoding vector
@item 
One of these mandatory entries in a font dictionary is @samp{Encoding},
which defines the encoding vector (@pxref{Encodings}) for that font.
This vector of 256 names maps each possible input character to a name.

@item
The interpreter retrieves the entry at position 83 of the encoding
vector. This value is a PostScript name: @code{/S}.

@findex CharStrings @r{dictionary}
@item
For Type 1 fonts (we're not going to discuss anything else), the
interpreter now looks up @code{/S} as a key in a dictionary named
@code{CharStrings}.  (@samp{CharStrings} is another of the mandatory
entries in a font dictionary.)

@cindex hints
@cindex character definitions in PostScript
@item
The value of @code{S} in @code{CharStrings} is the equivalent of a
series of standard PostScript commands like @samp{curveto},
@samp{lineto}, @samp{fill}, and so on. These commands are executed to
draw the character. There can also be @dfn{hint} information that helps
adapt the character to low-resolution rasters.  (@xref{Glyph files}.)

(The commands are actually represented in a more compact way than
standard PostScript code; see the Type 1 book for details.)  

@end enumerate

This method for typesetting characters is used in both Level 1 and Level
2 PostScript.  See the PostScript reference manuals for more
information.


@node Making a font available
@section Making a PostScript font available

@cindex installing fonts
@cindex fonts, installing
To make a PostScript font available in a @TeX{} document, you need to
install the font on your system and then define it within the document.
Once you have installed the font, of course, it is available for any
document thereafter and you don't need to reinstall it.  You must have
an AFM file for any font you install. Unless the font is built into your
printer, you must also have a PFA or PFB file.

In the following examples, we use the font @samp{Times-Roman} to
illustrate the process.  (But you should use the files for Times
supplied with Dvips for actual use, as explained above.)

Installation of a PostScript font proceeds in three steps.  @xref{Font
concepts}, for descriptions of the various files involved.

@enumerate

@item
Run @code{afm2tfm} to create a TFM file for the original font,
and a VPL file for the corresponding virtual font.
@xref{Invoking afm2tfm}.

@item
Run @code{vptovf} to generate a VF and TFM file for the virtual font
from the VPL file.

@item
Insert entries for the font in the @file{psfonts.map} file.
@xref{psfonts.map}.

@end enumerate

The typical invocation of Afm2tfm goes something like this:

@example
afm2tfm Times-Roman -v ptmr rptmr
@end example

@noindent
This produces two files as output, namely the `virtual property list'
file @file{ptmr.vpl}, and the raw font metric file @file{rptmr.tfm}.
(The uppercase @samp{-V} also produces a @samp{vpl} file, but maps a set
of small caps into the lower case alphabet.)  To use the font in @TeX{},
you first run

@pindex vptovf
@example
vptovf ptmr.vpl ptmr.vf ptmr.tfm
@end example

@noindent
You should then install the virtual font file @file{ptmr.vf} where Dvips
will see it and install @file{ptmr.tfm} and @file{rptmr.tfm} where
@TeX{} and Dvips will see them.

You can also make more complex virtual fonts by editing @file{ptmr.vpl}
before running @samp{vptovf}; such editing might add the uppercase Greek
characters in the standard @TeX{} positions, for instance.  (This has
already been done for the font files supplied with Dvips.)

Once this has been done, you're all set. You can use code like this in
@TeX{} henceforth:

@example
\font\myfont = ptmr at 12pt
\myfont Hello, I am being typeset in 12-point Times-Roman.
@end example

Thus we have two fonts, one actual (@samp{rptmr}, which is analogous to
the font in the printer) and one virtual (@samp{ptmr}, which has been
remapped to the standard @TeX{} encoding (almost), and has typesetting
know-how added. You could also say

@example
\font\PTR = rptmr at 10pt
@end example

@noindent
and typeset directly with that, but then you would have no ligatures or
kerning, and you would have to use Adobe character positions for special
letters like
@tex
\AE.
@end tex
@ifinfo
the ligature `AE'.
@end ifinfo
The virtual font @samp{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).  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).

As a final step you need to record information about both the virtual
font and the original font (if you ever might want to use it) in the
@file{psfonts.map} file. @xref{psfonts.map}.  For our example, you'd
insert the following into @file{psfonts.map}:
@example
rptmr      Times-Roman                 <rptmr.pfa
@end example

@cindex memory
@cindex efficient fonts
These PostScript fonts can be scaled to any size.  Go wild!  Using
PostScript fonts, however, does use up a great deal of the printer's
memory and it does take time.  You may find downloading bitmapped fonts
(possibly compressed) to be faster than using the built-in PostScript
fonts.


@node Invoking afm2tfm
@section Invoking Afm2tfm

@pindex afm2tfm

The Afm2tfm program converts an AFM file for a PostScript font to a TFM
file and a VPL file for a corresponding virtual font (or, in its
simplest form, to a TFM file for the PostScript font itself).  The
results of the conversion are affected by the command-line options and
especially by the reencodings you can specify with those options.  You
can also obtain special effects such as an oblique font.

@menu
* Changing font encodings::     Reencoding with -t, -p, -T.
* Special font effects::        Oblique fonts, small caps, and such.
* afm2tfm options::             afm2tfm command-line options.
@end menu


@node Changing font encodings
@subsection Changing font encodings

@cindex encoding changes
@cindex fonts, changing encoding of

Afm2tfm allows you to specify a different encoding for a PostScript font
(for a general introduction to encodings, @pxref{Encodings}).  You do
this with @samp{-t} for the @TeX{} encoding, @samp{-p} for the
PostScript encoding, or with @samp{-T} for both simultaneously.

@menu
* Changing TeX encodings::           -p changes what TeX sees.
* Changing PostScript encodings::    -t changes what PostScript sees.
* Changing both encodings::          -T changes both.
* Reencoding with Afm2tfm::          Problem with the default encoding.
* Encoding file format::             Syntax of an encoding file.
@end menu


@node Changing TeX encodings
@subsubsection Changing @TeX{} encodings

@cindex @TeX{} encoding, changing
@opindex -t @var{tex-enc}

If you are using Afm2tfm to build a virtual font, i.e., you have
specified the @samp{-v} or @samp{-V} option, you can then specify an
encoding for that virtual font with @samp{-t @var{tex-enc}}.  (@samp{-t}
is ignored if neither @samp{-v} nor @samp{-V} is present.) Any ligature
and kerning information you specify in @var{tex-enc} will be used in the
VPL, in addition to the ligature and kerning information from the AFM
file.

If the AFM file has no entry for a character specified in @var{tex-enc},
that character will be omitted from the VPL.

@flindex texmsym.enc
The @samp{-t} option is likely to be needed when you have a PostScript
font corresponding to a @TeX{} font other than a normal text font such
as Computer Modern.  For instance, if you have a PostScript font that
contains math symbols, you'd probably want to use the encoding in the
@file{texmsym.enc} file supplied with Dvips. (For a start; to actually
get usable math fonts, you have to define much more than just an
encoding.)


@node Changing PostScript encodings
@subsubsection Changing PostScript encodings

@cindex PostScript encoding, changing
@opindex -p @var{ps-enc}

By default, Afm2tfm uses the encoding it finds in the AFM file.  You can
specify a different PostScript encoding with @samp{-p @var{ps-enc}}.
This makes the raw TFM file (the one output by Afm2tfm) have the
encoding specified in the encoding file @var{ps-enc}.  Any ligature or
kern information specified in @var{ps-enc} is ignored by Afm2tfm, since
ligkern info is always omitted from the raw TFM anyway.

If you use this option, you must also arrange to download @var{ps-enc}
as part of any document that uses this font.  You do this by adding a
line like the following one to @file{psfonts.map} (@pxref{psfonts.map}):

@example
zpopr Optima "MyEncoding ReEncodeFont" <myenc.enc
@end example

@findex trademark @r{character, accessing}
@findex registered @r{character, accessing}
Using @samp{-p} is the only way to access characters in a PostScript
font that are neither encoded in the AFM file nor constructed from other
characters.  For instance, Adobe's @samp{Times-Roman} font contains the
extra characters @samp{trademark} and @samp{registered} (among others);
these can only be accessed through such a PostScript reencoding.


@node Changing both encodings
@subsubsection Changing both @TeX{} and PostScript encodings

@opindex -T @var{enc-file}

The option @samp{-T @var{enc-file}} is equivalent to @samp{-p
@var{enc-file} -t @var{enc-file}}.  If you make regular use of a private
non-standard reencoding @samp{-T} is usually the better idea, since you
can get unexpected inconsistencies in mapping otherwise.  An example of
when you might use this option is when you have a @TeX{} encoding that
is designed to be used with a particular PostScript font, e.g., a
dingbats font.


@node Reencoding with Afm2tfm
@subsubsection Reencoding with Afm2tfm

@cindex reencoding

The Afm2tfm program creates the TFM and VF files for the virtual
font corresponding to a PostScript font by @dfn{reencoding} the
PostScript font.  Afm2tfm generates these files from two
encodings: one for @TeX{} and one for PostScript.  The @TeX{} encoding
is used to map character numbers to character names while the PostScript
encoding is used to map each character name to a possibly different
number.  In combination, you can get access to any character of a
PostScript font at any position for @TeX{} typesetting.

In the default case, when you specify none of the @code{-t}, @code{-p},
or @code{-T} options, Afm2tfm uses a default @TeX{} encoding (which
mostly corresponds to the Computer Modern text fonts) and the default
PostScript encoding (the one found in the AFM file that came with the
font).  The reencoding is also sometimes called a @dfn{remapping}.

For example, the default encodings reencode the acute accent in two steps:
first the default @TeX{} encoding maps the number 19 to the character
name @samp{acute}; then the default PostScript encoding, as found in the
AFM file for an ordinary PostScript font, maps the character name
@samp{acute} to the number 194.  (The PostScript encoding works in
reverse, by looking in the encoding vector for the name and then
yielding the corresponding number.) 
The combined mapping of 19 to 194 shows up explicitly in the VF file and
also implicitly in the fact that the properties of PostScript character
194 appear in position 19 of the TFM file for the virtual font.

@cindex accents, in wrong position
@cindex Hungarian umlaut
@cindex dot accent
@cindex Swedish A ring
The remapped @code{p*} fonts mostly follow plain @TeX{} conventions for
accents.  The exceptions: the Hungarian umlaut (which is at position
@samp{0x7D} in @samp{cmr10}, but position @samp{0xCD} in @samp{ptmr});
the dot accent (at positions @samp{0x5F} and @samp{0xC7}, respectively);
and @samp{\AA}, which neds different tweaking.  In order to use these
accents with PostScript fonts or in math mode when @samp{\textfont0} is
a PostScript font, you will need to use the following definitions.
These definitions will not work with the Computer Modern fonts for the
relevant accents.  They are already part of the distributed
@file{psfonts.sty} for use with La@TeX{}.

@findex \H
@findex \.
@findex \dot
@findex \AA
@example
\def\H#1@{@{\accent"CD #1@}@}
\def\.#1@{@{\accent"C7 #1@}@}
\def\dot@{\mathaccent"70C7 @}
\newdimen\aadimen
\def\AA@{\leavevmode\setbox0\hbox@{h@}\aadimen\ht0
  \advance\aadimen-1ex\setbox0\hbox@{A@}\rlap@{\raise.67\aadimen
  \hbox to \wd0@{\hss\char'27\hss@}@}A@}
@end example


@node Encoding file format
@subsubsection Encoding file format

@cindex encoding file format

Afm2tfm's encoding files have the same format as an encoding vector in a
PostScript font.  Here is a skeletal example:

@example
% @r{Comments are ignored, unless the first word after the percent sign}
% @r{is @samp{LIGKERN}----see below.}
/MyEncoding [ % @r{exactly 256 entries follow, each with a leading @samp{/}}
  /Alpha /Beta /Gamma /Delta @dots{}
  /A /B @dots{} /Z 
  @dots{}  /.notdef /xfooaccent /yfooaccent /zfooaccent
] def
@end example

These encoding files are downloaded as part of changing the encoding at
the PostScript level (see the previous section).

@cindex comments
Comments, which start with a percent sign and continue until the end
of the line, are ignored unless they start with @samp{LIGKERN}.

The first non-comment word of the file must start with a forward slash
@samp{/} (i.e., a PostScript literal name) and defines the name of the
encoding.  The next word must be an left bracket @samp{[}.  Following
that must be precisely 256 character names; use @samp{/.notdef} for any
that you want to leave undefined.  Then there must be a matching right
bracket @code{]}.  A final @samp{def} token is optional.  All names are
case-sensitive.

Any ligature or kern information is given as a comment.  If the first
word after the @samp{%} is @samp{LIGKERN}, then the entire rest of the
line is parsed for ligature and kern information.  This ligature and
kern information is given in groups of words, each group of which must
be terminated by a semicolon (with a space before and after it, unless
it occurs at the end of a line).

@findex LIGKERN
In these @samp{LIGKERN} statements, three types of information may be
specified.  These three types are ligature pairs, kerns to ignore, and
the character value of this font's boundary character. 

@cindex boundary character
Throughout a @samp{LIGKERN} statement, the boundary character is
specified as @samp{||}. To set the boundary character value:

@example
% LIGKERN || = 39 ;
@end example

To indicate a kern to remove, give the names of the two characters
(without the leading slash) separated by @samp{@{@}}, as in @samp{one
@{@} one ;}.  This is similar to the way you might use @samp{@{@}} in a
@TeX{} file to turn off ligatures or kerns at a particular location.
Either or both of the character names can be given as @samp{*}, which is
a wild card matching any character; thus, all kerns can be removed with
@samp{* @{@} * ;}.

To specify a ligature, specify the names of the pair of characters,
followed by the ligature `operation' (as in Metafont), followed by the
replacing character name.  Either (but not both) of the first two
characters can be @samp{||} to indicate a word boundary.

Typically the operation is @samp{=:} meaning that both characters are
removed and replaced by the third character, but by adding @samp{|}
characters on either side of the @samp{=:}, you can specify which of the
two leading characters to retain.  In addition, by suffixing the
ligature operation with one or two @samp{>} signs, you can indicate that
the ligature scanning operation should skip that many characters before
proceeding.  This works just like in @sc{metafont}.  A typical ligature
might be specified with @samp{ff i =: ffi ;}.  A more convoluted
ligature is @samp{one one |=:|>> exclam ;} which indicates that every
pair of adjacent @samp{1}'s should be separated by an exclamation point,
and then two of the resulting characters should be skipped over before
continuing searching for ligatures and kerns.  You cannot give more
@samp{>}'s in an ligature operation as you did @samp{|}, so there are a
total of eight possible ligature operations:

@example
=: |=: |=:> =:| =:|> |=:| |=:|> |=:|>>
@end example

The default set of ligatures and kerns built in to Afm2tfm can
be specified with:

@example
% LIGKERN question quoteleft =: questiondown ;
% LIGKERN exclam quoteleft =: exclamdown ;
% LIGKERN hyphen hyphen =: endash ; endash hyphen =: emdash ;
% LIGKERN quoteleft quoteleft =: quotedblleft ;
% LIGKERN quoteright quoteright =: quotedblright ;
% LIGKERN space @{@} * ; * @{@} space ; 0 @{@} * ; * @{@} 0 ;
% LIGKERN 1 @{@} * ; * @{@} 1 ; 2 @{@} * ; * @{@} 2 ; 3 @{@} * ; * @{@} 3 ;
% LIGKERN 4 @{@} * ; * @{@} 4 ; 5 @{@} * ; * @{@} 5 ; 6 @{@} * ; * @{@} 6 ;
% LIGKERN 7 @{@} * ; * @{@} 7 ; 8 @{@} * ; * @{@} 8 ; 9 @{@} * ; * @{@} 9 ;
@end example


@node Special font effects
@subsection Special font effects

@cindex oblique fonts
@cindex slanted fonts
@cindex fonts, slanted
Besides the reencoding described in the previous section Afm2tfm can do
other manipulations.

For example, to make an obliqued variant of Times Roman:

@example
afm2tfm Times-Roman -s .167 -v ptmro rptmro
@end example

@noindent
which creates @file{ptmro.vpl} and @file{rptmro.tfm}.  To use this,
put the line

@findex SlantFont
@example
rptmro Times-Roman ".167 SlantFont"
@end example

@noindent
@flindex psfonts.map
into @file{psfonts.map}.  Then @samp{rptmro} (our name for the obliqued
Times) will act as if it were a resident font, although it is actually
constructed from Times-Roman via the PostScript routine @code{SlantFont}
(which slants everything 1/6 to the right, in this case).

@cindex expanded fonts
@cindex fonts, expanded
Similarly, you can get an expanded font with

@example
afm2tfm Times-Roman -e 1.2 -v ptmrre rptmrre
@end example

@noindent
and by recording the pseudo-resident font
@findex ExtendFont

@example
rptmrre Times-Roman "1.2 ExtendFont"
@end example

@noindent
in @file{psfonts.map}.

You can also create a small caps font with a command such as
@cindex small caps fonts
@cindex fonts, small caps

@example
afm2tfm Times-Roman -V ptmrc rptmrc
@end example

@noindent
This will generate a set of small caps mapped into the
usual lower case positions and scaled down to 0.8 of the
normal cap dimensions.  You can also specify the scaling
as something other than the default 0.8:

@example
afm2tfm Times-Roman -c 0.7 -V ptmrc rptmrc
@end example

It is unfortunately not possible to increase the width of the small caps
independently of the rest of the font.  If you want a really
professional looking set of small caps you will have to make up a custom
pair of TFM and VPL files using the @samp{-e} option, change the name
and checksum of the D 1 font in @samp{ptmrc.vpl} to match the customized
raw TFM, and replace the small caps at the lower case mappings with the
small caps in the customized file.  You can then throw away the
customized VPL file, but not the customized @samp{tfm}.  That must be
identified with an appropriate line in @file{psfonts.map}.

@findex PaintType
@cindex outline fonts
@cindex fonts, outlined
To change the @code{PaintType} in a font from filled (0) to outlined
(2), you can add @code{"/PaintType 2 store"} to @file{psfonts.map}, as
in the following:

@example
rphvrl   Helvetica "/PaintType 2 store"
@end example

The Afm2tfm program prints out the precise line you need to add to
@file{psfonts.map} to use that font, assuming the font is resident in
the printer; if the font is not resident, you must add the header
command to download the font yourself.  Each identical line only needs
to be specified once in the @samp{psfonts.map} file, even though many
different fonts (small caps variants, or ones with different output
encodings) may be based on it.


@node afm2tfm options
@subsection afm2tfm options

@cindex options to Afm2tfm
@cindex afm2tfm options

Synopsis:

@example
afm2tfm [ @var{option} ]@dots{} @var{afmfile}[.afm] [@var{tfmfile}[.tfm]]
@end example

Afm2tfm reads @var{afmfile} and writes a corresponding (but raw) TFM
file. If @var{tfmfile} is not supplied, the base name of the AFM file is
extended with @samp{.tfm} to get the output filename.

In the simplest case you could use Afm2tfm to convert an Adobe AFM file
such as @file{Times-Roman.afm} into a ``raw'' @TeX{} TFM file such as
@file{rptmr.tfm} with a command such as

@example
afm2tfm Times-Roman rptmr
@end example

@cindex accents
@noindent
The TFM file thus created is raw because it does no character remapping;
it simply contains the character information in the AFM file in TFM
form, which is the form that @TeX{} understands.  The characters have
the same code in the TFM file as in the AFM file.  The 96 printable
ASCII characters will be described correctly in the TFM file but the
other characters in the font will not be.  @footnote{It would be better
to have eschewed the use of the @samp{r} prefix in favor of using a
variant letter to specify the encoding; but we didn't think of that at
the time, and it's too late to change existing fonts.  @xref{Top, , ,
fontname, Filenames for @TeX{} fonts}.}  That is because standard
PostScript fonts have a different encoding scheme than the one that
plain @TeX{} expects.  @xref{Encodings}.  Although both schemes agree
for the printable ASCII characters, special characters such as ligatures
and accents are numbered quite differently.

To enable @TeX{} to use those special characters, you create a virtual
font as well, with the @samp{-v} or @samp{-V} option.  @xref{Making a
font available}.

The command line switches to Afm2tfm are:

@table @samp

@item -c @var{ratio}
@cindex scaling small caps
See @samp{-V}; overrides the default ratio of 0.8 for the
scaling of small caps.

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

@item -O
@cindex octal character codes
This option forces all character codes in the output @samp{vpl} file be
given as octal values; this is useful for symbol or other
special-purpose fonts where character names such as @samp{A} have no
meaning.

@item -p @var{file}
This specifies a file to use for the PostScript encoding of the font.
This file must also be mentioned as a header file for the font in
@samp{psfonts.map}.  @xref{Changing PostScript encodings}.

@item -s @var{slant}
All characters are slanted to the right by @var{slant}.
@cindex slanted fonts
If @var{slant} is negative, the letters slope to the left (or they might
be upright if you start with an italic font).

@item -t @var{file}
This specifies a file to use for the target @TeX{} encoding of the font.
Ligature and kern information may also be specified in @var{file}.
@var{file} is not mentioned in @file{psfonts.map}.

@item -T @var{file}
This option specifies that @var{file} is to be used for both the
PostScript and target @TeX{} encodings of the font.  Equivalent to
@samp{-p @var{file} -t @var{file}}.

@item -u
Have Afm2tfm use only those characters that are required by the @TeX{}
encoding, and no others.  Normally, Afm2tfm tries to include both
characters that fit the @TeX{} encoding and any additional characters that
might exist in the font.  This option stops those additional characters
from being added.

@item -v @var{file}
Generate a VPL (virtual property list) file as well as a TFM file.

@item -V @var{file}
Same as @samp{-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.

@end table

@vindex CODINGSCHEME
Here are the @samp{CODINGSCHEME}s that result from the various
possible choices for reencoding.

@table @samp
@item default encoding
@example
(CODINGSCHEME TeX text + AdobeStandardEncoding)
@end example

@item -p EC.enc
@example
(CODINGSCHEME TeX text + ECEncoding)
@end example

@item -t EC.enc
@example
(CODINGSCHEME ECEncoding + AdobeStandardEncoding)
@end example

@item -T EC.enc
@example
(CODINGSCHEME ECEncoding + ECEncoding)
@end example
@end table
@noindent
The @samp{CODINGSCHEME} line appears in the VPL file but is ignored by
Dvips.


@node psfonts.map
@section The PostScript font map file @file{psfonts.map}

@flindex psfonts.map
@cindex non-resident fonts
@cindex downloading fonts
@cindex fonts, downloading

The @file{psfonts.map} file associates a font with its files.
For example, the line

@example
rpstrn StoneInformal <StoneInformal.pfb
@end example

@noindent
causes Dvips to include @file{StoneInformal.pfb} in your document as if
it were a header file whenever the pseudo-resident font
@samp{StoneInformal} is used in a document @ref{Header files}.
Similarly, you can generate transformed fonts (@pxref{Special font
effects}) and include a line like

@example
rpstrc StoneInformal <StoneInformal.pfb ".8 ExtendFont"
@end example

@noindent
in @file{psfonts.map}. In this case @file{StoneInformal.pfb} will be
loaded whenever you use the StoneInformal-Condensed font. Each header file is
loaded at most once per document.

If you are using a @samp{pfb} file that has a nonstandard PostScript
encoding, you need to include a reference to the corresponding encoding
file in @samp{psfonts.map}.  If, for instance, you want to reencode the
PostScript font @samp{Optima} with the encoding @samp{MyEncoding}, stored
in @samp{myenc.enc}, you need:

@example
rpstrnx Optima "MyEncoding ReEncodeFont" <myenc.enc <Optima.pfb
@end example

When using PFB files, Dvips is smart enough to unpack the binary
PFB format into printable ASCII so there is no need to perform this
conversion yourself.  In addition, Dvips scans the font to
determine its memory usage, just as it does for any header file.

Here is a brief description of the contents of @file{psfonts.map}.  If a
line is empty or begins with a space, percent, asterisk, semicolon, or
hash mark, it is ignored.  Otherwise, the line is separated into words,
where words are separated by spaces or tabs, except that 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 a downloaded PostScript font).  There
can be more than one such header for a given font.  If a word starts
with a double quote, it is a special instruction for generating that
font.  Otherwise it is a name.  The first such name is the TFM file that
a virtual font file can refer to.  If there is another name, it is used
as the PostScript name; if there is only one name, it is used for both
the @TeX{} name and the PostScript name.


@node Color
@chapter Using Color with dvips

@cindex color

This new feature of Dvips is somewhat experimental so your
experiences and comments are welcome.  Initially added by Jim Hafner,
IBM Research, @samp{hafner@@almaden.ibm.com}, the color support has gone
through many changes by Tomas Rokicki.  Besides the changes to the
source code itself, there are additional @TeX{} macro files:
@samp{colordvi.tex} and @samp{blackdvi.tex}.  There are also @samp{.sty}
versions of these files that can be used with La@TeX{} and other similar
macro packages.  This feature adds one-pass multi-color printing of
@TeX{} documents on any color PostScript device.

In this section we describe the use of color from the document
preparer's point of view and then add some simple instructions on
installation for the system administrator.

@menu
* Macro Files::                 
* User Definable Colors::       User Definable Colors
* Color Subtleties::            Subtleties in Using Color
* Ted Turner::                  Printing in Black/White, after Colorizing
* Color Configuration ::        Configuring dvips for Color Devices
* Color Support Details::       Color Support Details
@end menu


@node Macro Files
@section Macro Files

@cindex macros for color
@cindex color macros

All the color macro commands are defined in @samp{colordvi.tex} (or
@samp{colordvi.sty}).  To access these macros simply add to the top of
your @TeX{} file the command

@example
\input colordvi
@end example

@noindent
or, if your document uses style files like La@TeX{}, add the @samp{colordvi}
style option as in 

@example
\documentstyle[12pt,colordvi]@{article@}
@end example

There are basically two kinds of color macros, ones for local color
changes to, say, a few words or even one symbol and one for global color
changes.  Note that all the color names use a mixed case scheme.  There
are 68 predefined colors, with names taken primarily from the Crayola
crayon box of 64 colors, and one pair of macros for the user to set his
own color pattern.  More on this extra feature later. You can browse the
file @samp{colordvi.tex} for a list of the predefined colors.  The
comments in this file also show a rough correspondence between the
crayon names and PANTONEs.

A local color command is in the form

@example
\ColorName@{this will print in color@}
@end example

@noindent
Here @samp{ColorName} is the name of a predefined color. As this example
shows, this type of command takes one argument which is the text that is
to print in the selected color.  This can be used for nested color
changes since it restores the original color state when it completes.
For example, suppose you were writing in green and want to switch
temporarily to red, then blue, back to red and restore green.  Here is
one way that you can do this:

@example
This text is green but here we are \Red@{switching to red,
\Blue@{nesting blue@}, recovering the red@} and back to
original green.
@end example

@noindent
In principle there is no limit to the nesting level, but it is not
advisable to nest too deep lest you loose track of the color history.
 
The global color command has the form

@example
\textColorName
@end example

@noindent 
This macro takes no arguments and immediately changes the default color
from that point on to the specified color. This of course can be
overriden globally by another such command or locally by local color
commands. For example, expanding on the example above, we might have

@example
\textGreen 
This text is green but here we are \Red@{switching to red, 
\Blue@{nesting blue@}, recovering the red@} and back to 
original green.
\textCyan 
The text from here on will be cyan unless 
\Yellow@{locally changed to yellow@}. Now we are back to cyan.
@end example
 
The color commands will even work in math mode and across math mode
boundaries.  This means that if you have a color before going into math
mode, the mathematics will be set in that color as well.  More
importantly however, in alignment environments like @samp{\halign},
@samp{tabular} or @samp{eqnarray}, local color commands cannot extend
beyond the alignment characters.
 
Because local color commands respect only some environment and
deliminator changes besides their own, care must be taken in setting
their scope.  It is best not to have then stretch too far.
 
At the present time there are no macros for color environments in La@TeX{}
which might have a larger range.  This is primarily to keep the @TeX{}
and La@TeX{} use compatible.


@node User Definable Colors
@section User Definable Colors
 
@cindex user-definable colors
@cindex colors, user-definable

There are two ways for the user to specify colors not already defined.
For local changes, there is the command @samp{\Color} which
takes two arguments.  The first argument is a quadruple of numbers
between zero and one and specifies the intensity of cyan, magenta,
yellow and black (CMYK) in that order.  The second argument is the
text that should appear in the given color.  For example, suppose you
want the words ``this color is pretty'' to appear in a color which is
50% cyan, 85% magenta, 40% yellow and 20% black.  You would use
the command

@example
\Color@{.5 .85 .4 .2@}@{this color is pretty@}
@end example

For global color changes, there is a command @samp{\textColor} which
takes one argument, the CMYK quadruple of relative color intensities.
For example, if you want the default color to be as above, then the
command

@example
\textColor@{.5 .85 .4 .2@}
The text from now on will be this pretty color
@end example

@noindent
will do the trick.
 
Making a global color change in the midst of a nested local colors is
highly discouraged.  Consequently, dvips will give you warning message
and do its best to recover by discarding the current color history.


@node Color Subtleties
@section Subtleties in Using Color

@cindex color subtleties

These color macros are defined by use of specialized @samp{\special}
keywords.  As such, they are put in the @samp{.dvi} file only as
explicit message strings to the driver.  The (unpleasant) result is that
certain unprotected regions of the text can have unwanted color side
effects.  For example, if a color region is split by @TeX{} across a
page boundary, then the footers of the current page (e.g., the page
number) and the headers of the next page can inherit that color.  To
avoid this effect globally, users should make sure that these special
regions of the text are defined with their own local color commands.
For example in @TeX{}, to protect the header and footer, use

@example
\headline@{\Black@{My Header@}@}
\footline@{\Black@{\hss\tenrm\folio\hss@}@}
@end example

This warning also applies to figures and other insertions, so be careful!

Of course, in La@TeX{}, this is much more difficult to do because of the
complexity of the macros that control these regions.  This is
unfortunate, but is somehow inevitable because @TeX{} and La@TeX{} were not
written with color in mind.

Even when writing your own macros, much care must be taken.  The color
macros that `colorize' a portion of the text work by prefixing the text
with a special command to turn the color on and postfixing it with a
different special command to restore the original color.  It is often
useful to ensure that @TeX{} is in horizontal mode before the first
special command is issued; this can be done by prefixing the color
command with @samp{\leavevmode}.


@node Ted Turner
@section Printing in Black/White, after Colorizing

If you have a @TeX{} or La@TeX{} document written with color macros and you
want to print it in black and white there are two options.  On all
(good) PostScript devices, printing a color file will print in
corresponding grey-levels.  This is useful since in this way you can get
a rough idea of where the colors are changing without using expensive
color printing devices.  The second option is to replace the call to
input @samp{colordvi.tex} with @samp{blackdvi.tex} (and similarly for
the @samp{.sty} files).  So in the above example, replacing the word
@samp{colordvi} with @samp{blackdvi} suffices.  This file defines the
color macros as no-ops, and so will produce normal black/white printing.
By this simple mechanism, the user can switch to all black/white
printing without having to ferret out the color commands.  Also, some
device drivers, particularly non-PostScript ones like screen previewers,
will simply ignore the color commands and so print in normal
black/white.  Hopefully, in the future screen previewers for color
displays will be compatible with some form of color support.

@node Color Configuration 
@section Configuring dvips for Color Devices

To configure dvips for a particular color device you need to fine tune
the color parameters to match your devices color rendition.  To do this,
you will need a PANTONE chart for your device.  The header file
@samp{color.lpro} shows a (rough) correspondence between the Crayola
crayon names and the PANTONE numbers and also defines default CMYK
values for each of the colors.  Note that these colors must be defined
in CMYK terms and not RGB as dvips outputs PostScript color commands in
CMYK.  This header file also defines (if they are not known to the
interpreter) the PostScript commands @samp{setcmykcolor} and
@samp{currentcmykcolor} in terms of a RGB equivalent so if your device
only understands RGB, there should be no problem.

The parameters set in this file were determined by comparing the PANTONE
chart of a Tektronics PHASER printer with the actual Crayola Crayons.
Because these were defined for a particular device, the actual color
rendition on your device may be very different.  There are two ways to
adjust this.  One is to use the PANTONE chart for your device to rewrite
@samp{color.lpro} prior to compilation and installation.  A better
alternative, which supports multiple devices, is to add a header file
option in the configuration file for each device that defines, in
@samp{userdict}, the color parameters for those colors that need
redefining.

For example, if you need to change the parameters defining
@samp{Goldenrod} (approximately PANTONE 109) for your device
@samp{mycolordev}, do the following.  In the PANTONE chart for your
device, find the CMYK values for PANTONE 109.  Let's say they are
@samp{@{\ 0 0.10 0.75 0.03 @}}. Then create a header file
named @samp{mycolordev.pro} with the commands

@example
userdict begin 
/Goldenrod @{ 0 0.10 0.75 0.03 setcmykcolor@} bind def
@end example

@noindent
Finally, in @samp{config.mycolordev} add the line 

@example
h mycolordev.pro
@end example

@noindent
This will then define @samp{Goldenrod} in your device's CMYK values in
@file{userdict} which is checked before defining it in @file{TeXdict} by
@file{color.pro}.

This mechanism, together with additions to @file{colordvi.tex} and
@file{blackdvi.tex} (and the @samp{.sty} files), can also be used to
predefine other colors for your users.


@node Color Support Details
@section Color Support Details

To support color, dvips recognizes a certain set of specials.  These
specials all start with the keyword @samp{color} or the keyword
@samp{background}.

We will describe @samp{background} first, since it is the simplest.  The
@samp{background} keyword must be followed by a color specification.
That color specification is used as a fill color for the background.
The last @samp{background} special on a page is the one that gets
issued, and it gets issued at the very beginning of the page, before any
text or specials are sent.  (This is possible because the prescan phase
of dvips notices all of the color specials so that the appropriate
information can be written out during the second phase.)

Ahh, but what is a color specification?  It is one of three things.
First, it might be a PostScript procedure as defined in a PostScript
header file.  The @samp{color.pro} file defines 64 of these, including
@samp{Maroon}.  This PostScript procedure must set the current color to
be some value; in this case, @samp{Maroon} is defined as @samp{0 0.87
0.68 0.32 setcmykcolor}.

The second possibility is the name of a color model (initially, one of
@samp{rgb}, @samp{hsb}, @samp{cmyk}, or @samp{gray}) followed by the
appropriate number of parameters.  When dvips encounters such a macro,
it sends out the parameters first, followed by the string created by
prefixing @samp{TeXcolor} to the color model.  Thus, the color
specification @samp{rgb 0.3 0.4 0.5} would generate the PostScript code
@samp{0.3 0.4 0.5 TeXrgbcolor}.  Note that the case of zero arguments is
disallowed, as that is handled by the single keyword case above (where
no changes to the name are made before it is sent to the PostScript
file.)

The third and final type of color specification is a double quote
followed by any sequence of PostScript.  The double quote is stripped
from the output.  For instance, the color specification
@samp{"AggiePattern setpattern} will set the `color' to the Aggie logo
pattern (assuming such exists.)

So those are the three types of color specifications.  The same type of
specifications are used by both the @samp{background} special and the
@samp{color} special.  The @samp{color} special itself has three forms.
The first is just @samp{color} followed by a color specification.  In
this case, the current global color is set to that color; the color stack
must be empty when such a command is executed.

The second form is @samp{color push} followed by a color specification.
This saves the current color on the color stack and sets the color to be
that given by the color specification.  This is the most common way to
set a color.

The final version of the @samp{color} special is just @samp{color pop},
with no color specification; this says to pop the color last pushed on
the color stack from the color stack and set the current color to be
that color.

The Dvips program correctly handles these color specials across
pages, even when the pages are repeated or reversed.

These color specials can be used for things such as patterns or screens
as well as simple colors.  However, note that in the PostScript, only
one `color specification' can be active at a time.  For instance, at the
beginning of a page, only the bottommost entry on the color stack is
sent; also, when a color is `popped', all that is done is that the color
specification from the previous stack entry is sent.  No @samp{gsave} or
@samp{grestore} is used.  This means that you cannot easily mix usage of
the @samp{color} specials for screens and colors, just one or the other.
This may be addressed in the future by adding support for different
`categories' of color-like state.


@node Invoking Dvips
@chapter Invoking Dvips

@cindex command-line options
@cindex options to dvips
@cindex invoking dvips

There many ways to control Dvips' behavior: configuration files,
environment variables, and command-line options.

@menu
* Dvips options::               
* Environment Variables::       
* Config Files::                
@end menu

@node Dvips options
@section Dvips options

Dvips 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 @samp{-r0}.  The
options that can be turned off in this way are @samp{a}, @samp{f},
@samp{k}, @samp{i}, @samp{m}, @samp{q}, @samp{r}, @samp{s}, @samp{E},
@samp{F}, @samp{K}, @samp{M}, @samp{N}, @samp{U}, and @samp{Z}.

This is a handy summary of the options; it is printed out when you run
dvips with no arguments.

@example
This is dvipsk @var{version} Copyright 1986, 1993 Radical Eye Software
     Usage: dvips [options] filename[.dvi]
 a*  Conserve memory, not time      y # Multiply by dvi magnification
 b # Page copies, for posters e.g.  A   Print only odd (TeX) pages
 c # Uncollated copies              B   Print only even (TeX) pages
 d # Debugging                      C # Collated copies
 e # Maxdrift value                 D # Resolution
 f*  Run as filter                  E*  Try to create EPSF
 h f Add header file                F*  Send control-D at end
 i*  Separate file per section      K*  Pull comments from inclusions
 k*  Print crop marks               M*  Don't make fonts
 l # Last page                      N*  No structured comments
 m*  Manual feed                    O c Set/change paper offset
 n # Maximum number of pages        P s Load config.$s
 o f Output file                    R   Run securely
 p # First page                     S # Max section size in pages
 q*  Run quietly                    T c Specify desired page size
 r*  Reverse order of pages         U*  Disable string param trick
 s*  Enclose output in save/restore V*  Send downloadable PS fonts as PK
 t s Paper format                   X # Horizontal resolution
 x # Override dvi magnification     Y # Vertical resolution
                                    Z*  Compress bitmap fonts
 pp #-# First-last page
     # = number   f = file   s = string  * = suffix, `0' to turn off
     c = comma-separated dimension pair (e.g., 3.2in,-32.1cm)
@end example

@table @samp

@item -
Ask for additional options from standard input.

@item -a
Conserve memory by making three passes over the @samp{dvi} file instead
of two and only loading those characters actually used.  Generally only
useful on machines with a very limited amount of memory, like some PCs.

@item -c @var{num}
Generate @var{num} copies of every page.
@cindex copies
Default is 1. (For collated copies, see the @samp{-C} option below.)

@item -b @var{num}
Generate @var{num} copies of each page, but duplicating the page body
rather than using the @samp{#numcopies} option.  This can be useful in
conjunction with a header file setting @samp{\bop-hook} to do color
separations or other neat tricks.

@item -d @var{num}
@cindex debugging
Set the debug flags.  This is intended only for emergencies or for
unusual fact-finding expeditions; it will work only if dvips has been
compiled with the @samp{DEBUG} option.  @xref{Debug Options}, for the
possible values of @var{num}.  Use a value of @samp{-1}, and specify the
option first, for maximum output.

@item -e @var{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, @dots{}] that are less than or equal to
the
@cindex 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.

@item -f
Run as a filter.
@cindex filter
Read the @samp{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.  This
option also disables the automatic reading of the @samp{PRINTER}
environment variable; use @samp{-P$PRINTER} after the @samp{-f} to read
it anyway.  It also turns off the automatic sending of control D if it
was turned on with the @samp{-F} option or in the configuration file;
use @samp{-F} after the @samp{-f} to send it anyway.

@item -h @var{name}
Prepend file @var{name}
@cindex header
as an additional header file. (However, if the name is simply @samp{-},
suppress all header files from the output.)  This header file gets added
to the PostScript @samp{userdict}.

@item -i
Make each section be a separate file.  Under certain circumstances,
dvips will split the document up into `sections' to be processed
independently; this is most often done for memory reasons.  Using this
option tells dvips to place each section into a separate file; the new
file names are created replacing the suffix of the supplied output file
name by a three-digit sequence number.  This option is most often used
in conjunction with the @samp{-S} option which sets the maximum section
length in pages.  For instance, some phototypesetters cannot print more
than ten or so consecutive pages before running out of steam; these
options can be used to automatically split a book into ten-page
sections, each to its own file.

@item -k
Print crop marks.  This option increases the paper size (which should be
specified, either with a paper size special or with the @samp{-T}
option) by a half inch in each dimension.  It translates each page by a
quarter inch and draws cross-style crop marks.  It is mostly useful with
typesetters that can set the page size automatically.

@item -l @var{num}
@cindex pages
The last page printed will be the first one numbered @var{num.} Default
is the last page in the document.  If the @var{num} is prefixed by an
equals sign, then it (and any argument to the @samp{-p} option) is
treated as a sequence number, rather than a value to compare with
@samp{\count0} values.  Thus, using @samp{-l =9} will end with the ninth
page of the document, no matter what the pages are actually numbered.

@item -m
Specify manual feed for printer.
@cindex manual feed

@item -mode @var{mode}
@opindex -mode
Use @var{mode} as the Metafont device name for path searching and
generating fonts.  This overrides any value from configuration files.
With the default paths, explicitly specifying the mode also makes the
program assume the fonts are in a subdirectory named @var{mode}.
@xref{TeX directory structure, @TeX{} directory structure, , kpathsea,
Kpathsearch library}.

If Metafont seems not to understand the @var{mode} name, see @ref{Unable
to Generate Fonts}.

@item -n @var{num}
At most @var{num} pages will be printed. Default is 100000.
@cindex pages

@item -o @var{name}
The output will be sent to file @var{name}.
@cindex output
If no file name is given, the default name is @samp{@var{file}.ps} where
the @samp{dvi} file was called @samp{@var{file}.dvi}; if this option
isn't given, any default in the configuration file is used.  If the
first character of the supplied output file name is @samp{!} or
@samp{|}, then the remainder will be used as an argument to
@samp{popen}; thus, specifying @samp{|lpr} as the output file will
automatically queue the file for printing as usual.  This option also
disables the automatic reading of the @samp{PRINTER} environment
variable, and turns off the automatic sending of control D.  See the
@samp{-f} option for how to override this.

@item -p @var{num}
@cindex pages
The first page printed will be the first one numbered @var{num.} Default
is the first page in the document.  If the @var{num} is prefixed by an
equals sign, then it (and any argument to the @samp{-l} option) is
treated as a sequence number, rather than a value to compare with
@samp{\count0} values.  Thus, using @samp{-p =3} will start with the
third page of the document, no matter what the pages are actually
numbered.

@item -pp @var{first}-@var{last}
@cindex page range
@opindex -pp @var{range}
Print pages @var{first} through @var{last}; equivalent to @samp{-p
@var{first} -l @var{last}}. The @samp{-} range separator can also be a
@samp{:}.

@item -q
Run quietly.  Don't chatter about pages converted, etc.; report
nothing but errors to standard error.
@cindex quiet

@item -r
Stack pages in reverse order.  Normally, page 1 will be printed first.
@cindex reverse

@item -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.

@item -t @var{papertype}
@cindex paper type
@cindex media
@cindex letter
@cindex legal
@cindex ledger
@cindex a4
@cindex a3
@cindex landscape
This sets the paper type to @var{papertype}.  The @var{papertype} should
be defined in one of the configuration files, along with the appropriate
code to select it.  See the documentation for @samp{@@}in the
configuration file option descriptions.  You can also specify @samp{-t
landscape}, which rotates a document by 90 degrees.  To rotate a
document whose size is not letter, you can use the @samp{-t} option
twice, once for the page size, and once for @samp{landscape}.  The upper
left corner of each page in the @samp{dvi} file is placed one inch from
the left and one inch from the top.  Use of this option is highly
dependent on the configuration file.  Note that executing the
@samp{letter} or @samp{a4} or other PostScript operators cause the
document to be nonconforming and can cause it not to print on certain
printers, so the default paper size should not execute such an operator
if at all possible.

@item -x @var{num}
@cindex magnification
Set the magnification ratio to @var{num}/1000. Overrides the
magnification specified in the @samp{dvi} file.  Must be between 10 and
100000.  It is recommended that you use standard magstep values (1095,
1200, 1440, 1728, 2074, 2488, 2986, and so on) to help reduce the total
number of PK files generated.

@item -A
This option prints only the odd pages.  This option uses the \TeX\
page numbering rather than the sequence page numbers.

@item -B
This option prints only the even pages.  This option uses the \TeX\
page numbering rather than the sequence page numbers.

@item -C @var{num}
@cindex copies
Create @var{num} copies, but collated (by replicating the data in the
PostScript file).  Slower than the @samp{-c} option, but easier on the
hands, and faster than resubmitting the same PostScript file multiple
times.

@item -D @var{num}
@cindex resolution
Set the resolution in dpi (dots per inch) to @var{num.} 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
@samp{-Z} flag should probably also be used.

@item -E
Makes dvips attempt to generate an EPSF file with a tight bounding box.
This only works on one-page files, and it only looks at marks made by
characters and rules, not by any included graphics.  In addition, it
gets the glyph metrics from the @samp{tfm} file, so characters that lie
outside their enclosing @samp{tfm} box may confuse it.  In addition, the
bounding box might be a bit too loose if the character glyph has
significant left or right side bearings.  Nonetheless, this option works
well for creating small EPSF files for equations or tables or the like.
(Of course, Dvips output is resolution dependent and
thus does not make very good EPSF files, especially if the images are to
be scaled; use these EPSF files with a great deal of care.)

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

@item -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 @samp{%%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.  This
option has been turned off by default because PostScript previewers and
spoolers have been getting better.

@item -M
Turns off the automatic font generation facility.  If any fonts are
missing, commands to generate the fonts are appended to the file
@flindex missfont.log
@file{missfont.log} in the current directory; this file can then be
executed to create the missing fonts.

@item -N
@cindex structured comments
@findex TranScript
Turns off structured comments; this might be necessary on some systems
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.

@item -O @var{offset}
Move the origin by a certain amount.  The @var{offset} is a
comma-separated pair of dimensions, such as @samp{.1in,-.3cm} (in the
same syntax used in the @samp{papersize} special).  The origin of the
page is shifted from the default position (of one inch down, one inch to
the right from the upper left corner of the paper) by this amount.

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

@item -R
@cindex security
Run securely. This disables command execution in @samp{\special} (via
@samp{`}) and config files (via the @samp{E} option), pipes as output
files, and opening of any absolute filenames.

@item -S @var{num}
Set the maximum number of pages in each `section'.  This option is most
commonly used with the @samp{-i} option; see that documentation above
for more information.

@item -T @var{offset}
Set the paper size to the given pair of dimensions.  This option takes
its arguments in the same style as @samp{-O}.  It overrides any paper
size special in the @samp{dvi} file.

@item -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.  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.

@item -V
Download non-resident PostScript fonts as bitmaps.  This requires use
@pindex mtpk
@pindex pstopk
of @code{mtpk} or @code{pstopk} or some combination of the two in order
to generate the required bitmap fonts; neither of these programs are
supplied with Dvips.

@item -X @var{num}
Set the horizontal resolution in dots per inch to @var{num.}
@cindex resolution

@item -Y @var{num}
Set the vertical resolution in dots per inch to @var{num.}
@cindex resolution

@item -Z
@cindex compression
Causes bitmapped fonts to be compressed before they are downloaded,
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.
@end table


@node Environment Variables
@section Environment Variables

@cindex environment variables

Dvips reads a certain set of environment variables to configure its
operation.  The path variables are read as needed, after all
configuration files are read, so they override values in the
configuration files.  (Except for the @samp{TEXCONFIG} variable.)

@xref{Path specifications, , Path specifications, kpathsea, Kpathsea
library}, for details of interpretation of environment variable values,
and the common environment variables.  Only the environment specific to
Dvips are mentioned here.

@table @samp

@item DVIPSFONTS
@vindex DVIPSFONTS
Default path to search for all fonts.  Overrides all the font-related
config file options and other environment variables.

@item DVIPSHEADERS
@vindex DVIPSHEADERS
Default path to search for PostScript header files.  Overrides the @samp{H}
config file option.

@item DVIPSMAKEPK
@vindex DVIPSMAKEPK
@pindex MakeTeXPK
Overrides @samp{MakeTeXPK} as the name of the program to invoke to
create missing PK fonts.  You can change the arguments passed to the
@samp{MakeTeXPK} program with the @samp{MAKETEXPK} environment
variables; see the Kpathsea documentation.

@item DVIPSSIZES
@vindex DVIPSSIZES
@cindex last-resort font sizes
Last-resort sizes for scaling for unfound fonts.  Overrides the @samp{R}
definition in config files.

@item PRINTER
@vindex PRINTER
This environment variable is read to determine which default printer
configuration file to read in.  It is the responsibility of
the configuration file to send output to the proper print queue, if such
functionality is desired.

@item TEXCONFIG
@vindex TEXCONFIG
@cindex configuration file path
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 are thus redundant.)

@item TEXPICTS
@vindex TEXPICTS
Path to search for special illustrations.  Overrides the @samp{S} config
file option.  If not set, @samp{TEXINPUTS} is used.
@end table


@node Config Files
@section Configuration Files

@cindex configuration files

This section describes the configuration files specific to Dvips. The
driver also reads the configuration files generic to Kpathsea
(@pxref{Config files, Config files, , kpathsea, Kpathsearch library}).

@menu
* Config File Searching::       Where config.* files are searched for.
* Config File Options::         Syntax of config.* files.
@end menu

@node Config File Searching
@subsection Configuration File Searching

@flindex config.ps
@cindex configuration file searching
@cindex searching config files, order of

The dvips program loads many different configuration files, so that
parameters can be set globally across the system, on a per-printer
basis, or individually by each user.

When dvips starts up, first the global @samp{config.ps} file is searched
for and loaded.  This file is looked for along the path for
configuration files, which is set in the @file{Makefile} at compilation.
After this master configuration file is loaded, a file by the name of
@flindex .dvipsrc
@samp{.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 @samp{-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 most options in the command line up to the point that the
@samp{-P} option was encountered.

@vindex PRINTER
After the command line has been completely scanned, if there was no
@samp{-P} option selected, and also the @samp{-o} and @samp{-f} command
line options were not used, a @samp{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.

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 configuration
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.

A few options are treated specially, in that they are not
overridden by configuration files:

@table @samp
@item -mode
This overrides any mode setting (@samp{M} line) in @samp{config.*}.
@samp{-mode} does not affect the resolution, however.

@item -o
This overrides any output setting (@samp{o} line) in @samp{config.*}.

@item -D
As well as setting the current resolution, this unsets the mode if the
mode was set from a configuration file.  If @file{config.$PRINTER} is
read, however, any @samp{D} or @samp{M} lines from it will take effect.

@end table

The purpose of these special cases is to (1) minimize the chance of
having a mismatched mode and resolution (which @samp{MakeTeXPK} cannot
handle), and (2) to let command-line options override config files.


@node Config File Options
@subsection Configuration File Options

@cindex printer configuration files
@cindex configuration files

Most of the configuration file options are similar to the command line
options, but there are a few differences.  As with command line options,
many may be turned off by suffixing the letter with a zero (0).  These
options are @samp{afqrKNUZ}.

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

@table @samp
@item @@ @var{name hsize vsize}
This option is used to set the paper size defaults
and options for the particular printer this configuration file
describes.  There are three formats for this option.  If the option is
specified on a line by itself, with no parameters, it instructs
dvips to discard all other paper size information (possibly from
another configuration file) and start fresh.  If three parameters
are given, as above, with the first parameter being a name and the second
and third being a dimension (as in 8.5in or 3.2cc, just like in the
@samp{papersize} special), then the option is interpreted as starting a new
paper size description, where @var{name} is the name and @var{hsize} and
@var{vsize} describe the horizontal and vertical size of the sheet of
paper, respectively.  If both @var{hsize} and @var{vsize} are equal to
zero (although you must still specify units!) then any page size will
match it.  If the @samp{@@} character is immediately followed by a
@samp{+} sign, then the remainder of the line (after skipping any leading
blanks) is treated as PostScript code to send to the printer to select
that particular paper size.  After all that, if the first character of
the line is an exclamation point, then the line is put in the initial
comments section of the final output file; else, it is put in the setup
section of the output file.  For instance, a subset of the paper size
information supplied in the default @samp{config.ps} looks like

@example
@@ letterSize 8.5in 11in
@@ letter 8.5in 11in
@@+ %%BeginPaperSize: Letter
@@+ letter
@@+ %%EndPaperSize
@@ legal 8.5in 14in
@@+ ! %%DocumentPaperSizes: Legal
@@+ %%BeginPaperSize: Legal
@@+ legal
@@+ %%EndPaperSize
@end example

@noindent
Note that you can even include structured comments in the configuration
file!  When dvips has a paper format name given on the command line, it
looks for a match by the @var{name}; when it has a @samp{papersize}
special, it looks for a match by dimensions.  The first match found (in
the order the paper size information is found in the configuration file)
is used.  If nothing matches, a warning is printed and the first paper
size given is used, so the first paper size should always be the
default.  The dimensions must match within a quarter of an inch.
Landscape mode for all of the paper sizes are automatically supported.
If your printer has a command to set a special paper size, then give
dimensions of @samp{0in 0in}; the PostScript code that sets the paper
size can refer to the dimensions the user requested as @samp{hsize} and
@samp{vsize}; these will be macros defined in the PostScript that return
the requested size in default PostScript units.  Note that virtually all
of the PostScript commands you use here are device dependent and degrade
the portability of the file; that is why the default first paper size
entry should not send any PostScript commands down (although a
structured comment or two would be okay).  Also, some printers want
@samp{BeginPaperSize} comments and paper size setting commands; others
(such as the NeXT) want @samp{PaperSize} comments and they will handle
setting the paper size.  There is no solution I could find that works
for both (except maybe specifying both.)  See the supplied
@samp{config.ps} file for a more realistic example.

@item a
Conserve memory by making three passes over the @samp{dvi} file instead
of two and only loading those characters actually used.  Generally only
useful on machines with a very limited amount of memory, like some PCs.

@item b @var{num}
Generate @var{num} copies of each page, but duplicating the page body
rather than using the @samp{#numcopies} option.  This can be useful in
conjunction with a header file setting @samp{\bop-hook} to do color
separations or other neat tricks.

@item e @var{num}
Set the maximum drift parameter to @var{num} dots (pixels) as explained
above.
@cindex maxdrift
@cindex drift

@item f
Run as a filter by default.
@cindex filter

@item h @var{name}
Add @var{name} as a PostScript header file to be downloaded at the
beginning.
@cindex header

@item i @var{num}
Make each section be a separate file, and set the maximum number of
pages in a given file to @var{num}.  Under certain circumstances, dvips
will split the document into `sections' to be processed independently;
this is most often done for memory reasons.  Using this option tells
dvips to place each section into a separate file; the new file names are
created by replacing the suffix of the supplied output file name with a
three-digit sequence number.  This is essentially a combination of the
command line options @samp{-i} and @samp{-S}; see the documentation for
these options for more information.

@item m @var{num}
@cindex memory
The value @var{num} is the virtual memory available for fonts and
strings in the printer.  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:

@example
%! Hey, we're PostScript
/Times-Roman findfont 30 scalefont setfont 144 432 moveto
vmstatus exch sub 40 string cvs show pop showpage
@end example

@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 @samp{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.

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

@item p @var{name}
The file to examine for PostScript font aliases is @var{name}.  It
defaults to @samp{psfonts.map}.  This option allows different printers
to use different resident fonts.  If the name starts with a @samp{+}
character, then the rest of the name (after any leading spaces) is used
as an additional map file; thus, it is possible to have local map files
pointed to by local configuration files that append to the global
map file.

@item q
Run quietly  by default.
@cindex quiet

@item r
Reverse the order of pages by default.
@cindex reverse

@item 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.

@item D @var{num}
@cindex resolution
Set the vertical and horizontal resolution to @var{num} dots per inch.
Useful in printer-specific configuration files.

@item E @var{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.

@item H @var{path}
@cindex header path
@vindex DVIPSHEADERS
The (colon-separated) path to search for PostScript header files is
@var{path}.  The environment variable @samp{DVIPSHEADERS} overrides this.

@item K
Filter comments out of included PostScript files; see the description
above for more information.

@item M @var{mode}
@cindex @samp{MakeTeXPK}
@cindex @sc{metafont}
Set @var{mode} as the @sc{metafont} mode to be used when generating
fonts and for path searching. The @samp{-mode} option overrides this.
With the default paths, specifying a mode this way also makes the
program assume the fonts are in a subdirectory named @var{mode}.
@xref{TeX directory structure, @TeX{} directory structure, , kpathsea,
Kpathsearch library}.

@item N
Disable PostScript comments by default.

@item O @var{offset}
Move the origin by a certain amount.  The @var{offset} is a
comma-separated pair of dimensions, such as @samp{.1in,-.3cm} (in the
same syntax as used in the @samp{papersize} special).  The origin of the
page is shifted from the default position (of one inch down, one inch to
the right from the upper left corner of the paper) by this amount.

@flindex testpage.tex
This is useful for a printer that consistently offsets output pages by a
certain amount. You can use the file @file{testpage.tex} to determine
the correct value for your printer. Be sure to do several runs with the
same @code{O} value---some printers vary widely from run to run.

@item P @var{path}
@cindex @samp{PKFONTS}
@cindex pk path
The (colon-separated) path to search for bitmap @samp{pk} font files is
@var{path}.  The @samp{PKFONTS}, @samp{TEXPKS}, @samp{GLYPHFONTS}, and
@samp{TEXFONTS} environment variables 
override this. @xref{TeX environment variables, @TeX{} environment
variables, , kpathsea, Kpathsearch library}.

@item R @var{num num @dots{}}
@cindex fallback resolutions
@cindex default resolutions
Sets up a list of default resolutions to search for @samp{pk} fonts, if
the requested size is not available.  The output will then scale the
font found using PostScript scaling to the requested size. 
The resulting output may be ugly, and thus a warning is issued.  To
turn this off, use a line with just the @samp{R} and no numbers.

@item S @var{path}
@vindex TEXPICTS
@vindex TEXINPUTS
The path to search for special illustrations (Encapsulated PostScript
files or psfiles) is @var{path}.  The @samp{TEXPICTS} and then
@samp{TEXINPUTS} environment variables override this.

@item T @var{path}
@vindex TEXFONTS
The path to search for the @samp{tfm} files is @var{path}.  The
@samp{TFMFONTS} and then @samp{TEXFONTS} environment variables overrides
this.  This path is used for resident fonts and fonts that can't
otherwise be found.

@item 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.

@item V @var{path}
@cindex @samp{vf}
@cindex virtual fonts
The path to search for virtual font @samp{vf} files is @var{path}.  This
may be device-dependent if you use virtual fonts to simulate actual
fonts on different devices.

@item W [@var{string}]
@cindex warning messages
If @var{string} is supplied, write it to stderr after reading all the
configuration files; otherwise, cancel any previous @samp{W} 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 about special characteristics of the resultant output from a
particular printer.

@item X @var{num}
@cindex resolution
Set the horizontal resolution to @var{num} dots per inch.

@item Y @var{num}
@cindex resolution
Set the vertical resolution to @var{num} dots per inch.

@item Z
Compress all downloaded fonts by default, as above.
@end table


@node Bells and Whistles
@chapter Other Bells And Whistles

@cindex @samp{bop-hook}
@cindex @samp{eop-hook}
@cindex @samp{start-hook}
@cindex @samp{end-hook}
For special effects, if any of the macros @samp{bop-hook},
@samp{eop-hook}, @samp{start-hook}, or @samp{end-hook} are defined in
the PostScript @samp{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 @samp{-h} option or the @samp{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.

The single argument to @samp{bop-hook} is the sequence number of the page
in the file; the first page gets zero, the second one, etc.  The procedure
must leave this number on the stack.  None of the other hooks are (currently)
given parameters, although this may change in the future.

As an example of what can be done, the following special will write
a light DRAFT across each page in the document:

@example
\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@}
@end example

Note that using @samp{bop-hook} or @samp{eop-hook} in any way that
preserves information across pages will break compliance with the Adobe
document structuring conventions, so if you use any such tricks, it is
recommended that you also use the @samp{-N} option to turn off
structured comments.

Several of the above tricks can be used nicely together, and it is not
necessary that a `printer configuration file' be used only for
printer.  For instance, a @samp{-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 @samp{h} line in the configuration file.  Multiple @samp{-P}
options can be used.


@node Installation
@chapter Installation

@cindex configuration
@cindex compilation
@cindex installation

To compile and install Dvipsk:

@enumerate

@include ../kpathsea/install.texi

@item
@flindex MakeTeXPK@r{, editing}
Check the paths in @samp{MakeTeXPK}, unless you do not want automatic
font generation.  @xref{Font Generation}.  The @file{MakeTeXPK} in the
distribution will overwrite the installed file only if the latter
contains the string @samp{original MakeTeXPK --}.

Dvipsk, unlike the original dvips, @emph{requires} @samp{MakeTeXPK} to
echo the generated filename (and nothing else) to standard output
(standard error can be used for commentary).  For more details, or in
general if @samp{MakeTeXPK} fails, @pxref{Unable to Generate Fonts}.

By default, @samp{MakeTeXPK} installs the new PK fonts under
@samp{/usr/local/lib/texmf/fonts/tmp/pk}.  For the simplest installation,
create that directory and make it publically writable.  @xref{Font
Generation}, for alternatives.

@item
@flindex config.ps@r{, editing}
Update the device parameters (available memory, resolution, etc.) in
@samp{config.ps}.  This file is installed as the system-wide
configuration file.  @xref{Config File Options}.  The @file{config.ps}
in the distribution will overwrite the installed file only if the latter
contains the string @samp{original config.ps --}.

@cindex devices, supporting more than one
@cindex multiple output devices, supporting
@vindex configdir
If you need support for more than one device, create configuration files
for each and install them in the directory named by the Make variable
@code{configdir}. See the @samp{-P} option in @ref{Invoking Dvips}.

@item
@vindex install_fonts @r{Make variable}
@opindex install-exec @r{Make target}
@opindex install-data @r{Make target}
Install the programs and supporting macros, fonts, and data files with
@code{make install}. If you want to install only the executables, do
@code{make install-exec}; for only the data files, @code{make
install-data}. And if you don't want to install the fonts (perhaps
because your directory structure is different from the default), but do
want everything else, set the Make variable @code{install_fonts=false}.

@item
@cindex fonts, free PostScript
@cindex PostScript fonts, freely available
Install additional fonts, if you want to.

A few Type 1 fonts (Utopia, Charter, Courier, Nimbus, Antiqua, @dots{})
have been contributed to the X Consortium, and thus are freely
available. You can get @TeX{} distributions for them from
@samp{ftp.cs.umb.edu} in @samp{pub/tex}, and from the CTAN hosts in
@file{tex-archive/fonts}.

@cindex fonts, system PostScript
@cindex PostScript fonts, on your system
@flindex psfonts.map
If you have a commercial Unix system, it may have come with additional
PostScript fonts.  If so, you can make them available to Dvips by (1)
copying or linking them with the appropriate filenames; and (2) running
Afm2tfm (@pxref{Installing PostScript fonts}) to make TFM and VF files
so the fonts will be available in the same encoding as the fonts
distributed with Dvips. Also check @file{psfonts.map} to be sure the
fonts are listed there (@pxref{psfonts.map}).

Here are the typical locations for vendor-supplied fonts:

@table @asis
@item DEC Ultrix
@file{/usr/lib/DPS/outline/decwin}
@item DEC OSF/1
@file{/usr/lib/X11/fonts/Type1Adobe}
@item IBM AIX
@file{/usr/lpp/DPS/fonts/outlines}
@item NeXT
@file{/NextLibrary/Fonts/outline}
@item SGI IRIX 
@file{/usr/lib/DPS/outline/base}
@item Sun Solaris
@file{/usr/openwin/lib/X11/fonts/Type1/outline}
@end table

@noindent The NeXT system supplies more fonts than the others, but the
sets are overlapping.  See the distributed @file{psfonts.map} for which
fonts each system supplies.

@item
@code{make distclean}.  This removes all files created by the build.

@end enumerate

@xref{Debug Options}, for runtime debugging options that may help track
down problems.

@xref{Reporting bugs, , , kpathsea, Kpathsea}, for the bug reporting
address and information. (Also at the end of @file{kpathsea/INSTALL}.)

@menu
* Problems::                    
* Font Generation::             
@end menu


@node Problems
@section Diagnosing problems

@cindex problems
@cindex trouble
@cindex debugging

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, it will also
reduce the number of possible interactions among different parts of the
system.

@menu
* Debug Options::               To see low-level operations.
* No Output::                   No output at all
* Small or Inverted::           Output Too Small or Inverted
* Printer Errors::              
* 400 DPI::                     400 dpi is used instead of 300 dpi
* Long Documents Fail::         Long Documents Fail To Print
* Including Graphics Fails::    
* Unable to Generate Fonts::    
@end menu


@node Debug Options
@subsection Debug Options

@cindex debug options

The @samp{-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.  To track all classes, you can use @code{-1} (output is
extremely voluminous).  Another useful value is @code{3650}, which
tracks everything having to do with file searching and opening.

The classes are:

@table @asis
@item 1 
specials
@item 2
paths
@item 4
fonts
@item 8
pages
@item 16
headers
@item 32
font compression
@item 64
files
@item 128
memory
@item 256
Kpathsea @code{stat} calls
@item 512
Kpathsea hash table lookups
@item 1024
Kpathsea path element expansion
@item 2048
Kpathsea path searches
@end table


@node No Output
@subsection No Output At All

If you are not getting any output at all, even from the simplest
one-character file (for instance, @samp{\ \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
@samp{ehandler.ps}.)
@flindex 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 @samp{dvips.h} and the
declarations in the @samp{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 @samp{-N} flag to turn off structured
comments and see what happens.


@node Small or Inverted
@subsection 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 @samp{-F} flag, but note that this
generates files with a binary character (control-D) in them.  You can
also try using the @samp{-s} flag to enclose the entire job in a
save/restore pair.


@node Printer Errors
@subsection 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 @samp{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 @samp{-N} option, but make sure you get your spooling software
updated.

Another error message is @samp{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 @samp{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.


@node 400 DPI
@subsection 400 DPI Is Used Instead Of 300 DPI

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


@node Long Documents Fail
@subsection Long Documents Fail To Print

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


@node Including Graphics Fails
@subsection 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 @samp{-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 ASCII hex) will probably fail with dvips.


@node Unable to Generate Fonts
@subsection Unable to Generate Fonts

This happens a lot if either @samp{MakeTeXPK} hasn't been properly
edited and installed, or if the local installation of @sc{metafont}
isn't correct.

@samp{MakeTeXPK} must echo the generated filename (and nothing else) to
standard output. @xref{Font Generation}.

If @sc{metafont} isn't found when @samp{MakeTeXPK} is running, then you
need to install it. Retrieve it from, e.g., @samp{ftp.cs.umb.edu} in
@file{pub/tex/web2c.tar.gz} and @file{pub/tex/web.tar.gz}.

If @sc{metafont} 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 @sc{metafont} base file probably hasn't been made properly.  To
make a proper @samp{plain.base}, assuming the local mode definitions are
contained in @samp{modes.mf} type the following command (assuming UNIX): 
@example
inimf "plain; input modes; dump"
@end example
@noindent
Then copy the @samp{plain.base} file from the current directory to where
the base files are stored on your system.


@node Font Generation
@section Automatic Font Generation

@cindex generating fonts
@cindex dynamic font generation
@cindex 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.
Dvips 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.

@pindex MakeTeXPK
It is the @samp{MakeTeXPK} shell script that is responsible for making
these fonts. It @emph{must} echo the filename of the new
font (and nothing else) to standard output. Use standard error for
commentary. 
 
@samp{MakeTeXPK} is passed various arguments, the first of which is the
font it's supposed to make. You can override the other argument
conventions with environment variables or at compilation time; see the
Kpathsea documentation.

The @samp{MakeTeXPK} script supplied invokes Metafont (using the Sauter
scripts first, if necessary and if they are installed) to create the
font and then copies the resultant @samp{pk} file to a world-writable
font cache area.

@samp{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 demands @samp{gf} fonts, you
can easily modify @samp{MakeTeXPK} to invoke @samp{gftopk} to convert the
@samp{gf} files to @samp{pk} files for dvips.  This provides the same space
savings listed above.

Because dvips (and thus @samp{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,
@samp{MakeTeXPK} can write to @samp{/tmp/pk} or some such directory, and
periodically the cached fonts can be moved to a more general system area.
The cache directory must exist on the @samp{pk} file search path
in order for @samp{MakeTeXPK} to work.


@node Index
@unnumbered Index

@printindex cp


@summarycontents
@contents

@bye
