summaryrefslogtreecommitdiff
path: root/dviware/dvgtk/doc/README
diff options
context:
space:
mode:
Diffstat (limited to 'dviware/dvgtk/doc/README')
-rw-r--r--dviware/dvgtk/doc/README426
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