.\"
.\" dvipage: DVI Previewer Program for Suns
.\"
.\" This program is based, in part, upon the program dvisun,
.\" distributed by the UnixTeX group, extensively modified by
.\" Neil Hunt at the Schlumberger Palo Alto Research Laboratories
.\" of Schlumberger Technologies, Inc.
.\"
.\" From the dvisun manual page entry:
.\"	Mark Senn wrote the early versions of [dvisun] 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. Further bug fixes
.\"	by Rafael Bracho at Schlumberger.
.\"
.\" Copyright (c) 1988 Schlumberger Technologies, Inc 1988.
.\" Anyone can use this software in any manner they choose,
.\" including modification and redistribution, provided they make
.\" no charge for it, and these conditions remain unchanged.
.\"
.\" This program is distributed as is, with all faults (if any), and
.\" without any warranty. No author or distributor accepts responsibility
.\" to anyone for the consequences of using it, or for whether it serves any
.\" particular purpose at all, or any other reason.
.\"
.\" HISTORY
.\"
.\" $Log:	dvipage.1,v $
.\" Revision 1.3  88/12/15  19:02:01  hunt
.\" Version 3.0 released.
.\" 
.\" 21 April 1988 - Neil Hunt.
.\"	Fixed a couple of typos.
.\"
.\" 12 April 1988 - Neil Hunt.
.\"	Version 2.0 released for use.
.\"
.\" Earlier history unavailable.
.\"
.TH DVIPAGE 1 "4 February 1988"
.SH NAME
dvipage \- display DVI files from TeX and LaTeX.
.SH SYNOPSIS
.B dvipage
.RB "[\|" \-H "\|]"
.RB "[\|" \-v
.IR mode "\|]"
.RB "[\|" \-m "\|]"
.RB "[\|" \-p "\|]"
.RB "[\|" \-q "\|]"
.RB "[\|" \-f "\|]"
.RB "[\|" \-r
.IR res "\|]"
.RB "[\|" \-s
.IR sample "\|]"
.RB "[\|" \-x
.IR x "\|]"
.RB "[\|" \-y
.IR y "\|]"
.RB "[\|" \-X
.IR X "\|]"
.RB "[\|" \-Y
.IR Y "\|]"
.RB "[\|" \-w
.IR w "\|]"
.RB "[\|" \-h
.IR h "\|]"
.RB "[\|" \-W... "\|]"
.RI "[\|" dvifile "[\|" .dvi "\|]\|]"
.SH DESCRIPTION
.IX dvipage "" "\fLdvipage\fR \(em display DVI files from TeX and LaTeX."
.I Dvipage
displays DVI files produced by TeX or LaTeX on a SunView window.
A new window is created, and the first page of the document is displayed.
The image of the page can be scrolled around in the window by
grabbing it with the middle mouse button, or by the keystrokes
.I "l r u d" (left, right, up, down).
The
.I space
key or the keys
.I RET
.I n
or
.I +
advance the display to the next page,
while the
.I LF
.I p
and
.I -
keys go back to the previous page.
The right mouse button invokes a menu with options to
move forward or backward one page, to go to the first or last page
in the document,
to reopen the same, or a different, DVI file,
to print either one page, or the whole document,
or to exit.
Various other key and menu options are described below.
.PP
On a monochrome display,
.I dvipage
uses a set of low resolution fonts, (typically 118 dots per inch),
to display the text.
When a colour display is available,
high resolution fonts are used, (typically 300 dpi),
the page is rendered onto an internal ``page'',
and image processing functions are invoked to
low pass filter the data and sample it down to a lower resolution.
The sampled data has substituted grey scale resolution for
spatial resolution, and retains much better readability than
simple binary fonts at the same scale of display.
On a colour display, four levels of sampling are possible,
with linear scales of 1, 2, 3 and 4.
The default is a sampling factor of 4.
(Sampling factor 3 actually obtains three samples for each eight
pixels horizontally and nine rows vertically, thus changing
the aspect ratio slightly.)
.PP
When a non unity sampling factor is used (the default on a colour display),
a magnifier is available to inspect a local region of the high resolution
unsampled data, by pressing the left mouse button.
The magnifier my be dragged around the page by moving the mouse with the
button down.
.PP
Dvipage understands both the old format PXL font files,
the new GF packed font files, and the most efficient PK font files.
It searches for font files in a list of standard places
(by default: ``/usr/local/lib/tex/fonts/pkb:/usr/local/lib/tex/fonts/pk'')
accepting either PK files, GF files or PXL files, whichever is found.
If the exact font specified is not found,
dvipage searches all the font directories
for the closest font match.
A warning is issued indicating the missing font
and its substitution.
The list of standard places for finding font files
can be overridden by the -p option (see below),
or by an environment variable
.B FONT_PATH.
.SH OPTIONS
.PP
.TP
.B \-H
Prints a simple help message.
.TP
.BI \-v " mode"
Sets a verboseness level for debugging (wizards only).
.TP
.B \-m
Makes
.B dvipage
think that it is running on a monochrome machine even if it finds
a colour display.
.TP
.BI \-p " font-area"
Overrides the list of standard places where
.B dvipage
looks for font files.
The argument is a colon separated
list of directories which contain either font files,
or subdirectories grouping fonts by family.
Either PXL, PK, or GF type files can be used.
If the environment variable
.B FONT_AREA,
is set, it also specifies a colon separated
list of filenames which override the
default font areas.
.TP
.BI \-P " flag"
If
.I flag
is 0, use of PXL files is suppressed.
Default is non zero, enabling the use of PXL files.
.TP
.BI \-K " flag"
If
.I flag
is 0, use of PK files is suppressed.
Default is non zero, enabling the use of PK files.
.TP
.BI \-G " flag"
If
.I flag
is 0, use of GF files is suppressed.
Default is non zero, enabling the use of GF files.
.TP
.B \-l
Normally
.B dvipage
seeks to the end of the DVI file and reads the cached font data located
there.
The
.B \-l
option suppresses this behaviour, causing the font data to be obtained
from the inline locations.
This is much slower, especially when skipping pages.
.TP
.B \-q
Certain errors detected by
.B dvipage
are displayed in a pop up message window.
The
.B \-q
flag suppresses the generation of these windows.
.TP
.B \-f
TeX has a concept of a rendering window with margins one inch
inside the edges of the paper;
the DVI coordinate system is relative to this frame.
Although it is possible (and even normal) to print outside
the boundaries of this frame, sometimes it is useful
to see its location on the page.
The
.B \-f
option causes the rendering frame to be shown on the page display.
.TP
.BI \-r " res"
Causes
.B dvipage
to use fonts at a resolution of
.I res
dots per inch.
If this is not a suitable size, it will generate many
error messages as it fails to find font files at the specified
resolution.
Common sizes are 118 and 300 dots per inch.
If this option is ommitted,
.B dvipage
will select the either the high resolution fonts (on a colour machine)
or the low resolution fonts (on a monochrome machine).
.TP
.BI \-s " sample"
Causes
.B dvipage
to use a sampling factor of
.I sample.
If this is not one of (1, 2, 3, or 4) a blank page will result.
This option is ignored if running on a monochrome machine.
.TP
.BI \-x " x " \-y " y"
The position of the top left hand corner of the page
from the top left hand corner of the display window,
measured in inches,
is set to be
.I "(x, y)"
at the ``home'' position (the position at which each new page is displayed
before moving it around with the mouse).
.TP
.BI \-X " X " \-Y " Y"
Normally the origin of the rendering window is set to be one inch
from the corner of the page.
This can be overriden by this option to match the actual behaviour of
your local printer.
.TP
.BI \-w " w " \-h " h"
Sets the width and height of the paper on which the image is rendered;
the default is 8 by 11 \(12 inches. Useful for viewing legal size or A4 size
documents.
.SH COMMANDS
.PP
The following keystrokes typed to the display window execute
various commands.
Some of these can be performed from a menu option.
Many of the commands can be preceeded by a number,
indicated by
.B #
in the description below.
.TP
.B MS_MIDDLE
The middle mouse button drags the page beneath the window to pan or scroll.
.TP
.B MS_LEFT
The left mouse button invokes a magnifier on the page near the mouse,
when running in sampled mode on a colour display.
.TP
.B MS_RIGHT
The right mouse button invokes a menu, which contains items for most
of the other commands listed below.
.TP
.B space, RET, n, or +
Advance to the next page in the document.
.TP
.B NL, p, or -
Go back to the previous page.
.TP
.BR _ " (underscore)"
Go to the first page in the document.
.TP
.B # g
Go to page number
.B #.
(If
.B #
is ommitted, go to the last page in the document.)
.TP
.B # G
Go to sheet number
.B #.
(If
.B #
is ommitted, go to the last page in the document.)
.TP
.B h
Return the page to the home position.
.TP
.B l, r, u or d
Move the page left, right, up or down in the window by a small increment.
.TP
.B m
Mark the current page position as the new home page position for subsequent
new pages and
.B h
commands.
.TP
.B S
Pops up a window in which a sampling factor can be typed.
This should be 1, 2, 3 or 4.
Close the window by mousing the
.B Abort
button or the
.B OK
button,
or by typing
.B "^C"
(for abort)
or
.B "ESC"
(for OK).
.TP
.B # s
Set a scaling factor of
.B #.
.TP
.B # R
Reopen the current DVI file on page
.B #.
(If
.B #
is ommitted, reopen on the current page.)
.TP
.B P
Print the DVI file on the default printer.
This requires site dependent printer commands to have
been specified when
.B dvipage
was installed. This is not implemented at DL.
.TP
.B "^P"
Attempts to print the current page on the default printer.
This requires site dependent printer commands to have
been specified when
.B dvipage
was installed. This is not implemented at DL.

.TP
.B w
Toggles the display of the rendering frame window.
.B # x
Sets the width of the magnifier (in pixels).
.B # y
Sets the height of the magnifier (in pixels).
.B # b
Sets the width of the border drawn around the magnifier.
Use
.B 0 b
to have no border. displayed.
.TP
.B # v
Sets verbose mode
.B #.
.TP
.B Q
.B dvipage
quits.
.SH SEE ALSO
dvips(1)
.SH BUGS
.PP
The command to print the current page is rather
crude. It needs special magic at installation time
to make it work.
.B Dvipage
does not change directories before printing,
so relative pathnames for included PostScript files (for example)
may not work if dvipage is invoked in one directory,
and opens a document in a different directory.
.PP
.B Dvipage
checks the modification time of the dvi file before tackling each page,
and refuses to proceed if you have reformatted the document, until you
instruct it to reopen the file.
However, if you reformat \fIwhile\fP it is in the process of reading a page,
it will probably crash messily.
.PP
Dvipage does not preview PostScript (or other) files included in a document.
A blank space is left where the included data would appear.
.SH AUTHOR
.PP
The original idea for this program came from
.B dvisun
developed by Mark Senn, Stephan Bechtolsheim, Bob Brown,
Richard Furuta, James Schaad, Robert Wells, and Norm Hutchinson,
with some bug fixes by Rafael Bracho at Schlumberger;
and from the program
.B suntroff
developed by Malcolm Slaney at Schlumberger.
.PP
.B Dvipage
was put together by
Neil Hunt at Schlumberger Palo Alto Research,
.B hunt@spar.slb.com,
using code borrowed from
.B dvisun
and greatly extended.
In particular the filtering and sampling concept
and the fast code to implement it, and the magnifier,
came from Neil Hunt.