⟦6e0222bf0⟧

TextFile

.\" man page for dvips
.ds PS P\s-2OST\s+2S\s-2CRIPT\s+2
.\" typeset examples in fixed size font as indented paragraph
.de Ex
.sp
.RS
.nf
.ft C
..
.de Xe
.RE
.sp
.fi
..
.TH DVIPS 1 "9 August 1990" TeXware
.SH NAME
dvips \- convert a TeX DVI file to \*(PS
.SH SYNOPSIS
.B dvips
[
.B \-c
.I num
]
[
.B \-d
.I num
]
[
.B \-e
.I num
]
[
.B \-f
]
[
.B \-h
.I file
]
[
.B \-l
.I num
]
[
.B \-m
]
[
.B \-n
.I num
]
[
.B \-o
.I file
]
[
.B \-p
.I num
]
[
.B \-q
]
[
.B \-r
]
[
.B \-s
]
[
.B \-t
.I modename
]
[
.B \-x
.I num
]
[
.B \-C
.I num
]
[
.B \-D
.I num
]
[
.B \-F
]
[
.B \-K
]
[
.B \-N
]
[
.B \-P
.I printername
]
[
.B \-U
]
[
.B \-X
.I num
]
[
.B \-Y
.I num
]
[
.B \-Z
]
[
.B \-?
]
.IR file [.dvi]
.br
.SH DESCRIPTION
The program
.B dvips
converts a DVI file
.IR file [.dvi]
produced by TeX (or by some other processor like GFtoDVI)
and converts it to \*(PS, normally
sending the result directly to the laserprinter.
The DVI file may be specified without the
.I .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
.B MakeTeXPK
program is installed,
.B dvips
will automatically invoke METAFONT to generate fonts that don't already exist.
.SH 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 \fBfmqrFKNUZ\fP.
The command line switches are:
.IP "\fB\-c\fP \fInum\fP"
Generate
.I num
copies of every page.
Default is 1. (For collated copies, see the
.B \-C
option below.)
.IP "\fB\-d\fP \fInum\fP"
Set the debug flags.
This is intended only for emergencies or for unusual
fact\-finding expeditions; it will work only if
.B dvips
has been compiled with the DEBUG option.
The file
.I debug.h
in the sources indicates what the values of
.I num
can be. Use a value of \-1 for maximum output.
.IP "\fB\-e\fP \fInum\fP"
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.
.IP "\fB\-f\fP"
Run as a filter.
Read the DVI file from standard input and write the \*(PS 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.
.IP "\fB\-h\fP \fIname\fP"
Prepend file
.I 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 \*(PS userdict.
.IP "\fB\-l\fP \fInum\fP"
The last page printed will be the first one numbered
.I num.
Default is the last page in the document.
.IP "\fB\-m\fP"
Specify manual feed for printer.
.IP "\fB\-n\fP \fInum\fP"
At most
.I num
pages will be printed out.
Default is 100000.
.IP "\fB\-o\fP \fIname\fP"
The output will be sent to file
.I name.
If no file name is given, the default name is
.IR 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.
.IP "\fB\-p\fP \fInum\fP"
The first page printed will be the first one numbered
.I num.
Default is the first page in the document.
.IP "\fB\-q\fP"
Run in quiet mode.
Don't chatter about pages converted, etc.; report nothing but errors to stderr.
.IP "\fB\-r\fP"
Stack pages in reverse order.
Normally, page one will be printed first.
.IP "\fB\-s\fP
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.
.IP "\fB\-t\fP \fImodename\fP"
This sets the mode to \fImodename\fP.
Currently, the only modes allowable are:
\fBletter\fP, which selects \fIletter\fP size (8.5 by 11 inch page);
\fBa3\fP, which selects \fIa3\fP size;
\fBa4\fP, which selects \fIa4\fP size;
\fBlegal\fP, which selects \fIlegal\fP size (8.5 by 14 inches);
\fBledger\fP, which selects \fIlegal\fP size (11 by 17 inches);
\fBlandscape\fP, which rotates the document by ninety degrees.
The default page size is \fIletter\fP.
The \fBlandscape\fP option may be combined with any of the others;
doing so requires giving the \fB-t\fP option twice.
The upper left corner of each page in
the DVI file is placed one inch from the left and one inch from the top.
.IP "\fB\-x\fP \fInum\fP"
Set the magnification ratio to
.I num
/1000. Overrides the magnification specified in the DVI file.
Must be between 10 and 100000.
.IP "\fB\-C\fP \fInum\fP"
Create
.I num
copies, but collated (by replicating the data in the \*(PS file).
Slower than the
.B \-c
option, but easier on the humans.
.IP "\fB\-D\fP \fInum\fP"
Set the resolution in dpi (dots per inch) to
.I num.
This affects the choice of bitmap fonts that are loaded and also the positioning
of letters in resident \*(PS fonts. Must be between 10 and 10000.
This affects both the horizontal and vertical resolution.
.IP "\fB\-F\fP"
Causes control\-D (ASCII code 4) to be appended as the very last character
of the \*(PS file. This is useful when
.B dvips
is driving the printer directly, as is common on extremely small systems,
instead of working through a spooler.
.IP "\fB\-K\fP"
Removes comments from included graphics files. Only necessary when
using brain-damaged spoolers or \*(PS postprocessors that don't
properly interpret structured comments.
.IP "\fB\-N\fP"
Turns off structured comments; this might be necessary on some systems
that try to interpret \*(PS comments in weird ways, or on some
\*(PS printers.
.IP "\fB\-P\fP \fIprintername\fP"
Sets up the output for the appropriate printer. This is implemented
by reading in
.I 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
.I config.ps
file and only things that vary
printer to printer go in the
.I config.printername
files. Note that
.I config.ps
is read before
.I config.printername.
In addition, another file called
.I ~/.dvipsrc
is searched for immediately after
.I config.ps;
this file is intended for user defaults. If no \fB\-P\fP command is
given, the environment variable \fBPRINTER\fP is checked. If that
variable exists, and a corresponding
.I config.\fBPRINTER\fP
exists, then that configuration file is read in.
.IP "\fB\-U\fP"
Turns off a virtual memory saving optimization that triggers a bug in
the Xerox 4045 \*(PS interpreter; not recommended unless you must
generate output to this printer.
.IP "\fB\-X\fP \fInum\fP"
Set the horizontal resolution in dpi (dots per inch) to
.I num.
.IP "\fB\-Y\fP \fInum\fP"
Set the horizontal resolution in dpi (dots per inch) to
.I num.
.IP "\fB\-Z\fP"
Causes bitmap fonts to be compressed before they are downloaded,
thereby reducing the size of the \*(PS 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
\*(PS printers.
.IP "\fB\-?\fP"
Print out the banner identifying the program.
.SH "CONFIG FILE OPTIONS"
The file
.I config.ps
(and the user's own
.I "~/.dvipsrc\fR)"
can be used to set many of the options to configure
.B 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 \fBTEXCONFIG\fP
(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:
.IP "\fBe\fP \fInum\fP"
Sets the maximum drift parameter to
.I num
dots (pixels) as explained above.
.IP "\fBf\fP"
Run as a filter by default.
.IP "\fBh\fP \fIname\fP"
Add
.I name
as a \*(PS header file to be downloaded at the beginning.
.IP "\fBm\fP \fInum\fP"
.I num
is the virtual memory available for fonts and strings in the printer.
Default is 180000.
.IP "\fBo\fP \fIname\fP"
The default output file is set to
.I name.
As above, it can be a pipe.
.IP "\fBq\fP"
Run in quiet mode by default.
.IP "\fBr\fP"
Reverse the order of pages by default.
.IP "\fBs\fP"
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.
.IP "\fBt\fP \fImodename\fP"
This sets the mode to \fImodename\fP.
Currently, the only modes allowable are:
\fBletter\fP, which selects \fIletter\fP size (8.5 by 11 inch page);
\fBa4\fP, which selects \fIa4\fP size;
\fBlegal\fP, which selects \fIlegal\fP size (8.5 by 14 inches);
\fBlandscape\fP, which rotates
a \fIletter\fP size document by ninety degrees.
The default mode is \fIletter\fP. 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 \fB\-t\fP \fImodename\fP option will override this.
.IP "\fBD\fP \fInum\fP"
Sets the vertical and horizontal resolution to
.I num
dots per inch (dpi).
.IP "\fBE\fP \fIcommand\fP"
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.
.IP "\fBH\fP \fIpath\fP"
The (colon\-separated) path to search for \*(PS header
files is
.I path.
.IP "\fBK\fP"
Removes \*(PS comments from included \*(PS graphics files.
.IP "\fBM\fP \fImode\fP"
Set
.I 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.
.IP "\fBN\fP"
Disable \*(PS comments by default.
.IP "\fBP\fP \fIpath\fP"
The (colon\-separated) path to search for bitmap (PK) font files is
.I path.
The TEXPKS environment variable will override this.
If a \fI%\fP character is found in \fIpath\fP,
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 \fImode\fP given
in the \fBM\fP option.
.IP "\fBR\fP \fInum\fP \fInum\fP \fI...\fP"
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 \*(PS 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.
.IP "\fBS\fP \fIpath\fP"
The (colon\-separated) path to search for special illustrations
(encapsulated \*(PS files or psfiles) is
.I path.
The TEXINPUTS environment variable will override this.
.IP "\fBT\fP \fIpath\fP"
The (colon\-separated) path to search for the tfm files is
.I 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.
.IP "\fBU\fP"
Turns off a memory-saving optimization; see the command line option for more
information.
.IP "\fBV\fP \fIpath\fP"
The (colon\-separated) path to search for virtual font (VF) files is
.I path.
This may be device\-dependent, if you use virtual fonts to simulate
actual fonts on different devices.
.IP "\fBW\fP \fIstring\fP"
Sends
.I 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.
.IP "\fBX\fP \fInum\fP"
Sets the horizontal resolution to
.I num
dots per inch (dpi).
.IP "\fBY\fP \fInum\fP"
Sets the vertical resolution to
.I num
dots per inch (dpi).
.IP "\fBZ\fP"
Compress all downloaded fonts by default.
.SH "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.
.PP
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:
.Ex
setenv TEXINPUTS ~:
.Xe
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.
.SH "POSTSCRIPT FONT SUPPORT"
This version of dvips supports \*(PS 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
.B 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
.B dvips
appears in the file
.I psfonts.map,
which should be updated whenever you install a new resident font. See
.B afm2tfm
for examples and more information on this file.
.SH "\especial OPTIONS"
This DVI driver allows the inclusion of \*(PS code
to be inserted in a TeX file via TeX's \especial command.
For compatibility with other systems, several different conventions
are supported.
.PP
First, there's a flexible key\-and\-value scheme:
.Ex
\especial{psfile="filename"[ key=value]*}
.Xe
This will download the \*(PS file called
.I filename
such that the current point will be the origin of the \*(PS
coordinate system.
If the
.I filename
string begins with the ` (grave accent) character then the remainder of the
.I filename
field is treated as a Unix Bourne shell script to be
executed with its
.I sysout
down loaded as a \*(PS file.
For example:
.Ex
\especial{psfile="`zcat packed.ps" ...}
.Xe
will uncompress the file
.I packed.ps.Z
for inclusion in
.B dvips
output.
.PP
The optional key/value assignments allow you
to specify transformations on the \*(PS in
.I filename.
The possible keys are:
.RS
.nf
.ta 1.5i
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)
.fi
.RE
The hoffset, voffset, hsize, and vsize are given in \*(PS 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 \*(PS file.
The hscale and vscale are given in non\-dimensioned percentage units, and the
rotate value is specified in degrees.
Thus
.Ex
\especial{psfile=foo.ps hoffset=72 hscale=90 vscale=90}
.Xe
will shift the graphics produced by file
.I 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 \especial command, and are
unaffected by scaling or rotation. Rotation is counterclockwise about (0,0).
The order of operations is: Take the \*(PS 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 \*(PS coordinates of the graphic in cropthis.ps,
you would say
.Ex
\especial{psfile=cropthis.ps
hoffset=\-100 yoffset=\-200
hsize=72 vsize=72}
.Xe
Secondly, if your file conforms to the
.I "Encapsulated Post Script"
(EPS) conventions, then it is possible to use a simpler
.B \especial
command that will automatically reserve the required space.
.PP
To use, simply say
.Ex
\einput epsf % at the beginning of your TeX document
\eepsfbox{filename.ps} % at the place where you want the figure
.Xe
A
.I 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 `\eepsfxsize'
to something else, such as `\ehsize'; the figure will be scaled so that
\eepsfxsize is its final width.
A more general facility for sizing is available by defining the
`\eepsfsize' macro. This macro is used to give \eepsfxsize a
value each time \eepsffile is called. It takes two parameters;
the first is the horizontal natural size of the \*(PS figure,
and the second is the vertical natural size. (Natural size, in
this case, is the size in \*(PS points from the bounding box
comment.) The default definition of this macro is
.Ex
\edef\eepsfsize#1#2{\eepsfxsize}
.Xe
which just means to take the value that was set before the macro
was invoked. Note that the variable \eepsfxsize is reset to zero
at the end of each call to \eepsffile. 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:
.Ex
\eepsfxsize % just leave the old value alone
0pt % use the natural sizes
#1 % use the natural sizes
\ehsize % scale to full width
0.5#1 % scale to 50% of natural size
\eifnum#1>\ehsize\ehsize\eelse#1\efi % smaller of natural, hsize
.Xe
The resultant vbox can be centered with \ecenterline, or treated as any other vbox. If you are using LaTeX and the center environment, be sure to execute
a \eleavevmode before each use of \eepsffile, so that LaTeX leaves the
vertical mode and enters the paragraph making mode. (This should probably
be provided by the LaTeX macros themselves.)
.PP
(The \eepsfbox 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 \*(PS file to be included is not EPSF, you are probably better
off using the
.I psfile
special instead.)
.PP
Thirdly, there are special commands for drawing diagrams using the conventions
of `TPIC' (a portable, non\-\*(PS\-dependent program by Tim Morgan,
with \*(PS implementation by Dorab Patel). For example,
`\especial{pn 2}' in this language sets the pen size to .002 inch.
.PP
A fourth type of \especial allows you to write \*(PS instructions that
will be passed literally to dvips's output file. These are intended for
people whose favorite graphics language is raw \*(PS.
.Ex
\especial{" \fItext\fP}
.Xe
includes
.I text
literally in the output \*(PS document,
after translating the origin to the current page position, opening a
special user dictionary, and
and reverting to the \*(PS convention of 72 units=1in.
.Ex
\especial{! \fItext\fP}
.Xe
includes
.I 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 \especial{"}.
Note that
.I 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 \*(PS definitions are used, provided that
you give definitions before their first use.
.PP
A fifth type of \especial allows literal \*(PS instructions to be
inserted
.I 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 \*(PS 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:
.Ex
\especial{ps:\fItext\fP}
\especial{ps::\fItext\fP}
\especial{ps::[begin]\fItext\fP}
\especial{ps::[end]\fItext\fP}
.Xe
(with longer forms taking precedence over shorter forms, when they are used).
Exception: The command
.Ex
\especial{ps: plotfile \fIfilename\fP}
.Xe
will copy the commands from
.I 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
.B rotate.tex,
which makes it easy to typeset text turned 90 degrees.
.PP
Finally, there are two special cases of \especial, which provide
alternatives to certain dvips command\-line options: (1) You may put the command
.Ex
.B "\especial{landscape}"
.Xe
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
.Ex
.B "\especial{header=\fIfilename\fP}"
.Xe
may be used to add
.I 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 \*(PS userdict.
.PP
For special effects, if any of the macros
.I bop\-hook, eop\-hook, start\-hook,
or
.I end\-hook
are defined in the \*(PS 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 \*(PS coordinate system
is in effect. Such macros can be defined in headers added by the
.B \-h
option or the
.B 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.
.PP
Several of the above tricks can be used nicely together. For instance, a
.B \-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
.B h
line in the configuration file. Note that multiple
.B \-P
options can be used.
.PP
If the filename in any of the \*(PS inclusion options begins with a
backtick, that name is interpreted instead as a command to be executed to
generate the appropriate file. The \*(PS must be generated to
standard output by the command. This is useful, for instance, for
uncompressing large \*(PS files using zcat.
.SH FILES
Files used by dvips are usually system dependent, but the following
are typical:
.RS
.nf
.ta 2.5i
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
.fi
.RE
.SH "SEE ALSO"
mf(1), afm2tfm(1), tex(1), latex(1), lpr(1)
.SH NOTES
\*(PS is a registered trademark of Adobe Systems Incorporated.
.SH AUTHOR
Tomas Rokicki <rokicki@neon.stanford.edu>; extended to virtual fonts
by Don Knuth.

DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦6e0222bf0⟧ TextFile

Derivation

TextFile