3rdparty/dtl/README

   1 This file is public domain.
   2 Originally written 1995, Geoffrey Tobin.
   3 The author has expressed the hope that any modification will retain enough content to remain useful. He would also appreciate being acknowledged as the original author in the documentation.
   4 This declaration added 2008/11/14 by Clea F. Rees with the permission of Geoffrey Tobin.
   5
   6 README for DTL package - Thu 9 March 1995
   7 -----------------------------------------
   8 Author: Geoffrey Tobin <G.Tobin@ee.latrobe.edu.au>
   9 Version: 0.6.1
  10 CTAN Archive-path: dviware/dtl
  11 Brief Description:
  12  DTL (DVI Text Language) files are equivalent to TeX's DVI files,
  13  but are humanly readable, instead of binary.  Two programs are
  14  provided to translate between DVI and DTL:  dv2dt, dt2dv.
  15  dt2dv warns if byte addresses or string lengths recorded in a DTL
  16  file are incorrect, then overrides them.  This makes DTL files
  17  editable.  It also allows quoted apostrophes (\') and quoted quotes
  18  (\\) in strings.  The current DTL variety, sequences-6, separates
  19  font paths into directory and font, which makes them freely editable.
  20  In this release, DTL line numbers are correctly calculated, and three
  21  memory leaks have been fixed.
  22 Keywords: dvi, TeX
  23 Includes:
  24  Makefile  README  dt2dv.c  dtl.h  dv2dt.c
  25  man2ps  dtl.doc  dvi.doc  dt2dv.man  dv2dt.man
  26  hello.tex  example.tex  tripvdu.tex  edited.txt
  27
  28 Motivation:
  29
  30  When TeX has typeset a document, it writes its handiwork to a DVI
  31 file, for DVI processing software (such as viewers, printer drivers,
  32 dvidvi, and dvicopy) to read.
  33
  34 The file  dvi.doc  lists the DVI file commands, with their opcodes
  35 (byte values), nominal command names, arguments, and meanings.  For a
  36 detailed description of DVI file structure, see one of these:
  37 1.  Donald E. Knuth's book _TeX: The Program_;
  38 2.  The file tex.web, which contains source and documentation for TeX:
  39         CTAN:  systems/knuth/tex/tex.web
  40 3.  The source for Knuth's dvitype program:
  41         CTAN:  systems/knuth/texware/dvitype.web
  42 4.  Joachim Schrod's DVI drivers standard document, the relevant part
  43     of which is at
  44         CTAN:  dviware/driv-standard/level-0
  45
  46 Sometimes human beings are interested to see exactly what TeX has
  47 produced, for example when viewing or printing of the DVI file gives
  48 unexpected results.  However, a DVI file is a compact binary
  49 representation, so we need software to display its contents.
  50
  51 Binary file editors, when available, can show the DVI bytes, but not
  52 their meanings, except for the portions that represent embedded text.
  53 In particular, the command names are not shown, and the command
  54 boundaries are not respected.
  55
  56 By contrast, Knuth's dvitype program is designed as an example of a
  57 DVI driver.  However, dvitype is inconvenient for studying the DVI
  58 file alone, for the following reasons:
  59 1.  Being a DVI driver, dvitype endeavors to read the TFM font metric
  60 files referenced in the DVI file.  If a TFM file is absent, dvitype
  61 quits with an error message.
  62 2.  When it starts, it prompts the user interactively for each of a
  63 series of options.
  64 3.  Even the least verbose option gives masses of information that is
  65 not contained in the DVI file, coming instead from a combination of
  66 the data in the DVI file and TFM files.
  67 4.  It does NOT show the DVI information in a way that accurately
  68 reflects the structure of the DVI file.
  69 5.  Its output, if redirected to a file, produces a very large file.
  70 6.  There is no automated procedure for converting the output of
  71 dvitype back to a DVI file, and doing it by hand is totally
  72 unreasonable.
  73
  74 The first disadvantage is a killer if a TFM file is absent.
  75 Disadvantages two to four make dvitype very inconvenient for studying
  76 a DVI file.  The fifth problem makes dvitype's output tedious,
  77 disk-hungry (so one deletes it almost immediately), and unsuitable for
  78 file transfer.
  79
  80 The sixth disadvantage of dvitype is important to those people who are
  81 interested in editing DVI files.  Since the DVI files refer explicitly
  82 to their own internal byte addresses, it's very easy to mess up a DVI
  83 file if one were to try to edit it directly, even apart from the problem
  84 of how to recognise a command.
  85
  86 So an exact, concise, textual representation of a DVI file is needed,
  87 but dvitype does not produce one.
  88
  89 Resolution:
  90
  91  Therefore, working from Joachim Schrod's description, I designed DTL
  92 and its conversion programs dv2dt (DVI -> DTL) and dt2dv (DTL -> DVI),
  93 which are provided as C sources:
  94
  95     dtl.h
  96     dv2dt.c
  97     dt2dv.c
  98
  99 Although I was motivated by the TFM <-> PL conversion provided by
 100 Knuth's tftopl and pltotf programs, I deliberately designed DTL to be
 101 a much more concise and literal translation than the `property list'
 102 structure exemplified by PL.  The result is that a DTL file is
 103 typically three times the size of its equivalent DVI file.  The
 104 document  dtl.doc  lists the correspondence between the DTL command
 105 names and the (nominal) DVI command names.
 106
 107 A clear advantage of an exact two-way conversion is that we can check
 108 (and prove) whether the converters worked truly on a given DVI file.
 109 The provided plain TeX files:
 110     example.tex
 111     tripvdu.tex
 112 can be used to test whether the compiled programs are behaving
 113 sensibly.  Whereas  example.tex  is a simple document that uses a
 114 variety of plain TeX commands,  tripvdu.tex  provides a kind of
 115 `trip test' for DVI processor programs.  Both documents are taken,
 116 with permission, from Andrew K. Trevorrow's dvitovdu (alias dvi2vdu)
 117 distribution (and are also part of the dvgt viewer distribution).
 118
 119 The  Makefile  might have to be edited for your site, as it assumes
 120 gcc  for your C compiler.  Makefile compiles dv2dt and dt2dv, then
 121 runs  tex  on example.tex and tripvdu.tex, and also converts the
 122 resulting DVI files to DTL files, back to DVI files (with a change
 123 of name), then back again to DTL files, so that the results can be
 124 compared using a textual differencing program.  (Many computer systems
 125 have such a program; on unix, as assumed by Makefile, this is named
 126 `diff';  ms-dos has one named `comp'.)  This should produce a
 127 zero-length  .dif  file for each document, proving that the two DTL
 128 files are identical.
 129
 130 A keen tester might also use a binary difference program on the DVI
 131 files, to check that they are identical, as they need to be.  (On unix
 132 systems, the `diff' program suffices for that purpose.)
 133
 134 Note:
 135
 136  In representing numeric quantities, I have mainly opted to use
 137 decimal notation, as this is how most of us are trained to think.
 138 However, for the checksums in the `fd' (font definition) commands, I
 139 chose octal notation, as this is used for checksums in Knuth's PL
 140 files, against which DVI files must be compared when a DVI driver
 141 loads a font.
 142
 143 Caveat:
 144
 145 The length of DTL commands is limited by the size of the line buffer
 146 in dt2dv.c.
 147
 148 End of README