path: root/dviware/dvgtk/doc/README

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