Previous Next Contents

Chapter 3:   All the command line options

3.1   -c: perform simple validity check

The -c option does a simple validity check of the dvi file: (a) the first two bytes should be 247 2, (b) there should be at least four 233's at the end of the file immediately preceded by a 2.

This is not much of a check: it will certainly not catch dvi files whose middle bytes have become corrupted, but it will at least catch files that are clearly not dvi files (such as text files).

Note that the -c option is implicit in almost every other option, so its main use is to detect files that are probably not dvi files.

See section 15 of dvitype.web for more information.

Example of use:
dvii -c test.dvi 

dvi file 'test.dvi' passed validation check (level 0).

3.2   -C: perform more rigorous (and slower) validity check

(Note: this is a capital 'C'.) This command causes dvii to traverse the entire dvi file parsing each opcode. If the dvi file is corrupted, this command will detect it.

However, you pay for this: -C is much slower than -c. 

dvii -C test

dvi file 'test.dvi' passed validation check (level 1).

3.3   -d: dump opcodes

(This option is available in version 0.42 and later.) This option (which implies the -C option) displays all the opcodes. Here is a sample: 
dvii -d test

o:247
o:139
o:141
o:159
o:142
...
o:248
dvi file 'test.dvi' passed validation check (level 1).
where ... are many opcodes. The script details.pl uses this mode to create an opcode summary of the file; see section C.3 for more information on details.pl.

3.4   -f: display fonts

If you want to list all the fonts used in a dvi file, use the -f option. Note that different sizes of the same font will list separately. 

dvii -f test

f:[50/cmr10/1200]::4bf16079
f:[23/cmbx10/1000]::1af22256
f:[0/cmr10/1000]::4bf16079
The file test.dvi calls 3 fonts: font number 50 is cmr10 at size 1200, font number 23 is cmr10 at size 1000, and font number 0 is cmbx10 at size 1000. (For more information on fonts, see chapter 5.)

3.5   -F: display fonts on each page

This option (which implies the -p and -f options) lists the fonts used on each page. 

dvii -F test

f:[50/cmr10/1200]::4bf16079
f:[23/cmbx10/1000]::1af22256
f:[0/cmr10/1000]::4bf16079
p:[1/1]
  start of font list
  Font [0/cmr10/1000]
  end of font list
p:[2/2]
  start of font list
  Font [0/cmr10/1000]
  end of font list
p:[3/3]
  start of font list
  Font [0/cmr10/1000]
  Font [23/cmbx10/1000]
  end of font list
p:[4/4]
  start of font list
  Font [0/cmr10/1000]
  end of font list
p:[5/-1]
  start of font list
  Font [0/cmr10/1000]
  Font [50/cmr10/1200]
  end of font list
p:[6/-3]
  start of font list
  Font [0/cmr10/1000]
  end of font list

3.6   -g: suppress control characters when showing special text

The -g option can be used when displaying \special information. If a \special contains text with unprintable characters, it may corrupt some computer screens. So, instead of trying to print these unpleasant characters, dvii will instead print a `.'.

Here is what the \special text looks like without the -g option: 
dvii -s test.dvi 

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/-2]:: Some control characters: []
(Note: there are four control characters between the square brackets; because TeX does not like these particular characters, you cannot see them here.)

Now with the -g option: 
dvii -s -g test.dvi 

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/-2]:: Some control characters: [....]

3.7   -h: show main help screen

This option shows the main help screen which begins 
dvii -h

This is dvii 0.?? (DVI file information) by Adam Lewenberg
Send bug reports to adam@macrotex.net

dvii -h             (Print help screen) 
dvii dvifile        (Print dvi information)
dvii [many possible options] dvifile 
-------------------------------------------
 -H : show complete list of options
 -h : show this help screen
 -u : display dvi summary
...
etc.

3.8   -H: show options help screen

This option displays all the command line options: 
dvii -H 

All the command line options:
  -c : perform simple validity check
  -C : perform more rigorous (and slower) validity check
  -f : display fonts
...
etc.

3.9   -m#: add message digest information when displaying pages

(See Chapter 7 on message digests.) Display a 16-byte message digest for each page. 
dvii -m test

[message digest: simple sum]
p:[1/1]::D8C977816A091771A3A631E7592DAE6D
p:[2/2]::16E5A31EF87F926DB1F86CAD165C5453
p:[3/3]::1139D12267E3D60267CC788905909170
p:[4/4]::68E5A2E9D7320743CB85769CAAE9B023
p:[5/-1]::DE72BC3345FFDF7E779C8C667DCE3F97
p:[6/-3]::12808C9489FD3430C3C8EDAD8A4EC760

3.10   -M#: add message digest information but ignore certain opcodes

(See Chapter 7 on message digests.) Display a 16-byte message digest for each page, but ignore certain dvii opcodes.

Depending upon the value of #, certain of the dvi information will be ignored when computing the message digest.

These options can be combined by adding; for example, to ignore fonts and \special's, use -M5. A rationale as to why you might want to ignore certain dvii page information when computing a message digest follows.

If you use page message digests to detect when a page has changed, you may get false alarms when the only thing that changes in the dvi file is the order of font definitions: the page looks the same but will have a different message digest because the message digest has changed.

For example, consider the two files 
% File A                      % File B
\font\a=cmr10 at 11pt         \font\b=cmr10 at 12pt
\font\b=cmr10 at 12pt         \font\a=cmr10 at 11pt
\a A                          \a A
\b A                          \b A
\end                          \end
These two files generate identical looking output but different dvi code because the font numbering is different. If you use dvii -m you will see different fingerprints: 
[message digest: simple sum]
A: p:[1/1]::6676847979940C046D093C93789A1812
B: p:[1/1]::6676837979940B056D093C94789A1812
                         ^
But, if you use dvii -M1 you get 
[message digest: simple sum (ignore font)]
A: p:[1/1]::B42E10A601774236B86D11CE2F8C25E4
B: p:[1/1]::B42E10A601774236B86D11CE2F8C25E4
By examining the fonts with the -f option you can see where the two dvi files differ: 

dvii -f filea                       dvii -f fileb 
f:[51/cmr10/1200]::4bf16079         f:[51/cmr10/1100]::4bf16079
f:[50/cmr10/1100]::4bf16079         f:[50/cmr10/1200]::4bf16079
f:[0/cmr10/1000]::4bf16079          f:[0/cmr10/1000]::4bf16079
The font cmr10 at 1200 is font 51 in filea, whereas it is font 50 in fileb.

3.11   -n#: display # bytes of special text

Normally, dvii -s test will display a maximum of 128 bytes of the \special text. For example, let filec.tex be the file 
\special{0123456789abcdefghijklmnopqrstuvwxyzABCDE...}
\bye
(Note that the '...' indicates more special text which we omit due to space limitations in this manual.) 

dvii -s filec
s:[1/1]:: 0123456789abcdefghijklmnopqrstuvwxyzABCDE...
However, you can tell dvii how many bytes to display by using the -n option: 
dvii -s -n20 filec
s:[1/1]:: 0123456789abcdefghij
Finally, if you want to display all the \special text, use -n-1: 
dvii -s -n-1 test
s:[1/1]:: 0123456789abcdefghijklmnopqrstuvwxyzABCDE...
Here, the output of dvii -s -n-1 test looks like dvii -s test only because we do not have enough page to show the entire \special text, but believe me, dvii -s -n-1 test will display all the \special text.

3.12   -p: display page information

To display a list of physical page/TeX page pairs, use the -p option: 
dvii -p test

p:[1/1]
p:[2/2]
p:[3/3]
p:[4/4]
p:[5/-1]
p:[6/-3]
The first number indicates the physical page and the second number indicates the TeX page. For example, the sixth physical page has TeX page -3.

For more information on the difference between physical pages and TeX pages, see section 4.1.

3.13   -P: suppress the display of physical pages

(This option is available in version 0.43 and later.) This option only makes sense when you are listing page information, e.g., when using the -p or the -M option. Here is what you get with dvii -p test: 
dvii -p test

p:[1/1]
p:[2/2]
p:[3/3]
p:[4/4]
p:[5/-1]
p:[6/-3]
and here is what you get when you add the -P option: 
dvii -p -P test

p:[XX/1]
p:[XX/2]
p:[XX/3]
p:[XX/4]
p:[XX/-1]
p:[XX/-3]
So, why might you want to do something so silly? This is most useful when using the message digest feature to detect page changes (see Chapter 7). Imagine that you have message digest information for your entire 1000-page book. Later, you compile only one chapter. If you create a message digest of the chapter, the physical pages will no longer agree with the message digest for the entire book. So, suppressing the physical pages is the only way you can reliably tell if there has been a change.

3.14   -s: display specials

The -s lists each \special in the file and the page on which it appears. For example: 
dvii -s test

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: []
Thus, there is a \special on (physical) page 2 consisting of the text `A short special'.

The \special text on page 6/-3 contains some control characters which do not show up on the printed page because they do not correspond to any printable characters. (Actually, the text is [^A^B^C^D].)

3.15   -S: count number of specials

Normally, the summary that the -u option generates includes the number of pages and the number of fonts, but not the number of specials. If you want a count of the number of specials, use -S; note that -S implies -u 
dvii -S test

File size: 1500 bytes (1 K)
Comment string:  TeX output 2001.01.25:0933
Page count: 6
Number of fonts: 3
Number of specials: 8

3.16   -T: give timing information

To see how long dvii took to run, use the -T option: 
dvii -T -C test

dvi file 'test.dvi' passed validation check (level 1).
User time: 0.0 seconds
Real time: 0.0 seconds
The `User time' is the time external to the computer to run; that is, if you started a stopwatch before executing the command and then stopped it after the command finished, the elapsed time corresponds to the `User time'.

On the other hand, most modern operating systems are capable of running many programs at once, switching from one to the other. So, while it may appear to you that a command takes 5 minutes to run, the computer itself may have only spent 1 minute of the 5 minutes on your program, spending the other 4 minutes on other tasks. Hence, 1 minute would be `Real time'.

If the file is small enough (as it is in the cast of test.dvi above), you may see both times listed as 0.0 seconds.

3.17   -u: display summary

To display a summary of a dvi file, use the -u option: 
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 test.dvi file is 1500 bytes long (roughly 1 kilobyte), was compiled on December 5, 1999 at 7:51 AM, has 6 pages, and contains 3 fonts.

See also the -S option.

Previous Next Contents