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.
6 README for DTL package - Thu 9 March 1995
7 -----------------------------------------
8 Author: Geoffrey Tobin <G.Tobin@ee.latrobe.edu.au>
10 CTAN Archive-path: dviware/dtl
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.
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
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.
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
44 CTAN: dviware/driv-standard/level-0
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.
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.
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
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
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
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.
86 So an exact, concise, textual representation of a DVI file is needed,
87 but dvitype does not produce one.
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:
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.
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:
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).
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
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.)
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
145 The length of DTL commands is limited by the size of the line buffer