diff options
Diffstat (limited to 'dviware/dvgtk/doc/userguide.tex')
-rw-r--r-- | dviware/dvgtk/doc/userguide.tex | 1286 |
1 files changed, 1286 insertions, 0 deletions
diff --git a/dviware/dvgtk/doc/userguide.tex b/dviware/dvgtk/doc/userguide.tex new file mode 100644 index 0000000000..f70df582d9 --- /dev/null +++ b/dviware/dvgtk/doc/userguide.tex @@ -0,0 +1,1286 @@ +% 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 |