dvips
Go back to
index
NAME
dvips - convert a TeX DVI file to PostScript (PostScript is
a trademark of Adobe Systems, Inc.)
SYNOPSIS
dvips [ -c num ] [ -d num ] [ -e num ] [ -f ] [ -h file ] [
-l num ] [ -m ] [ -n num ] [ -o file ] [ -p num ] [ -q ] [
-r ] [ -s ] [ -t modename ] [ -x num ] [ -C num ] [ -D num ]
[ -F ] [ -N ] [ -P printername ] [ -X num ] [ -Y num ] [ -Z
] [ -? ] file[.dvi]
DESCRIPTION
The program dvips converts a DVI file file[.dvi] produced by
TeX (or by some other processor like GFtoDVI) and converts
it to PostScript, normally sending the result directly to
the laserprinter. The DVI file may be specified without the
.dvi extension. Fonts used may either be resident in the
printer or defined as bitmaps in PK files, or a `virtual'
combination of both. If the MakeTeXPK program is installed,
dvips will automatically invoke METAFONT to generate fonts
that don't already exist.
OPTIONS
Boolean flags that are turned on by certain letters (such as
-r to reverse pages) can be turned off by following the
option immediately with a 0 (as in -r0). The options that
this can be used with are fmqrFNZ. The command line
switches are:
-c num
Generate num copies of every page. Default is 1. (For
collated copies, see the -C option below.)
-d num
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
DEBUG option. The file debug.h in the sources
indicates what the values of num can be. Use a value
of -1 for maximum output.
-e num
Make sure that each character is placed at most this
many pixels from its `true' resolution-independent
position on the page. The default value of this
parameter is resolution dependent (it is the number of
entries in the list [100, 200, 300, 400, 500, 600, 800,
1000, 1200, 1600, 2000, 2400, 2800, 3200, ...] that are
less than or equal to the 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.
-f Run as a filter. Read the DVI file from standard input
and write the PostScript to standard output. The
standard input must be seekable, so it cannot be a
pipe. If you must use a pipe, write a shell script
that copies the pipe output to a temporary file and
then points dvips at this file.
-h name
Prepend file name as an additional header file.
(However, if the name is simply `-', suppress all
header files from the output.) This header file gets
added to the PostScript userdict.
-l num
The last page printed will be the first one numbered
num. Default is the last page in the document.
-m Specify manual feed for printer.
-n num
At most num pages will be printed out. Default is
100000.
-o name
The output will be sent to file name. If no file name
is given, the default name is file.ps; if this option
isn't given, the default name is !lpr. If the first
character of the file name is an exclamation mark, then
the remainder will be used as an argument to popen;
thus, specifying !lpr as the output file will
automatically queue the file for printing.
-p num
The first page printed will be the first one numbered
num. Default is the first page in the document.
-q Run in quiet mode. Don't chatter about pages
converted, etc.; report nothing but errors to stderr.
-r Stack pages in reverse order. Normally, page one will
be printed first.
-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.
-t modename
This sets the mode to modename. Currently, the only
modes allowable are: letter, which selects letter size
(8.5 by 11 inch page); a4, which selects a4 size;
legal, which selects legal size (8.5 by 14 inches);
landscape, which rotates a letter size document by
ninety degrees. The default mode is letter. The upper
left corner of each page in the DVI file is placed one
inch from the left and one inch from the top.
-x num
Set the magnification ratio to num /1000. Overrides the
magnification specified in the DVI file. Must be
between 10 and 100000.
-C num
Create num copies, but collated (by replicating the
data in the PostScript file). Slower than the -c
option, but easier on the humans.
-D num
Set the resolution in dpi (dots per inch) to 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.
-F 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, as
is common on extremely small systems, instead of
working through a spooler.
-N 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.
-P printername
Sets up the output for the appropriate printer. This
is implemented by reading in config.printername, which
can then set the output pipe (as in, 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 config.ps
file and only things that vary printer to printer go in
the config.printername files. Note that config.ps is
read before config.printername. In addition, another
file called ~/.dvipsrc is searched for immediately
after config.ps; this file is intended for user
defaults. If no -P command is given, the environment
variable PRINTER is checked. If that variable exists,
and a corresponding config.PRINTER exists, then that
configuration file is read in.
-X num
Set the horizontal resolution in dpi (dots per inch) to
num.
-Y num
Set the horizontal resolution in dpi (dots per inch) to
num.
-Z Causes bitmap 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.
-? Print out the banner identifying the program.
CONFIG FILE OPTIONS
The file config.ps (and the user's own ~/.dvipsrc) can be
used to set many of the options to configure dvips for a
particular site and printer. These will probably be set up
by the installer, so normal users can skip this section.
The name and location of the config file can be changed at
installation time. The environment variable TEXCONFIG (if
it exists) is used as the path to configuration files. Each
line of the file specifies a configuration option. If the
initial character is a space, an asterisk, a pound sign, or
a semicolon, the line is ignored. But if the initial
character is an option like "o", for example, the remainder
of the line is considered to be a parameter. The options
are:
e num
Sets the maximum drift parameter to num dots (pixels)
as explained above.
f Run as a filter by default.
h name
Add name as a PostScript header file to be downloaded
at the beginning.
m num
num is the virtual memory available for fonts and
strings in the printer. Default is 180000.
o name
The default output file is set to name. As above, it
can be a pipe.
q Run in quiet mode by default.
r Reverse the order of pages by default.
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.
t modename
This sets the mode to modename. Currently, the only
modes allowable are: letter, which selects letter size
(8.5 by 11 inch page); a4, which selects a4 size;
legal, which selects legal size (8.5 by 14 inches);
landscape, which rotates a letter size document by
ninety degrees. The default mode is letter. The upper
left corner of each page in the DVI file is placed one
inch from the left and one inch from the top. The -t
modename option will override this.
D num
Sets the vertical and horizontal resolution to num dots
per inch (dpi).
E command
Executes the command listed; can be used to get the
current date into a header file for inclusion, for
instance. Possibly dangerous; in many installations
this may be disabled, in which case a warning message
will be printed if the option is used.
H path
The (colon-separated) path to search for PostScript
header files is path.
M mode
Set mode as the METAFONT mode to be used when
generating fonts. This is passed along to MakeTeXPK
and overrides mode derivation from the base resolution.
N Disable PostScript comments by default.
P path
The (colon-separated) path to search for bitmap (PK)
font files is path. The TEXPKS environment variable
will override this. If a % character is found in path,
the following substitutions will be made, and then a
search will be made for the resulting filenames. A %f
is replaced by the font name. A %d is replaced by the
font size in dots per inch (dpi). A %p is replaced by
the font family. This is always "pk". A %m is
replaced by the font mode. This is the mode given in
the M option.
S path
The (colon-separated) path to search for special
illustrations (encapsulated PostScript files or
psfiles) is path. The TEXINPUTS environment variable
will override this.
T path
The (colon-separated) path to search for the tfm files
is path. The TEXFONTS environment variable will
override this. This path is used for resident fonts and
fonts that can't be otherwise found. It's usually best
to make it identical to the path used by TeX.
V path
The (colon-separated) path to search for virtual font
(VF) files is path. This may be device-dependent, if
you use virtual fonts to simulate actual fonts on
different devices.
W string
Sends string to stderr, if it exists; otherwise it
cancels another previous message. This is useful in
the default configuration file if you want to require
the user to specify a printer, for instance, or if you
want to notify the user that the resultant output has
special characteristics.
X num
Sets the horizontal resolution to num dots per inch
(dpi).
Y num
Sets the vertical resolution to num dots per inch
(dpi).
R num num ...
Sets up a list of default resolutions to search for PK
fonts, if the requested size is not available. The
output will then scale the font found using PostScript
scaling to the requested size. Note that the resultant
output will be ugly, and thus a warning is issued. To
turn this off, simply don't use such a line in the
configuration file.
Z Compress all downloaded fonts by default.
PATH INTERPRETATION
All paths variables are the names of directories (path
elements), separated by colons. Each path element can be
either the literal name of a directory or one of the ~ forms
common under Unix. If a path element is a single tilde, it
is replaced by the contents of the environment variable
HOME, which is normally set to the user's home directory.
If the path element is a tilde followed by anything, the
part after the tilde is interpreted as a user name, and his
home directory is fetched from the system password file and
used as the real path element.
Where environment variables can override paths, an
additional path element form is allowed. If a path element
is the empty string, it is replaced with the system
defaults. Thus, to say (with an environment variable) to
search the user's home directory, followed by the system
default paths, the following command would be used:
setenv TEXINPUTS ~:
This is a path of two elements. The first is the user's
home directory. The second path element is the empty
string, indicating that the system defaults should be
searched.
POSTSCRIPT FONT SUPPORT
This version of dvips supports PostScript fonts. You need
TFM (TeX Font Metric) files for all fonts seen by TeX; they
can be generated from AFM (Adobe Font Metric) files by
running the program afm2tfm (which is described on its own
manual page). That program also creates virtual fonts with
which you can use normal plain TeX conventions. The set of
all resident fonts known to dvips appears in the file
psfonts.map, which should be updated whenever you install a
new resident font. See afm2tfm for examples and more
information on this file.
\special OPTIONS
This DVI driver allows the inclusion of PostScript code to
be inserted in a TeX file via TeX's \special command. For
compatibility with other systems, several different
conventions are supported.
First, there's a flexible key-and-value scheme:
\special{psfile="filename"[ key=value]*}
This will download the PostScript file called filename such
that the current point will be the origin of the PostScript
coordinate system. If the filename string begins with the `
(grave accent) character then the remainder of the filename
field is treated as a Unix Bourne shell script to be
executed with its sysout down loaded as a PostScript file.
For example:
\special{psfile="`zcat packed.ps" ...}
will uncompress the file packed.ps.Z for inclusion in dvips
output.
The optional key/value assignments allow you to specify
transformations on the PostScript in filename. The possible
keys are:
hoffset The horizontal offset (default 0)
voffset The vertical offset (default 0)
hsize The horizontal clipping size (default 612)
vsize The vertical clipping size (default 792)
hscale The horizontal scaling factor (default 100)
vscale The vertical scaling factor (default 100)
angle The rotation (default 0)
The hoffset, voffset, hsize, and vsize are given in
PostScript units (1/72 of an inch), called bp elsewhere in
TeX; these are the units of the default coordinate system
assumed to be valid in the PostScript file. The hscale and
vscale are given in non-dimensioned percentage units, and
the rotate value is specified in degrees. Thus
\special{psfile=foo.ps hoffset=72 hscale=90 vscale=90}
will shift the graphics produced by file foo.ps right by 1",
and will draw it at 0.9 normal size. If either hsize or
vsize is specified, the figure will be clipped to a
rectangular region from (0,0) to (hsize,vsize) in default
coordinates, after scaling, translation, and/or rotation.
Otherwise no clipping will be done. Offsets are given
relative to the point of the \special command, and are
unaffected by scaling or rotation. Rotation is
counterclockwise about (0,0). The order of operations is:
Take the PostScript figure, rotate it, then scale it, then
offset it, then clip it. For example, if you want to extract
a one-inch-square figure bounded by (100,200), (172,200),
(172,272), and (100,272) in the PostScript coordinates of
the graphic in cropthis.ps, you would say
\special{psfile=cropthis.ps hoffset=-100 yoffset=-200 hsize=72 vsize=72}
Secondly, if your file conforms to the Encapsulated Post
Script (EPS) conventions, then it is possible to use a
simpler \special command that will automatically reserve the
required space.
To use, simply say
\input epsf % at the beginning of your TeX document
\epsfbox{filename.ps} % at the place where you want the figure
A vbox of the appropriate size for the bounding box will be
built. The height and width of this vbox will be the height
and width of the figure; the depth of the vbox will be zero.
By default, the graphic will have its `natural' width. If
you wish to enlarge or reduce it, simply set the dimension
`\epsfxsize' to something else, such as `\hsize'; the figure
will be scaled so that \epsfxsize is its final width. A
more general facility for sizing is available by defining
the `\epsfsize' macro. This macro is used to give
\epsfxsize a value each time \epsffile is called. It takes
two parameters; the first is the horizontal natural size of
the PostScript figure, and the second is the vertical
natural size. (Natural size, in this case, is the size in
PostScript points from the bounding box comment.) The
default definition of this macro is
\def\epsfsize#1#2{\epsfxsize}
which just means to take the value that was set before the
macro was invoked. Note that the variable \epsfxsize is
reset to zero at the end of each call to \epsffile. You can
redefine this macro to do almost anything. It must return
the xsize to use, or 0 if natural scaling is to be used.
Common uses include:
\epsfxsize % just leave the old value alone
0pt % use the natural sizes
#1 % use the natural sizes
\hsize % scale to full width
0.5#1 % scale to 50% of natural size
\ifnum#1>\hsize\hsize\else#1\fi % smaller of natural, hsize
The resultant vbox can be centered with \centerline, or
treated as any other vbox. If you are using LaTeX and the
center environment, be sure to execute a \leavevmode before
each use of \epsffile, so that LaTeX leaves the vertical
mode and enters the paragraph making mode. (This should
probably be provided by the LaTeX macros themselves.)
(The \epsfbox macro does its job by scanning filename.ps for
a standard `BoundingBox' comment. The figure is clipped to
the size of that bounding box. If the bounding box is not
found, a bounding box of `72 72 540 720' is assumed. If the
PostScript file to be included is not EPSF, you are probably
better off using the psfile special instead.)
Thirdly, there are special commands for drawing diagrams
using the conventions of `TPIC' (a portable,
non-PostScript-dependent program by Tim Morgan, with
PostScript implementation by Dorab Patel). For example,
`\special{pn 2}' in this language sets the pen size to .002
inch.
A fourth type of \special allows you to write PostScript
instructions that will be passed literally to dvips's output
file. These are intended for people whose favorite graphics
language is raw PostScript.
\special{" text}
includes text literally in the output PostScript document,
after translating the origin to the current page position,
opening a special user dictionary, and and reverting to the
PostScript convention of 72 units=1in.
\special{! text}
includes text literally in the prolog (before all
typesetting is done), putting definitions in the special
dictionary; this is good for definitions you intend to use
with \special{"}. Note that dvips will always include such
specials in the prolog, unless they occur on pages after the
last page printed. This allows correct printing of selected
pages, even when literal PostScript definitions are used,
provided that you give definitions before their first use.
A fifth type of \special allows literal PostScript
instructions to be inserted without enclosing them in an
invisible 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 tortuous history; any of
the following will work:
\special{ps:text}
\special{ps::text}
\special{ps::[begin]text}
\special{ps::[end]text}
(with longer forms taking precedence over shorter forms,
when they are used). Exception: The command
\special{ps: plotfile filename}
will copy the commands from filename verbatim into dvips's
output (but omitting lines that begin with %). An example
of the proper use of literal specials can be found in the
file rotate.tex, which makes it easy to typeset text turned
90 degrees.
Finally, there are two special cases of \special, which
provide alternatives to certain dvips command-line options:
(1) You may put the command
\special{landscape}
anywhere in your document (except after the final page
selected for printing), and the entire document will be
printed in landscape mode. (2) The command
\special{header=filename}
may be used to add filename as a header file (i.e., a file
that will be downloaded before the start of processing).
This is usually used for Macintosh header files. The header
file will be added to the PostScript userdict.
For special effects, if any of the macros bop-hook,
eop-hook, start-hook, or end-hook are defined in the
PostScript userdict, they will be executed at the beginning
of a page, end of a page, start of the document, and end of
a document, respectively. When these macros are executed,
the default PostScript coordinate system is in effect. Such
macros can be defined in headers added by the -h option or
the header= special, and might be useful for writing, for
instance, DRAFT across the entire page, or, with the aid of
a shell script, dating the document. These macros are
executed outside of the save/restore context of the
individual pages, so it is possible for them to accumulate
information, but if a document must be divided into sections
because of memory constraints, such added information will
be lost across section breaks.
Several of the above tricks can be used nicely together.
For instance, a -P file can be set up to print the date on
each page; the particular configuration file will execute a
command to put the date into a header file, which is then
included with a h line in the configuration file. Note that
multiple -P options can be used.
If the filename in any of the PostScript inclusion options
begins with a backtick, that name is interpreted instead as
a command to be executed to generate the appropriate file.
The PostScript must be generated to standard output by the
command. This is useful, for instance, for uncompressing
large PostScript files using zcat.
FILES
Files used by dvips are usually system dependent, but the
following are typical:
the prolog dir /usr/lib/tex/ps
the config dir /usr/lib/tex/ps
the tfm dir /usr/lib/tex/fonts/tfm
the font dir /usr/lib/tex/fonts/pk
the virtual font dir /usr/lib/tex/fonts/vf
the epsf/psfile dir .:..:/usr/lib/tex/inputs
SEE ALSO
mf(1), afm2tfm(1), tex(1), latex(1), lpr(1)
AUTHOR
Tomas Rokicki ; extended to
virtual fonts by Don Knuth.