Plan 9 /sys/man/1/dformat

NAME

dformat –– a program for typesetting data formats

SYNOPSIS

dformat [ file ... ] | pic | troff ...

DESCRIPTION

dformat is yet another preprocessor like eqn, pic, etc., this time for producing data formats. For instance, this dformat input

.begin dformat style bitwid 0.08 RR 0–7 Opcode 8–11 R1 12–15 R2 RX 0–7 Opcode 8–11 R1 12–15 X2 16–19 B2 20–31 D2 .end

Produces a pic picture that looks something like

+––––––+–––+–––+
RR |Opcode| R1| R2| +––––––+–––+–––+ 0 8 12 +––––––+–––+–––+–––+–––––––––––+ RX |Opcode| R1| X2| B2| D2 | +––––––+–––+–––+–––+–––––––––––+ 0 8 12 16 20

The pic output is more detailed and prettier, but you get the idea.
In a style reminiscent of eqn and pic, data formats are written in a special language and occur in a document surrounded by lines beginning

.begin dformat

and

.end

(in the first column, naturally). Anything outside these is copied through intact; whatever is between .begin dformat and .end is converted into pic commands to draw the diagram. Thus a document that contains dformat is compiled with a pipeline like

dformat paper.in | pic | eqn | troff –ms >paper.out

Each input line describes a record that contains several fields. Lines that start in column 1 name the records; subsequent lines that begin with white space give the field widths and names, in order.
The style command

style bitwid 0.08

can be viewed as an assignment of the value 0.08 inches to the parameter bitwid. A 32–bit record is therefore 2.56 inches across. Here are other available variables:
box center; c c c c c c l n l. Name Initial Explanation Value _ bitwid 0.125 Width of 1 bit in inches charwid 0.07 Width of 1 character in inches recht 0.3 Height of boxes, in inches recspread 0.15 Spread between boxes, in inches textht 0.167 Height of text lines below box, in inches linedisp 0.04 Distance of line from right of box, in inches addrht 0.055 Height of addresses above box, in inches addrdelta 4 Delta point size for printing bits (0 <= d <= 9) addr both Where to print addresses (left, right, both, off)
The values of variables are retained from one dformat display to another. This allows you to define a style for a document by setting all values in the first display. To allow you to use a different style in a single picture, the old value of a variable is stored when a new value is assigned. The old value of the variable bitwid, for instance, may be restored by an assignment of the form

style bitwid reset

Several other bells and whistles, along with many examples, are described in AT&T Bell Laboratories Computing Science Technical Report 142, DFORMAT – A Program for Typesetting Data Formats, .}f by Jon Bentley, April 1988.


	For problems or praise, contact Jon Bentley, AT&T Bell Laboratories, 2C–317, Murray Hill, NJ 07974; 201–582–2315; `research!jlb`.