% userguide.tex - 18:29 GMT +10:00 Wed 25 Aug 1993 - modifier Geoffrey Tobin.
%**start of header
% This is the TeX source file for the "dvgt 3.51 User Guide".
% Details peculiar to our site are indicated by the string "SYSDEP".
% Cross references are indicated by the string "XREF".
% Feel free to make modifications applicable to your site.
\input guidemacs
%**end of header
\null
\vfil
\centerline{\title \dvgt\ User Guide}
\bigskip
\vskip\parskip
\centerline{\bigbf DVItoVDU 3.0, in Modula-2: Andrew Trevorrow, October 1988}
\smallskip
\centerline{\bigbf DVItoVDU 3.0, C conversion: Ian Dall, November 1990}
\smallskip
\centerline{\bigbf dvgt 3.51: Geoffrey Tobin
({\tt ecsgrt@luxor.latrobe.edu.au}),
Aug 1993}
\bigskip
\noindent
This document explains how to use {\dvgt}, a \TeX\ page previewer.
The program allows you to look at \TeX-generated DVI pages on a variety
of commonly available VDUs.
It is assumed you are already familiar with \TeX.
\bigskip
\vskip\parskip
\centerline{\bigbf Contents}
\bigskip
\def\aligneddots{\leaders\hbox to .75em{\hss.\hss}\hfil}
% XREF: make sure titles and page numbers are up-to-date!!!
\line{Introduction \aligneddots\ 1}
\line{Program Options \aligneddots\ 2}
\line{\hskip1cm Options in Detail \aligneddots\ 3}
\line{Screen Regions \aligneddots\ 7}
\line{\hskip1cm Dialog region \aligneddots\ 7}
\line{\hskip1cm Window region \aligneddots\ 8}
\line{The Commands \aligneddots\ 10}
\line{\hskip1cm Miscellaneous \aligneddots\ 10}
\line{\hskip1cm Selecting a Page \aligneddots\ 10}
\line{\hskip1cm Changing How a Page is Displayed \aligneddots\ 11}
\line{\hskip1cm Changing Units \aligneddots\ 11}
\line{\hskip1cm Moving the Window \aligneddots\ 12}
\line{\hskip1cm Changing Window Size \aligneddots\ 12}
\line{The Coordinate Scheme \aligneddots\ 14}
\line{Some Examples \aligneddots\ 15}
\vfil\eject
% The above is the title page; let's make a few adjustments to some parameters:
\footline={\hss\rm\folio\hss} % turn page numbers back on
\pageno=1 % and restart numbering
\subhead{Introduction.}
Let's assume you've just run \TeX\ and created a file called |foo.dvi|.
Even if \TeX\ did not find any errors, you cannot be sure that
the document is formatted correctly. There might be bad line breaks, bad
page breaks, alignment problems, pages too big for your printer's paper,
missing fonts---not to mention spelling mistakes.
The lack of visual feedback is one of the major disadvantages of
using a document compiler like \TeX\null.
Without a previewing program, the only way to check |foo.dvi| is to
continue through the \TeX\ cycle and look for errors in the printed output.
This can be time consuming and is a waste of paper.
Instead, you can use {\dvgt} to look at |foo.dvi| on a variety of commonly
available terminals.
\dvgt\ is an interactive program; you can enter commands to
select a particular page for display, look at the overall format of the
entire page and then request a smaller region for closer examination.
The manner in which the page is displayed can be varied from a full,
accurate representation to a terse, fast display for when fine details
are unimportant.
All the commands are described in detail in a later section. % XREF
Some environment variables and/or command options are needed for {\dvgt}
to work properly. In particular, set the |DV_TERM| environment variable
to describe the type of VDU you are using; or else use the |-v| option.
Then to look at |foo.dvi|, just type `|dvgt foo|'.
\vfil\eject
\subhead{Program Options.}
The |dvgt| program has a number of options, each of which must be
followed by a value.
If the same option appears more than once, then the last value will be used.
If a particular option does not appear, then a default value will be used,
which might be taken from an environment variable. If no appropriate
environment variable is set, the default value used is that specified
in the source code --- either in `options.c', or as one of the constants
in `defaults.h'. The constants in `defaults.h' all begin with the prefix
`|DEF_|'. All the environment variables that are specific to {\dvgt} begin
with `|DV_|'. All options begin with `|-|'.
\begindisplay
Option& Program& Environment& Default value& Meaning\cr
& Variable& Variable&&\cr
\noalign{\medskip}
|-H|& |hoffset|& ---& |0mm|& Horizontal page offset,\cr
&&&& in given units.\cr
\noalign{\medskip}
|-V|& |voffset|& ---& |0mm|& Vertical page offset,\cr
&&&& in given units.\cr
\noalign{\medskip}
|-d|& |dummy_pk|& |DV_DUMMY_PK|& |DEF_DUMMY_PK|& Dummy PK font, used when\cr
&&&& correct font's absent.\cr
\noalign{\medskip}
|-e|& |dummy_tfm|& |DV_DUMMY_TFM|& |DEF_DUMMY_TFM|& Dummy TFM, used when\cr
&&&& correct TFM's absent.\cr
\noalign{\medskip}
|-f|& |pkdir|& |TEXPKS|& |DEF_PK_DIR|& PK fonts' directory.\cr
&& else&&\cr
&& |PKFONTS|&&\cr
&& else&&\cr
&& |TEXFONTS|&&\cr
\noalign{\medskip}
|-h|& |cmd_help|& |DV_HELP|& |DEF_CMD_HELP|& Command help file read\cr
&&&& by `?' command.\cr
\noalign{\medskip}
|-i|& |immed_help|& |DV_IMMED_HELP|& |DEF_IMMED_HELP|& Help file displayed\cr
&&&& at startup.\cr
\noalign{\medskip}
|-l|& |landscape|& ---& (portrait)& Landscape page\cr
&&&& (swaps |-x| and |-y|).\cr
\noalign{\medskip}
|-m|& mag& ---& (DVI mag)& Magnification.\cr
\noalign{\medskip}
|-p|& |psprefix|& |DV_PSPREFIX|& |DEF_PS_PREFIX|& PS font name prefix.\cr
\noalign{\medskip}
|-r|& |xres|,& |DV_RES|& |DEF_XRES|,& X and Y resolutions,\cr
& |yres|&& |DEF_YRES|& in dots per inch (dpi).\cr
\noalign{\medskip}
|-t|& |tfmdir|& |TEXFONTS|& |DEF_TFM_DIR|& TFM files' directory.\cr
\noalign{\medskip}
|-v|& |vdu|& |DV_TERM|& ---& Type of VDU.\cr
&& else&&\cr
&& |TERM|&&\cr
\noalign{\medskip}
|-x|& |paperwd|& |DV_PAPERWD|& |DEF_PAPERWD|& Paper width,\cr
&&&& in given units.\cr
\noalign{\medskip}
|-y|& |paperht|& |DV_PAPERHT|& |DEF_PAPERHT|& Paper height,\cr
&&&& in given units.\cr
\noalign{\medskip}
\enddisplay
Options -d -e -f -h -i -p -r -t are really for system wizards;
their default values have been set up so that most users need never worry
about changing them.
% SYSDEP: take note system wizards!
\noindent Example: A4 paper using a 180 by 360 dpi printer:
\begindisplay
|dvgt -r 180,360 -x 210mm -y 297mm|
\enddisplay
\bigskip
\noindent Default values in the supplied `defaults.h'.
The default TFM and PK directories are:
\begindisplay
|.:/usr/local/lib/tex/fonts|\cr
|.:/usr/local/lib/tex/fonts/tmp|\cr
\enddisplay
These cause {\dvgt} to look first in the current directory, then in the
directories that are standard for Karl Berry's TeX distribution.
The default dummy TFM metric and PK font files are:
\begindisplay
|cmr10.tfm|\cr
|cmr10.300pk|\cr
\enddisplay
since cmr10 is the most commonly used font on most TeX systems,
and 300 dpi seems the most common resolution among medium quality
printers at present.
Consequently, the default resolution is 300,300 (dots per inch).
In Karl Berry's font naming convention, PostScript fonts' TFM files
are prefixed with the letter `p'. By default, {\dvgt} follows this
convention.
Several PS font prefixes can be separated by the `:' character,
as with the PK and TFM directories. The `:' character was chosen
because it seems easy to remember.
If no PS font prefixes are specified, as when the list of prefixes is
an empty string, `', then {\it no\/} fonts are considered PS fonts.
The command and immediate help files default to:
\begindisplay
|/usr/local/lib/tex/dvgt/cmd.hlp|\cr
|/usr/local/lib/tex/dvgt/immed.hlp|\cr
\enddisplay
Since most of the industrial world uses metric paper, the default
paper size is A4 (approximately 210 mm wide by 297 mm high).
\medskip
\bigskip
\leftline{OPTIONS in DETAIL.}
\bigskip
\noindent
Each option is followed by a value of a certain type:
{\it string\/} is a string of alphanumeric characters,
{\it i, x, y\/} are positive integers,
{\it file\/} is a file,
{\it dir\/} is a directory, and
{\it dimen\/} is an integer or real number followed by a
two-letter unit: |bp|, |cm|, |in|, |mm|, |pc|, |pt|, |px| or |sp|.
(Most of these should be familiar from \TeX\null. {\dvgt} provides
an additional unit, |px|, which stands for ``paper pixels''.
These two-letter sequences can be arguments to the `|C|' interactive
command to change the unit of dimensions---see page 11 for details.) % XREF
\bigskip
\noindent |-H| {\it dimen\/}~~and~~|-V| {\it dimen\/}
These two qualifiers allow you to shift the location of each page within
the paper. Negative dimensions are allowed;
for example, |-H -.5in| shifts each page half an inch to the left.
\bigskip
\noindent |-d| {\it file\/}
\dvgt\ will warn you if your document uses a font at a non-existent size.
Rather than abort, it will load the dummy PK file specified by |-d|, and
following the PK paths, then continue so you can look for more errors.
Paragraphs using this dummy information are likely to have ragged right
margins, and tables are likely to be horizontally distorted.
The quickest way to check your DVI file for missing fonts is to type
the |S| (Statistics) command. The resulting display will indicate
any PK files that do not exist, and list TFM files that are used
for Bounding Boxes.
\bigskip
\noindent |-e| {\it file\/}
If a TFM file is missing, then a dummy TFM is sought in the TFM paths.
The dummy TFM filename may be set using the |-e| option.
\bigskip
\noindent |-f| {\it dir\/}
{\dvgt} gets all its bit-mapped font information from PK files stored
in the specified directory (which can, but need not, end with |/|).
\TeX\ gets all its font information from TFM files. A particular TFM file
usually has a number of corresponding bit-mapped font files, each one
corresponding to the same set of ideal character shapes, but at a
different size.
Although \TeX\ allows you to scale a font to virtually any size,
it is obviously impossible to provide an infinite number of bit-mapped fonts.
That is why it is best to stick to the pre-defined |\magstep| values when
scaling such fonts---you're much more likely to stay within the range of
existing PK files.
The above warning does not apply to TFM files for resident
PostScript or other scalable fonts. Such fonts can be used at any
desired size.
However, since no bit-map information is available, \dvgt\ cannot
show characters from such fonts in a Full display.
Instead, it shows those characters as outline rectangles, using the
TFM files to determine their bounding boxes, just as in Box mode.
\bigskip
\noindent |-h| {\it file\/}
The |?| command reads the help file specified by this option.
The default help file contains a brief summary of all the commands.
If no help file can be found, then a pre-compiled help text is shown.
\bigskip
\noindent |-i|
This `option' only displays the current immediate help file's pathname
and the name of the corresponding environment variable (|DV_IMMED_HELP|).
The immediate help file is displayed when {\tt dvgt} is typed alone
on the command line.
\bigskip
\noindent |-m| {\it i\/}
This option allows you to replace the magnification used
in the DVI file with some other value;
{\it i\/} is a positive integer 1000 $\times$ the desired magnification.
The given value should be chosen carefully so that the new font sizes
still correspond to existing PK files.
Unless you know exactly what you are doing, you should avoid changing
the DVI magnification,
especially if your \TeX\ source file uses |\magnification| {\it and\/} |true|
dimensions.
You should only supply a replacement magnification if you intend to
print the DVI file with the same override.
\bigskip
\noindent |-r| {\it x,y\/}
\noindent |-r| {\it x\/}
{\dvgt} treats the imaginary sheet of paper on which a DVI page will appear
as a two-dimensional array of tiny dots called {\it paper pixels\/}.
{\it x\/} and {\it y\/} are positive integers that define the number
of paper pixels per inch ({\it horizontally} and {\it vertically},
respectively). When only {x\/} is given, y is assigned the same value.
The |-r| values should match the respective resolutions of the device
that will be used to print your document.
The Apple LaserWriter, for instance, has a resolution of 300 dots per
inch, so {\tt dvgt -r 300} suits it.
\bigskip
\noindent |-t| {\it dir\/}
If a font name does not include an explicit directory, and requires
a TFM file, then \dvgt\ will use the |-t| value to locate the file.
The given value can, but need not, end with |/|.
\bigskip
\noindent |-v| {\it string\/}
This option explicitly tells {\dvgt} what type of VDU you are using.
If |-v| is not given, the value of the |DV_TERM| environment variable is used;
if that is not defined, the value of the |TERM| environment variable is used.
For example, if you're using a VISUAL 603 terminal and |DV_TERM| and |TERM|
do not equal |vis603|, then you'll need to type `|dvgt -v vis603 foo|'.
The purpose of |DV_TERM| is to allow {\dvgt} to use a graphics mode
distinct from the usual text display mode. This can be useful across
a network or in X11 windows.
\noindent
The current version of {\dvgt} will accept the following {\it string\/}
values in upper or lower case:
\begindisplay
|aed512|& (AED 512 with 512 by 512 screen)\cr
|kermit|& (MS-Kermit, in Tek4010 emulation: same as ncsatel below)\cr
|ncsatel|& (NCSA Telnet, in Tek4010 emulation)\cr
|regis|& (any ReGIS compatible VDU;
synonyms = |gigi|, |vk100|, |vt125|, |vt240|)\cr
|tek4010|& (Tek4010 emulation: same as ncsatel above)\cr
|vis240|& (VISUAL 240; synonym = |vis241|)\cr
|vis500|& (VISUAL 500)\cr
|vis550|& (VISUAL 550)\cr
|vis603|& (VISUAL 603)\cr
|vis630|& (VISUAL 630)\cr
|vt100|& (any VT100 compatible VDU)\cr
|vt100132|& (any VT100 compatible VDU in 132 column mode)\cr
|vt220|& (VT220 using down-loaded chunky graphics)\cr
|vt640|& (VT100 with Retro-Graphics)\cr
\enddisplay
\noindent
It is assumed your terminal has been set up to obey XON/XOFF flow control.
\noindent
Some VDUs require special settings for {\dvgt} to work properly:
\item{$\bullet$}
When using MS-Kermit (eg, version 3.12) over TCP/IP (eg, TELNET), for
best appearances you may wish to add the following to MSCUSTOM.INI:
\begindisplay
set flow-control none\cr
set terminal graphics character-writing opaque\cr
set terminal graphics cursor off\cr
\enddisplay
\item{$\bullet$}
When writing to a PC monitor over NCSA Telnet, the |ncsatel| terminal
may sometimes leave you in the wrong screen mode. If that happens,
type NCSA Telnet's |Alt-R| command to reset the screen to VT102 mode.
Typing NCSA Telnet's `help' command, |Alt-H|, gives a (VT102 mode) screen
containing more information.
\item{$\bullet$}
The |vis630| terminal needs to be in interlace mode.
Simply hit |Shift-PF3|.
\item{$\bullet$}
The |vis500| and |vis550| terminals have function keys which control how
information on the screen is to be displayed. {\dvgt}
assumes graphic images and alphanumeric text can be seen at the
same time. To ensure that this is possible, you may need to:
{\parskip=0pt
\smallskip
\itemitem{---} hit the |SET-UP| key
\itemitem{---} hit the |F6| function key until |F6=BOTH| appears
\itemitem{---} hit the |SET-UP| key to return to normal operating mode.
\smallskip
\item{}
You can do these steps while {\dvgt} is running.
Both terminal types should also have the Scale Factor set at 3\;:\;4.
\par
} % \parskip back to normal
\item{$\bullet$}
The |regis| VDUs use VT100 escape sequences to update the dialog region,
and the |vis550| VDU is assumed to be emulating a VT100.
Change the appropriate |SET-UP| value if your screen becomes full of junk.
\item{$\bullet$}
The |vt100132|, |vt220|, |vis603| and |vis630| VDUs are automatically
switched to 132 columns when \dvgt\ starts up
(and then to 80 columns when you quit).
MS-Kermit may not approve of 132 columns.
\bigskip
\noindent |-x| {\it dimen\/}~~and~~|-y| {\it dimen\/}
These two options define the width and height of the paper upon which your
document will eventually be printed.
% SYSDEP
Note that their default values specify A4 paper
(|210mm| wide and |297mm| high).
Every time you select a page, {\dvgt} uses the paper dimensions
to check that all the printed material will fit on the paper.
\vfil\eject
\subhead{Screen Regions.}
\medskip
\bigskip
\leftline{DIALOG REGION.}
\bigskip
If your command line is correct and if the |-v| value matches the type of
terminal you're actually using, then {\dvgt} will clear the screen
and display
\begindisplay
||$n$| pages DVI page=0 TeX page=[0] Auto=+ F Zoom=2.00|\cr
|Window at (|$h$|,|$v$|) |$wwd$| by |$wht
$| Page at (|$minh$|,|$minv$|) |$pwd$| by |$pht$| IN|\cr
|This is dvgt 3.51 (DVItoVDU, v. 3.0, gt mod 5 rev. 1) - Wed 25 Aug 93|\cr
|Command: |\cr
\enddisplay
These lines represent the ``dialog region''; the rest of the screen is
called the ``window region'' and should be blank at this stage.
\noindent
The top two lines show status information. The first status line shows:
\item{$\bullet$} $n$, the total number of pages in the DVI file.
\item{$\bullet$} The current DVI page and its corresponding \TeX\ page counters.
Particular pages can be selected by their position in the DVI
file (1 to $n$) or by the value of their \TeX\ counters.
\item{$\bullet$} The |A| command allows you to toggle
(alternately enable or disable)
the automatic calculation of window position and size upon page
selection; initially enabled (|+|).
\item{$\bullet$} The current display mode; initially |F|, for |Full|.
The |T|, |B| and |F| commands allow you to toggle each of the
|Terse|, |Box| and |Full| display modes. All combinations of these
are permissible, but you be the judge of which combinations are useful,
and when.
\item{$\bullet$} The current |Zoom| factor; initially |2.00|.
The |ZI|, |ZO|, |ZCI| and |ZCO| commands zoom in and out by the
current zoom factor.
|ZI| $z$ and |ZCI| $z$ zoom in, and |ZCI| $z$ and |ZCO| $z$ zoom
out, by the factor $z$, which then becomes the current zoom factor.
\noindent
The second status line shows:
\item{$\bullet$} The current location and size of the window.
$h$ and $v$ are horizontal and vertical coordinates that define
the current paper position of the top left corner of the window region.
The following section has details on the coordinate scheme used
by {\dvgt}\null. The |W| command allows you to move the window to an
absolute position; the |U|, |D|, |L| and |R| commands allow relative
positioning.
$wwd$ and $wht$ represent the current width and height of the window region;
their values are changed by the |H| and |V| commands (and by |ZI|,
|ZO|, |ZCI| and |ZCO|).
The initial window size depends on the |-r| value and the size and
resolution of your VDU screen.
\item{$\bullet$} The location and size of the ``page rectangle''.
$minh$, $minv$, $maxh$ and $maxv$ define the smallest rectangle containing
all the rules and characters in the current page.
$(minh{,}minv)$ is the top left corner of this rectangle; it is
$pwd$ units wide and $pht$ units high.
\item{$\bullet$} The current units; initially inches.
All numbers shown in this line are dimensions in terms of these units.
The two letters shown at the end of the line are the unit names.
These are: inches (|IN|), centimetres (|CM|), millimetres (|MM|),
points (|PT|), picas (|PC|), big (or PostScript, or standard) points
(|BP|), scaled points (|SP|), and paper pixels (|PX|).
Pixel values are shown as integral numbers and represent exact dimensions;
all other values are shown as real numbers rounded to two decimal places.
To change the current units, use the |C| command, then the unit name.
For example, either |CMM| or |C MM| will change to millimetres.
\noindent
The third line initially shows the current version number.
{\dvgt} displays messages of various
kinds in this line. Some of these messages appear only briefly but may convey
helpful information.
Others are more important and indicate some sort of problem, such as
an invalid command or a page that won't fit on the paper;
in these cases, hit the |RETURN| key before continuing.
The last line in the dialog region is for entering commands. The first
thing you normally want to do is choose a particular page for display.
For example, typing `|1|' will select the first page in the DVI file.
Many commands can be entered in the one command line. Hit |RETURN| to
execute the command(s).
\medskip
\bigskip
\leftline{WINDOW REGION.}
\bigskip
The number of paper pixels per inch is given by the |-r| option.
A pixel can be either black (corresponding to a tiny blob of ink) or white
(no ink). However, on a screen with black background, inked pixels are
commonly white, and uninked pixels are black. In the following, `black'
means inked, and `white' means uninked.
A typical DVI page contains characters from one or more fonts, and
perhaps a few rules.
A rule is simply a rectangular region of black pixels, usually in the shape of
a thin horizontal or vertical line.
A character is usually a more complicated pattern of black and white pixels.
Every character and rule has a
paper position---or ``reference point''---defined
by a pair of pixel values $(h{,}v)$
where $h$ is the horizontal coordinate and $v$ is the vertical coordinate.
{\dvgt} uses a coordinate scheme in which the
position $(0{,}0)$ is a pixel one inch in from the top and left edges of
the paper. Vertical coordinates increase down the paper,
horizontal coordinates increase to the right.
Confused? The illustration on page~14 may help clear things up. % XREF
The window region is used to view the current DVI page.
{\dvgt} treats this region of the VDU screen as a two-dimensional array
of dots called ``screen pixels'' (to distinguish them
from the paper pixels described above).
A screen pixel is the smallest possible area on a VDU screen that
can be drawn or erased; the greater the number of screen pixels in a given area,
the higher the resolution of the VDU.
The initial size of the window region depends on the VDU; the width and height
are set so that each paper pixel corresponds to exactly one screen pixel.
The most accurate representation of a page will occur at these values since
neither horizontal nor vertical scaling is necessary:
\begindisplay
VDU& initial window size (width by height in pixels)\cr
\noalign{\smallskip}
|aed512|& \enskip 512 by 471\cr
|ncsatel|& 1024 by 780\cr % - gt - Is ncsatel correct?
|regis|& \enskip 768 by 400\cr
|vis240|& \enskip 800 by 500\cr
|vis500|, |vis550|& 1024 by 688\cr
|vis603|& 1024 by 620\cr
|vis630|& 1024 by 698\cr
|vt100|& \quad 80 by \enskip20\cr
|vt100132|& \enskip 132 by \enskip20\cr
|vt220|& \enskip 132 by 100\cr
|vt640|& 1024 by 650\cr
\enddisplay
Use the |H| command to change the width (the Horizontal size), and the
and |V| command to change the height (the Vertical size).
Try to avoid weird aspect ratios: `|H0.1 V100|' is a perfectly legal
command string, but produces a very distorted display!
If you want to zoom in or out, the |ZI|, |ZO|, |ZCI| and |ZCO| commands
are safer because they tend to maintain the current aspect ratio.
The higher the resolution of the VDU,
the greater the accuracy of such scaled displays.
The command string `|HV|' will restore the window size to the above unscaled
dimensions.
Note the very low resolution of the |vt100| and |vt100132| VDUs.
Since the individual dots making up their screens cannot be turned on and off,
{\dvgt} has to define a screen pixel to be an entire character position.
A |vt100| screen typically consists of 24 lines of 80 characters,
therefore the initial window region is 80 pixels wide and 20 pixels high
(the top 4 lines are used for the dialog region).
These VDUs can still show bitmap character shapes, if you zoom in
closely enough!
At more useful window sizes the resulting displays will be extremely crude.
Nevertheless, a variety of formatting errors can still be detected on such
terminals---just don't try proofreading your document!
If automatic window calculation is enabled (|Auto=+|),
then the size and location of
the window region are automatically set every time a page is selected.
{\dvgt} tries to show as much of the
paper (and presumably the page) as possible, and at a readable scale,
but without too much distortion.
After comparing the shape of the paper with the shape of your
VDU's {\it initial\/} window region, and depending on the location of the
page, {\dvgt} may show the entire paper,
or the top or bottom half, or the left or right half.
If any part of the page is off the paper, then the entire paper
{\it and\/} the entire page will initially be shown.
Since most paper sizes have portrait dimensions (width $<$ height), and most
VDU screens have landscape dimensions (width $>$ height), {\dvgt} will
normally show the top half of a sheet of paper containing the selected page.
\vfil\eject
\subhead{The Commands.}
In response to the `|Command: |' prompt, you can enter one or more of the
following commands in upper or lower case. Multiple commands are
processed in the order given, but the window region is only updated,
if necessary, at the end of a line of commands. For example,
if you type `|NFD|' then {\dvgt} will get the Next page, toggle
Full display mode, move the window Down, and only then display the page.
If an illegal command is detected, any further commands are ignored.
Most commands consist of only one or two characters; some can be followed by
parameters. Spaces before and after commands and parameters are optional.
\parskip=0pt % TURN OFF FROM HERE ON.
\medskip
\bigskip
\leftline{MISCELLANEOUS.}
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|?|\hfil}\null
Display brief help on the available commands.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|^C|\hfil}\null
|^C| will return you to the `|Command: |' level of {\dvgt}.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|^L|\hfil}\null
Refresh the window. (This is not immediate, because all interactive
commands are read before any is parsed and executed.) Useful if
the screen gets messed up, as may happen with some network software
on some VDUs.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|^Q|\hfil}\null
|^Q| is ignored.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|^S|\hfil}\null
|^S| is ignored.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|^Z|\hfil}\null
|^Z| will suspend {\dvgt}.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|A|\hfil}\null
Toggle Automatic window calculation after page selection.
When |Auto| is enabled, \dvgt\ will usually show the top half
of the imaginary sheet of paper. When |Auto| is disabled,
\dvgt\ will use the current window size and location to display the
new page.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|Q|\hfil}\null
Quit from {\dvgt}\null.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|S|\hfil}\null
Show the option values being used, as well as statistics about the number of
fonts, characters and rules used on the current page.
The file specs of each font used (on any page) will be listed.
You'll also be warned about any fonts that don't exist.
\medskip
\bigskip
\leftline{SELECTING A PAGE.}
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{$i$\hfil}\null
Select the $i$th DVI page. $i$ must be a positive integer from
1 to $n$ where $n$ is the total number of pages in the DVI file.
\bigskip
\noindent |[|$i_0$|.|$i_1$|.| $\scriptstyle\cdots$ |.|$i_9$|]|
\item{}
Select the DVI page whose \TeX\ page counters match the given specification.
$i_0$ to $i_9$ are integers separated by periods. 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.
If more than one DVI page matches, the lowest will be chosen.
E.g., |[]| is equivalent to |[.........]| and will select the first DVI page,
even though the request matches every possible page.
\medskip
\item{}
\TeX\ stores the values of |\count0,\count1,...,\count9| in each DVI page.
Plain \TeX\ only uses |\count0| to control page numbering; the remaining
counters are set to zero.
Some macro packages may use the other counters for section or chapter
numbering; e.g., |[2.5]| might mean ``select page~2 from chapter~5''.
When showing the current \TeX\ page in the top status line, {\dvgt}
always shows the value of |\count0|, but trailing counters with zero values are
not shown.
Note that plain \TeX\ uses negative values in |\count0| to indicate page
numbers in roman numerals (such as in a preface).
In most documents, the $i$th DVI page will be the same as \TeX\ page |[|$i$|]|.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|N|\hfil}\null
Select the Next DVI page.
Before any page has been requested, |N| will select the first DVI page.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|P|\hfil}\null
Select the Previous DVI page.
Before any page has been requested, |P| will select the last DVI page.
\medskip
\bigskip
\leftline{CHANGING HOW A PAGE IS DISPLAYED.}
\bigskip
\noindent
The |B|, |F| and |T| commands toggle each of three different ways
of displaying a page. They may be combined.
The choice of display mode depends on the capabilities of your VDU
and the level of detail you wish to see.
Whatever the display mode, the window region
is always updated in the following manner:
Visible paper edges are drawn first, followed by visible rules.
Visible characters are then shown on a font by font basis; those fonts
with the least number of characters on the page are drawn first.
\medskip
\noindent
While the window region is being updated,
but not during the drawing of a rule or character,
{\dvgt} will check to see if you've typed something at the keyboard.
You can hit the |RETURN| key to abort the display,
or you can change the display mode by hitting the |T|, |B| or |F| keys
in any combination (without hitting |RETURN|). There might be a
delay between the time you hit a key and the time something actually
happens, especially if a (visually) large rule or character is being
drawn. Over slow remote connections, this may take a while!
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|B|\hfil}\null
Toggle the display of Box outlines of the smallest rectangles containing all
black pixels in characters.
The reference point of a \TeX\ character is usually located near
the bottom left corner of one of these boxes.
Box mode is intermediate in speed between Terse and Full modes;
it is a quick and accurate way of checking
the alignment of entries in a table, for example --- assuming that
accurate TFM metrics are being used.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|F|\hfil}\null
Toggle the display of a Full representation of all pixels in characters.
Full display is the most accurate but may take some time;
hit |RETURN| or switch to Terse or Box mode if you get bored.
The fact that the display mode can be changed {\it while the window is
being updated\/} can be very useful.
A good compromise between speed and accuracy is
to start off in Full mode so that math symbols and any other special
characters are displayed correctly, then to switch to Terse mode
(by hitting |T|) when the bulk of the text begins.
Note that characters from a font that lacks a PK file, but has a TFM metric,
such as PostScript or other scalable fonts, are shown as outline rectangles
of roughly the right size.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|T|\hfil}\null
Toggle the display of a Terse representation of characters.
On high resolution VDUs the \TeX\ text fonts should be quite readable;
characters will be in
approximately the right position and may even be about the right size.
The display on low resolution VDUs can be a bit confusing; characters get
overwritten if they are too close together. Don't worry too much
if you suddenly see many more spelling mistakes than usual!
Note that the text fonts will all look alike in Terse mode.
The only way to distinguish between different fonts is to note the
order in which characters are displayed (the less used fonts are drawn first).
Most of {\dvgt}'s VDU drivers assume all characters come from a
\TeX\ text font, such as cmr10, and then attempt to map them into
similar-looking ASCII characters.
Characters from non-text fonts, such as math symbols, will usually appear
incorrect.
\medskip
\bigskip
\leftline{CHANGING UNITS.}
\bigskip
\noindent
All the numbers in the second line of the dialog region are dimensions in
terms of the units shown at the end of the line.
The parameters following some commands are also dimensions, in the
current units:
unlike the dimensions in \TeX, you don't explicitly type the units when you
need to specify a dimension after a \dvgt\ interactive command---simply
enter an integer or real value.
This value is rounded up internally to the nearest paper pixel, based on the
current units and the conversion factors shown below.
To change the units, use the |C| command, followed by the unit name.
For example, `|CCM H5 V3.4|' will change the units to centimetres and set the
window size to be 5\;cm wide and 3.4\;cm high.
The available units are as follows.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|BP|\hfil}\null
Dimensions are in terms of big points
(72\;bp $=$ 1\;in).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|CM|\hfil}\null
Dimensions are in terms of centimetres
(2.54\;cm $=$ 1\;in).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|IN|\hfil}\null
Dimensions are in terms of inches.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|MM|\hfil}\null
Dimensions are in terms of millimetres
(10\;mm $=$ 1\;cm).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|PC|\hfil}\null
Dimensions are in terms of picas
(1\;pc $=$ 12\;pt).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|PT|\hfil}\null
Dimensions are in terms of points
(72.27\;pt $=$ 1\;in).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|PX|\hfil}\null
Dimensions are in terms of paper pixels.
(The |-r| command line option sets the numbers of horizontal and
vertical paper pixels per inch).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|SP|\hfil}\null
Dimensions are in terms of scaled points
(65536\;sp $=$ 1\;pt).
\medskip
\bigskip
\leftline{MOVING THE WINDOW.}
\bigskip
\noindent
The window region can be moved to any position over the current page.
You will be told if the window moves entirely outside the page rectangle
defined by $minh$, $minv$, $maxh$ and $maxv$. If this does happen, movement
is restricted to {\it just outside\/} the edges to make it easier to get back
over the page using only the |U|, |D|, |L| and |R| commands.
If |Auto=+| then the location of the window is automatically set every time a
page is selected. This position will normally be
the top left corner of the paper; i.e., $(-1,-1)$ in inches.
The parameters $h$ and $v$ are dimensions ranging from $-480$ inches to
$+480$ inches (for those of you \TeX ing billboards).
\bigskip
\noindent |W| $h$|,|$v$
\item{}
Move the Window region's top left corner to the given paper position.
$h$ is the horizontal coordinate, $v$ is the vertical coordinate.
If $h$ and $v$ are absent then the window is moved to $(minh{,}minv)$,
the top left corner of the page rectangle.
\bigskip
\noindent |U| $v$
\item{}
Move the window Up $v$ units.
If $v$ is absent then move up an amount equal to half the window's
current height.
\bigskip
\noindent |D| $v$
\item{}
Move the window Down $v$ units.
If $v$ is absent then move down an amount equal to half the window's
current height.
\bigskip
\noindent |L| $h$
\item{}
Move the window Left $h$ units.
If $h$ is absent then move left an amount equal to half the window's
current width.
\bigskip
\noindent |R| $h$
\item{}
Move the window Right $h$ units.
If $h$ is absent then move right an amount equal to half the window's
current width.
The default behavior of |U|, |D|, |L| and |R| was changed in {\dvgt}
version 3.5 to move by half the window dimension instead of by the
full window size. The newer behavior retains some visible context
when moving the window.
\medskip
\bigskip
\leftline{CHANGING WINDOW SIZE.}
\bigskip
\noindent
The |H| and |V| commands are used to change the
width and height of the window region.
It is up to you to maintain a sensible aspect ratio.
The |ZI|, |ZO|, |ZCI| and |ZCO| zoom commands change both dimensions
by the same factor and so maintain the current aspect ratio.
|ZI| and |ZO| keep the top left of the window fixed;
|ZCI| and |ZCO| hold the centre of the window fixed.
If zooming causes the page to become invisible, the location of the
window may change;
otherwise, |ZCI| and |ZCO| are equivalent to |DRZI<z>UL| and
|DRZO<z>UL|, respectively,
where |<z>| represents the specified zoom factor (if any).
If |Auto=+| then the width and height of the window are automatically set every
time a page is selected; the values chosen will depend on the paper dimensions.
The parameters $wd$ and $ht$ are dimensions ranging from 1 pixel to 480 inches.
\bigskip
\noindent |H| $wd$
\item{}
Set the Horizontal size of the window to the given width.
If $wd$ is absent then set window width to its initial, unscaled value
(one screen pixel's width equals one paper pixel's width).
\bigskip
\noindent |V| $ht$
\item{}
Set the Vertical size of the window to the given height.
If $ht$ is absent then set window height to its initial, unscaled value
(one screen pixel's height equals one paper pixel's height).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|ZI| $z$\hfil}\null
Zoom In (holding the top left of the window) by dividing the current
window height and width both by $z$.
This also sets the current zoom factor to $z$.
If $z$ is absent, then Zoom In by the current zoom factor.
Initially, the current zoom factor is 2 (two).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|ZO| $z$\hfil}\null
Zoom Out (holding the top left of the window) by multiplying the
current window height and width both by $z$.
This also sets the current zoom factor to $z$.
If $z$ is absent, then Zoom Out by the current zoom factor.
Initially, the current zoom factor is 2 (two).
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|ZCI| $z$\hss}\null
Zoom Center In --- as for |ZI|, except holding the window's centre.
\bigskip
\item{} \hskip -\the\parindent \hbox to \parindent{|ZCO| $z$\hss}\null
Zoom Center Out --- as for |ZO|, except holding the window's centre.
\vfil\eject
\subhead{The Coordinate Scheme.}
% MACROS FOR DIAGRAM.
% \plot is based on \point macro described on page 389 of _The TeXbook_.
\newdimen\unit
\unit=1truein
\def\plot % #1 is down, #2 is right, #3 is stuff to plot
#1 #2 #3\endplot
{\rlap{\kern#2\unit
\vbox to 0pt{\parindent=0pt\offinterlineskip\kern#1\unit#3}}}
\newdimen\pix
\pix=.003truein % SYSDEP: .003" is approx 1 pixel for a 300dpi device
\def\bigdot{\hbox to 0pt{\hss\kern3\pix$\scriptstyle\bullet$\hss}}
\def\dot{\chlap{$\cdot$}}
\def\ulap#1{\vbox to 0pt{\vss#1}} % vertical analog of \llap
\def\dlap#1{\vbox to 0pt{#1\vss}} % vertical analog of \rlap
\def\cvlap#1{\vbox to 0pt{\vss#1\vss}} % centre vertically
\def\chlap#1{\hbox to 0pt{\hss#1\hss}} % centre horizontally
\def\vleaders{\leaders\vbox to .1\unit
{\vss\hrule width1sp height.05\unit\vss}\vfil}
\def\hleaders{\leaders\hbox to .1\unit
{\hss\vrule height1sp width.05\unit\hss}\hfil}
\def\cornervrule{\hbox{\vrule width1sp height.075\unit}}
\def\cornerhrule{\vrule width.075\unit height1sp}
\newdimen\paperwd \paperwd =\hsize
\newdimen\paperht \paperht =8.0\unit
\newdimen\pagewd \pagewd =3.0\unit
\newdimen\pageht \pageht =4.0\unit
\newdimen\windowwd \windowwd =2.5\unit
\newdimen\windowht \windowht =2.6\unit
\def\draworiginbox
{\plot 0 0
\cvlap{\bigdot}
\ulap{\vbox to 1\unit
{\kern.25truemm
\leaders\vbox to 1truemm{\vss\moveright1\pix\dot\vss}\vfil
\kern.75truemm
}
}
\cvlap{\kern2\pix % shift dots down slightly
\llap{\hbox to 1\unit
{\kern.25truemm
\leaders\hbox to 1truemm{\hss\dot\hss}\hfil
\kern.75truemm
}}
}
\ulap{\vbox to 1\unit
{\vfil
\rlap{~~\rlap{$1''$}~~~~~~The numbers of horizontal and
vertical pixels per inch
are set by |-r| option.}
\vfil
}
}
\ulap{\llap{$(0{,}0)$~~}
\medskip
}
\cvlap{\rlap{~~\rlap{$\rightarrow$}~~~~~~increasing $h$ coordinates}}
\dlap{\kern 1ex
\llap{\strut \hbox to 1\unit{\hfil$1''$\hfil}}
}
\dlap{\kern 1ex
\chlap{\strut $\downarrow$}
\chlap{\strut increasing}
\chlap{\strut $v$ coordinates}
}
\endplot
}
\def\drawpaperbox
{\plot -1 -1 % top left corner of paper box
\vbox
{\hsize=\paperwd % width of paper box
\ulap
{\line{\rlap{$(-1,-1)$ in inches}\hss
Paper edges will be displayed if visible.\hss}
\medskip
}
\cvlap{\bigdot}
\hrule height 1sp
\hbox to \hsize
{\vrule height \paperht width 1sp % height of paper box
\vbox to \paperht
{\vfil
\rlap{ \strut Paper height is set}
\rlap{ \strut by |-y| option.}
\vfil
}\hfil
\vrule height \paperht width 1sp
}
\hrule height 1sp
\medskip
\centerline{Paper width is set by |-x| option.}
}
\vss
\endplot
}
\def\drawpagebox
{\plot 2.2 0.6 % top left corner of page box
\vbox
{\hsize=\pagewd % width of page box
\cvlap{\llap{Page at $(minh{,}minv)$~~}}
\cvlap{\bigdot}
\cvlap{\rlap{\hbox to \pagewd
{\cornerhrule\hleaders\cornerhrule}}}
\dlap{\vbox to \pageht
{\centerline{\title Chapter 56}
\vskip1.175\unit
{\advance\hsize by 6\pix % get N touching maxh
\line{\title How\hfil to\hfil LOGIN}
}
\vfil
\setbox0=\hbox{\bigbf g}
\setbox1=\copy0
\dp0=0sp
\centerline
{\bigbf HAL\thinspace9000 Be\copy0inner's Guide}
\kern\dp1 % get g touching maxv
}
}
\hbox to \hsize
{\vbox to \pageht % height of page box
{\cornervrule\vleaders\cornervrule}%
\vbox to \pageht
{\vfil
\llap{Page height. }
\vfil
}%
\hfil
\vbox to \pageht
{\cornervrule\vleaders\cornervrule}%
}
\cvlap{\rlap{\hbox to \pagewd
{\cornerhrule\hleaders\cornerhrule}}}
\cvlap{\rightline{\bigdot}}
\cvlap{\rightline{\rlap{~~$(maxh{,}maxv)$}}}
\medskip
\centerline{Page width.}
}
\vss
\endplot
}
\def\drawwindowbox
{\plot 1.2 1.6 % top left corner of window box
\vbox
{\hsize=\windowwd % width of window box
\ulap
{\centerline{Window width is set by |H| command.}
\medskip
}
\cvlap{\llap{Window at $(h{,}v)$~~}}
\cvlap{\bigdot}
\cvlap{\rlap{\hbox to \windowwd
{\cornerhrule\hleaders\cornerhrule}}}
\dlap{\medskip
\centerline{\strut Use |U|, |D|, |L|, |R| and |W| commands}
\centerline{\strut to move the window.}
}
\dlap{\kern1\unit
\vbox to 1.6\unit
{\hsize=2\unit
\vfil
\centerline{\strut Only this portion of the}
\centerline{\strut page is currently visible.}
\vfil
}
}
\hbox to \hsize
{\vbox to \windowht % height of window box
{\cornervrule\vleaders\cornervrule}%
\hfil
\vbox to \windowht
{\cornervrule\vleaders\cornervrule}%
\vbox to \windowht
{\vfil
\rlap{ \strut Window height is}
\rlap{ \strut set by |V| command.}
\vfil
}\relax
}
\cvlap{\rlap{\hbox to \windowwd
{\cornerhrule\hleaders\cornerhrule}}}
}
\vss
\endplot
}
% SWITCH TO SMALLER FONT, MOVE TO 0,0 AND START PLOTTING.
\smallrm
\vskip 1.5\unit
\hbox
{\kern 1\unit % 0,0 is 1\unit in from left margin
\draworiginbox
\drawpaperbox
\drawpagebox
\drawwindowbox
}
\rm % back to normal text
\vfil\eject
\subhead{Some Examples.}
\medskip
\noindent
For clarity, commands are separated by spaces and typed
in upper case; neither condition is mandatory.
\bigskip\noindent
|P P P|
\item{}
If these commands are given before a page has been requested, they will select
the 3rd last page for display (assuming there are at least 3 pages).
The first |P| selects the last page;
the remaining |P|s go back another 2 pages.
Note that only the 3rd last page will be displayed. The intervening pages are
still processed, though, and you'll be warned about any problems with them
(such as a page off the paper).
\bigskip\noindent
% |1 F W H V| % - gt - in the days before dvgt 3.5,
% % when Full was not a toggle, and
% % Terse mode was the default.
|1 W H V|
\item{}
This command sequence is very useful for looking carefully at the results of
a small \TeX\ experiment. You might, for instance, want to look closely
at the appearance of two characters separated by a small |\kern|.
Suppose that Full display only is on (as is easily arranged). Then:
|1|~selects the first DVI page (usually the only page in such experiments);
% |F|~sets the display mode to full; % - gt - since dvgt 3.5, |F| toggles,
% % and Full mode is the default.
|W|~moves the window to the top left corner of the page;
|H|~sets the horizontal size of the window to its unscaled value, and
|V|~sets the vertical size of the window to its unscaled value.
Remember that this unscaled window size produces the most accurate display,
since each screen pixel corresponds to exactly one paper pixel, both
horizontally and vertically.
\bigskip\noindent
|R9999 L D9999 U|
\item{}
Sometimes you want to move quickly to the right edge of the page to have a
look at line breaks, or you might want to go to the bottom and look at where
the page was broken.
This particular command sequence will move the window's {\it bottom right\/}
corner to the bottom right corner of the current page; i.e., $(maxh{,}maxv)$.
In most current units (except scaled points, |SP|, which are minute),
|R9999|~suffices to move the entire window to the right of the page,
but only just;
|L|~then moves the window left by its current width so that the {\it right\/}
edges of the window and the page coincide;
|D9999|~moves the entire window below the page, but only just;
|U|~then moves the window up by its current height so that the {\it bottom\/}
edges of the window and page also coincide.
\bigskip\noindent
|1 ZO2 FB|
\item{}
It is often useful to get an overview of the positioning of printed matter
within the sheet of paper.
These commands will do just that on all the VDUs currently
implemented, assuming that automatic window calculation is enabled
and that the display mode is already set to Full only.
|1|~selects the first page, moves the window to the top left corner of
the paper, sets the window height to half the paper height and the
window width to the paper width
(resulting in a sensible aspect ratio on a typical VDU screen);
|ZO2|~doubles the window height and width, keeping the top left
corner of the window coincident with the top left corner of the paper,
so that the entire sheet of paper is visible and maintains the right
proportions;
|FB|~changes the Full only display mode to Box outlines only,
since the characters are now likely to be too small to read.
\bigskip\noindent
% |[.56] W IN H2.5 V2.6 R1 U1 F| % - gt - before dvgt 3.5. Now:
|[.56] W IN H2.5 V2.6 R1 U1|
\item{}
This is the likely command sequence that led to the window display shown in the
illustration on the previous page. % XREF
The [original] author [Andrew Trevorrow] has been clever enough to define
a |\chapter| macro that sets |\count1| to the given chapter number.
|[.56]|~will thus select the appropriate DVI page (|\count0| is ignored);
|W|~moves the window to the top left corner of the page;
|IN|~sets the current units to inches;
|H2.5|~and |V2.6|~set the window dimensions;
|R1|~moves the window right 1 inch;
|U1|~moves the window up 1 inch;
% |F|~sets the display mode to full. % - gt - before dvgt 3.5.
\finishline
\bye