Literate Programming

D. E. KNUTH

statistics-gathering is pointless unless someone is actu-

ally going to use the results. In order to make the in-

strumentation code optional, I include the word ‘stat’

just before any special code for statistics, and ‘tats’

just after such code; and I tell WEAVE to regard stat

and tats as if they were begin and end. But stat and

tats are actually simple macros. When I do want to

gather the statistics, I define stat and tats to be null;

but in a production version of the software, I make stat

expand to ‘@{’ and tats expand to ‘@}’, where @{ and @}

are special braces that TANGLE does not remove. Thus

the optional code appears as a harmless comment in

the

PASCAL

program.

WEB’s macros are allowed to have at most one pa-

rameter. Again, I did this in the interests of simplicity,

because I noticed that most applications of multiple pa-

rameters could in fact be reduced to the one-parameter

case. For example, suppose that you want to define

something like

mac(#1,#2) == m[#1*r+#2]

which WEB doesn’t permit. You can get essentially the

same result with two one-parameter macros

mac_tail(#) == #]

mac(#) == m[#*r+mac_tail

since, e.g., ‘mac(a)(b)’ will expand into ‘m[a*r+b]’.

Here is another example that indicates some of the

surprising generality of one-parameter macros: Con-

sider the two definitions

define two_cases(#)==case j of

1:#(1); 2:#(2); end

define reset_file(#)==reset(file@#)

where ‘@&’ in the second definition is the concatenation

operation that pastes two texts together. You can now

say

two_cases(reset_file)

and the resulting

PASCAL

output will be

case j of

1:reset(file1);

2:reset(file2);

end

In other words, the name of one macro can usefully be

a parameter to another macro. This particular trick

makes it possible to live with

PASCAL

compilers that

do not allow arrays of files.

I. PORTABILITY

One of the goals of my TEX research has been to pro-

duce portable software, and the WEB system has been

extremely helpful in this respect. Although my own

work is done on a DEC-10 computer with Stanford’s

one-of-a-kind operating system, the software developed

with WEB has already been transported successfully to a

wide variety of computers made by other manufactur-

ers (including IBM, Control Data, XEROX, Hewlett-

Packard), and to a variety of different operating sys-

tems for those machines. To my knowledge, no other

software of such complexity has ever been transported

to so many different machines. It seems likely that TEX

will soon be operating on all but the smallest of the

world’s computer systems.

To my surprise, the main bottleneck to portability of

the TEXware has been the lack of suitable

PASCAL

com-

pilers, because

PASCAL

has often been implemented

without system programming in mind. Anybody who

has a decent

PASCAL

compiler can install WEB (and all

programs written in WEB) without great difficulty, es-

sentially as follows:

1) Start with the three files WEAVE.WEB, TANGLE.WEB,

and TANGLE.PAS. (The programs have not been copy-

righted, so these files are not difficult to obtain.)

2) Run TANGLE.PAS through your

PASCAL

compiler to

get a working TANGLE program.

3) Check your TANGLE by applying it to TANGLE.WEB;

your output file should match TANGLE.PAS.

4) Apply your TANGLE to the file WEAVE.WEB, obtaining

WEAVE.PAS; then apply

PASCAL

to WEAVE.PAS and

you’ll have a working WEAVE system.

5) The same process applies to any software written

in WEB, notably to TEX itself. (However, you need

fonts and suitable output equipment in order to make

proper use of TEX; that may be another bottleneck.)

Once you have TEX working, you can apply WEAVE

and TEX to your WEB files, thereby getting program

documents as illustrated above.

Notice that a TANGLE.PAS file is needed in order to get

this “bootstrapping” process started. If you have just

WEAVE.WEB and TANGLE.WEB, you can’t do the first step.

However, anybody who has looked seriously into the

question of software portability will realize that my

comments in the preceding paragraphs have been over-

simplified. I have glossed over some serious problems

that arise: Character sets are different; file naming con-

ventions are different; special conventions are needed to

interact with a user’s terminal; data is packed differ-

ently on different machines; floating-point arithmetic is

always nonstandard and sometimes nonexistent; users

want “friendly” interaction with existing programs for

editing and spooling; etc., etc. Furthermore, many of

the world’s

PASCAL

compilers are incredibly bizarre.

Therefore it is quite na¨ıve to believe that a single pro-

gram TANGLE.PAS could actually work on very many

different machines, or even that one single source file

TANGLE.WEB could be adequate; some system-dependent

changes are inevitable.

The WEB system caters to system-dependent changes

in a simple but surprisingly effective way that I ne-

glected to mention when I listed its other features. Both

TANGLE and WEAVE are designed to work with two in-

put files, not just one: In addition to a WEB source

file like TEX.WEB, there is also a “change file” TEX.CH

that contains whatever changes are needed to customize

TEX for a particular system. (Similarly, the source

files WEAVE.WEB and TANGLE.WEB are accompanied by

WEAVE.CH and TANGLE.CH.)

Here’s how change files work: Each change has the

form “replace x

1

. . . x

m

by y

1

. . . y

n

,” for some m ≥ 1

and n ≥ 0; here x

i

and y

j

represent lines in the change

file. The WEAVE and TANGLE programs read data from

the WEB input file until finding a line that matches x

1

;

this line, and the m − 1 following lines, are replaced

10 submitted to THE COMPUTER JOURNAL

---