Go to the first, previous, next, last section, table of contents.

9. DVI utilities

TeX outputs a file in DVI (DeVice Independent) format as a compact representation of the original document. DVI files can be translated to meet the requirements of a real physical device, such as PostScript printers (see section `Introduction' in Dvips), PCL printers (see dvilj(1)), and X displays (see xdvi(1)). In fact, DVI translators are available for virtually all common devices: see `CTAN:/dviware' (for CTAN info, see section `unixtex.ftp' in Kpathsea).

For the precise definition of the DVI file format, see (for example) the source file `web2c/dvitype.web'.

The DVI-processing programs in the Web2c distribution are not device drivers; they perform generic utility functions.

dvicopy invocation: Expand virtual fonts.
dvitype invocation: DVI to human-readable text.

9.1 DVIcopy: Canonicalize virtual font references

DVIcopy reads a DVI file, expands any references to virtual fonts (see section `Virtual fonts' in Dvips) to base fonts, and writes the resulting DVI file. Thus you can use virtual fonts even if your DVI processor does not support them, by passing the documents through DVIcopy first. Synopsis:

dvicopy [option]... [indvi[.dvi] [outdvi[.dvi]]]

DVIcopy reads standard input if indvi is not specified, and writes standard output if outdvi is not specified.

The program accepts the following options, as well as the standard `-help' and `-version' (see section 3.2 Common options):

`-magnification=integer': Override existing magnification in indvi with integer; 1000 specifies no magnification. This is equivalent to setting TeX's \mag parameter.
`-max-pages=n': Process n pages; default is one million.
`-page-start=page-spec': Start at the first page matching page-spec, which is one or more (signed) integers separated by periods, corresponding to TeX's \count0...9 parameters at \shipout time; `*' matches anything. Examples: `3', `1.*.-4'.

9.2 DVItype: Plain text transliteration of DVI files

DVItype translates a DeVice Independent (DVI) file (as output by TeX, for example) to a plain text file that humans can read. It also serves as a DVI-validating program, i.e., if DVItype can read a file, it's correct. Synopsis:

dvitype [option]... dvifile[.dvi]

DVItype does not read any bitmap files, but it does read TFM files for fonts referenced in dvifile. The usual places are searched (see section `Supported file formats' in Kpathsea). To see all the relevant paths, set the environment variable KPATHSEA_DEBUG to `-1' before running the program.

Output goes to standard output.

The program accepts the following options, as well as the standard `-help' and `-version' (see section 3.2 Common options):

`-dpi=real'

Do pixel movement calculations at real pixels per inch; default 300.0.

`-magnification=integer'

Override existing magnification in indvi with integer; 1000 specifies no magnification. This is equivalent to setting TeX's \mag parameter.

`-max-pages=n'

Process n pages; default is one million.

`-output-level=n'

Verbosity level of output, from 0 to 4 (default 4):

0: Global document information only.
1: Most DVI commands included, and typeset characters summarized.
2: Character and movement commands explicitly included.
3: DVI stack and current position calculations included.
4: Same information as level 3, but DVItype does random positioning in the file, reading the DVI postamble first.

`-page-start=page-spec'

Start at the first page matching page-spec, which is one or more (signed) integers separated by periods, corresponding to TeX's \count0...9 parameters at \shipout time; `*' matches anything. Examples: `1', `5.*.-9'.

`-show-opcodes'

Show numeric opcode values (in decimal) for DVI commands, in braces after the command name. This can help in debugging DVI utilities. We use decimal because in the DVI format documentation (in `dvitype.web', among others) the opcodes are shown in decimal.

dvitype output example

9.2.1 DVItype output example

As an example of the output from DVItype (see section above), here is its (abridged) translation of the `story.dvi' resulting from running the example in The TeXbook, with `-output-level=4' and `-show-opcodes' on.

...
Options selected:
  Starting page = * 
  Maximum number of pages = 1000000
  Output level = 4 (the works)
  Resolution = 300.00000000 pixels per inch
numerator/denominator=25400000/473628672
magnification=1000;       0.00006334 pixels per DVI unit
' TeX output 1992.05.17:0844'
Postamble starts at byte 564.
maxv=43725786, maxh=30785863, maxstackdepth=3, totalpages=1
Font 33: cmsl10---loaded at size 655360 DVI units 
Font 23: cmbx10---loaded at size 655360 DVI units 
Font 0: cmr10---loaded at size 655360 DVI units 
 
42: beginning of page 1 
87: push {141} 
level 0:(h=0,v=0,w=0,x=0,y=0,z=0,hh=0,vv=0) 
88: down3 -917504 {159} v:=0-917504=-917504, vv:=-58 
92: pop {142} 
...
104: putrule {137} height 26214, width 30785863 (2x1950 pixels) 
113: down3 5185936 {159} v:=655360+5185936=5841296, vv:=370 
117: push {141} 
level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) 
118: right4 12265425 {146} h:=0+12265425=12265425, hh:=777 
[ ]
123: fntdef1 23 {243}: cmbx10 
145: fntnum23 {194} current font is cmbx10 
146: setchar65 h:=12265425+569796=12835221, hh:=813 
147: w3 251220 {150} h:=12835221+251220=13086441, hh:=829 
151: setchar83 h:=13086441+418700=13505141, hh:=856 
...
164: setchar82 h:=17448202+565245=18013447, hh:=1142 
165: x0 -62805 {152} h:=18013447-62805=17950642, hh:=1138 
166: setchar89 h:=17950642+569796=18520438, hh:=1174 
[A SHORT STORY]
167: pop {142} 
level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) 
...
550: pop {142} 
level 0:(h=0,v=42152922,w=0,x=0,y=0,z=0,hh=0,vv=2670) 
551: down3 1572864 {159} v:=42152922+1572864=43725786, vv:=2770 
555: push {141} 
level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) 
556: right4 15229091 {146} h:=0+15229091=15229091, hh:=965 
561: setchar49 h:=15229091+327681=15556772, hh:=986 
[ 1]
562: pop {142} 
level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) 
563: eop {140}

Explanation:

The DVItype options are recorded at the beginning, followed by global information about the document, including fonts used.
Each DVI command is preceded by its byte position in the file (`42:', `87:', ...), and (because of the `-show-opcodes') followed by its decimal opcode value in braces (`{141}', `{142}', ...).
The `level' lines record information about the DVI stack; `h' and `v' define the current position in DVI units, while `hh' and `vv' are the same in pixels.
Text sequences are summarized in brackets, as in `[A SHORT STORY]' and the `[ 1]'.

Go to the first, previous, next, last section, table of contents.