DVIPS

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

-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); a3, which selects a3 size; a4, which selects a4 size; legal, which selects legal size (8.5 by 14 inches); ledger, which selects legal size (11 by 17 inches); landscape, which rotates the document by ninety degrees. The default page size is letter. The landscape option may be combined with any of the others; doing so requires giving the -t 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.

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

-K

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

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

-U

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

-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

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.

K

Removes PostScript comments from included PostScript graphics files.

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.

U

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

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

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

\special OPTIONS

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:

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}

       \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

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

AUTHOR

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

CONFIG FILE OPTIONS

PATH INTERPRETATION

POSTSCRIPT FONT SUPPORT

\special OPTIONS

FILES

SEE ALSO

AUTHOR