% 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 |DRZIUL| and |DRZOUL|, respectively, where || 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