'\" e
.\" $Header: /usr/jjc/dvitops/RCS/dvitops.1,v 1.5 90/08/14 13:31:17 jjc Rel $
.TH DVITOPS L
.SH NAME
dvitops \- convert the output of TeX to PostScript
.SH SYNOPSIS
.B dvitops
[
.B \-qrs
] [
.BI \-c ncopies
] [
.BI \-f firstpage
] [
.BI \-n npages
]
.if n .ti +0.5i
[
.BI \-m magnification
] [
.BI \-y kmem
] [
.BI \-h hoffset
] 
.if n .ti +0.5i
.if t .ti +0.5i
[
.BI \-v voffset
] [
.BI \-p papersize
] [
.BI \-d dpi
] [
.I dvifile
]
.SH DESCRIPTION
.B dvitops
converts a dvi file produced by TeX into PostScript.
If the
.I dvifile
argument is not present,
.B dvitops
reads the standard input. In this case the standard input must be a file
rather than a pipe.
The extension
.B .dvi
may be omitted.
The output is written on the standard output, and is normally piped
into
.BR lpr .
Either bitmap fonts in pk format, or ordinary PostScript fonts
may be used. If PostScript fonts are used which are not
resident in the printer, the output of
.B dvitops
must be passed through a filter or spooler that can handle
font downloading.
.SH OPTIONS
.TP
.B \-q
Quiet mode. Don't print the numbers of pages as they are printed.
.TP
.B \-r
Output pages in reverse order.
.TP
.B \-s
Sort pages by their
.B \ecount0
values.
.TP
.BI \-c ncopies
Print
.I ncopies
of each page. The copies will not be collated. The default is 1.
.TP
.BI \-f firstpage
The first page to be output will be
.I firstpage.
This is specified in the same way as in
.BR dvitype :
a sequence of one to ten numbers or asterisks separated by periods.
For example,
.B \-1.*.3
will match the first page whose
.B \ecount0
value is \-1, and whose
.B \ecount2
value is 3. The default is
.BR * ,
which will match any page.
.TP
.BI \-n npages
Output at most
.I npages
pages. The default is a large number.
.TP
.BI \-m magnification
Replace the magnification in the input file by
.IR magnification .
A magnification of 1000 means no magnification; a magnification to 2000
means magnification by a factor of 2.
.TP
.BI \-y kmem
Use at most
.IR kmem k
bytes of printer memory for preloading bitmap fonts.
In order to improve performance,
.B dvitops
puts the bitmap fonts that are most used in the document at the
beginning of the output; other fonts have to be output for each page
on which they are used. The default value is 100, which is suitable for
the oldest PostScript printers. Newer printers with more memory will
give better performance with a higher value.
.TP
.BI \-h hoffset
Position the left hand edge of the output
.I hoffset
away from the left edge of the paper.
.I hoffset
is given as a number with an optional decimal point followed by one
of the units of measure recognised by TeX.
The default value is 1 inch, which is the value assumed by most macro
packages.
.TP
.BI \-v voffset
Position the top edge of the output
.I voffset
away from the top edge of the paper.
.I voffset
is given as a number with an optional decimal point followed by one
of the units of measure recognised by TeX.
The default value is 1 inch, which is the value assumed by most macro
packages.
.TP
.BI \-p papersize
Produce output suitable for
.I papersize
paper.
.I papersize
is one of the standard PostScript paper types: 
.BR a4 ,
.BR letter ,
.BR legal ,
.BR b5 ,
.BR b4 ,
.BR tabloid ,
.BR ledger ,
.BR statement ,
.BR executive ,
.BR a3 ,
.BR a5 ,
.BR folio ,
.B quarto
or
.BR 10x17 .
The default is
.BR letter .
.B dvitops
uses the paper dimensions to position the output correctly.
Non-standard paper sizes can be accommodated using the
.B \-h
or
.B \-v
options.
.TP
.BI \-d dpi
Choose bitmap fonts suitable for a printer with a resolution
of
.I dpi
dots per inch. The default is 300.
.SH USAGE
.B dvitops
supports the use of TeX's
.B \especial
primitive to take advantage of some of PostScript's advanced facilities.
.B dvitops
recognises only
.B \especial
commands whose arguments start with a
.B dvitops:\&
tag.
The following
.B \especial
commands are available:
.TP
\fB\especial{dvitops: landscape}\fP
Print the current page in landscape mode,
with its top along the long side of the paper.
.TP
\fB\especial{dvitops: import \fIfilename width height \
\fR[ \fIoption\fR\|.\|.\|. ] \fB}\fR
This is used to include a picture in the output.
.I filename
must contain PostScript code.
The picture will be positioned with its
lower left hand corner at the current position.
The
.I width
and
.I height
arguments
give the desired height and width of the illustration in the output;
these are given as numbers with an optional decimal point followed
by one of the units of measure recognised by TeX.
.B dvitops
will scale the picture to fit this space. 
Usually
.B dvitops
will scale the picture by the same amount vertically as horizontally,
so that the picture retains its original proportions, and
will center the picture in any surplus horizontal or vertical white space.
An option of
.BR top ,
.BR bottom ,
.B left
or
.B right
will cause the picture to be positioned at the top, bottom, left or
right of the specified space, rather than being centered.
An option of
.B fill
will cause the picture to be scaled to fit the specified space both
horizontally and vertically. The imported file must
comply with the Adobe Document Structuring Conventions. In particular
it must contain a
.B %%BoundingBox:
comment in an appropriate place. Additionally, the file should
comply with the guidelines given in the specification of EPSF
(Encapsulated PostScript Format). A file beginning with the line
.br
.B "%!PS-Adobe-2.0 EPSF-1.2"
.br
is likely to meet these requirements.
.TP
\fB\especial{dvitops: inline \fIanything\fB}\fR
Include the arbitrary PostScript code
.I anything
in the output.
When this code is executed, the coordinate system in effect will
be TeX's: units are scaled points (65536 in a point) with the origin
1 inch down from and 1 inch to the right of the top left corner of
the page; currentpoint will be set to the currrent position
in the dvi file. All
.B inline
commands occurring on a given page will be collected together and output
at the end of page in the order in which they appeared.
.TP
\fB\especial{dvitops: prolog \fIfilename\fB}\fR
Make the PostScript definitions contained in
.I filename
available at this point in the file.
An extension of
.B .ps
may be omitted from
.IR filename .
This command is intended for use with the
.B inline
command. The
.B inline
command should be used simply to invoke procedures defined in other files
and made available by the
.B prolog
command.
The
.B prolog
command must be given at each place that the definitions that it contains
are required. This ensures that the definitions will be available even
if not all pages are output. The file will be downloaded at most once,
however many times it appears.
.TP
\fB\especial{dvitops: begin \fIregion\fB}\fR
.PD 0
.TP
\fB\especial{dvitops: end}\fR
Delimit a region of the dvi file to which
some geometric transformation is to be applied; the
.I region
argument serves to identify the region.
Regions cannot be nested, nor can they extend over more than one
output page. There can be multiple
.B begin
and
.B end
commands for each region.
.PD
.TP
\fB\especial{dvitops: origin \fIregion\fB}\fR
Make the current position the origin for transformations to be applied to
.IR region .
By default the origin is TeX's origin, 1 inch down from and 1 inch to
the right of the top left hand corner of the page.
.TP
\fB\especial{dvitops: rotate \fIregion \(*h\fB}\fR
Rotate
.I region
clockwise about its origin by \(*h degrees.
.TP
\fB\especial{dvitops: transform \fIregion a b c d\fB}\fR
Apply the affine transformation represented by the matrix
.EQ
left [ matrix { 
ccol { a above c } 
ccol { b above d }
} right ].
.EN
to
.IR region .
Arbitrarily many transformations may be applied to each region.
They will be applied in the order in which they are given.
.TP
\fB\especial{dvitops: gray \fIregion shade\fB}\fR
Use the gray shade corresponding to
.IR shade ,
which must be a number between 0 and 1, for
.IR region .
0 corresponds to black and 1 corresponds to white.
.TP
\fB\especial{dvitops: rgbcolor \fIregion red green blue\fB}\fR
Use the color described by the parameters
.IR red ,
.IR green ,
and
.IR blue ,
each of which must be numbers between 0 and 1, for
.IR region .
.TP
\fB\especial{dvitops: hsbcolor \fIregion hue saturation brightness\fB}\fR
Use the color described by the parameters
.IR hue ,
.IR saturation ,
and
.IR brightness ,
each of which must be numbers between 0 and 1, for
.IR region .
.SH ENVIRONMENT
.B dvitops
uses various environment variables in order to find the files
it requires. They each contain lists separated by colons.
.TP 15
.B
.SM TEXINPUTS
A list of directories in which to search for text input files.
.TP
.B
.SM TEXFONTS
A list of directories in which to search for tfm files.
.TP
.B
.SM TEXPK
A list of prototypes of names of pk files.
When a particular font is being searched for, a
.B %d
in the prototype will be replaced by the magnification of
the font in dots per inch, and a
.B %f
will be replaced by the name of the font.
.TP
.B
.SM TEXMAGS
A list of all the magnifications for which there is some pk file.
The magnifications are expressed in dots per inch.
.B dvitops
will only look for pk files at these magnifications. If a font
is required at some other magnification, a scaled version of the
font at one of the listed magnifications will be used.
.TP
.B
.SM DVITOPS
The value of this variable will be interpreted as if it had been typed in
at the beginning of the command line. For example, if it is set to
.B \-r
all output from
.B dvitops
will appear in reverse order (unless overridden by a second occurrence of
.BR \-r ).
.SH FILES
.PD 0
.TP 30
.B /usr/local/tex/inputs/dvitops.pro
PostScript definitions used by dvitops
.TP
.B /usr/local/tex/input/dvitops.fnt
list of the TeX and PostScript names of PostScript fonts
.TP
.B /usr/local/tex/pk/*.*pk
pk files
.TP
.B /usr/local/tex/fonts/*.tfm
tfm files
.TP
.B /usr/local/tex/fonts/*.enc
encoding files
.PD
.SH "SEE ALSO"
.LP
.\" IR "DVITOPS User Manual" ,
.BR tex (L)
.SH AUTHOR
James Clark <jjc@jclark.uucp>