summaryrefslogtreecommitdiff
path: root/dviware/dvgtk/doc/sysguide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'dviware/dvgtk/doc/sysguide.tex')
-rw-r--r--dviware/dvgtk/doc/sysguide.tex914
1 files changed, 914 insertions, 0 deletions
diff --git a/dviware/dvgtk/doc/sysguide.tex b/dviware/dvgtk/doc/sysguide.tex
new file mode 100644
index 0000000000..438f14cefa
--- /dev/null
+++ b/dviware/dvgtk/doc/sysguide.tex
@@ -0,0 +1,914 @@
+% sysguide.tex - 20:13 GMT +10:00 Tue 3 Aug 1993 - modifier Geoffrey Tobin.
+% This is the TeX source file for the "dvgt System 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.
+% Andrew Trevorrow, July 1986.
+%
+% Note: Andrew wrote to me in 1992 to say that he's released DVItoVDU
+% to the public domain, and that he is no longer maintaining it.
+% You may also modify dvgt to your heart's content, though it would
+% be more pleasant for the users if you rename it, first.
+% Don't forget to change the documentation: userguide.tex,
+% sysguide.tex, README, CHANGES, TODO, the Makefile-s, and any other
+% documentary evidence of what you've done to the software.
+% Geoffrey Tobin, May 1993.
+
+\input guidemacs
+
+% \centerline{\crest} % SYSDEP: University of Adelaide crest
+\vfil
+\centerline{\title \dvgt~~System~~Guide}
+\bigskip
+\vskip\parskip
+\centerline{\bigbf DVItoVDU Version 1.0 for VAX/UNIX in Modula-2
+ was by Andrew Trevorrow, July 1986}
+\smallskip
+\centerline{\bigbf DVItoVDU Version 3.0 ported to C
+ by Ian Dall, Novemebr 1990}
+\smallskip
+\centerline{\bigbf \dvgt\ for AIX and Sun/OS unix systems
+ is a modification by Geoffrey Tobin, May 1993}
+\bigskip
+
+\noindent
+This document explains how to install or modify \dvgt,
+a \TeX\ page previewer written in C.
+Details on how to use the program can be found in the
+{\sl \dvgt~User Guide}.
+It is assumed you are familiar with \TeX\ under unix\null.
+Please convey any problems or suggestions to:
+
+\medskip
+% SYSDEP
+%
+% \centerline{Andrew Trevorrow}
+% \centerline{Computing Services, University of Adelaide}
+% \centerline{GPO Box 498, Adelaide, South Australia, 5001}
+% \centerline{ACSnet address: |akt@uacomsci.ua.oz|~~Phone: (08) 228 5984}
+%
+\centerline{Geoffrey Tobin}
+\centerline{Electronic Engineering, La Trobe University}
+\centerline{Bundoora, Victoria, 3083}
+\centerline{Internet address: |ecsgrt@luxor.latrobe.edu.au|~~Phone:
+ |+ (03) 479 1987|}
+
+\bigskip
+\vskip\parskip
+\centerline{\bigbf Contents}
+\bigskip
+
+% XREF: make sure page numbers are up-to-date!!!
+\line{Important files\leaders\hbox to .75em{\hss.\hss}\hfil 1}
+\line{Installing \dvgt\leaders\hbox to .75em{\hss.\hss}\hfil 3}
+\line{Overview\leaders\hbox to .75em{\hss.\hss}\hfil 4}
+\line{Module map\leaders\hbox to .75em{\hss.\hss}\hfil 7}
+\line{Modifying \dvgt\leaders\hbox to .75em{\hss.\hss}\hfil 8}
+\line{Testing \dvgt\leaders\hbox to .75em{\hss.\hss}\hfil 10}
+\line{Revision history\leaders\hbox to .75em{\hss.\hss}\hfil 11}
+
+\vfil
+% \centerline{\smallrm University of Adelaide Computing Services} % SYSDEP
+\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{Important files.}
+
+\noindent
+Let's suppose you've unpacked the distribution into some directory and
+are now looking at its contents. The files are:
+\begindisplay
+Top-level distribution files\cr
+\noalign{\medskip}
+|DVGT.README|& overview of current distribution\cr
+|Makefile.dvgt|& make a tar, shar or zip distribution\cr
+|dvgt/|& parent of doc, help, misc and src directories\cr
+\noalign{\bigskip}
+Top-level files\cr
+\noalign{\medskip}
+|CHANGES|& list of changes since previous version\cr
+|README|& brief overview of \dvgt\cr
+|TODO|& wish-list\cr
+|doc/|& documentation and test files, in TeX\cr
+|help/|& help files\cr
+|misc/|& miscellaneous C headers\cr
+|src/|& sources for \dvgt\ executable\cr
+\noalign{\bigskip}
+|TAGS|, in |src| directory\cr
+\noalign{\medskip}
+|TAGS|& list of identifiers, with source location\cr
+& - useful with some editors, such as elvis\cr
+& - a "tags" or "ctags" program is needed,\cr
+& if you wish to make a TAGS file\cr
+\noalign{\bigskip}
+Program make files, in |src| directory\cr
+\noalign{\medskip}
+|Makefile.aix|& make |dvgt| for IBM Risc/6000 under AIX\cr
+|Makefile.sun|& make |dvgt| for Sparc 1 under Sun/OS\cr
+\noalign{\bigskip}
+C sources, in |src| directory\cr
+\noalign{\medskip}
+|version.h|& version description string\cr
+|config.h|& system-dependent C macros, types and variables\cr
+|dvitovdu.c|& main program's source file\cr
+|globals.h|& global things, often defined in |dvitovdu.c|\cr
+|options.c|/|h|& command-line options\cr
+|defaults.h|& system-dependent defaults for certain values\cr
+& used and/or set in |dvitovdu.c| and |options.c|\cr
+|files.h|& unix random access file i/o declarations,\cr
+& for |dvireader.c| and |fontreader.c|\cr
+|help.h|& (fall-back) option and interactive help texts\cr
+|screenio.c|/|h|& low-level terminal i/o routines\cr
+& (see also |unixio.c|/|h|)\cr
+|unixio.c|/|h|& unix command line interface routines\cr
+|lstring.c|/|h|& length specified strings\cr
+|new.h|& generic memory allocation\cr
+|dvireader.c|/|h|& DVI file translation routines and data structures\cr
+|fontreader.c|/|h|& PK and TFM font file access routines\cr
+|vdu.c|/|vdu.h|& generic VDU parameters and routines\cr
+|aed512vdu.c|& routines for AED 512\cr
+|ncsatelvdu.c|& routines for NCSA Telnet's tek4010 emulation\cr
+|regisvdu.c|/|h|& routines for ReGIS compatible VDUs\cr
+|tek4010emu.c|/|h|& routines for Tektronix 4010/4014 emulating VDUs\cr
+|vis240vdu.c|& routines for VISUAL 240\cr
+|vis500vdu.c|/|h|& routines for VISUAL 500\cr
+|vis550vdu.c|& routines for VISUAL 550\cr
+|vis603vdu.c|& routines for VISUAL 603\cr
+|vis630vdu.c|& routines for VISUAL 630\cr
+|vt100vdu.c|/|h|& routines for VT100\cr
+|vt100132vdu.c|& routines for VT100 in 132 column mode\cr
+|vt220vdu.c|& routines for VT220\cr
+|vt640vdu.c|& routines for VT100 with Retrographics\cr
+\noalign{\bigskip}
+Miscellaneous C headers, in |misc| directory\cr
+\noalign{\medskip}
+|stdlib.h|& Ian Dall's sample |"stdlib.h"| file,\cr
+& for those systems without |<stdlib.h>|\cr
+\noalign{\bigskip}
+Help files, in |help| directory\cr
+\noalign{\medskip}
+|cmd.hlp|& text file read by \dvgt's |?| interactive command\cr
+|immed.hlp|& on-line help file\cr
+|options.hlp|& detailed description of \dvgt\ options\cr
+\noalign{\bigskip}
+Documents, in |doc| directory\cr
+\noalign{\medskip}
+|Makefile|& make file for Documentation and Test files\cr
+|guidemacs.tex|& macros used by the following guides\cr
+|sysguide.tex|& source for this document, the {\sl \dvgt\ System Guide}\cr
+|userguide.tex|& source for the {\sl \dvgt\ User Guide}\cr
+\noalign{\bigskip}
+Test file, in |doc| directory\cr
+\noalign{\medskip}
+|tripvdu.tex|& source for |tripvdu.dvi|, a torture test for \dvgt\cr
+\enddisplay
+
+\vfil\eject
+\subhead{Installing \dvgt.}
+
+\noindent
+To make {\dvgt}, you need a C compiler, linker, and many of the most
+usual header and library files. \dvgt\ should compile under ANSI C,
+and under at least some traditional and pre-ANSI C compilers. Minor
+modifications may be necessary for some compilers and/or operating
+systems.
+
+\noindent
+This distribution is designed for IBM Risc/6000 computers under
+(a no-longer supported version (!) of) AIX, and for Sparc 1 computers
+under (a locally-modified) Sun/OS 4.0.3, but variants of these systems
+may possibly compile, link and run \dvgt\ as distributed.
+
+\noindent
+Reports of successful ports, as well as of bugs encountered, and of
+further items for the wish-list, are welcome.
+
+\noindent
+The executable file is called |dvgt|.
+Before making |dvgt| available to other users at your site,
+read the section on command options in the {\sl \dvgt\ User Guide}.
+If you have a C compiler and libraries, you may want to
+make a few changes to |defaults.h| to suit your site:
+
+\item{$\bullet$}
+Change |DEF_X_RESOLUTION| and |DEF_Y_RESOLUTION| (the default values of
+|-rx| and |-ry|) to match the X and Y resolutions of your printer,
+in dots per inch.
+
+\item{$\bullet$}
+Change |DEF_PAPERWD| and |DEF_PAPERHT| (the default values of |-x| and |-y|)
+to define the dimensions of the default paper used by your printer.
+
+\item{$\bullet$}
+Change |DEF_PK_DIR| and |DEF_TFM_DIR| (the default values of |-f| and |-t|)
+to tell \dvgt\ where to look for PK and TFM files.
+
+\item{$\bullet$}
+Change |DEF_DUMMY_PK| (the default value of |-d|)
+to indicate which PK file to use when a requested one does not exist.
+
+\item{$\bullet$}
+Change |DEF_HELP_FILE| (the default value of |-h|) to indicate the
+location of |cmd.hlp|.
+
+\noindent
+Individual users can of course override any of these defaults.
+Any changes you make should be reflected in the user documentation
+in |userguide.tex|, |immed.hlp|, |CHANGES| and |README|.
+(the |immed.hlp| file provides a suitable basis for a |man| entry).
+System-dependent information in these
+files is flagged by the string ``|SYSDEP|'' so you can quickly locate where
+changes need to be made.
+
+\vfil\eject
+\subhead{Overview.}
+
+\noindent
+A C program is typically built up from a number of separately compiled
+|.c| source files.
+Let's use the term |object| loosely for a type, constant, macro,
+variable, or function.
+The source files certainly must share some objects, in order to
+cooperate as a single program.
+
+\noindent
+Shared objects in C are defined in exactly one file.
+
+\noindent
+To increase the likelihood that the sources use shared objects
+correctly, common practice is to declare each shared object in
+exactly one |header| file, mnemonically suffixed |.h|. Any file
+that must use that shared object should |#include| that header.
+Headers should not allocate storage; that should be left to |.c|
+files.
+
+\noindent
+In the case of types, constants and macros, which don't require
+runtime storage, the declaration constitutes the definition, so
+if these are shared, then they are defined and declared in the
+same file, which will be a header.
+
+\noindent
+However, for variables and functions, which do need storage at runtime,
+a definition not only describes the object, but it also allocates
+storage for it, whereas a declaration is a mere description.
+Consequently, shared variables and functions are defined in one
+|.c| file, and declared in a header typically named after it.
+That header may also define types, constants and macros needed
+by those shared variables and functions.
+
+\noindent
+For example, |fontreader.c| defines some shared functions, which are
+declared in |fontreader.h|, which is |#include|-ed by the C source
+files (including |fontreader.c| itself) that use those functions.
+
+\noindent
+If this is done wisely, then rapid system regeneration is possible,
+because the |.c| files only use information provided in the headers;
+each |.c| file may be modified (e.g., optimized) without the need to
+recompile the others. This is called |modular| programming, and we
+may then meaningfully speak of the |.c| and any accompanying |.h| file
+as a |module|. To carry the terminology further, we can loosely
+describe the defining file (or module) as |implementing| the shared
+objects, which it |exports|, through the |interface| provided by its
+header, to the |client| modules that |import| those shared objects
+in order to use them.
+
+\noindent
+The module map on page 7 % XREF
+shows the importation dependencies of all the modules of \dvgt\null.
+
+\noindent
+Not only do modules allow a large program to be broken up into manageable
+chunks, they also provide a sensible basis for describing a program:
+
+\medskip
+\noindent |DVItoVDU|
+
+\nobreak\noindent
+The main module is primarily concerned with the user interface.
+It handles all the interactive command processing
+and contains the high-level logic used to update the dialogue and window
+regions. Data and procedures are imported from the following modules to help
+the main module carry out its many tasks.
+
+\medskip
+\noindent |Options|
+
+\nobreak\noindent
+This module provides the interface to the UNIX shell.
+The command line used to invoke \dvgt\ is parsed and the DVI file name
+extracted. All the options are also initialized, either to explicit
+values given in the command line or to site-dependent default values.
+
+\medskip
+\noindent |VDUinterface|
+
+\nobreak\noindent
+\dvgt\ can work efficiently on different types of VDUs by letting
+C function pointers act as generic VDU routines.
+These routines, along with the generic VDU parameters, are defined in
+|VDUinterface|.
+
+\noindent
+The generic VDU routines are:
+\begindisplay
+|StartText|& switch to ``text mode''\cr
+|ClearTextLine|& erase given line\cr
+|MoveToTextLine|& move cursor to start of given line\cr
+|ClearScreen|& erase the entire screen\cr
+|StartGraphics|& switch to ``graphics mode''\cr
+|LoadFont|& simulate the given font for future |ShowChar| calls\cr
+|ShowChar|& display a Terse mode character at given screen location\cr
+|ShowRectangle|& display a given rectangular region of screen pixels\cr
+|ResetVDU|& reset VDU to its normal state\cr
+\enddisplay
+Most of these are quite trivial to implement for a specific VDU.
+The main module looks after all the tricky graphic operations such as the
+clipping of characters and rules outside the current
+window region, and the way in which visible paper pixels are scaled
+to screen pixels.
+
+\noindent
+From an efficiency point of view, the two most critical routines are
+|ShowChar| and |ShowRectangle|.
+|ShowChar| is used by the main module to display a character in Terse
+mode. The only information given is the \TeX\ character (currently
+restricted to |\char0..\char255|) and its screen position.
+Since characters are displayed one font at a time, some VDUs can use scaling
+information sent by the most recent |LoadFont| routine to select an
+appropriate hardware ``font''.
+
+\noindent
+|ShowRectangle| is used for all other window graphics.
+It is used to draw the paper edges, to draw all rules (regardless of display
+mode), to draw all glyph outlines in a Box display, and to draw the horizontal
+lines making up all glyphs in a Full display.
+The majority of rectangles are in fact horizontal or vertical lines just one
+screen pixel thick.
+\bigbreak
+
+\noindent
+The generic VDU parameters are:
+\begindisplay
+|DVIstatusl|& DVI status line, usually 1\cr
+|windowstatusl|& window status line, usually 2\cr
+|messagel|& message line, usually 3\cr
+|commandl|& command line, usually 4\cr
+|bottoml|& bottom text line in screen\cr
+|windowh|& window region's top left h coordinate\cr
+|windowv|& window region's top left v coordinate\cr
+|windowwd|& unscaled window width\cr
+|windowht|& unscaled window height\cr
+\enddisplay
+These ``parameters'' are actually integer variables. The main module
+treats them as constants.
+
+\noindent
+There are two screen coordinate systems used by \dvgt:
+
+\item{(1)}
+When updating the screen in text mode (i.e., when updating the
+dialogue region or during a |?| or |S| command), \dvgt\ assumes
+text lines start at 1 and increase downwards. The bottom
+text line on the screen is given by the parameter |bottoml|.
+
+\item{(2)}
+When updating the screen in graphics mode,
+\dvgt\ assumes the top left screen pixel
+is positioned at (0,0). Horizontal coordinates increase to the right
+and vertical coordinates increase down the screen. The top left pixel
+in the window region is at (|windowh|,|windowv|).
+Specific VDU modules may have to do a translation to the actual
+coordinate scheme used by the VDU\null.
+The size of the window region in screen pixels
+is given by |windowwd| and |windowht|.
+
+\medskip
+\noindent |aed512vdu|, |ncsatelvdu|, |regisvdu|, etc.
+
+\nobreak\noindent
+Each specific VDU module exports an initialization routine
+that will assign appropriate procedures to the generic VDU routines
+and specific integers to the generic VDU parameters.
+|VDUinterface| imports all these initialization routines and
+uses the |-v| value set in |Options| to
+execute one of them.
+
+\medskip
+\noindent |DVIReader|
+
+\nobreak\noindent
+This module exports the routines and data structures needed
+to move about randomly in a DVI file and interpret selected pages.
+Although the main module is currently the only client,
+it is anticipated that |DVIReader| could just as well form the basis of
+another DVI translator, such as a non-interactive device driver.
+
+\noindent
+Font, character and rule information is stored in dynamically allocated
+lists to avoid imposing any limit on their numbers.
+The length of the font list is determined soon after opening the DVI file by
+reading all the font definitions in the postamble.
+Each font node is a record made up of many fields; one of these fields is the
+head of a character list. The nodes in each character list will
+store the positions and \TeX\ codes of all characters on a page.
+Besides the font list, there is also a rule list.
+The nodes in the rule list will store the positions and dimensions of
+all rules on a page.
+(Character and rule positions are stored as pairs of horizontal and vertical
+paper pixel coordinates.
+The manner in which |DVIReader| calculates such positions is based
+firmly on Donald Knuth's |DVItype|.)
+
+\noindent
+Just before interpreting a selected DVI page, the rule list and all the
+character lists are deallocated if necessary.
+During interpretation, |DVIReader| adds a new rule or character
+node to the {\it tail\/} of an appropriate list.
+When the main module processes such lists, rules and characters will be
+displayed in somewhat the same sequence as seen in the DVI page; i.e.,
+top-to-bottom and left-to-right.
+(Since there is a separate rule list, as well as a character list for
+each font, the precise sequence is not remembered.)
+After interpretation, the nodes in the font list are sorted so
+that fonts with the least number of characters ($>$ 0) will
+be processed first.
+
+\noindent
+The various lists contain most of the information needed to display the page;
+they are traversed by the main module whenever the window region is updated.
+If the page isn't empty then |DVIReader| will also determine
+the edges of the page rectangle. This is the smallest
+rectangle containing all black pixels in glyphs and rules, as well
+as all character reference points (needed for Terse displays).
+The main module uses the page rectangle to decide if the page is off the paper,
+and to restrict window movement.
+
+\medskip
+\noindent |FontReader|
+
+\nobreak\noindent
+\dvgt\ gets all its character information from standard PK files.
+|FontReader| exports routines for moving about in such files and
+grabbing various bytes and words.
+A PK file contains the crucial TFM widths needed by |DVIReader| to
+correctly position characters when interpreting a DVI page. These widths,
+along with other details about each glyph, are kept in the PK file.
+The PK file is loaded just once for each font (the very first
+time the font is seen) and \dvgt\ will write
+`|Loading font data from ...|' to the log file.
+
+\noindent
+A PK file also contains glyph shape information (in the form of bitmaps)
+for all characters in a \TeX\ font.
+\dvgt\ uses these bitmaps during a Full display to draw
+characters a font at a time.
+
+\noindent
+Because |DVIReader| creates a separate character list
+for each font used on a page,
+there never needs to be more than one PK file open at any given time.
+(But there are! - Geoffrey Tobin observes.)
+
+\medskip
+\noindent |ScreenIO|
+
+\nobreak\noindent
+All low-level terminal i/o is handled by the routines defined in this module.
+It uses some C routines written by Alex Dickinson (see |unixio.c|).
+
+\vfil\eject
+\subhead{Module map.}
+
+\font\arrowfont=linew10 at 10truept
+
+% MACROS FOR MAP.
+% \plot is based on \point macro described on page 389 of TeXbook.
+
+\newdimen\unit
+\unit=1in
+
+\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\vss}}}
+
+\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\drawbox ht#1 wd#2 #3\endbox
+ {\vbox{\hsize=#2\unit
+ \hrule height10sp
+ \hbox to \hsize
+ {\vrule width10sp
+ \vbox to #1\unit
+ {\vfil #3\vfil}%
+ \vrule width10sp
+ }
+ \hrule height10sp
+ }
+ }
+
+\def\mainmodule
+ {\drawbox ht.7 wd1.2
+ \centerline{\strut |DVItoVDU|}
+ \centerline{\strut (main module)}
+ \endbox
+ }
+
+\def\midmodules
+ {\drawbox ht.4 wd1
+ \centerline{|DVIReader|}
+ \endbox
+ \kern .3\unit
+ \drawbox ht.4 wd1
+ \centerline{|FontReader|}
+ \endbox
+ \kern .3\unit
+ \drawbox ht.4 wd1
+ \centerline{|VDUinterface|}
+ \endbox
+ \kern .3\unit
+ \drawbox ht.4 wd1
+ \centerline{|Options|}
+ \endbox
+ \kern .5\unit
+ \drawbox ht.4 wd1.5
+ \centerline{|ScreenIO|}
+ \endbox
+ }
+
+\def\vdumodules
+ {\drawbox ht1.2 wd1.3
+ \centerline{\strut VDU modules:}
+ \centerline{\strut |aed512vdu|}
+ \centerline{\strut |ncsatelvdu|}
+ \centerline{\strut |regisvdu|}
+ \centerline{\strut etc.}
+ \endbox
+ }
+
+\def\uline#1 {\ulap{\hrule width 10sp height#1\unit}}
+\def\dline#1 {\dlap{\hrule width 10sp height#1\unit}}
+\def\lline#1 {\llap{\vrule height10sp width #1\unit}}
+\def\rline#1 {\rlap{\vrule height10sp width #1\unit}}
+
+\def\uarrow#1 {\ulap{\arrowfont\dlap{\hbox{\char'66 }}
+ \hrule width10sp height#1\unit}}
+\def\darrow#1 {\dlap{\arrowfont\hrule width10sp height#1\unit
+ \ulap{\hbox{\char'77 }}}}
+\def\rarrow#1 {\rlap{\vrule height10sp width#1\unit
+ \setbox0=\hbox{\arrowfont\char'55 }\ht0=0pt\dp0=0pt
+ \llap{\box0}}}
+\def\larrow#1 {\llap{\setbox0=\hbox{\arrowfont\char'33 }\ht0=0pt\dp0=0pt
+ \rlap{\box0}\relax
+ \vrule height10sp width#1\unit}}
+
+% START PLOTTING MAP
+
+\noindent
+An arrow from module |A| to module |B| indicates the latter
+imports data and/or procedures from the former.
+Module |B| is said to be a {\it client\/} of module |A|\null.
+
+\vskip 1in
+
+\hbox
+ {\kern-.3\unit % shift 0,0 left
+ % plot all the module boxes:
+ \plot 0.0 0.5 \mainmodule \endplot
+ \plot 1.0 2.5 \midmodules \endplot
+ \plot 2.4 4.4 \vdumodules \endplot
+ % plot all the arrows:
+ \plot 1.2 1.5 \uarrow 0.5 \endplot % DVIReader to main
+ \plot 1.2 1.5 \rline 1.0 \endplot
+ \plot 1.9 1.3 \uarrow 1.2 \endplot % FontReader to main
+ \plot 1.9 1.3 \rline 1.2 \endplot
+ \plot 2.6 1.1 \uarrow 1.9 \endplot % VDUinterface to main
+ \plot 2.6 1.1 \rline 1.4 \endplot
+ \plot 3.3 0.9 \uarrow 2.6 \endplot % Options to main
+ \plot 3.3 0.9 \rline 1.6 \endplot
+ \plot 4.2 0.7 \uarrow 3.5 \endplot % ScreenIO to main
+ \plot 4.2 0.7 \rline 1.8 \endplot
+ \plot 4.0 3.0 \uarrow 0.5 \endplot % ScreenIO to Options
+ \plot 4.0 3.8 \uline 1.3 \endplot % ScreenIO to VDUinterface
+ \plot 2.7 3.8 \larrow 0.3 \endplot
+ \plot 3.9 3.8 \darrow 0.1 \endplot % down arrow at point 6
+ \plot 3.1 3.0 \uarrow 0.3 \endplot % Options to VDUinterface
+ \plot 2.5 4.4 \larrow 0.9 \endplot % point 5 to VDUinterface
+ \plot 2.5 4.3 \rarrow 0.1 \endplot % right arrow at point 5
+ \plot 4.2 4.0 \rline 2.3 \endplot % line to right of ScreenIO
+ \plot 4.2 6.3 \uline 3.0 \endplot % ScreenIO to vdus, font, dvi
+ \plot 3.0 6.3 \larrow 0.6 \endplot % ScreenIO to vdus
+ \plot 1.9 6.3 \larrow 2.8 \endplot % ScreenIO to FontReader
+ \plot 1.2 6.3 \larrow 2.8 \endplot % ScreenIO to DVIReader
+ % plot all the numbers:
+ \plot 1.5 2.4 \llap{1} \endplot
+ \plot 2.4 2.4 \llap{2} \endplot
+ \plot 3.1 2.4 \llap{3} \endplot
+ \plot 2.9 3.1 \rlap{4} \endplot
+ \plot 2.3 4.3 \llap{5} \endplot
+ \plot 3.8 3.9 \rlap{6} \endplot
+ }
+
+\vfill
+
+\noindent Points of interest:
+
+\item{1 }
+|DVIReader| does not depend on |FontReader|.
+It does know that PK files contain crucial typesetting data, but leaves it
+up to the main module to specify how and where to get such information.
+
+\item{2 }
+|VDUinterface| exports the generic VDU routines and parameters
+for use in the main module.
+
+\item{3 }
+|Options| extracts the DVI file name and options from
+the |dvgt| command line.
+
+\item{4 }
+|VDUinterface| needs the |-v| value to select an appropriate VDU
+initialization routine.
+
+\item{5 }
+Specific VDU modules import the generic VDU routines and parameters
+from |VDUinterface|. In return, each VDU module
+exports an initialization routine.
+
+\item{6 }
+|ScreenIO| needs to use some |VDUinterface| routines to be able to
+leave the VDU screen in a decent state after abnormal termination.
+
+\vfil\eject
+\subhead{Modifying \dvgt.}
+
+\noindent
+\dvgt\ is descended from Andrew Trevorrow's |DVItoVDU|.
+
+\noindent
+|DVItoVDU| was originally developed under VAX/VMS
+using the Modula-2 system from Hamburg University.
+The UNIX version of |DVItoVDU| was developed using the
+Modula-2 compiler from DEC WRL and can run under ULTRIX or UNIX 4.2 BSD\null.
+The main module and all the supporting modules of |DVItoVDU| are
+written in Modula-2, except for the C routines in |unixio.c|.
+
+\noindent
+Ian Dall ported |DVItoVDU| version 3.0 to traditional C in November 1990,
+working from December 1989, with amendments in January 1991.
+Geoffrey Tobin (conditionally) ported it to ANSI C in May 1992,
+renaming it |dvgt| to avoid confusion.
+Significant modifications have been made to the user interface and
+code of |dvgt| up to the present date (May 1993), especially in
+versions 3.4 (first official public release, December 1992) and 3.5.
+
+\noindent
+If you wish to modify \dvgt\ you'll obviously need C, preferably either
+ANSI C or gcc (Gnu C), because those compilers provide stronger checks
+than earlier versions of C.
+Conversion to another C system should, however, be quite easy,
+particularly since traditional C is still provided for, via a test
+for the ANSI C macro |__STDC__|.
+
+\noindent
+All the source files avoid non-standard compiler features (IF NOT,
+PLEASE REPORT!),
+and system-dependent code is flagged by the string ``|SYSDEP|''\null.
+Terminal i/o is isolated in the |ScreenIO| module,
+and most file operations are restricted to |DVIReader| and |FontReader|.
+
+\noindent
+(The VMS-to-UNIX conversion took [Andrew Trevorrow] about two weeks.
+A working version was up in less than a week; it then took another week
+to fix some terminal i/o problems and produce a new {\sl User Guide}.
+[He] was a bit surprised at just how easy the conversion was.)
+
+\noindent
+[ Andrew Trevorrow, re the Modula-2 version of DVItoVDU:
+
+\noindent
+What about conversion to another language?
+An obvious candidate is Pascal.
+The similarities in syntax would allow any decent text editor to
+carry out much of the conversion automatically.
+The major difficulty in translation to standard Pascal would be
+the lack of procedure variables;
+it might be easier to implement just one type of VDU before
+attempting anything more sophisticated.
+]
+
+\medskip
+\noindent IMPLEMENTING A NEW VDU.
+
+\noindent
+Assuming you have a C compiler, the most likely change you'll want to
+make is to add a new type of VDU to the program's capabilities.
+The code takes advantage of separate compilation (modularity),
+so that such a task can be undertaken without having to make any changes to
+the main module.
+
+\noindent
+The steps required to implement a new VDU (which we'll call brand XXX)
+are as follows, assuming that each of the other C files has been compiled
+to a |.o| file. This includes how to compile and link by hand; the
+changes to the Makefile-s should be evident to anyone who has even
+a little experience with |make| on either unix or another system.
+
+\item{$\bullet$}
+Read |vdu.h| to see if the task is even possible.
+\dvgt\ requires XXX to be able to carry out a number of
+primitive graphic operations
+such as clearing the screen, addressing individual pixels, etc.
+As little as possible is assumed about the capabilities of a VDU\null.
+In particular, the availability of a graphic input device is ignored.
+\dvgt\ should be able to work on any terminal that can:
+
+\itemitem{---} Mix text and graphics on the screen
+(some VDUs make no distinction).
+{\parskip=0pt
+\itemitem{---} Erase all of the screen, or individual text lines.
+\itemitem{---} Move the cursor to any given screen pixel.
+\itemitem{---} Display a rectangular region of screen pixels
+(possibly just one).
+
+} % reset \parskip
+
+\item{$\bullet$}
+Look at some of the |*vdu.h| files and use them to help you
+create |xxxvdu.h|.
+
+\item{$\bullet$}
+Look at some of the |*vdu.c| files and use them to help you
+create |xxxvdu.c|.
+Type `|cc -c xxxvdu.c|' to create |xxxvdu.o|. % SYSDEP
+
+\item{$\bullet$}
+Edit |vdu.c| and add appropriate code in the recommended locations
+(search for occurrences of ``|XXX|'').
+Type `|cc -c vdu.c|' to create a new |.o| file. % SYSDEP
+
+\item{$\bullet$}
+Relink |dvgt| by typing `|cc -o dvgt *.o|'. % SYSDEP
+
+\item{$\bullet$}
+Test the new version of |dvgt| (see the next section).
+
+\noindent
+It should be pointed out that \dvgt\ is currently targeted towards
+relatively primitive terminals. Significant changes to both the display
+logic and page data structures would probably
+be needed to take full advantage of the latest graphic work\-stations.
+For instance, a large amount of bit-mapped memory could store an entire
+rasterized page and allow much more sophisticated updating of
+the window region.
+Pan and zoom operations would also be much easier using a mouse or thumbwheel
+cursor controls.
+
+\vfil\eject
+\subhead{Testing \dvgt.}
+
+\noindent
+The file |tripvdu.dvi| was created to test \dvgt\ using much the same
+philosophy as Donald Knuth's torture test for \TeX\null.
+Most pages exercise rarely-used parts of the program:
+\begindisplay
+page& contents\cr
+\noalign{\medskip}
+1& empty page (but with |\special| stuff that will be ignored)\cr
+2& one black pixel at (0{,}0)\cr
+3& entirely blackened A4 sheet of paper\cr
+4& like page 3 but one pixel wider\cr
+5& like page 3 but one pixel longer\cr
+6& has a rulelist with one full ruletable node (300 rules)\cr
+7& like page 6 but has one more rule\cr
+8& has a charlist with one full chartable node (3000 characters)\cr
+9& like page 8 but has one more character\cr
+10& multiple \TeX\ page counters\cr
+11& negative \TeX\ page counter\cr
+12& characters from many fonts\cr
+13& characters from many fonts, some of which have no PK file\cr
+14& paragraph using most characters from standard roman font\cr
+15& page in bottom half of A4 paper\cr
+16& page entirely above and to the left of A4 paper\cr
+17& page entirely below and to the right of A4 paper\cr
+18& page extending beyond all edges of A4 paper\cr
+\enddisplay
+Type `|dvgt tripvdu|'
+and go through all the pages to verify that the program is working correctly.
+You may need to specify a |-v| value to tell |dvgt| what type of terminal
+you're using.
+See the {\sl \dvgt\ User Guide} for details on
+what |-v| values are available and the special requirements of some VDUs.
+
+\noindent
+If a catastrophe occurs and \dvgt\ actually crashes, please report
+the problem back to me, Geoffrey Tobin.
+
+\noindent
+If the reason for the crash is not obvious,
+and you have a C compiler, you might try to rebuild |dvgt| after
+editing the |.c| files that contain debugging code.
+
+\noindent
+Before all comments of the form |#ifdef <MACRO>|, perhaps at the top
+of the source file, so you can find them easily, write |#define <MACRO>|.
+Here |<MACRO>| represents an identifier, usually in all capitals, such
+as |DEBUG|, or |BORING_MESSAGES|.
+
+\noindent
+Alternatively, write code of your own to output |snapshots| (current
+information) to the |logfile|. Wrap this code in an
+|#ifdef ... #else ... #endif| test, remembering to |#define| the
+appropriate macro constant when you're debugging. I like to label
+the |#else| and |#endif| lines with the name of the macro constant,
+so that its easy to see matching lines.
+
+\noindent
+Only a few modules have such code; use `|grep #ifdef *.c|' to list them.
+Note that the occurrences with |__STDC__| in them are not debugging code,
+but ANSI/non-ANSI detection switches, so you'll need to exclude those
+from your list; one way is to use the |-v| pattern exclusion option
+of |grep|, thus: `|grep #ifdef *.c| $\|$ |grep -v __STDC__|'. You might
+also want to redirect th eoutput to a file, or pipe it to either |more|
+or |less| (an improvement over |more| that allows backward scrolling,
+and much besides).
+
+\noindent
+The extra code might provide additional clues as to what is going wrong.
+
+\vfil\eject
+\subhead{Revision history}
+
+\medskip
+\noindent |DVItoVDU 1.0|
+
+\nobreak\noindent
+Version 1.0 of DVItoVDU for VAX/UNIX was based on
+version 1.5 for VAX/VMS (TUGboat vol.~7 no.~1 has an article
+describing the VMS version).
+The UNIX version of DVItoVDU is virtually identical as far as the user
+is concerned. The command option syntax is a little
+different of course, and there are a couple of new VDU types,
+but the interactive commands are exactly the same.
+
+\noindent
+A few improvements have been made to the UNIX version:
+
+\item{$\bullet$}
+Whenever a |\special| command is ignored, the first few bytes are
+displayed in case some users need to see them.
+
+\item{$\bullet$}
+While updating the window region, the main module uses
+|BusyRead| from |ScreenIO| to check for user input
+after drawing each visible rule or character.
+(The VMS version checked after every 8th rule or character; the overheads
+for |BusyRead| seem to be much less under UNIX.)
+
+\item{$\bullet$}
+|ScreenIO| required significant changes to be able to handle
+some of the more useful UNIX interrupts:
+|^C| can be used to return quickly to the `|Command:|' level, and
+|^Z| can be used to suspend |DVItoVDU|.
+(Thanks to Alex Dickinson who wrote the necessary |unixio.c| routines.)
+These interrupts are only detected during |Read|, |ReadString| and
+|BusyRead|.
+
+\medskip
+\noindent |DVItoVDU 2.0 to 3.0|
+
+\nobreak\noindent
+Lamentably mysterious.
+
+\medskip
+\noindent |C port|
+
+\nobreak\noindent
+Geoffrey Tobin is not aware of any significant functional changes
+introduced by Ian Dall.
+
+\medskip
+\noindent |dvgt 3.1 to 3.4|
+
+\nobreak\noindent
+See the README file in the dvgt/ directory.
+
+\medskip
+\noindent |dvgt 3.5|
+
+\nobreak\noindent
+See the CHANGES file in the dvgt/ directory, and/or the README file.
+
+\finishline
+\bye