Category : EmTeX is a TeX/LaTeX document editor
Archive   : DVIPS54.ZIP
Filename : DVIPS.DOC

 
Output of file : DVIPS.DOC contained in archive : DVIPS54.ZIP




DVIPS(1) Pyramid OSx Operating System DVIPS(1)



NNAAMMEE
dvips - convert a TeX DVI file to PostScript (PostScript is
a trademark of Adobe Systems, Inc.)

SSYYNNOOPPSSIISS
dvips [ --cc _n_u_m ] [ --dd _n_u_m ] [ --ee _n_u_m ] [ --ff ] [ --hh _f_i_l_e ] [
--ll _n_u_m ] [ --mm ] [ --nn _n_u_m ] [ --oo _f_i_l_e ] [ --pp _n_u_m ] [ --qq ] [
--rr ] [ --ss ] [ --tt _m_o_d_e_n_a_m_e ] [ --xx _n_u_m ] [ --CC _n_u_m ] [ --DD _n_u_m ]
[ --FF ] [ --KK ] [ --NN ] [ --PP _p_r_i_n_t_e_r_n_a_m_e ] [ --UU ] [ --XX _n_u_m ] [
--YY _n_u_m ] [ --ZZ ] [ --?? ] _f_i_l_e[.dvi]

DDEESSCCRRIIPPTTIIOONN
The program ddvviippss converts a DVI file _f_i_l_e[.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
._d_v_i 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 MMaakkeeTTeeXXPPKK program is installed,
ddvviippss will automatically invoke METAFONT to generate fonts
that don't already exist.

OOPPTTIIOONNSS
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 ffmmqqrrFFKKNNUUZZ. The command line
switches are:

--cc _n_u_m
Generate _n_u_m copies of every page. Default is 1. (For
collated copies, see the --CC option below.)

--dd _n_u_m
Set the debug flags. This is intended only for emer-
gencies or for unusual fact-finding expeditions; it
will work only if ddvviippss has been compiled with the
DEBUG option. The file _d_e_b_u_g._h in the sources indi-
cates what the values of _n_u_m can be. Use a value of -1
for maximum output.

--ee _n_u_m
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 parame-
ter 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



Printed 11/25/90 9 August 1990 1






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



new word, improves the spacing of letters in words.

--ff Run as a filter. Read the DVI file from standard input
and write the PostScript to standard output. The stan-
dard 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.

--hh _n_a_m_e
Prepend file _n_a_m_e as an additional header file. (How-
ever, if the name is simply `-', suppress all header
files from the output.) This header file gets added to
the PostScript userdict.

--ll _n_u_m
The last page printed will be the first one numbered
_n_u_m. Default is the last page in the document.

--mm Specify manual feed for printer.

--nn _n_u_m
At most _n_u_m pages will be printed out. Default is
100000.

--oo _n_a_m_e
The output will be sent to file _n_a_m_e. If no file name
is given, the default name is _f_i_l_e.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 automati-
cally queue the file for printing.

--pp _n_u_m
The first page printed will be the first one numbered
_n_u_m. Default is the first page in the document.

--qq Run in quiet mode. Don't chatter about pages con-
verted, etc.; report nothing but errors to stderr.

--rr Stack pages in reverse order. Normally, page one will
be printed first.

--ss 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 out-
put.

--tt _m_o_d_e_n_a_m_e



Printed 11/25/90 9 August 1990 2






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



This sets the mode to _m_o_d_e_n_a_m_e. Currently, the only
modes allowable are: lleetttteerr, which selects _l_e_t_t_e_r size
(8.5 by 11 inch page); aa33, which selects _a_3 size; aa44,
which selects _a_4 size; lleeggaall, which selects _l_e_g_a_l size
(8.5 by 14 inches); lleeddggeerr, which selects _l_e_g_a_l size
(11 by 17 inches); llaannddssccaappee, which rotates the docu-
ment by ninety degrees. The default page size is
_l_e_t_t_e_r. The llaannddssccaappee option may be combined with any
of the others; doing so requires giving the --tt 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.

--xx _n_u_m
Set the magnification ratio to _n_u_m /1000. Overrides the
magnification specified in the DVI file. Must be
between 10 and 100000.

--CC _n_u_m
Create _n_u_m copies, but collated (by replicating the
data in the PostScript file). Slower than the --cc
option, but easier on the humans.

--DD _n_u_m
Set the resolution in dpi (dots per inch) to _n_u_m. 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.

--FF Causes control-D (ASCII code 4) to be appended as the
very last character of the PostScript file. This is
useful when ddvviippss is driving the printer directly, as
is common on extremely small systems, instead of work-
ing through a spooler.

--KK Removes comments from included graphics files. Only
necessary when using brain-damaged spoolers or
PostScript postprocessors that don't properly interpret
structured comments.

--NN Turns off structured comments; this might be necessary
on some systems that try to interpret PostScript com-
ments in weird ways, or on some PostScript printers.

--PP _p_r_i_n_t_e_r_n_a_m_e
Sets up the output for the appropriate printer. This
is implemented by reading in _c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e, which
can then set the output pipe (as in, o !lpr -Pprinter-
name) 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 _c_o_n_f_i_g._p_s file



Printed 11/25/90 9 August 1990 3






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



and only things that vary printer to printer go in the
_c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e files. Note that _c_o_n_f_i_g._p_s is read
before _c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e. In addition, another file
called ~/._d_v_i_p_s_r_c is searched for immediately after
_c_o_n_f_i_g._p_s; this file is intended for user defaults. If
no --PP command is given, the environment variable
PPRRIINNTTEERR is checked. If that variable exists, and a
corresponding _c_o_n_f_i_g.PPRRIINNTTEERR exists, then that confi-
guration file is read in.

--UU Turns off a virtual memory saving optimization that
triggers a bug in the Xerox 4045 PostScript inter-
preter; not recommended unless you must generate output
to this printer.

--XX _n_u_m
Set the horizontal resolution in dpi (dots per inch) to
_n_u_m.

--YY _n_u_m
Set the horizontal resolution in dpi (dots per inch) to
_n_u_m.

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

CCOONNFFIIGG FFIILLEE OOPPTTIIOONNSS
The file _c_o_n_f_i_g._p_s (and the user's own ~/._d_v_i_p_s_r_c) can be
used to set many of the options to configure ddvviippss 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 TTEEXXCCOONNFFIIGG (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 char-
acter is an option like "o", for example, the remainder of
the line is considered to be a parameter. The options are:

ee _n_u_m
Sets the maximum drift parameter to _n_u_m dots (pixels)
as explained above.

ff Run as a filter by default.




Printed 11/25/90 9 August 1990 4






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



hh _n_a_m_e
Add _n_a_m_e as a PostScript header file to be downloaded
at the beginning.

mm _n_u_m
_n_u_m is the virtual memory available for fonts and
strings in the printer. Default is 180000.

oo _n_a_m_e
The default output file is set to _n_a_m_e. As above, it
can be a pipe.

qq Run in quiet mode by default.

rr Reverse the order of pages by default.

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

tt _m_o_d_e_n_a_m_e
This sets the mode to _m_o_d_e_n_a_m_e. Currently, the only
modes allowable are: lleetttteerr, which selects _l_e_t_t_e_r size
(8.5 by 11 inch page); aa44, which selects _a_4 size;
lleeggaall, which selects _l_e_g_a_l size (8.5 by 14 inches);
llaannddssccaappee, which rotates a _l_e_t_t_e_r size document by
ninety degrees. The default mode is _l_e_t_t_e_r. 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 --tt
_m_o_d_e_n_a_m_e option will override this.

DD _n_u_m
Sets the vertical and horizontal resolution to _n_u_m dots
per inch (dpi).

EE _c_o_m_m_a_n_d
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.

HH _p_a_t_h
The (colon-separated) path to search for PostScript
header files is _p_a_t_h.

KK Removes PostScript comments from included PostScript
graphics files.

MM _m_o_d_e
Set _m_o_d_e as the METAFONT mode to be used when



Printed 11/25/90 9 August 1990 5






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



generating fonts. This is passed along to MakeTeXPK
and overrides mode derivation from the base resolution.

NN Disable PostScript comments by default.

PP _p_a_t_h
The (colon-separated) path to search for bitmap (PK)
font files is _p_a_t_h. The TEXPKS environment variable
will override this. If a % character is found in _p_a_t_h,
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 _m_o_d_e given in
the MM option.

SS _p_a_t_h
The (colon-separated) path to search for special illus-
trations (encapsulated PostScript files or psfiles) is
_p_a_t_h. The TEXINPUTS environment variable will override
this.

TT _p_a_t_h
The (colon-separated) path to search for the tfm files
is _p_a_t_h. The TEXFONTS environment variable will over-
ride 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.

UU Turns off a memory-saving optimization; see the command
line option for more information.

VV _p_a_t_h
The (colon-separated) path to search for virtual font
(VF) files is _p_a_t_h. This may be device-dependent, if
you use virtual fonts to simulate actual fonts on dif-
ferent devices.

WW _s_t_r_i_n_g
Sends _s_t_r_i_n_g to stderr, if it exists; otherwise it can-
cels 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 spe-
cial characteristics.

XX _n_u_m
Sets the horizontal resolution to _n_u_m dots per inch
(dpi).

YY _n_u_m



Printed 11/25/90 9 August 1990 6






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



Sets the vertical resolution to _n_u_m dots per inch
(dpi).

RR _n_u_m _n_u_m ...
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 con-
figuration file.

ZZ Compress all downloaded fonts by default.

PPAATTHH IINNTTEERRPPRREETTAATTIIOONN
All paths variables are the names of directories (path ele-
ments), 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 addi-
tional 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.

PPOOSSTTSSCCRRIIPPTT FFOONNTT SSUUPPPPOORRTT
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 run-
ning the program aaffmm22ttffmm (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 ddvviippss appears in the file
_p_s_f_o_n_t_s._m_a_p, which should be updated whenever you install a
new resident font. See aaffmm22ttffmm for examples and more infor-
mation on this file.




Printed 11/25/90 9 August 1990 7






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



\\ssppeecciiaall OOPPTTIIOONNSS
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 conven-
tions are supported.

First, there's a flexible key-and-value scheme:

\special{psfile="filename"[ key=value]*}

This will download the PostScript file called _f_i_l_e_n_a_m_e such
that the current point will be the origin of the PostScript
coordinate system. If the _f_i_l_e_n_a_m_e string begins with the `
(grave accent) character then the remainder of the _f_i_l_e_n_a_m_e
field is treated as a Unix Bourne shell script to be exe-
cuted with its _s_y_s_o_u_t down loaded as a PostScript file. For
example:

\special{psfile="`zcat packed.ps" ...}

will uncompress the file _p_a_c_k_e_d._p_s._Z for inclusion in ddvviippss
output.

The optional key/value assignments allow you to specify
transformations on the PostScript in _f_i_l_e_n_a_m_e. 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 _f_o_o._p_s 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 rec-
tangular region from (0,0) to (hsize,vsize) in default coor-
dinates, after scaling, translation, and/or rotation. Other-
wise 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



Printed 11/25/90 9 August 1990 8






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



(0,0). The order of operations is: Take the PostScript fig-
ure, 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 _E_n_c_a_p_s_u_l_a_t_e_d _P_o_s_t
_S_c_r_i_p_t (EPS) conventions, then it is possible to use a
simpler \\ssppeecciiaall 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 _v_b_o_x 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 \epsfx-
size 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



Printed 11/25/90 9 August 1990 9






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



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 _p_s_f_i_l_e 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{" _t_e_x_t}

includes _t_e_x_t 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{! _t_e_x_t}

includes _t_e_x_t literally in the prolog (before all typeset-
ting is done), putting definitions in the special diction-
ary; this is good for definitions you intend to use with
\special{"}. Note that _d_v_i_p_s will always include such spe-
cials 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 instruc-
tions to be inserted _w_i_t_h_o_u_t 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:




Printed 11/25/90 9 August 1990 10






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



\special{ps:_t_e_x_t}
\special{ps::_t_e_x_t}
\special{ps::[begin]_t_e_x_t}
\special{ps::[end]_t_e_x_t}
(with longer forms taking precedence over shorter forms,
when they are used). Exception: The command

\special{ps: plotfile _f_i_l_e_n_a_m_e}

will copy the commands from _f_i_l_e_n_a_m_e 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 rroottaattee..tteexx,, which makes it easy to typeset text turned
90 degrees.

Finally, there are two special cases of \special, which pro-
vide alternatives to certain dvips command-line options: (1)
You may put the command

\\ssppeecciiaall{{llaannddssccaappee}}

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

\\ssppeecciiaall{{hheeaaddeerr==_f_i_l_e_n_a_m_e}}

may be used to add _f_i_l_e_n_a_m_e 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 _b_o_p-_h_o_o_k,
_e_o_p-_h_o_o_k, _s_t_a_r_t-_h_o_o_k, or _e_n_d-_h_o_o_k 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 --hh option or
the hheeaaddeerr== 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 exe-
cuted 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 --PP 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



Printed 11/25/90 9 August 1990 11






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



included with a hh line in the configuration file. Note that
multiple --PP 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.

FFIILLEESS
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

SSEEEE AALLSSOO
mf(1), afm2tfm(1), tex(1), latex(1), lpr(1)

AAUUTTHHOORR
Tomas Rokicki ; extended to vir-
tual fonts by Don Knuth.




























Printed 11/25/90 9 August 1990 12






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



NNAAMMEE
dvips - convert a TeX DVI file to PostScript (PostScript is
a trademark of Adobe Systems, Inc.)

SSYYNNOOPPSSIISS
dvips [ --cc _n_u_m ] [ --dd _n_u_m ] [ --ee _n_u_m ] [ --ff ] [ --hh _f_i_l_e ] [
--ll _n_u_m ] [ --mm ] [ --nn _n_u_m ] [ --oo _f_i_l_e ] [ --pp _n_u_m ] [ --qq ] [
--rr ] [ --ss ] [ --tt _m_o_d_e_n_a_m_e ] [ --xx _n_u_m ] [ --CC _n_u_m ] [ --DD _n_u_m ]
[ --FF ] [ --KK ] [ --NN ] [ --PP _p_r_i_n_t_e_r_n_a_m_e ] [ --UU ] [ --XX _n_u_m ] [
--YY _n_u_m ] [ --ZZ ] [ --?? ] _f_i_l_e[.dvi]

DDEESSCCRRIIPPTTIIOONN
The program ddvviippss converts a DVI file _f_i_l_e[.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
._d_v_i 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 MMaakkeeTTeeXXPPKK program is installed,
ddvviippss will automatically invoke METAFONT to generate fonts
that don't already exist.

OOPPTTIIOONNSS
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 ffmmqqrrFFKKNNUUZZ. The command line
switches are:

--cc _n_u_m
Generate _n_u_m copies of every page. Default is 1. (For
collated copies, see the --CC option below.)

--dd _n_u_m
Set the debug flags. This is intended only for emer-
gencies or for unusual fact-finding expeditions; it
will work only if ddvviippss has been compiled with the
DEBUG option. The file _d_e_b_u_g._h in the sources indi-
cates what the values of _n_u_m can be. Use a value of -1
for maximum output.

--ee _n_u_m
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 parame-
ter 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



Printed 11/25/90 9 August 1990 1






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



new word, improves the spacing of letters in words.

--ff Run as a filter. Read the DVI file from standard input
and write the PostScript to standard output. The stan-
dard 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.

--hh _n_a_m_e
Prepend file _n_a_m_e as an additional header file. (How-
ever, if the name is simply `-', suppress all header
files from the output.) This header file gets added to
the PostScript userdict.

--ll _n_u_m
The last page printed will be the first one numbered
_n_u_m. Default is the last page in the document.

--mm Specify manual feed for printer.

--nn _n_u_m
At most _n_u_m pages will be printed out. Default is
100000.

--oo _n_a_m_e
The output will be sent to file _n_a_m_e. If no file name
is given, the default name is _f_i_l_e.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 automati-
cally queue the file for printing.

--pp _n_u_m
The first page printed will be the first one numbered
_n_u_m. Default is the first page in the document.

--qq Run in quiet mode. Don't chatter about pages con-
verted, etc.; report nothing but errors to stderr.

--rr Stack pages in reverse order. Normally, page one will
be printed first.

--ss 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 out-
put.

--tt _m_o_d_e_n_a_m_e



Printed 11/25/90 9 August 1990 2






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



This sets the mode to _m_o_d_e_n_a_m_e. Currently, the only
modes allowable are: lleetttteerr, which selects _l_e_t_t_e_r size
(8.5 by 11 inch page); aa33, which selects _a_3 size; aa44,
which selects _a_4 size; lleeggaall, which selects _l_e_g_a_l size
(8.5 by 14 inches); lleeddggeerr, which selects _l_e_g_a_l size
(11 by 17 inches); llaannddssccaappee, which rotates the docu-
ment by ninety degrees. The default page size is
_l_e_t_t_e_r. The llaannddssccaappee option may be combined with any
of the others; doing so requires giving the --tt 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.

--xx _n_u_m
Set the magnification ratio to _n_u_m /1000. Overrides the
magnification specified in the DVI file. Must be
between 10 and 100000.

--CC _n_u_m
Create _n_u_m copies, but collated (by replicating the
data in the PostScript file). Slower than the --cc
option, but easier on the humans.

--DD _n_u_m
Set the resolution in dpi (dots per inch) to _n_u_m. 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.

--FF Causes control-D (ASCII code 4) to be appended as the
very last character of the PostScript file. This is
useful when ddvviippss is driving the printer directly, as
is common on extremely small systems, instead of work-
ing through a spooler.

--KK Removes comments from included graphics files. Only
necessary when using brain-damaged spoolers or
PostScript postprocessors that don't properly interpret
structured comments.

--NN Turns off structured comments; this might be necessary
on some systems that try to interpret PostScript com-
ments in weird ways, or on some PostScript printers.

--PP _p_r_i_n_t_e_r_n_a_m_e
Sets up the output for the appropriate printer. This
is implemented by reading in _c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e, which
can then set the output pipe (as in, o !lpr -Pprinter-
name) 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 _c_o_n_f_i_g._p_s file



Printed 11/25/90 9 August 1990 3






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



and only things that vary printer to printer go in the
_c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e files. Note that _c_o_n_f_i_g._p_s is read
before _c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e. In addition, another file
called ~/._d_v_i_p_s_r_c is searched for immediately after
_c_o_n_f_i_g._p_s; this file is intended for user defaults. If
no --PP command is given, the environment variable
PPRRIINNTTEERR is checked. If that variable exists, and a
corresponding _c_o_n_f_i_g.PPRRIINNTTEERR exists, then that confi-
guration file is read in.

--UU Turns off a virtual memory saving optimization that
triggers a bug in the Xerox 4045 PostScript inter-
preter; not recommended unless you must generate output
to this printer.

--XX _n_u_m
Set the horizontal resolution in dpi (dots per inch) to
_n_u_m.

--YY _n_u_m
Set the horizontal resolution in dpi (dots per inch) to
_n_u_m.

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

CCOONNFFIIGG FFIILLEE OOPPTTIIOONNSS
The file _c_o_n_f_i_g._p_s (and the user's own ~/._d_v_i_p_s_r_c) can be
used to set many of the options to configure ddvviippss 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 TTEEXXCCOONNFFIIGG (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 char-
acter is an option like "o", for example, the remainder of
the line is considered to be a parameter. The options are:

ee _n_u_m
Sets the maximum drift parameter to _n_u_m dots (pixels)
as explained above.

ff Run as a filter by default.




Printed 11/25/90 9 August 1990 4






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



hh _n_a_m_e
Add _n_a_m_e as a PostScript header file to be downloaded
at the beginning.

mm _n_u_m
_n_u_m is the virtual memory available for fonts and
strings in the printer. Default is 180000.

oo _n_a_m_e
The default output file is set to _n_a_m_e. As above, it
can be a pipe.

qq Run in quiet mode by default.

rr Reverse the order of pages by default.

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

tt _m_o_d_e_n_a_m_e
This sets the mode to _m_o_d_e_n_a_m_e. Currently, the only
modes allowable are: lleetttteerr, which selects _l_e_t_t_e_r size
(8.5 by 11 inch page); aa44, which selects _a_4 size;
lleeggaall, which selects _l_e_g_a_l size (8.5 by 14 inches);
llaannddssccaappee, which rotates a _l_e_t_t_e_r size document by
ninety degrees. The default mode is _l_e_t_t_e_r. 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 --tt
_m_o_d_e_n_a_m_e option will override this.

DD _n_u_m
Sets the vertical and horizontal resolution to _n_u_m dots
per inch (dpi).

EE _c_o_m_m_a_n_d
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.

HH _p_a_t_h
The (colon-separated) path to search for PostScript
header files is _p_a_t_h.

KK Removes PostScript comments from included PostScript
graphics files.

MM _m_o_d_e
Set _m_o_d_e as the METAFONT mode to be used when



Printed 11/25/90 9 August 1990 5






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



generating fonts. This is passed along to MakeTeXPK
and overrides mode derivation from the base resolution.

NN Disable PostScript comments by default.

PP _p_a_t_h
The (colon-separated) path to search for bitmap (PK)
font files is _p_a_t_h. The TEXPKS environment variable
will override this. If a % character is found in _p_a_t_h,
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 _m_o_d_e given in
the MM option.

SS _p_a_t_h
The (colon-separated) path to search for special illus-
trations (encapsulated PostScript files or psfiles) is
_p_a_t_h. The TEXINPUTS environment variable will override
this.

TT _p_a_t_h
The (colon-separated) path to search for the tfm files
is _p_a_t_h. The TEXFONTS environment variable will over-
ride 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.

UU Turns off a memory-saving optimization; see the command
line option for more information.

VV _p_a_t_h
The (colon-separated) path to search for virtual font
(VF) files is _p_a_t_h. This may be device-dependent, if
you use virtual fonts to simulate actual fonts on dif-
ferent devices.

WW _s_t_r_i_n_g
Sends _s_t_r_i_n_g to stderr, if it exists; otherwise it can-
cels 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 spe-
cial characteristics.

XX _n_u_m
Sets the horizontal resolution to _n_u_m dots per inch
(dpi).

YY _n_u_m



Printed 11/25/90 9 August 1990 6






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



Sets the vertical resolution to _n_u_m dots per inch
(dpi).

RR _n_u_m _n_u_m ...
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 con-
figuration file.

ZZ Compress all downloaded fonts by default.

PPAATTHH IINNTTEERRPPRREETTAATTIIOONN
All paths variables are the names of directories (path ele-
ments), 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 addi-
tional 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.

PPOOSSTTSSCCRRIIPPTT FFOONNTT SSUUPPPPOORRTT
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 run-
ning the program aaffmm22ttffmm (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 ddvviippss appears in the file
_p_s_f_o_n_t_s._m_a_p, which should be updated whenever you install a
new resident font. See aaffmm22ttffmm for examples and more infor-
mation on this file.




Printed 11/25/90 9 August 1990 7






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



\\ssppeecciiaall OOPPTTIIOONNSS
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 conven-
tions are supported.

First, there's a flexible key-and-value scheme:

\special{psfile="filename"[ key=value]*}

This will download the PostScript file called _f_i_l_e_n_a_m_e such
that the current point will be the origin of the PostScript
coordinate system. If the _f_i_l_e_n_a_m_e string begins with the `
(grave accent) character then the remainder of the _f_i_l_e_n_a_m_e
field is treated as a Unix Bourne shell script to be exe-
cuted with its _s_y_s_o_u_t down loaded as a PostScript file. For
example:

\special{psfile="`zcat packed.ps" ...}

will uncompress the file _p_a_c_k_e_d._p_s._Z for inclusion in ddvviippss
output.

The optional key/value assignments allow you to specify
transformations on the PostScript in _f_i_l_e_n_a_m_e. 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 _f_o_o._p_s 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 rec-
tangular region from (0,0) to (hsize,vsize) in default coor-
dinates, after scaling, translation, and/or rotation. Other-
wise 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



Printed 11/25/90 9 August 1990 8






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



(0,0). The order of operations is: Take the PostScript fig-
ure, 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 _E_n_c_a_p_s_u_l_a_t_e_d _P_o_s_t
_S_c_r_i_p_t (EPS) conventions, then it is possible to use a
simpler \\ssppeecciiaall 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 _v_b_o_x 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 \epsfx-
size 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



Printed 11/25/90 9 August 1990 9






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



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 _p_s_f_i_l_e 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{" _t_e_x_t}

includes _t_e_x_t 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{! _t_e_x_t}

includes _t_e_x_t literally in the prolog (before all typeset-
ting is done), putting definitions in the special diction-
ary; this is good for definitions you intend to use with
\special{"}. Note that _d_v_i_p_s will always include such spe-
cials 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 instruc-
tions to be inserted _w_i_t_h_o_u_t 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:




Printed 11/25/90 9 August 1990 10






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



\special{ps:_t_e_x_t}
\special{ps::_t_e_x_t}
\special{ps::[begin]_t_e_x_t}
\special{ps::[end]_t_e_x_t}
(with longer forms taking precedence over shorter forms,
when they are used). Exception: The command

\special{ps: plotfile _f_i_l_e_n_a_m_e}

will copy the commands from _f_i_l_e_n_a_m_e 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 rroottaattee..tteexx,, which makes it easy to typeset text turned
90 degrees.

Finally, there are two special cases of \special, which pro-
vide alternatives to certain dvips command-line options: (1)
You may put the command

\\ssppeecciiaall{{llaannddssccaappee}}

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

\\ssppeecciiaall{{hheeaaddeerr==_f_i_l_e_n_a_m_e}}

may be used to add _f_i_l_e_n_a_m_e 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 _b_o_p-_h_o_o_k,
_e_o_p-_h_o_o_k, _s_t_a_r_t-_h_o_o_k, or _e_n_d-_h_o_o_k 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 --hh option or
the hheeaaddeerr== 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 exe-
cuted 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 --PP 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



Printed 11/25/90 9 August 1990 11






DVIPS(1) Pyramid OSx Operating System DVIPS(1)



included with a hh line in the configuration file. Note that
multiple --PP 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.

FFIILLEESS
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

SSEEEE AALLSSOO
mf(1), afm2tfm(1), tex(1), latex(1), lpr(1)

AAUUTTHHOORR
Tomas Rokicki ; extended to vir-
tual fonts by Don Knuth.




























Printed 11/25/90 9 August 1990 12