Crate dvi

DVI file format

This crate implements the DVI (“device-independent file format”) format.

The most important type in the crate is Op, which describes a single operation or command in a DVI file. A DVI file is just a list of such operations.

The crate provides an iterator, Deserializer, that accepts raw DVI bytes and returns the operations in the DVI data. The inverse of this deserializer is the serialize() function.

Knuth’s description of the format

The text in this section was written by Donald Knuth. It appears as documentation in TeX.2021.583.

The most important output produced by a run of TeX is the “device independent” (DVI) file that specifies where characters and rules are to appear on printed pages. The form of these files was designed by David R. Fuchs in 1979. Almost any reasonable typesetting device can be driven by a program that takes DVI files as input, and dozens of such DVI-to-whatever programs have been written. Thus, it is possible to print the output of TeX on many different kinds of equipment, using TeX as a device-independent “front end.”

A DVI file is a stream of 8-bit bytes, which may be regarded as a series of commands in a machine-like language. The first byte of each command is the operation code, and this code is followed by zero or more bytes that provide parameters to the command. The parameters themselves may consist of several consecutive bytes; for example, the set_rule command (Op::TypesetRule with move_h=true) has two parameters, each of which is four bytes long. Parameters are usually regarded as nonnegative integers; but four-byte-long parameters, and shorter parameters that denote distances, can be either positive or negative. Such parameters are given in two’s complement notation. For example, a two-byte-long distance parameter has a value between -2^15 and 2^{15}-1. As in TFM files, numbers that occupy more than one byte position appear in big endian order.

A DVI file consists of a “preamble,” followed by a sequence of one or more “pages,” followed by a “postamble.” The preamble is simply a command (Op::Preamble command, with its parameters that define the dimensions used in the file; this must come first. Each “page” consists of a Op::BeginPage command, followed by any number of other commands that tell where characters are to be placed on a physical page, followed by an (Op::EndPage command. The pages appear in the order that TeX generated them. If we ignore Op::NoOp commands and Op::DefineFont command, which are allowed between any two commands in the file), each Op::BeginPage command is immediately followed by a Op::EndPage command, or by a Op::BeginPostamble command; in the latter case, there are no more pages in the file, and the remaining bytes form the postamble. Further details about the postamble will be explained later.

Some parameters in DVI commands are “pointers.” These are four-byte quantities that give the location number of some other byte in the file; the first byte is number~0, then comes number~1, and so on. For example, one of the parameters of a bop command points to the previous bop; this makes it feasible to read the pages in backwards order, in case the results are being directed to a device that stacks its output face up. Suppose the preamble of a DVI file occupies bytes 0 to 99. Now if the first page occupies bytes 100 to 999, say, and if the second page occupies bytes 1000 to 1999, then the bop that starts in byte 1000 points to 100 and the bop that starts in byte 2000 points to 1000. (The very first bop, i.e., the one starting in byte 100, has a pointer of -1.)

Modules

• transforms
  Transforms on DVI data.

Structs

• Deserializer
  Iterator that deserializes bytes into Op values.
• Values
  Data structure for tracking values in DVI data.

Enums

• InvalidDviData
  Error returned if deserializing DVI data fails.
• Op
  Operation that appears in DVI data.
• Var
  A variable in DVI data.

Functions

• serialize
  Serialize operations to DVI data bytes.