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