From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- dviware/dvgtk/doc/CHANGES | 448 ++++++++++++++ dviware/dvgtk/doc/Makefile | 24 + dviware/dvgtk/doc/README | 426 +++++++++++++ dviware/dvgtk/doc/TODO | 36 ++ dviware/dvgtk/doc/ansi2knr.1 | 19 + dviware/dvgtk/doc/example.tex | 232 +++++++ dviware/dvgtk/doc/guidemacs.tex | 105 ++++ dviware/dvgtk/doc/options.txt | 139 +++++ dviware/dvgtk/doc/sysguide.tex | 914 ++++++++++++++++++++++++++++ dviware/dvgtk/doc/tripvdu.tex | 279 +++++++++ dviware/dvgtk/doc/userguide.tex | 1286 +++++++++++++++++++++++++++++++++++++++ 11 files changed, 3908 insertions(+) create mode 100644 dviware/dvgtk/doc/CHANGES create mode 100644 dviware/dvgtk/doc/Makefile create mode 100644 dviware/dvgtk/doc/README create mode 100644 dviware/dvgtk/doc/TODO create mode 100644 dviware/dvgtk/doc/ansi2knr.1 create mode 100644 dviware/dvgtk/doc/example.tex create mode 100644 dviware/dvgtk/doc/guidemacs.tex create mode 100644 dviware/dvgtk/doc/options.txt create mode 100644 dviware/dvgtk/doc/sysguide.tex create mode 100644 dviware/dvgtk/doc/tripvdu.tex create mode 100644 dviware/dvgtk/doc/userguide.tex (limited to 'dviware/dvgtk/doc') diff --git a/dviware/dvgtk/doc/CHANGES b/dviware/dvgtk/doc/CHANGES new file mode 100644 index 0000000000..3f5acd5c0b --- /dev/null +++ b/dviware/dvgtk/doc/CHANGES @@ -0,0 +1,448 @@ +CHANGES - dvgt up to 3.51 - 18:30 GMT +10:00 Wed 25 August 1993. + +---------------------------------------------------------------------- +dvgt 3.4 (3 mod 4) : changes not recorded here. +---------------------------------------------------------------------- + +1. - 18:17 GMT +10:00 Thu 18 Mar 1993 - +options.c : + Added DV_TERM environment variable, to override TERM. + +2. - Sun 2 May 1993 - +fontreader.c, lstring.c, lstring.h : + Length specified strings introduced to make the TFM and PK font + file specification string formation more controlled. + +3. - Sun 2 May 1993 - + Using strncpy widely in place of strcpy, to keep string memory + accesses within bounds. + +4. - 17:48 GMT +10:00 Mon 3 May 1993 - +ncsatelvdu.c, vduinterface.c : + Added Vijay's (vijay@ncst.ernet.in) NCSA Telnet driver. + Now my picture is clear. + +5. - About or before Sun 9 May 1993 - +defaults.h : + Added constant "DEF_DUMMY_TFM", in case I implement such a thing. + +6. - 21:22 GMT +10:00 Sun 9 May 1993 - +All drivers and other files that referred to "tek4010vdu" : + Renamed: tek4010vdu.c -> tek4010emu.c + tek4010vdu.h -> tek4010emu.h + This was because some users have been misled by the name to think + that these files were for a true TEK4010 terminal. But they are + not: they are only for the use of the TEK4010 emulating drivers. + +7. - 21:20 GMT +10:00 Mon 10 May 1993 - +In all *.c files that use exit() : + All deliberate exits produce a message. + + (I don't account for outside interruptions, such as power failures.) + +8. - 21:24 GMT +10:00 Mon 10 May 1993 - + All message text is logged in a file named `.vlg', + where the DVI file is named `.dvi'. + If that log file cannot be opened, then `dvgt.log' is opened. + If then `dvgt.log' cannot be opened, dvgt exits with a message. + +9. - Tue 11 May 1993 - +fontreader.c : + TFM and PK font paths may now contain multiple directories. + For example, "setenv PKFONTS .:/usr/local/lib/tex/fonts/tmp" + allows searching in current directory, then in the other location. + +10. - Tue 11 May 1993 - +fontreader.c : + Dummy font's file specification is now formed in the same way + as other PK fonts. + +11. - 20:02 GMT +10:00 Wed 12 May 1993 - +dvitovdu.c : + Inability to write a log file no longer exits dvgt. + Instead, logfile is set NULL, and subsequently ignored. + Some other exits deleted as due to non-fatal conditions. + +12. - 20:02 GMT +10:00 Wed 12 May 1993 - +config.h, globals.h, dvitovdu.c, fontreader.c : + "bitmap_rec" replaced by "Word" which I typedef as int. + Bitmaps are dynamicaly allocated, so they can be much smaller + or much larger, as the case requires. + +13. - 22:06 GMT +10:00 Wed 12 May 1993 - +fontreader.c : + Fatal message "Couldn't open dummy font!" is now written to the + terminal, after resetting VDU, and appears cleanly - at least + after use of the "ncsatel" vdu mode. + +14. - 22:06 GMT +10:00 Wed 12 May 1993 - +dvitovdu.c : + The following signals are caught so that the screen may be reset + before exit: SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM. + Any other signal is also caught! + +15. - Fri 14 May 1993 - +tek4010emu.c : + In Terse mode, i.e. in TEK4010ShowChar(), the unrepresented font + characters, previously shown as '?', are now displayed as + hexadecimal escape sequences. E.g., code 1 appears as '\01'. + +16. - Fri 14 May 1993 - +dvitovdu.c : + 'N' and 'P' commands now page forward and back, to the next and + previous page, respectively. + So, the '<' and '>' commands are deleted. + +17. - Fri 14 May 1993 - +dvitovdu.c : + Added control-L command to refresh screen. + +18. - Fri 14 May 1993 - +dvitovdu.c : + Units are now changed by a 'C' command. The 'C' may be followed by + zero or more spaces, and then the unit name. (The actual unit names + are as before: IN, CM, MM, PT, BP, PC, BP, SP and PX.) + +19. - Fri 14 May 1993 - +dvitovdu.c, help.h : + The '?' interactive command help is now integrated into the source + code, in "help.h", using a ShowText() function. + +20. - Sun 16 May 1993 - +dvitovdu.c, tek4010emu.c : + The "F" (Full), "B" (Box) and "T" (Terse) commands are now toggles. + Any combination of these display modes is now accepted. + Change necessary to tek4010emu.c, to correct a faulty assumption at + the beginning of TEK4010ShowChar(). + +21. - Sun 16 May 1993 - +dvitovdu.c : + The "A" Auto window command is now a toggle. + +22. - Mon 17 May 1993 - +dvitovdu.c : + BoxChar() is now used in place of FullCharPS in Full mode when a TFM + gives the Bounding Box information, because I prefer outlines to + solid rectangles. + +23. - Fri 21 May 1993 - +fontreader.c, dvitovdu.c : + BuildFontSpec() and PixelTableRoutine() have been altered, so that + dvgt seeks a PK font first, then a TFM, then the dummy PK font. + Consequently, the PostScript prefix code and option are eliminated. + +24. - Fri 21 May 1993 - +vdu.h, vduinterface.c, dvitovdu.c : + For each VDU, the value "vdu_clears_lines" is set true if the VDU + can clear a single line. The "ncsatel" driver cannot, due to a + property of the Tek4010 terminal and (I suppose) its emulators. + So, for the "ncsatel" vdu, when the Status lines should be updated, + the whole display is now updated. + +25. - Sun 23 May 1993 - +userguide.tex, sysguide.tex, guidemacs.tex : + Updated Andrew Trevorrow's documentation to reflect Ian Dall's port + of DVItoVDU to C and features of dvgt 3.5. + +26. - Mon 24 May 1993 - +In all files that used "__((void))" : + In "config.h", VOID is defined as "void" for ANSI C, empty otherwise. + All function and function pointer declarations and definitions + that used "__((void))" now use "(VOID)" instead. + This helps "tags" and "ctags" programs to identify functions + correctly. (It also marginally reduces source code size.) + +27. - Tue 25 May 1993 - +options.c : + Fixed "-r" option to interpret "-r x,y" to set the X and Y resolutions + to x and y respectively. Retained "-r x" to set the X and Y resolutions + to the common value x, and "-r" to display the default resolutions. + +28. - Tue 25 May 1993 - +defaults.h, options.c: + Renamed the constant DEF_HELP_FILE to DEF_CMD_HELP, + and renamed the environment variable DV_HELP to DV_CMD_HELP. + +29. - Tue 25 May 1993 - +defaults.h, options.c, fontreader.c : + Fall back to dummy TFM, in case dummy PK not found. + Added env. var. DV_DUMMY_TFM. + Renamed DV_DUMMYFONT to DV_DUMMY_PK. + +30. - Wed 26 May 1993 - +options.c, defaults.h : + Added DV_PAPERWD and DV_PAPERHT env. vars. + These and DEF_PAPERWD and DEF_PAPERHT now accept dimensions, + else they default to inches. + +31. - Wed 26 May 1993 - +defaults.h, options.c : + Renamed DEF_IMMEDIATE_HELP to DEF_IMMED_HELP. + +32. - Wed 26 May 1993 - +dvgt/help directory: + Renamed "help" file to "cmd.help". + +33. - Sun 30 May 1993 - +defaults.h, options.c : + Renamed DEF_XRESOLUTION to DEF_XRES and DEF_YRESOLUTION to DEF_YRES. + Renamed DEF_PSPREFIX to DEF_PS_PREFIX. + +34. - Sun 30 May 1993 - +options.c : + Resolution option "-r" now allows one or two ("xres,yres") arguments. + Added DV_RES environment variable for both X and Y resolutions. + Renamed env. var. DV_PSPREFIX to DV_PS_PREFIX. + +35. - Mon 31 May 1993 - +dvireader.h, fontreader.c, dvitovdu.c : + Added "honest" field to "fontinfo" structure. This records whether + the true font (for the given fontname) is specified in the fontspec. + Now have "psfont", "pkfont" and "honest" fields to guide treatment + of fonts and their description by ShowStatistics. + +36. - Mon 31 May 1993 - +dvitovdu.c : + ShowStatistics shows either "H" or "S", and either "P" or "K" or "T", + to indicate whether the font used is Honest or a Substitute, and + whether it is a PostScript font TFM, a PK font bitmap, or a + non-PostScript TFM, respectively. + ShowStatistics also shows fontsize (in pt), and the font description + is more compact, to allow for the extra info. Attempted to align + lines of info. for different fonts. + +37. - Mon 31 May 1993 - +fontreader.c : + Font search order is now: + PK -> PS -> TFM -> dummy PK -> dummy TFM -> fail. + +38. - Mon 31 May 1993 - +dvitovdu.c : + Added time info (ANSI C only), to logfile. + +39. - Tue 1 June 1993 - +dvgt/src and dvgt directories: + Moved CHANGES and TODO files from dvgt/src to dvgt directory. + +40. - Tue 1 June 1993 - +dvitovdu.c : + Default Left, Right, Up and Down movements are by _half_ the window + dimension (instead of by the full dimension). + +41. - Tue 1 June 1993 - +dvitovdu.c : + Zoom In/Out to/from Centre of window (instead of Top Left corner). + +42. - Wed 2 June 1993 - +fontreader.c : + Multiple PS font prefixes, separated by same characters (in DIRSEP) + as (PK and TFM) directories. In dvgt 3.5, which is for unix, + DIRSEP = ":", a colon. + +43. - Thu 3 June 1993 - +fontreader.c, dvitovdu.c : + Font search is now: + PK -> PS -> dummy PK -> TFM -> dummy TFM -> DVI Terse. + So, if no other representation can be found, then a missing font + is guesstimated using the design size in the DVI file, and displayed + as in Terse mode. Other fonts are unaffected. + Currently, I estimate character size in design size units as 1 unit + high and 0.5 unit wide. This seems not too far off-mark for normal + text; preview of "example.dvi" is too wide by about one part in + eight. + (Another possibility, allowed by the DVI Standard, Level 0, is to + ignore such fonts entirely, but that would give the user less + information.) + +44. - Fri 25 June 1993 - +options.h, options.c, fontreader.c, dvitovdu.c : + C variable "fontdir" renamed to "pkdir". + +45. - Mon 19 Jul 1993 - +help and src directories: + Updated cmd.hlp, immed.hlp, options.hlp, and help.h, for dvgt 3.5's +commands, options, and VDU types. + +46. - Wed 21 Jul 1993 - +doc directory: + Updated sysguide.tex, userguide.tex to reflect dvgt 3.5's options +and commands. + +47. - Wed 21 Jul 1993 - +version.h, dvitovdu.h, help.h : + Renamed C quantity "version" to "dvgt_version", because of clash +with an enumerated type of the same name in System V's . + +48. - Wed 21 Jul 1993 - +dvitovdu.c : + Renamed C static variable "signals" to "common_signals", in case of +a clash, and eliminated the "extern int signals" line. + +49. - Wed 21 Jul 1993 - +Makefile.dvgt : + Added "regisvdu.h" to list of files to distribute. (Bad oversight!) + +50. - Wed 21 Jul 1993 - +fontreader.c : + Changed test of the boolean function OpenFontFile from the +erroneous "< 0" to the correct test for true. + +51. - Wed 21 Jul 1993 - +Makefile.sun : + Removed references to site specific include directories. + +52. - Mon 2 Aug 1993 - +unixio.c : + In non-BSD OS's, used TCGETA, TCSETAW with ioctl. + (Suggested by Guy Harris.) + +53. - Mon 2 Aug 1993 - +unixio.c, Makefile.aix, Makefile.sun : + Used "string" in unixio.c; so add dependency on "globals.h". + +54. - Mon 2 Aug 1993 - +src/dvitovdu.c, doc/userguide.tex : + Reverted to ZI, ZO holding window's top left; +introduced ZCI, ZCO to hold window's centre. + +55. - Tue 3 Aug 1993 - +screenio.c : + MesgLine now unsets raw mode, if it's on (so that NL -> CR+NL), +and finally restores it, if it was. + +56. - Tue 3 Aug 1993 - +doc directory : +sysguide.tex, userguide.tex updated. + +57. - Tue 3 Aug 1993 - +dvitovdu.c : + Defer call to InitScreenIO, so that "fprintf (stderr, ...);" will +have the normal line discipline. + +58. - Wed 4 Aug 1993 - +dvitovdu.c, dvireader.c, options.c, vdu.c : + Delete old DEBUG code that wrtes to stderr. + +59. - Wed 4 Aug 1993 - +unixio.c, unixio.h, screenio.c : + Separate initial and temporary tty state. + +60. - Wed 4 Aug 1993 - +dvitovdu.c, dvireader.c, (fontreader.c), (options.c), vdu.c : + Ensure that RestoreTerminal is called immediately before each exit. + +61. - Wed 4 Aug 1993 - +options.c : + In DimenPixels, account for unimplemented unit, in the newer code. + +62. - Wed 4 Aug 1993 - +dvitovdu.c : + In main, save initial terminal settings, early, using save_init_tty. + +---------------------------------------------------------------------- +RELEASE of dvgt 3.5 to SHSU (hence to CTAN). +---------------------------------------------------------------------- + +63. - Mon 16 Aug 1993 - +new.h : + Deleted #ifndef Malloc ... #endif around #include "config.h" . + Replaced #ifdef __STDC__ by #ifdef HAS_STDLIB . + +64. - Mon 16 Aug 1993 - +config.h : + Big rearrangement and recoding, to allow for an ANSI compiler (eg, +gcc) with a non-ANSI library (eg, Sun/OS 4.0 's BSD-like cc library). + Added #include and #include for when +BSD is true. + Also for when BSD is true, added twelve further (non-ANSI style) +function declarations. + Added also for non-BSD library with non-ANSI +compiler. + Now #define GNUC_LIB if and only if ANSI compiler with non-BSD +library. + +65. - Tue 17 Aug 1993 - +options.c : + Moved #define NEW_DIMEN_PIXELS to top of file. + Deleted inclusion and getenv() declaration, as config.h +already handles those. + Added code to protect (eg, ANSI C compilers') use of constant +storage for strings from Sun/OS 4.0 's library's sscanf function's +use of ungetc. + Added ToLower debugging code. + Changed definition of ToLower to always check for isupper. + Deleted block from around ToLower and Luname. + +66. - Tue 17 Aug 1993 - +Makefile.cc-sun : + New Makefile for Sun/OS 4.0 's non-ANSI compiler, "cc". + Mentions dependency on and . + +67. - Wed 18 Aug 1993 - +dvitovdu.c, dvireader.c : + SetConversionFactor's magnification argument now has the +interpretation that 1 corresponds to the document's normal size. +Non-ANSI compilers don't convert int mag to double magnification, +so dvitovdu.c now calls SetConversionFactor with its magnification +argument = mag/1000.0, to coerce it to be double. + +68. - Wed 18 Aug 1993 - +options.c : + Deleted ToLower debugging code. + +69. - Wed 18 Aug 1993 - +config.h : + Deleted "#include " from STDC, non-BSD case, because it +duplicated that in the general non-BSD case. + +70. - Wed 18 Aug 1993 - +version.h : + Version upped to "3.51". + +71. - Wed 18 Aug 1993 - +Makefile.gcc : + New. (Based on gcc code in old "Makefile.sun".) + +72. - Wed 18 Aug 1993 - +Makefile.sun : + Now refers only to Sun's "cc" compiler. + Deleted comments referring to , and . + +73. - Fri 20 Aug 1993 - +options.c : + PK search now = TEXPKS || PKFONTS || TEXFONTS || DEF_PK_DIR. + +74. - Fri 20 Aug 1993 - +new.h : + Deleted code, because "config.h" already handles that. + +75. - Fri 20 Aug 1993 - +TODO : + Added wish to "Make TFM, PK path and file spec. strings dynamic." + +76. - Fri 20 Aug 1993 - +Makedist.dvgt : + Added line for "dvgt/src/Makefile.gcc". + +77. - Fri 20 Aug 1993 - +README : + Refer to Makefile.gcc; change description of Makefile.sun. + +78. - Fri 20 Aug 1993 - +Makedist.dvgt : + Added "sane" Bourne shell script for resetting terminal, in case +dvgt leaves it seriously messed up. + +79. - Fri 20 Aug 1993 - +misc/stdlib.h : + Emended non-ANSI function declarations. + Added headlines with date. + +80. - Wed 25 Aug 1993 - +README, userguide.tex : + Updated for dvgt 3.51, specifically the use of TEXPKS. + +---------------------------------------------------------------------- +dvgt 3.51 : 3 mod 5 revision 1. +---------------------------------------------------------------------- + diff --git a/dviware/dvgtk/doc/Makefile b/dviware/dvgtk/doc/Makefile new file mode 100644 index 0000000000..58e0c10bbe --- /dev/null +++ b/dviware/dvgtk/doc/Makefile @@ -0,0 +1,24 @@ +# Makefile for DVItoVDU documents. 18:56 Tue 11 May 1993. Geoffrey Tobin. + +.tex.dvi: + tex $< + +dvi: guidemacs.tex example.dvi sysguide.dvi tripvdu.dvi userguide.dvi + +# AIX make is not very smart: it cannot follow the .tex.dvi line. +# Sun/OS make has no trouble. + +example.dvi: example.tex + tex example + +sysguide.dvi: guidemacs.tex sysguide.tex + tex sysguide + +tripvdu.dvi: tripvdu.tex + tex tripvdu + +userguide.dvi: guidemacs.tex userguide.tex + tex userguide + +clean: + rm *.dvi *.log diff --git a/dviware/dvgtk/doc/README b/dviware/dvgtk/doc/README new file mode 100644 index 0000000000..3d7c29fbf5 --- /dev/null +++ b/dviware/dvgtk/doc/README @@ -0,0 +1,426 @@ +README - 18:22 GMT +10:00 Wed 25 August 1993 - Geoffrey Tobin. +- for "dvgt 3.51", + alias: "DVItoVDU version 3.0, gt modification 5 revision 1". + +Addresses: ecsgrt@luxor.latrobe.edu.au + gt@ee.latrobe.edu.au + + +DVItoVDU, also known as "dvitovdu", "dvi2vdu", and "dv", is a public +domain screen previewer for TeX DVI files using PK fonts. It was +invented long ago by Andrew Trevorrow (author also of OzTeX, a TeX +for Macintoshes), and has passed through several hands since. + +"dvgt" is a modification of Ian Dall's "dv" (a C translation of a +Pascal (or Modula-2 ?) version of DVItoVDU 3.0). Some bug fixes have +been applied, and the source has been ported to the IBM Risc/6000 +under AIX using the "xlc" compiler. It is also compilable on Sparc 1 +workstations under Sun/OS using the Gnu C compiler, "gcc", and may +- perhaps with minor changes - also compile under some traditional +(Kernighan and Ritchie, _The C Programming Language_, first edition) +C compilers. + +This previewer is neither sophisticated nor pretty, but it can drive +a number of common visual display terminals, such as VT series, Gigi, +Regis, VK100, VIS series, and terminals that emulate Tek4010. (Not a +real Tek4010, sadly.) A full list of supported terminals is contained +in the immediate help file, "immed.hlp", and in the "options.hlp" +document. + +** Currently, those who wish to use a Tek4010 emulation are advised +to try the terminal types kermit, ncsatel, tek4010, vis500, vis550, +vis630 or vt640. ** + +I first used dvgt on a Sun Sparc 1 to preview DVI files in Terse mode +(like ascii) on a remote vt220 terminal. Now I use its "ncsatel" +driver (coutesy of Vijay, vijay@ncst.ernet.in, in India) to view in +Full (graphics) mode on a PC connected over NCSA Telnet to the dvgt +host machine, using Tek4010 emulation. The Tek4010 emulation drivers +kermit, ncsatel and tek4010 also work with MS-Kermit 3.12. + + +NOTE WELL: + +1. Current directory (and upper-level file) structure is: + + Makefile.dvgt dvgt/ + CHANGES README TODO doc/ help/ misc/ src/ + +The documents in doc/ are based on Andrew Trevorrow's Modula-2 version, +but they now have been updated for dvgt 3.5. Not every version +of DVItoVDU has the full collection of documents. Hopefully, they're +all gathered here. If not, please lead me to any omitted files. + +The single file in the misc/ subdirectory, "stdlib.h", is inherited +from Ian Dall's version. It's there in case someone wishes to port to +a system that lacks a suitable header for the C standard library. +However, it's not needed for either the AIX or the Sun/OS port. + +2. The "src" source directory's Makefile must be correct for your +machine, operating system and compiler. + +Three Makefiles are provided: + + Makefile.aix for IBM machines (such as the Risc/6000) running AIX. + Makefile.gcc for gcc (tested on Suns and Sparcs running Sun/OS 4 and 5). + Makefile.sun for Suns and Sparcs running Sun/OS, with Sun's non-ANSI cc. + +These can serve as templates for other Makefiles. (I made the AIX and +gcc ones from the Sun Makefile.) + +Copy the appropriate one to "Makefile", then edit it to suit your +site. + +3. The source header "defaults.h" needs to be customised for each site, +as it contains absolute directory information. (Even though these +paths may be overridden by environment variables, it's more convenient +if they point to where the system manager puts the appropriate files.) + +(The files "dvitovdu.c" and "options.c" include "defaults.h".) + +4. The source header "config.h" also needs attention. + +Especially be sure that either LITTLE_ENDIAN or BIG_ENDIAN is defined +correctly for your machine, and remember that if you define both, then +LITTLE_ENDIAN will prevail. + +(The C source files use "config.h". Also, "unixio.h" assumes that +"config.h" has been read before it.) + +5. In setting the environment variables on the system, or on your own +account, be careful to set them sensibly. I once set DV_IMMED_HELP to +point to a directory by mistake, and when I typed just "dvgt", instead +of getting immediate help, I saw a line consisting of leading spaces +and a dot. + +The C shell script, "dv-env", in the src directory, is a sample for +setting dvgt's environment variables. + +6. Note that page drawing can (as in the original dvitovdu) be +interrupted by a carriage return, but only _between_ characters and +rules. A very large character or rule won't be interrupted, even +though this means waiting for some time. + +7. To get the best appearance for dvgt's output when using it over +MS-Kermit 3.12, set the following in your MSCUSTOM.INI : + + set terminal flow-control none + set terminal graphics character-writing opaque + set terminal graphics cursor off + +The first line gets rid of most of the ^S and ^Q characters that may +otherwise appear on the dvgt command line. The second causes message +lines to overwrite opaquely, which makes the messages in certain +drivers much more readable. The third renders the graphics cursor +invisible. + +Because one ^S^Q pair still remains on my command line when I use +MS-Kermit 3.12, despite the above precaution, I've made the ^Q and ^S +characters into no-op commands in dvgt. + + +BRIEF HISTORY. + +The initial C code for this version of DVItoVDU was copied from Ian +Dall's site, augean.oz.au : pub/misc/dv.tar.Z. Ian had, as his source +code seems to indicate, automatically translated it from Pascal. +(Andrew Trevorrow wrote the original DVItoVDU in Modula-2.) + +A thorough history of the various versions of "dvitovdu", "dvi2vdu", +and "dv" in the world is beyond the scope of this README file, and +exceeds my competence. + +Version 3.4 was the first public release of dvgt. It was uploaded to + + Niord.SHSU.edu + +and subsequently propagated to the CTAN sites: + + ftp.shsu.edu + ftp.tex.ac.uk + ftp.uni-stuttgart.de + + +SUMMARY of CHANGES to dvitovdu 3.0 in the "gt" MODS up to "mod 5". + +1. Commands. + +U (Up), D (Down), L (Left) and R (Right) now move by half a screen +(instead of a full screen), to retain more context. + +The zoom commands, ZI and ZO, now take an optional argument, the zoom +factor. The initial default zoom is 2. When a new zoom factor is +specified, that becomes the new default value. This value is +displayed at the far right in the top line of the screen. + +Whereas ZI and ZO maintain the top left of the window stationary, +ZCI and ZCO zoom in and out relative to the window's centre. +These have very nearly the same effects as DR ZI UL and DR ZO UL, +respectively. + +Two new units commands, BP for big point, and SP for scaled point, +have been added, because TeX has these, and because big point +(1/72 inch) is the American standard point, used by PostScript. + +Units are now set by the C command, which allows zero or more +spaces between it and the following unit. For example: + + C IN + CMM + C PX + +The < and > commands have been deleted, in favor of N always paging +forwards, and P paging back. + +The T (Terse), B (Box), F (Full) are now toggles, and any combination +of these can be applied simultaneously. If all are off, then font +characters will not show, but rules will. + +The A (Auto window scaling) command has been made a toggle. +A+ and A- no longer exist. + +Control-L (^L, ascii character 12 decimal, 14 octal, C hexadecimal) +is a new command to refresh the page. The usual command line parsing +still applies, so the page is not refreshed until after a carriage +return is typed. + +Control-Q (^Q) and Control-S (^S) do nothing. + +2. Help. + +There are now three help files, "cmd.hlp", "immed.hlp" and "options.hlp". + +If dvgt can find "immed.hlp" - ie, if the environment variable +DV_IMMED_HELP points to it - then a novice user, who types simply "dvgt" +on the command line, will see "immed.hlp" displayed. Otherwise, the +file listed in "defaults.h" as "IMMEDIATE_HELP", is displayed. If +even that cannot be opened, then the precompiled message from "help.h" +is shown - this is intended to be very similar to "immed.hlp". + +Also, if a command line option is typed without an argument, as, eg, +"dvgt -f", then dvgt will describe the option. Another example is +"dvgt -i", which has no valid argument, and prints out the current +pathname of the immediate help file. + +Once in the program, the command "?" as before, will display the +"cmd.hlp" file, which has been updated because of the changes to the +commands. If that file cannot be found, then the precompiled command +help text is displayed. + +The file "options.hlp" is an expanded version of "immed.hlp", to +describe the options more fully. dvgt does not read "options.hlp": +the user is directed to do that for her/himself. + +3. Environment Variables and Command Line Options. + +There are now a variety of environment variables that the installer of +the program is supposed to set before dropping "dvgt" on the poor users. +Otherwise, the user must specify options to "dvgt" to override defaults. +Here is a table (not in TeX, as this is a README file). + + +Option Program Environment Constant in Purpose + Variable Variable "defaults.h" + + -H hoffset --- --- Horizontal page offset, + in given units. + + -V voffset --- --- Vertical page offset, + in given units. + + -d dummy_pk DV_DUMMY_PK DEF_DUMMY_PK Dummy PK font, used when + correct font's absent. + + -e dummy_tfm DV_DUMMY_TFM DEF_DUMMY_TFM Dummy TFM, used when + correct TFM's absent. + + -f pkdir TEXPKS DEF_PK_DIR PK fonts' directory. + else + PKFONTS + else + TEXFONTS + + -h cmd_help DV_HELP DEF_CMD_HELP Help file for "?" command. + + -i immed_help DV_IMMED_HELP DEF_IMMED_HELP Give help at startup. + + -l landscape --- --- Landscape page dimensions. + + -m mag --- --- Magnification. + + -p psprefix DV_PSPREFIX DEF_PS_PREFIX Prefix in PS font names. + + -r xres, DV_RES DEF_XRES, X and Y resolutions, + yres DEF_YRES in dots per inch (dpi). + + -t tfmdir TEXFONTS DEF_TFM_DIR TFM metric files' directory. + + -v vdu DV_TERM --- Terminal type. + else + TERM + + -x paperwd DV_PAPERWD DEF_PAPERWD Paper width, + in given units. + + -y paperht DV_PAPERHT DEF_PAPERHT Paper height, + in given units. + + +Command line options override environment variables, which override +the constants in "defaults.h". + +TEXPKS (as used by Rokicki's dvips) is used for the PK fonts +directory, but if it is absent, then PKFONTS is used; if that is +also absent, then TEXFONTS is used. + +Since TERM is usually set in every users' account, there is no +hard-wired value for the terminal in "defaults.h". Often, however, +for example when using NCSA Telnet for viewing, it is necessary to +have a different terminal type for dvgt than for the regular screen +mode; to avoid confusion, dvgt will use the terminal type given in the +environment variable DV_TERM (if it exists) in preference to that in +TERM. + +4. Terminal names. + +The vdu names `kermit', `ncsatel' and `tek4010' are synonyms for the +NCSA Telnet driver. + +5. Bitmaps. + +Dynamic memory allocation of bitmaps replaces the old static +allocation. Small glyphs now require little memory, and huge glyphs +(such as those in mfpic(*) picture fonts) can be viewed. + +(*) Mfpic is a macro package by Thomas Leathrum (moth@dartmouth.edu) +to enable TeX to draw graphics using MetaFont. Such graphics are +viewable by almost any TeX DVI previewer. + +6. PK and TFM multiple path searching. + +Multiple paths have been implemented for TFM and PK file directories +under unix. For instance, + + .:/usr/local/lib/tex/fonts + +will seek the TFM files in the current directory, and then in the +directory /usr/local/lib/tex/fonts (where they are found on a +significant number of systems). This enables the regular TEXFONTS +environment variable (if used for TeX) to be employed for dvgt. + +Similarly for PK fonts (env. vars. TEXPKS, PKFONTS), though less +flexibly as subdirectory searching is not implemented in dvgt 3.5 and +TeX installations can differ markedly in how they place PK fonts. + +7. Font substitution strategy. + +When a font is missing, dvgt 3.5 tries each of several replacements +in turn. Briefly: + + PK -> PS -> dummy PK -> TFM -> dummy TFM -> DVI Terse. + +In words, if the correct PK bitmap (plus or minus one dot per inch in +its resolution) is found, then that is used. + +Otherwise, if the font is identified as a PostScript font (using the +list of PostScript prefixes) and the correct TFM is found, then +display the TFM bounding boxes (in outline - previous versions used +solid blocks). + +If that fails, then display the dummy PK font, provided that it can +be found. + +Otherwise, try the correct TFM metric file. + +If that is missing, then seek the dummy TFM metric file. + +If nothing else succeeds, then use the font's scaled size from the +DVI file, assuming heights equal to the scaled size and widths of half +the scaled size. Display the characters of such a font in Terse mode. +(Other fonts are unaffected.) + + +FILE TIMES and DATES. + +The times and dates in the various files of this distribution are the +modification times of those files. "GMT" signifies Greenwich Mean +Time, and "GMT +10:00" means ten hours in advance of GMT. In the +absence of "GMT", the time is local to Melbourne, Victoria, Australia. + + +ACKNOWLEDGMENTS. + +Andrew Trevorrow, for developing DVItoVDU, which has stood the test of +time. + +Masahiro Kitagawa (kitagawa@will.ntt.jp), for inventing the Japanese +versions 1.0J and 1.1J, for encouraging me in this work, and for much +advice, including the original recommendation of Ian Dall's port, of +which I was hitherto oblivious. Also for reporting user-hostile +deficiencies in dvgt's error handling. + +Ian Dall, for porting version 3.0 to C. + +The many others who have enhanced, ported and otherwise improved +one branch or another of DVItoVDU's family tree over the years. + +Guy Harris and Dave Curry for each pointing out a bug in the System +Vr4 and Solaris code of `unixio.c'. + +The patient testers, many of whom are still waiting for code that will +drive a true Tek4010 graphics terminal or a VGA monitor, and one or +two other things. I wish I could have delivered these features, but +my Winnie-the-Pooh brain was sorely taxed by trying to make sense of +AIX's C compilers (cc, c89, xlc), not to mention the differing header +files and object libraries on BSD and System Vr4 and hybrids thereof. + +If it's any consolation to those who're missing a desired feature, +Masahiro wrote to me that "dvgt" (since version 3.4) works fine with +Japanese text. + +La Trobe University Computer Services and the Department of Electronic +Engineering, for providing the resources by which DVItoVDU became +dvgt, and dvgt has been maintained. + +The archivers, who kindly donated machine resources and their own +time and effort, to provide a place for this software to rest. +Without their generosity, many of you would not be reading this. + +IBM, for inventing the Risc/6000. AIX? Well, it's a long story ... + + +PLEAS. + +Suggestions for improvements of "dvgt" are welcome. +So is practical advice. Here is a brief wish list for enhancements +which are beyond my current reach. + +1. If you know how to drive a true Tek4010 terminal (copy from +Gnuplot?), and would can implement this in dvgt, you may make at least +one other user happy. + +2. An EGA/VGA driver that functions over MS-Kermit or Telnet would be +very helpful! I was told that (part of) the driver must reside on the +PC, but TSRs and such are out of my league. + +3. Someone with a strong stomach might attempt to make the data +structures more "object-oriented", I mean "easy to modify correctly". +Tread _very_ carefully! + +4. Make dvgt fully conformant with the TUG DVI Driver Standard, +wherever appropriate. + +5. Also see the "TODO" file. + + +DISCLAIMER. + +dvgt is _not_ conformant with the TUG DVI Driver Standards Committee's +_DVI Driver Standard, Level 0_, for ``minimally functional'' DVI +processors, although I have a copy of draft 0.5 of that document +(from CTAN). [See if you can spot the differences: some of them are +flagged in the source code.] + + +All the Best! +Geoffrey Tobin diff --git a/dviware/dvgtk/doc/TODO b/dviware/dvgtk/doc/TODO new file mode 100644 index 0000000000..5b15511436 --- /dev/null +++ b/dviware/dvgtk/doc/TODO @@ -0,0 +1,36 @@ +TODO - for dvgt 3.5 - 21:22 GMT +10:00 Fri 20 August 1993 - Geoffrey Tobin. + +1. Subdirectory searching? + +2. Scale substitute PK and TFM files (like zoom, but restricted to + one font), to match the scaled size of the missing font. + +3. More VDU drivers. + +4. Allow an output character recoding file? + That might be useful where the glyph encoding differs from ascii, + or, more generally, from the encoding of the display. + One way would be pairs of (hexadecimal?) integers. + Might allow "D" for decimal, "C" for ascii character, + "X" for hexadecimal, and "O" for octal, as in Knuth's TFM files. + Default would be which `number system'? + + To Terse mode, add a user-definable glyph encoding? + (Currently uses an encoding based on cmr10.) + Employ a character recoding file, which the user could alter? + + Virtual Fonts? + A fanciful dream, that one. + +5. Macros? + +6. String Search in the DVI file. + +7. Conform dvgt to TUG's DVI Driver Standard, Level 0, at least more + nearly. + +8. Choose different DVI files interactively? + +9. Make TFM, PK path and file spec. strings dynamic. + +Geoffrey Tobin diff --git a/dviware/dvgtk/doc/ansi2knr.1 b/dviware/dvgtk/doc/ansi2knr.1 new file mode 100644 index 0000000000..434ce8f042 --- /dev/null +++ b/dviware/dvgtk/doc/ansi2knr.1 @@ -0,0 +1,19 @@ +.TH ANSI2KNR 1 "31 December 1990" +.SH NAME +ansi2knr \- convert ANSI C to Kernighan & Ritchie C +.SH SYNOPSIS +.I ansi2knr +input_file output_file +.SH DESCRIPTION +If no output_file is supplied, output goes to stdout. +.br +There are no error messages. +.sp +.I ansi2knr +recognizes functions by seeing a non-keyword identifier at the left margin, followed by a left parenthesis, with a right parenthesis as the last character on the line. It will recognize a multi-line header if the last character on each line but the last is a left parenthesis or comma. These algorithms ignore whitespace and comments, except that the function name must be the first thing on the line. +.sp +The following constructs will confuse it: +.br + - Any other construct that starts at the left margin and follows the above syntax (such as a macro or function call). +.br + - Macros that tinker with the syntax of the function header. diff --git a/dviware/dvgtk/doc/example.tex b/dviware/dvgtk/doc/example.tex new file mode 100644 index 0000000000..858ad3b9bb --- /dev/null +++ b/dviware/dvgtk/doc/example.tex @@ -0,0 +1,232 @@ +% This is the TeX source file for the "TeXnical Typesetting" document. +% Notice how you can put in comments? If TeX sees a % it simply ignores +% the rest of the line. + +% A4 paper is 8.3in wide and 11.7in high; we set the page dimensions so that +% there are 1in margins all around: +\hsize 6.3in % page width +\vsize 9.7in % page height + +\parskip 8pt plus 2pt minus 1pt % glue before a paragraph + +% Define a few extra fonts for later use: +\font\bigrm=cmr10 scaled\magstep4 % big version of the standard roman font +\font\ninerm=cmr9 % 9pt roman +\font\fiverm=cmr5 % 5pt roman +\font\sm=cmcsc10 % caps and small caps +\font\ss=cmss10 % sans serif + +% Here's a macro that we'll use to produce all subheadings: +\def\subhead#1{\bigskip % extra glue before subheading + \noindent{\bf #1}\par % unindented boldface subheading + \nobreak} % prevent a page break after subheading + +\centerline{\bigrm \TeX nical Typesetting} + +\vskip 2.5cm % dimensions can be metric + +\subhead{What is \TeX?} + +\TeX\ (pronounced ``teck'') is a computerized typesetting system developed by +Donald Knuth and others at Stanford University. It is used to create +high-quality documents, particularly those containing mathematics. +The name \TeX\ is an uppercase form of the Greek letters $\tau\epsilon\chi$, +the first three letters of a Greek word meaning {\sl art} as well as +{\sl technology}. +The lowering of the ``E'' is a reminder that \TeX\ is about typesetting, +which can be thought of as the next stage beyond word processing. +On devices where such lowering is difficult or impossible you may see \TeX\ +written as {\tt TeX}. + +% the above blank line ends the first paragraph + +Most word processors allow you to +create and modify a document interactively --- what +you see on the screen is usually what your output will look like. +\TeX\ does {\it not} work in this way. +Like other typesetting systems (such as SCRIBE and +{\sl troff\/}), \TeX\ is known as a ``document compiler''. Using your +favourite text editor you need to create a file containing the +text of your manuscript along with the \TeX\ typesetting commands. +\TeX\ gives you the ability to produce printed matter with a quality +matching that found in books, depending on the output device. +Adelaide University has an {\sm imagen} laser printer +with a resolution of 240 dots per inch. +This publication shows both the capabilities of \TeX\ and +the output quality of the laser printer. + +\subhead{Fonts} + +One of the more obvious advantages of \TeX\ is the large range of fonts from +which you can choose. A font is a collection of characters each having a +similar size and style. Some of the fonts currently available include: +$$ % enter display math mode just to get space above and below \line +\line + {\hfil % infinitely stretchable glue + \rm roman\hfil \sl slanted\hfil \it italic\hfil \bf boldface\hfil + \tt typewriter\hfil \ss sans serif\hfil \sm small caps\hfil + } % take care to ensure each { has a matching } +$$ +Many of these also come in a variety of sizes: +$$ +\centerline{{\bigrm from the very big},~ % extra space after comma + {\ninerm to the very small},~ + {\fiverm to the ridiculous}.} +$$ +Apart from a large selection of mathematical symbols, +many special characters and accents are available: +$$ +\vbox + {\tabskip 10pt plus 1fil % glue before and after all columns + \halign to\hsize + {& \hfil#\hfil\cr % specify a variable number of centred columns + \copyright& \it\$& \S& \P& \dag& \ddag& + $\circ$& $\bigcirc$& % some symbols must be accessed from math mode + $\leftarrow$& $\rightarrow$& $\triangle$& $\clubsuit$& + \`a& \'e& \c c& \^o& \"u\cr + } + } +$$ +\TeX\ does a few subtle things automatically. +Certain sequences of characters in your text will +be replaced by {\sl ligatures} in the printed output (consider the ``{\tt ffi}'' +in ``difficult''), while other pairs of characters need to be {\sl kerned} +(e.g., the ``o'' and ``x'' in ``box'' look better if they are moved closer +together). The range and quality of fonts available will continue to improve. + +\subhead{Mathematics} + +A major design goal of \TeX\ was to simplify the task of typesetting +mathematics --- and to do it properly. Mathematicians will be pleasantly +surprised at the ease with which formulae and expressions can be created; +from simple in-line equations +such as $e^{i\pi}=-1$ and $f_{n+2}=f_{n+1}+f_n$, to more extravagant displays: +$$ +\sum_{k\ge1} \sqrt{x_k-\ln k}\quad\ne\quad +\int_{0}^\infty {e^{-x^3}+\sqrt{x} \over \left(123-x\right)^3} \,dx +$$ +\TeX\ looks after most of the nitty gritty details, such as spacing things +correctly and choosing the right sizes for superscripts, parentheses, +square root signs etc. (The discoverer of the above relation wishes to +remain anonymous.) + +\subhead{Alignment} + +The preparation of tabular material such as in lists and matrices can be a +tedious job for a person armed only with a typewriter and a bottle of +correction fluid. With a little help from \TeX, computers can make it so +much easier: +$$ +\vcenter % a vertically centred \vbox + {\tabskip 0pt % no space before column 1 + \halign to 3.5in % width of table + {\strut#& % col 1 is a strut + \vrule#\tabskip .5em plus2em& % col 2 is a vrule; also set col spacing + #\hfil& % col 3 is left justified + \vrule#& % col 4 is a vrule + \hfil#\hfil& % col 5 is centred + \vrule#& % col 6 is a vrule + \hfil#& % col 7 is right justified + \vrule#\tabskip 0pt % col 8 is a vrule; no space after it + \cr % end of the preamble + \noalign{\hrule} + & & \multispan5 \hfil Oldest players to represent\hfil& \cr + & & \multispan5 \hfil England in a Test Match\hfil& \cr + \noalign{\hrule} + & & \omit\hfil Name\hfil& & % \omit ignores template in preamble + \omit\hfil Age\hfil& & + \omit\hfil Versus\hfil& \cr + \noalign{\hrule} + & & W.Rhodes& & 52y 165d& & West Indies, 1930& \cr + \noalign{\hrule} + & & W.G.Grace& & 50y 320d& & Australia, 1899& \cr + \noalign{\hrule} + & & G.Gunn& & 50y 303d& & West Indies, 1929& \cr + \noalign{\hrule} + & & J.Southerton{\ninerm*}& & 49y 139d& & Australia, 1877& \cr + \noalign{\hrule\smallskip} + & \multispan7\ninerm* (This was actually his Test debut.)\hfil \cr + } + } +\hskip .5in % space between table and matrix +A=\pmatrix % parenthesized matrix + {a_{11}& a_{12}& \ldots& a_{1n}\cr + a_{21}& a_{22}& \ldots& a_{2n}\cr + \vdots& \vdots& \ddots& \vdots\cr + a_{m1}& a_{m2}& \ldots& a_{mn}\cr + } +$$ + +\vskip -\the\belowdisplayskip % avoid too much space below display + +\subhead{Other features} + +Space does not permit examples of all the things \TeX\ can do. Here are some +more features you might like to know about: + +\item{$\bullet$} +Multi-column output can be generated. + +{\parskip=0pt % temporarily turn off the skipping between paragraphs +\item{$\bullet$} +\TeX\ has a very sophisticated paragraph building algorithm and rarely needs +to resort to hyphenation. Paragraphs can be indented and shaped in many +different ways. + +\item{$\bullet$} +Automatic insertion of footnotes,\footnote{\dag}{\ninerm Here is +a footnote.} running heads, page numbers etc. + +\item{$\bullet$} +\TeX\ makes provision for generating a table of contents, a bibliography, even +an index. Automatic section numbering and cross referencing are also possible. + +\item{$\bullet$} +A powerful macro facility is built into \TeX. This lets you do some very +useful things, like creating an abbreviation for a commonly used phrase, or +defining a new command that will have varying effects depending on the +parameters it is given. A macro package can enhance \TeX\ by making it much +easier to generate a document in a predefined format. +\par % end the last paragraph BEFORE ending the group +} % \parskip will now revert to its previous value + +\subhead{What CAN'T \TeX\ do?} + +Complex graphics such as diagrams and illustrations pose +a major problem --- at the moment you have to leave an appropriate amount of +blank space and paste them in later. +Graphic facilities are the subject of current research. + +\subhead{\TeX\ and VAX/VMS} + +The \TeX\ source file used to generate this document is available for +inspection on any VAX node that has \TeX --- +just type `{\tt scroll tex\char'137 inputs:example.tex}'. +A few steps are needed to print such a file: + +\item{(1)} +Type `{\tt tex example}' to ``compile'' the file. +(\TeX\ looks for a {\tt .tex} file by default. If it can't find the given +file in your current directory it will look in {\tt tex\char'137 inputs}.) +Two new files will be created in your current directory: +{\tt example.dvi} and {\tt example.lis}. +The former is a device independent description of the document; +the latter is simply a log of the \TeX\ run. + +{\parskip=0pt % temporarily turn off \parskip +\item{(2)} +Type `{\tt dvitovdu example}' to preview the document on a terminal screen. +This program can be used to detect a variety of formatting problems, +saving both time and paper. + +\item{(3)} +Type `{\tt imprint example}' to print the document. +(Note that the DVIto\kern-.15em VDU and IMPRINT commands +accept a {\tt .dvi} file by default). + +} % restore \parskip + +Detailed help on all these commands is available on-line --- try typing +`{\tt help tex}' to get started. + +\bye diff --git a/dviware/dvgtk/doc/guidemacs.tex b/dviware/dvgtk/doc/guidemacs.tex new file mode 100644 index 0000000000..11f556ae9f --- /dev/null +++ b/dviware/dvgtk/doc/guidemacs.tex @@ -0,0 +1,105 @@ +% guidemacs.tex - 14:31 GMT +10:00 Sun 23 May 1993 - modifier Geoffrey Tobin. +% I don't have the original Andrew Trevorrow guidemacs. +% This will have to do. -- Ian Dall + +\def \dvgt {{dvgt 3.5}} +\font\bigbf=cmbx12 +\font\Bigbf=cmbx12 scaled \magstep1 +\font\title=cmbx10 scaled \magstep5 +\font\smallrm=cmr8 +\def \subhead #1{\bigskip\leftline{\Bigbf #1}\medskip} +\let \;=\unskip +\def \finishline{} +\parskip=10pt + + +% Macros for verbatim TeX (from MANMAC.TEX): +% After \inputing this file you can use the following macros: +% +% 1. || +% +% 2. \begintt +% +% \endtt +% +% 3. \begindisplay +% +% |text in \tt|& |text in \tt|& text in current font\cr +% \enddisplay +% +% 4. \listing{foo} +% foo.tex will be \input and set verbatim in \tt; \parskip must be non-zero +% if you want to see any empty lines + +\catcode`@=11 % borrow some PLAIN macros which use @ as a letter + +\newskip\ttglue +\ttglue=0.5em plus.25em minus.15em + +\chardef\other=12 +\def\ttverbatim{\begingroup + \catcode`\\=\other + \catcode`\{=\other + \catcode`\}=\other + \catcode`\$=\other + \catcode`\&=\other + \catcode`\#=\other + \catcode`\%=\other + \catcode`\~=\other + \catcode`\_=\other + \catcode`\^=\other + \obeyspaces \obeylines \tt} +{\obeyspaces\gdef {\ }} % active space = \ , not \space + +\outer\def\begintt{$$\let\par=\endgraf \ttverbatim \parskip=\z@ + \catcode`\|=\other + \rightskip-5pc \ttfinish} +{\catcode`\|=0 |catcode`|\=\other % | is temporary escape character + |obeylines % end of line is active + |gdef|ttfinish#1^^M#2\endtt{#1|dimen0=|hsize|advance|dimen0 by -|hangindent% + |hsize=|dimen0|vbox{#2}|endgroup$$}} +% \begintt ... \endtt will now work in a paragraph with \hangindent, such +% as an \item + +\catcode`\|=\active +{\obeylines \gdef|{\ttverbatim \spaceskip\ttglue \let^^M=\ \let|=\endgroup}} + +\catcode`@=12 % return @ its normal category of "other" + +% Macros for non-centered displays: +% Note that we turn \ttglue off so |stuff| spaces will all be equal. +\outer\def\begindisplay{\obeylines\startdisplay} +{\obeylines\gdef\startdisplay#1 + {\catcode`\^^M=5$$\ttglue=0em#1\halign to\hsize% +\bgroup\indent##\hfil\tabskip 0pt plus 1000pt&&\qquad##\hfil\cr}} +\outer\def\enddisplay{\crcr\egroup$$} + +% MACROS FOR VERBATIM LISTINGS (ADAPTED FROM TEXBOOK APPENDIX D, P380) + +\def\uncatcodespecials{\def\do##1{\catcode`##1=12 }\dospecials} + + +\def\setupverbatim{\tt % \lineno=0 + \def\par{\leavevmode\egroup\box0\endgraf} + \obeylines \uncatcodespecials \obeyspaces + \catcode`\`=\active \catcode`\^^I=\active + \everypar{ % \advance \lineno by1 \llap{\sevenrm\the\lineno\ \ } + \startbox}} +\newdimen\w \setbox0=\hbox{\tt\space} \w=8\wd0 % tab amount +% \newcount\lineno +\def\startbox{\setbox0=\hbox\bgroup} +{\catcode`\^^I=\active + \gdef^^I{\leavevmode\egroup + \dimen0=\wd0 % the width so far, or since the previous tab + \divide\dimen0 by\w + \multiply\dimen0 by\w % compute previous multiple of \w + \advance\dimen0 by\w % advance to next multiple of \w + \wd0=\dimen0 \box0 \startbox}} + +\def\listing#1{\par\begingroup\parindent0pt \parskip0pt + \vskip\baselineskip + \setupverbatim + \catcode`\|=\other % allow | in listing file + \input#1 + \vskip\baselineskip\endgroup} + diff --git a/dviware/dvgtk/doc/options.txt b/dviware/dvgtk/doc/options.txt new file mode 100644 index 0000000000..b913ebb1f9 --- /dev/null +++ b/dviware/dvgtk/doc/options.txt @@ -0,0 +1,139 @@ +dvgt is a version of the DVItoVDU interactive TeX page previewer. +The program allows you to look at TeX-generated DVI files on a variety +of commonly available VDUs. + +The "DVItoVDU User Guide", "userguide.tex", explains how to use the program. + +USAGE: dvgt filename[.dvi] + [-H x_offset] [-V y_offset] [-d dummy_pk] [-e dummy_tfm] + [-f pk_directory] [-h helpfile] [-i] [-l] + [-m magnification] [-p postscript_font_prefix] + [-r xres yres] [-t tfm_directory] + [-v vdu] [-x paperwd] [-y paperht] + +NOTE ON OPTIONS' DEFAULTS: + +All options have default values. +System dependent initial defaults are set at compile-time. +(Compilation note: these constants are set in the source file "defaults.h".) +Some defaults can be set by environment variables. +The command line options override the environment variables, which in +turn override the compiled initial defaults. + +BRIEF SUMMARY OF OPTIONS: + +-H horizontal_offset (default = 0.0 in) +-V vertical_offset (default = 0.0 in) +-l (set landscape mode, instead of the default portrait mode) +-m magnification (default = DVI file's intrinsic magnification) +-v vdu (default = value of the environment variable TERM) + + vdu may be one of: + + aed512 gigi kermit ncsatel regis tek4010 vis240 vis241 vis500 vis550 + vis603 vis630 vk100 vt100 vt100132 vt102 vt125 vt200 vt220 vt240 + vt640 + +The other options' default values are system dependent. +Try "dvgt -f", for example, to find the current default PK font directory. + +COMMAND OPTIONS: + +-H horizontal_offset (default = 0.0in) + +-V vertical_offset (default = 0.0in) + + TeX, by default, considers the top left corner of the printed page as + one inch below and one inch to the right of the physical page. So + does dvgt. The two offsets move this corner. Positive dimensions + move it downwards and rightwards; negative offsets are allowed. + +-d file (default is system dependent; environment: DV_DUMMY_PK) + + dvgt will warn you if your document uses a font at a non-existent size. + Rather than abort, it will load the PK font specified after -d and continue + so you can look for more errors. Paragraphs using this dummy information + are likely to have ragged right margins. + +-e file (default is system dependent; environment: DV_DUMMY_TFM) + + Default TFM file, similar to -d option. + +-f file (default is system dependent; environment: PKFONTS or TEXFONTS) + + dvgt gets all its font information from PK files. These files are + kept within the directory specified by this option. + +-h file (default is system dependent; environment: DV_HELP) + + The ? command reads the help text file specified by this option. + +-i (default is system dependent; environment: DV_IMMED_HELP) + + Display the path name of the immediate help file. + Typing "dv" by itself displays the immediate help file. + +-l + + Set landscape mode: exchange x and y dimensions. + (This does NOT rotate the page, sorry.) + The default is portrait mode. + +-m i (default = DVI magnification) + + This option allows you to replace the magnification used in the + DVI file with some other value; 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 using -m, + especially if your TeX source file uses \magnification AND true dimensions. + +-r x,y (default is system dependent) +-r x + + dvgt treats the imaginary sheet of paper on which a DVI page will + appear as a two dimensional array of tiny dots known as paper pixels. + x and y are positive floating point numbers that define the numbers of + pixels per inch in the horizonatl and vertical directions, respectively. + Their values should match the respective resolutions of the device that + will be used to print your document. + If only one value is given, then it is used as the resolution both + horizontally and vertically. + +-t tfm_directory (default is system dependent; environment: TEXFONTS) + + This sets the directory where dvgt will look for TFM (TeX Font + Metric) files, such as "cmr10.tfm". + +-v string (default = value of TERM) + + This option is used to tell dvgt what type of VDU you are using. + If TERM does not describe your VDU, you need to override the default value. + Typing `dvgt -v vis550 foo' will tell dvgt you're using a VISUAL 550. + The current version will accept the following strings + (in upper or lower case): + + aed512 (AED 512 with 512 by 512 screen) + kermit (same as ncsatel) + ncsatel (NCSA Telnet's Tektronix 4010 emulation) + regis (any ReGIS compatible VDU; synonyms = GIGI, VK100, VT125, VT240) + tek4010 (same as ncsatel) + vis240 (VISUAL 240; synonym = VIS241) + vis500 (VISUAL 500) + vis550 (VISUAL 550) + vis603 (VISUAL 603) + vis630 (VISUAL 630) + vt100 (any VT100 compatible VDU in 80 column mode; synonym = VT102) + vt100132 (any VT100 compatible VDU in 132 column mode) + vt220 (VT220 using down-loaded chunky graphics; synonym = VT200) + vt640 (VT100 with Retro-Graphics) + +-x dimen (default is system dependent) +-y dimen (default is system dependent) + + These two options define the width and height of the paper upon which your + document will be printed. Both values are specified as dimensions like + those used in TeX, but the units are restricted to BP, CM, IN, MM, PC, PT, + PX, or SP. PX is specific to dvgt, and represents one paper pixel. + Every time you select a page, dvgt will use these paper dimensions + to check that all printed material falls within the paper edges. 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 ||\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 |, perhaps at the top +of the source file, so you can find them easily, write |#define |. +Here || 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 diff --git a/dviware/dvgtk/doc/tripvdu.tex b/dviware/dvgtk/doc/tripvdu.tex new file mode 100644 index 0000000000..d8c3d25729 --- /dev/null +++ b/dviware/dvgtk/doc/tripvdu.tex @@ -0,0 +1,279 @@ +% TeX source file for creating TRIPVDU.DVI, a torture file for DVItoVDU +% (using the same philosophy as Donald Knuth's torture test for TeX). + +\nopagenumbers +\topskip 0pt +\parindent 0pt +\parskip 0pt + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 1 +% This page is completely empty but has some \special stuff. + +\message{Empty page.} +\null +\special{DVItoVDU should warn user that it is ignoring this stuff.} +\special{And this.} +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 2 +% This page has 1 black pixel at (0,0). + +\message{1 black pixel at (0,0).} +\hrule height 1sp width 1sp depth 0sp +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 3 +% This page will fill an A4 sheet with black pixels, assuming A4 paper is +% 8.3in by 11.7in and (0,0) is 1in from the top and left edges. + +\message{A4 sheet full of black pixels.} +{% change page size and location temporarily +\hsize 10in +\vsize 12in +\hoffset -1in +\voffset -1in +% Because ref pts of rules are at BOTTOM left corner we first need to output +% a rule that will guarantee Minv = -1in, then output the large rule with +% slightly less than A4 height. +\hrule height 1sp width 8.299in depth 0sp +\hrule height 11.695in width 8.299in depth 0sp +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 4 +% This page is 1 pixel wider than page 3. +% DVItoVDU should detect that page is too wide for A4 paper. + +\message{As above but 1 pixel too wide.} +\hrule height 1sp width 8.301in depth 0sp +\hrule height 11.695in width 8.301in depth 0sp +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 5 +% This page is 1 pixel longer than page 3. +% DVItoVDU should detect that page is too low for A4 paper. + +\message{As above but 1 pixel too low.} +\hrule height 11.701in width 8.299in depth 0sp +\vfil\eject + +}% reset page size and location + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 6 +% This page has a rulelist with a full ruletable (= 300 rules). +% Note that DVItoVDU does not impose any limits +% on the number of rules or characters in a page. Pages 6 to 9 +% test the list manipulating code in DVIReader and DVItoVDU. + +\message{Page with ruletablesize rules.} +\newcount\temp +\temp=300 +\loop\ifnum\temp>0 + \hrule height 1sp width \hsize % 1 pixel high + \vfil + \advance\temp by -1 +\repeat +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 7 +% This page has ruletablesize+1 rules (so rulelist has 2 nodes). + +\message{Page with ruletablesize+1 rules.} +\temp=301 +\loop\ifnum\temp>0 + \hrule height 1sp width \hsize % 1 pixel high + \vfil + \advance\temp by -1 +\repeat +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 8 +% This page has a charlist with a full chartable (= 3000 characters). + +\message{Page with chartablesize characters from one font.} +\font\small=cmr5 +{\small \offinterlineskip + \temp=30 + \loop\ifnum\temp>0 + \leftline{iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii + iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii} % 100 chars + \advance\temp by -1 + \repeat +} +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 9 +% This page has chartablesize+1 characters (so charlist has 2 nodes). + +\message{Page with chartablesize+1 characters from one font.} +{\small \offinterlineskip + \temp=30 + \loop\ifnum\temp>0 + \leftline{iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii + iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii} % 100 chars + \advance\temp by -1 + \repeat + \leftline{i} % the extra character +} +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 10 + +\message{Multiple TeX page counters.} +\footline={\hss\tenrm\folio\hss} % turn on page numbers +\pageno=0 +\count1=1 \count2=2 \count3=3 \count4=4 \count9=9 +\noindent +This is \TeX\ page [0.1.2.3.4.....9]. +\vfil\eject + +\count1=0 \count2=0 \count3=0 \count4=0 \count9=0 % reset TeX counters + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 11 + +\message{Negative TeX page.} +\pageno=-11 +\noindent +This is \TeX\ page [-11]. +\vfil\eject + +\pageno=12 % DVI page = TeX page again +\nopagenumbers % turn off page numbers again + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 12 +% This page has characters from many fonts. +% Note that the page is off the right edge of A4 paper. + +\message{Page with characters from many fonts.} +% avoid redefining plain TeX's \i, \j etc. +\font\Fb=cmr5 +\font\Fc=cmr5 scaled\magstep5 +\font\Fe=cmr10 scaled\magstep5 +\font\Fg=cmbx10 +\font\Fh=cmbx10 scaled\magstep5 +\font\Fj=cmsl10 +\font\Fk=cmsl10 scaled\magstep5 +\font\Fm=cmtt10 +\font\Fn=cmtt10 scaled\magstep5 +\font\Fo=cmss10 +\font\Fp=cmcsc10 +\font\Fq=cmdunh10 + +\leftline{\Fb These characters are from CMR5 at mag 1000.} +\leftline{\Fc These characters are from CMR5 at mag 2488.} +\leftline{\tenrm These characters are from CMR10 at mag 1000.} +\leftline{\Fe These characters are from CMR10 at mag 2488.} +\leftline{\Fg These characters are from CMBX10 at mag 1000.} +\leftline{\Fh These characters are from CMBX10 at mag 2488.} +\leftline{\Fj These characters are from CMSL10 at mag 1000.} +\leftline{\Fk These characters are from CMSL10 at mag 2488.} +\leftline{\Fm These characters are from CMTT10 at mag 1000.} +\leftline{\Fn These characters are from CMTT10 at mag 2488.} +\leftline{\Fo These characters are from CMSS10 at mag 1000.} +\leftline{\Fp These characters are from CMCSC10 at mag 1000.} +\leftline{\Fq These characters are from CMDUNH10 at mag 1000.} +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 13 +% This page has characters from many fonts, some of which have no corresponding +% PXL file. DVItoVDU should warn user about non-existent font files and +% continue as best it can by loading dummy font info. +% Note that the page is off the right edge of A4 paper. + +\message{Page with characters from fonts at unknown magnifications.} +% PXL files do not exist at the requested magnifications: +\font\Fr=cmr5 scaled 500 +\font\Fs=cmr5 scaled 3000 +\font\Ft=cmr10 scaled 200 +\font\Fu=cmr10 scaled 5000 +\font\Fv=cmsl10 scaled 200 +\font\Fw=cmsl10 scaled 10000 + +\leftline{\Fr CMR5 at mag 500 does not exist.} +\leftline{\Fb These characters are from CMR5 at mag 1000.} +\leftline{\Fs CMR5 at mag 3000 does not exist.} +\leftline{\Ft CMR10 at mag 200 does not exist.} +\leftline{\tenrm These characters are from CMR10 at mag 1000.} +\leftline{\Fu CMR10 at mag 5000 does not exist.} +\leftline{\Fv CMSL10 at mag 200 does not exist.} +\leftline{\Fj These characters are from CMSL10 at mag 1000.} +\leftline{\Fw CMSL10 at mag 10000 does not exist.} +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 14 +% This page has a paragraph illustrating most of the characters from the +% standard roman TeX text font. + +\message{Standard paragraph.} +\rm +Our task is to create a paragraph illustrating what a typical piece of text +looks like in the standard \TeX\ font. It should be stressed that not all +\TeX\ fonts can be used for typesetting text. We need to show most of the +characters in this font---for instance, something like ``the quick brown fox +jumps over a lazy dog'' would use all the lower-case letters. Hmmm \dots\ +how about ``THE QUICK BROWN FOX JUMPS OVER 9876543210 LAZY DOGS'' to make +sure we show all the upper-case letters and digits? Such a paragraph would +hardly be typical! Then there's ligatures (try and fit in words like +fluffy, waffle, firefly, difficult) and examples of kerning (boxer, cooked, +vowel). Not to mention the various accents and other special letters: +prot\'eg\'e, r\^ole, na\"\i ve, \AE sop's \OE vres en fran\c cais. +But how do we put all this stuff into a paragraph that makes sense!? +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 15 + +\message{Page in bottom half of A4 paper.} +\null\vfil +\centerline{Page in bottom half of A4 paper.} +\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 16 + +\message{Page completely above left of A4 paper.} +\voffset -3in +\hoffset -9in +\leftline{Page completely above left of A4 paper.} +\vfil\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 17 + +\message{Page completely below right of A4 paper.} +\voffset 3in +\hoffset 9in +\null\vfil +\rightline{Page completely below right of A4 paper.} +\eject + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DVI page 18 + +\message{Page beyond all edges of A4 paper.} +\voffset -3in +\hoffset -3in +\vsize 15in +\hsize 15in +\line{Page beyond all edges of A4 paper.\hfil + Page beyond all edges of A4 paper.} +\vfil +\line{Page beyond all edges of A4 paper.\hfil + Page beyond all edges of A4 paper.} +\eject +\voffset 0in \hoffset 0in % offsets back to normal + +\bye 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 |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 -- cgit v1.2.3