# 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:
1. It should be fast, faster than `dvitype`.
2. 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.
3. It should be useful to the TeX community.
4. 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.