diff options
Diffstat (limited to 'dviware/dvgtk/doc/README')
-rw-r--r-- | dviware/dvgtk/doc/README | 426 |
1 files changed, 426 insertions, 0 deletions
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 |