Chapter 1: Introduction

dvii is a utility written in C that extracts information from a TeX dvi file. Information displayed can include a summary:

File comment (usually the date the file was compiled)
File size
Number of (physical) pages
Number of fonts

as well as more detailed information:

Font names for all fonts used
List of physical page number/TeX page number pairs
List of all \specials and the page on which they appear
List of all fonts used on a given page

For example, running the command dvii -u test.dvi generates the summary

File size: 1500 bytes (1 K)
Comment string:  TeX output 1999.12.05:1951
Page count: 6
Number of fonts: 3

Here is the file that generated the above: test.dvi.

1.1 Design Goals

I have designed this utility with the following goals in mind:

It should be fast, faster than dvitype.
It should be easy to use the output as a back end to PERL, enabling the easy manipulation of the data for more specific purposes.
It should be useful to the TeX community.
It should be portable.

In light of these goals, I encourage all those who use it to send me bug reports, comments, and suggestions on how it can be improved. In particular, I am interested in making this program compile on as many different platforms as possible, so if you have compiling problems, please let me know.

1.2 Some examples of use

The following examples use the file test.dvi whose source can be found in Appendix B.

1.2.1 Basic usage

The syntax for use is

dvii [options] dvifile

where dvifile is the name of the dvi file that you want information about. You can leave off the extension dvi; thus, dvii test and dvii test.dvi are equivalent. (Unless you also have a file named simply test in which case dvii will complain that test is not a valid dvi file. In such cases, be sure to explicitly supply the extension .dvi.)

1.2.2 Display a summary of information

dvii -u test.dvi

File size: 1500 bytes (1 K)
Comment string:  TeX output 1999.12.05:1951
Page count: 6
Number of fonts: 3

The summary tells us: the dvi file test.dvi is 1500 bytes long (roughly 1 kilobyte), was compiled on December 5, 1999 at 7:51 PM, has 6 pages, and contains 3 fonts.

1.2.3 List all information

dvii test.dvi

File size: 1500 bytes (1 K)
Comment string:  TeX output 1999.12.05:1951
Page count: 6
Number of fonts: 3
f:[50/cmr10/1200]::4bf16079
f:[23/cmbx10/1000]::1af22256
f:[0/cmr10/1000]::4bf16079
p:[1/1]
p:[2/2]
p:[3/3]
p:[4/4]
p:[5/-1]
p:[6/-3]
s:[2/2]:: A short special
s:[3/3]:: abcdefghijklmnopqrstuvwxyzABCDE...
s:[4/4]:: PSfile 1.eps
s:[4/4]:: PSfile 2.eps
s:[4/4]:: PSfile 3.EPS
s:[4/4]:: PSfile dog1.gif
s:[4/4]:: PSfile cat.eps
s:[6/-3]:: Some control characters: []

With no options, dvii first displays a summary of the dvi file (see section 1.2.2). The next 3 lines list the three fonts used by the dvi file.

The succeeding 6 lines list page information. The format p:[m/n] means that this is physical page m corresponding to TeX page n. The physical page is the page in the order that it would be displayed or printed out on a printer. The TeX page is the page number that would appear (in normal circumstances) at the bottom of the page. For more on the difference between physical and TeX pages, see section 4.1.

The last 6 lines list all the \special's included in the dvi file. Note that not every dvi file will contain \special's. The format is the same as that for pages; the text following the double colon :: is the first 128 bytes of the \special text.

1.3 The `dvii` home page

The dvii home page can be found at http://www.macrotex.net/dvii/dvii.html