1 PSDVI

USAGE:   PSDVI filename[.DVI] [qualifiers]

PSDVI is not really meant to be used by itself; it is part of the PSPRINT
system.  PSDVI reads a given DVI file (produced by TeX or LaTeX) and
creates a PostScript output file called OUT.PS (unless /OUTPUT is used
to specify some other name).  The output file uses PostScript procedures
whose definitions must be sent to the printer first.  The /HEADER qualifier
can be used to include an appropriate file of definitions at the start of
the output.  PSDVI displays the DVI page number and TeX page counter(s)
as each page is translated.

2 Errors

PSDVI can detect certain errors while translating a DVI file.
The sort of errors you are most likely to see include:

   Page off paper (paper is ...
      The current page contains material beyond one or more paper edges.
      Use DVItoVDU to see where the problem lies.

   Couldn't open font file: ...
      Your DVI file uses a font at a non-existent size.
      Try a different \magstep value in your TeX source file.

   Couldn't open \special file: ...
      PSDVI could not locate the given \special file.
      Check the file's spelling and/or directory location.

Error messages apply to the most recently displayed DVI/TeX page.

2 Graphics

PSDVI allows the inclusion of PostScript graphics using TeX's \special
command.  The given argument is interpreted as a file name, possibly
followed by a space and additional PostScript text that will be treated
as a separate line at the start of the given file.
For example, "\special{figure.ps 2 1 scale}" will cause PSDVI to write a
line containing "2 1 scale" to the output file, then copy the contents
of FIGURE.PS.  (Such a figure will be twice as wide as one included
by \special{figure.ps}.)  The PSPRINT User Guide has more details.

2 Qualifiers

/OUTPUT=file
(default=OUT.PS)

Give an explicit file specification to the output file.

/HEADER=file
(default=no header)

Include the given file at the start of the output file.

/PAGES=first:final
(default=all pages)

Translate a selected subrange of pages from the DVI file.
"first" and "final" can select either DVI page numbers (positive integers)
or TeX page numbers.

Assuming TeX generated the 5 DVI pages `[0] [1] [2.1] [2.2] [3]',
here are some examples of how you could use /PAGES:

   $ PSDVI FOO /PAGES=2      --- translates the second DVI page ([1])
   $ PSDVI FOO /PAGES=2:     --- translates the last four pages
   $ PSDVI FOO /PAGES=:4     --- translates the first four pages
   $ PSDVI FOO /PAGES=[2]    --- translates [2.1] and [2.2]
   $ PSDVI FOO /PAGES=1:[2]  --- translates the first four pages
   $ PSDVI FOO /PAGES=[2.2]: --- translates the last two pages

Note that "first" and "final" are optional; they default to
the first and last DVI pages respectively.

A TeX page specification is of the form [i0.i1...i9].  i0 to i9 are
integers separated by periods and represent the 10 counter values that
TeX stores with each DVI page.  Any number of these integers may be absent
and trailing periods may be omitted.  An absent integer will match any value
in the corresponding counter.  Many DVI pages may match a particular TeX page
specification; if "first" is a TeX page then the LOWEST matching DVI page
is selected, and if "final" then the HIGHEST matching page is selected.

/INCREMENT=i
(default=1)

Assuming f is the first DVI page selected (where f is either 1 or the
start of a /PAGE subrange) then an increment of i tells PSDVI to translate
pages f, f+i, f+2i, f+3i, ... , f+ni, where f+ni is <= the final DVI page
selected.  The primary use of /INCREMENT is to simplify the printing of a
document on both sides of the paper.  E.g., if FOO.DVI has 7 pages then:

   $ PSDVI FOO /INC=2              --- will translate DVI pages 1, 3, 5, 7
   $ PSDVI FOO /INC=2 /PAG=2:      --- will translate DVI pages 2, 4, 6
   $ PSDVI FOO /INC=2 /PAG=2: /REV --- will translate DVI pages 6, 4, 2

Note that the use of /REVERSE with /INCREMENT has no effect on WHICH pages
are translated; it simply changes the ORDER in which they are done.

/MAGNIFICATION=i
(default=use DVI magnification)

Override the DVI magnification with a number representing 1000 times the
desired magnification.  The given integer should correspond to
TeX's \magstep values; see chapter 4 of The TeXbook.

/UNITS=XX
(default=IN)

Set the units of dimensions displayed in some PSDVI messages
(e.g., if the page is off the paper).  XX can be one of:

   IN for inches      (the default)
   CM for centimetres (2.54cm = 1in)
   MM for millimetres (25.4mm = 1in)
   PT for points      (72.27pt = 1in)
   PC for picas       (12pc = 1pt)
   BP for big points  (72bp = 1in)
   PX for pixels      (e.g., an Apple LaserWriter has 300 pixels per inch)

/REVERSE
/NOREVERSE
(default=/noreverse)

By default PSDVI translates pages in ascending order.
Use /REVERSE to translate pages in descending order.

/STATS
/NOSTATS
(default=/nostats)

Use /STATS to see statistics on the number of rules/fonts/characters
appearing on each page, and other useful(?) information.

/CONSERVE_VM
/NOCONSERVE_VM
(default=/noconserve_vm)

Use /CONSERVE_VM if your document won't print because of a "VM error"
(i.e., Virtual Memory is exhausted).  This qualifier will tell PSDVI to
conserve VM at the expense of downloading character bitmaps more often
(resulting in a larger output file that takes longer to print).

/RESOLUTION=i
(default=300)

i is a positive integer specifying the resolution of your printer
in pixels per inch (horizontally and vertically).

/HOFFSET=dimension
/VOFFSET=dimension
(default=0in)
(default=0in)

These qualifiers allow you to shift the printed location of each page
according to the given dimensions.  For example, "/hoffset=-0.5in" would
move each printed page half an inch to the left.
A "dimension" is any integer or real number (possibly negative) followed
by a two-letter unit: IN,CM,MM,PC,PT,BP,PX (same as those for /UNITS).

/XSIZE=posdimen
/YSIZE=posdimen
(default=210mm)
(default=297mm)

PSDVI will automatically check each DVI page to make sure it fits
within the given paper dimensions.  The default values describe
A4 paper with the usual "portrait" orientation.
Swap these values if you plan to use "landscaped" paper.
A "posdimen" is any positive integer or real number followed by a
two-letter unit: IN,CM,MM,PC,PT,BP,PX (same as those for /UNITS).

/PSPREFIX=string
(default="ps-")

PSDVI needs to read TFM files if your document uses resident PostScript
fonts (for which bitmapped information does not exist).
All such fonts must have names beginning with this prefix.

/TFM_DIRECTORY=directory
(default=disk$utils:[utilities.tex.fonts])

Specifies the location of TFM files for resident PostScript fonts.

/FONT_DIRECTORY=directory
(default=disk$utils:[utilities.tex.300pk])

PSDVI gets all its character bitmap information from font files located
in the given directory.

/DUMMY_FONT=file
(default=cmr10.300pk)

This qualifier indicates the naming convention and format of all font files.
PSDVI will warn you about non-existent fonts.  Rather than abort, it will
use the font file specified by /DUMMY_FONT and continue as best it can.
Unlike DVItoVDU, dummy font characters do NOT appear in the output.

! See PSDVI.CLD for details on how these last two qualifiers are used by PSDVI
! to determine the location, naming convention and format of font files.
