.TH DVI2PS L ""
.UC
.SH NAME
dvi2ps \- convert a TeX DVI file to PostScript  
.br
(PostScript is a trademark of Adobe Systems, Inc).
.SH SYNOPSIS
.B dvi2ps
[-a fontpaths] [-b tfmpaths] [-B budget]
[-c] [-d density] [-D] [-E] [-f from] [-h] [-i file] [-l] 
[-m{0|h|1|2|3|4|5| mag}] [-n copies]
[-o option] [-O] [-p] [-q] [-r] [-s] [-S] [-t to] [-w] [-x extrapages]
dvifile[.dvi]
.br
.SH DESCRIPTION
.I Dvi2ps
converts a DVI file to PostScript,
and writes the result to standard output.
DVI files are usually produced by the TeX or LaTeX text formatting systems.
The result requires a moderate amount of PostScript
source to precede it to the printer, before it can be successfully printed.
By default, that PostScript code is prepended to the output.
.PP
When
.I dvi2ps
starts, it looks for a standard startup file called ".dvi2ps" in the current
 directory. If it is not found there, then
.I dvi2ps
looks in the user's home directory. Any command line argument may be placed 
in this file. Exactly one argument is allowed per line; the first
character of the line must by a valid option. Actual command line 
arguments are processed after the setup file.
.SH FONTS
Resident PostScript fonts can be used. The dictionary which translates
between the TeX names and the PostScript names of the resident fonts is 
contained in the file "/usr/local/tex/DVIware/psfonts.map". 
.I Dvi2ps
must have access to the .tfm files in order to use the resident fonts.
These files are searched for in the default directory 
"/usr/local/tex/fonts". If there is an environment variable TEXFONTS,
its value replaces the default with a colon-separated list of directories.
This value can also be replaced using the command line option "-b".
All other needed fonts are included in the Postscript code as explicit bitmaps.
This leads to very large Postscript files.
.PP
Other font files are assumed to exist somewhere on the font path.
The font path is made up of all the font directories listed on the
colon-separated default path ".:/usr/local/tex/fonts". The default is 
replaced by the value of the environment variable DVIFONTS, or both of these
can be replaced by the command line argument "-a".
The program will search each directory in the list; it will also search
any subdirectories named "pk", "pk300", "gf", "gf300", or "pxl" if fonts
of the named type are expected to be used. Within any of these directories, 
the presence of a file named SUBDIR indicates that fonts are further separated
into subdirectories. For example, all magnifications of "cmr10" will be 
found in a subdirectory with that name. Finally, the program
recognizes absolute path names for fonts if these have been specified in the
TeX file.
.PP
If a font file is not available (on the font path)
in the exact resolution needed to display on the laser printer
.I dvi2ps
will attempt a font substitution.
If a ``good match'' is found,
then a font substitution is made and logged. This substituted font will be
scaled using PostScript scaling operations to attempt a reasonable fit.
When no font can be substituted for a missing font,
.I dvi2ps
will continue to process the DVI file, and will log a warning message.
Gaps will appear in the document where the missing characters should have been.
.PP This version of
.I dvi2ps
supports the use of Japanese fonts ("jis", "dm", "dg") and Chinese fonts
("chfont"). To optimize the use of these fonts, the prefixes should be listed 
in the file "/usr/local/tex/DVIware/psfonts.map". The simplest prefix entry
is of the form "jis prefix", which indicates to
.I dvi2ps
that there is a family of fonts beginning with that name, which can be 
intermingled when downloaded to the printer. these entries can me modified
with either "downloaded", to mean that the fonts have been permanently
downloaded to the printer; or with "onewidth firstchar lastchar tfmw", to mean
that the first character code is "firstchar", the last is "lastchar", and
all characters in the font have the same tfm width "tfmw".
.SH PAGINATION
There are several command line options that affect which pages are printed.
These are "-f from", "-t to", "-x", "-E", and "-O". Regardless of the order
in which they appear, the "-f" and "-t" options are processed first. The
"-E" and "-O" options are special cases of "-x", which appears in three forms:
"-x single", "-x from:to", or "-x from:by:to". These options all read the
TeX variable count0. They cannot be used to get multiple copies of single pages;
the list of pages produced is always just the union of all specified pages.
Multiple copies can only be specified on a job-wise basis through the
"-n" option.
.SH OPTIONS
.TP
.B \-a fontpaths
Specify a different list of directories to be searched for font files. 
This list replaces the default or the value of the environment variable
DVIFONTS; the best use is probably to specify something like 
"dvi2ps -a newdir:$DVIFONTS ..."
.TP
.B \-b tfmpaths
Specify a different list of directories to be searched for tfm files of
builtin fonts.  This list replaces the default or the value of the 
environment variable TEXFONTS.
.TP
.B \-B budget
Specify a value for the estimated available Virtual Memory. The default
is 90000. Setting the value too low may slow down printing considerably;
setting the value too high may lead to a VM error on the printer.
.TP
.B \-c
Create an output file in the spool directory. On most systems, if your DVI 
file is called "myfile.dvi", using this option will create a PostScript file 
called "myfile.ps". On Apollos, this option directs output to a file with
a unique name, created in a spool directory. This option may be disabled
at some sites.
.TP
.B \-d density
Specify the font pixel density of the output. The default is 300 dots per
inch (suitable for the Apple LaserWriter).
.TP
.B \-D
Turn on debugging output. (You almost certainly don't want to.) This may be 
disabled at some sites.
.TP
.B \-E
Only print even numbered pages.
.TP
.B \-f from
Specify a starting page number. Default is -10000.
(this is a TeX page number -- \\count0).
.TP
.B \-h
Do not copy the standard header file through to output. The default, 
"/usr/local/tex/DVIware/dvi2ps.pro", can be overridden by the environment
variable PSHEADER.
.TP
.B \-i file
Copy the named file to the output
The contents of the file named will be copied to the output
after the standard header file has been copied,
but before the DVI file is translated.
.TP
.B \-l
Disable logging of errors. Without this option, warnings will be logged 
to "myfile.dlog" in addition to being written to stderr. Any errors that 
occur before the command line is fully processed may not be logged correctly.
.TP
.B \-m{0|h|1|2|3|4|5| mag}
Specify a magnification to use to print the document.  The forms -m0,-mh,...,
-m5 indicate the standard magic numbers 1000, 1095,..., 2488. This option 
might be disabled at some sites.
.TP
.B \-n number
Specify the number of copies to print
.TP
.B \-o option
Specify a PostScript printing option.
Recognized options are "letter", "note", "legal", "landscape", "draft", 
"twoup", "duplex" and "manualfeed" (without the quotes). 
This argument may be repeated 
several times.
.TP
.B \-O
Only print odd numbered pages.
.TP
.B \-p
Do not preload font information.
Occasionally there may be insufficient memory to hold the
information about all of the fonts in the system.  Portions
of the document may be converted by including the -p option
on the command line.  This will prevent the preloading of
all fonts into the system and instead use demand loading of
the font tables. The -p option implies the -r option.
.TP
.B \-q
Be quiet.  Don't chatter about pages converted, etc.
.TP
.B \-r
Stack pages in reverse order.
Normally, the DVI pages are processed in reverse order, with the
result that they are stacked in the correct order in the output
tray.  This option reverses that.
.TP
.B \-s
Run as an lpd spooler; take input from stdin. May be disabled at some sites.
.TP
.B \-S
Turn on printing of statistics.
Some versions of 
.I dvi2ps
will optionally print statistics about
font usage and some other information that is generally only 
interesting to developers.  On these systems, -s turns on
the statistics printing.
.TP
.B \-t to
Specify an ending page number. Default is 10000.
.TP
.B \-w
Don't print out warnings.
.TP
.B \-x extrapages
Specify additional pages to print. extrapages must be in one of the forms
"single", "from:to", or "from:by:to". The first form specifies a single 
page to print. The second form specifies a range of pages. The final form 
specifies a modular range of pages---print every by'th page, starting with
page "from". Can be used any number of times, or multiple arguments can be 
separated by commas. All extrapages are processed after the -f
and -t options, regardless of where they appear in the command line. Note 
that "-f from -t to" is equivalent to "-x from:to".
.SH TeX \\\\special command:
.I Dvi2ps
supports Trevor Darrell's psfig/TeX ((C) Copyright 1987, 1988 by Trevor Darrell).
This is a package of TeX macros for including PostScript graphics. This is the 
recommended methos for including graphics. A user's guide to psfig/TeX is 
available. For those who, nevertheless, prefer to do things by hand, the 
following \\special's are available:
.PP
Specifying "\\special{psfile=foo.ps}" in the TeX source will result in the 
contents of file "foo.ps" (assumed to contain PostScript code) being copied 
into the output at that point.  For most included graphics, the
users (0,0) point will be set to the point of the \\special command
with x and y coordinates increasing up and to the right and in units
of PostScript points (72/inch) -- thus you must explicitly leave space
above the \\special command for most graphics.  This works, for example,
with the output of the version of "fig2ps" included with the TransFig
package.  For graphics produced by 
Apple Macintoshes (i.e., MacDraw, MacPaint, etc.), the top left corner of 
the drawing will be at the point of the \\special command; in this case you
must leave the required space below the \\special.
.PP
The \\special string can contain any number of the following 
"keyword=value" pairs, separated by blanks:

   Keyword   Value Type
   -------   ----------
   psfile    string      - A PostScript file to include
   hsize     dimension   - Maximum horizontal size
                              (for clipping)
   vsize     dimension   - Maximum vertical size
                              (for clipping)
   hoffset   dimension   - Amount to shift right
   voffset   dimension   - Amount to shift up
                              (or down, for MacDraw'ings)
   hscale    number      - A scale factor in x-dimension
   vscale    number      - A scale factor in y-dimension
.PP
dimensions are given in inches.
.PP
THUS: \\special{psfile=foo.ps hoffset=1 hscale=0.9 vscale=0.9}
will shift the graphics produced by file "foo.ps" right by
1", and will draw it at 0.9 normal size.
.PP
hsize and vsize are given relative to the (0,0) point of the drawing
and are unaffected by offsets and scales.
.PP
hoffset and voffset are given relative to the point of the \\special command,
and are unaffected by scales.
.PP
If Macintosh drawings are to be included, the proper laserprep file
must be downloaded to the printer, either permanently or as another
header file in addition to the standard "dvi2ps.pro" header file.
.PP
The \\special{pstext=...} copies the PostScript code specified as the value
of pstext directly into the output file. This feature is primarly useful
for including PostScript definitions needed by included graphics.
.SH ENVIRONMENT
DVIFONTS                    Default path for font files.
TEXFONTS                     Default path for tfm files.
HEADER                   Name of the default header file.
.SH FILES
*.dvi                TeX DeVice Independent output file.
*.ps                            Output file, if created.
*.dlog                                  Dvi2ps log file.
/HOME/.dvi2ps                        User's set up file.
/usr/local/tex/fonts              TeX default tfm files.
/usr/local/tex/fonts/pk300   TeX default PK font rasters.
/usr/local/tex/fonts/gf300   TeX default GF font rasters.
/usr/local/tex/fonts/pxl     TeX default PXL font rasters.
/usr/local/tex/DVIware/dvi2ps.pro         PostScript code.
.SH SEE ALSO
tex(1L), latex(1L), dviselect(1L)
.SH BUGS
The positioning algorithm is the "official" dvitype-sanctified algorithm
when using the cm fonts. It may not be quite correct when using the
builtin fonts. Options "-s" and "-c" may not work correctly if both are
specified. The implementation of asian fonts has not been fully tested,
since I don't write Japanese or Chinese. The inability to specify pages
with anything other than count0 should be rectified; it should also be
possible to specify multiple copies of individual pages.
.SH AUTHORS
.PP
Mark Senn wrote the early versions of this program for the
BBN BitGraph.  Stephan Bechtolsheim, Bob Brown, Richard
Furuta, James Schaad and Robert Wells improved it.  Norm
Hutchinson ported the program to the Sun.  Neal Holtz ported
it to the Apollo, and then to produce PostScript.
Howard Trickey made it read GF files instead of PXL files.
Les Carr added the capacity to use builtin LaserWriter fonts, and psfig.
Van Jacobson added the font flushing control and improved the handling of 
builtin fonts. Van Jacobson and Piet van Oostrum made it read PK fonts. 
Jing-bai Wang added several specials. Greg Lee added support for getopt. 
Kevin Coombes merged several versions, improved the font searching routines, 
and enhanced the page specification option. Thousands of other people have 
probably been left off this list.
