Literate Programming

D. E. KNUTH

a specific top-level description. Notice that the top-

level description has been abbreviated to ‘@

to print...@>’. Since the names of sections tend to

be rather long, it is a nuisance to type them in full each

time; WEB allows you to type ‘...’ after you have given

enough text to identify the remainder uniquely.

The ‘@!’ operation in the program text of Figure 2b

governs the underlining of index entries. The ‘@;’ spec-

ifies an invisible symbol that has the effect of a semi-

colon in

PASCAL

syntax. Commands such as these are

comparatively unimportant, but they are available for

polishing up the final documentation when you want to

maintain fine control.

Figure 2c shows key portions of the WEB text that

generated §6. Notice that the command ‘@d’ introduces

a macro definition. All features of WEB that appear in

our example program are illustrated in Figures 2a, 2b,

and 2c; the remainder of PRIMES.WEB simply uses the

same conventions again and again. In fact, most of the

WEB file is much simpler than the examples shown here;

Figure 2 has illustrated only the difficult parts.

E. THE TANGLED OUTPUT

Figure 3 shows the

PASCAL

program PRIMES.PAS that

results when TANGLE is applied to PRIMES.WEB. This

program is not intended for human consumption—it’s

only supposed to be readable by a

PASCAL

compiler—

so TANGLE does not go to great pains to produce a beau-

tiful format. Notice that underlines have been removed

from the identifier names, and that all of the letters

have been converted to uppercase (except in strings);

TANGLE tries to produce a format that will be acceptable

to a standard

PASCAL

compiler.

TANGLE removes all of the commentary in the WEB

file, but it inserts new comments of its own. If for some

reason you need to correlate the tangled

PASCAL

code

with the woven documentation, you can find the pro-

gram text for, say, §8 by looking between the comments

‘{8:}’ and ‘{:8}’.

A comparison of Figure 3 to Figure 2 should make it

clear why the TANGLE processor has acquired its name.

F. THE WOVEN OUTPUT

I mentioned earlier that WEAVE is a program that con-

verts a file like PRIMES.WEB into a file PRIMES.TEX that

is a syntactically correct source file for TEX. Figure 4

gives a sampling of PRIMES.TEX, which is even more un-

readable than PRIMES.PAS. The instructions that cause

TEX to produce formatted

PASCAL

programs, with ap-

propriate typefaces and indentation, etc., are somewhat

complex because they are supposed to give decent re-

sults regardless of the page size.

There is no need to discuss Figure 4 further in the

present paper, because the details of “pretty printing”

are not relevant to my main theme. I have shown this

much of PRIMES.TEX only to make the point that it is

nice to have a program like WEAVE to do all the format-

ting; computer programs are not easy to typeset.

{1:}{2:}PROGRAM PRINTPRIMES(OUTPUT);

CONST M=1000;{5:}RR=50;CC=4;WW=10;{:5}{19:}

ORDMAX=30;{:19}VAR{4:}

P:ARRAY[1..M]OF INTEGER;{:4}{7:}

PAGENUMBER:INTEGER;PAGEOFFSET:INTEGER;

ROWOFFSET:INTEGER;C:0..CC;{:7}{12:}J:INTEGER;

K:0..M;{:12}{15:}JPRIME:BOOLEAN;{:15}{17:}

ORD:2..ORDMAX;SQUARE:INTEGER;{:17}{23:}

N:2..ORDMAX;{:23}{24:}

MULT:ARRAY[2..ORDMAX]OF INTEGER;{:24}

BEGIN{3:}{11:}{16:}J:=1;K:=1;P[1]:=2;{:16}

{18:}ORD:=2;SQUARE:=9;{:18};

WHILE K

IF J=SQUARE THEN BEGIN ORD:=ORD+1;{21:}

SQUARE:=P[ORD]*P[ORD];{:21}{25:}

MULT[ORD-1]:=J;{:25};END{:20};{22:}N:=2;

JPRIME:=TRUE;

WHILE(N

WHILE MULT[N]

;IF MULT[N]=J THEN JPRIME:=FALSE{:26};N:=N+1;

END{:22};UNTIL JPRIME{:14};K:=K+1;P[K]:=J;

END{:11};{8:}BEGIN PAGENUMBER:=1;

PAGEOFFSET:=1;

WHILE PAGEOFFSET<=M DO BEGIN{9:}

BEGIN WRITE(’The First ’);WRITE(M:1);

WRITE(’ Prime Numbers --- Page ’);

WRITE(PAGENUMBER:1);WRITELN;WRITELN;

FOR ROWOFFSET:=PAGEOFFSET TO PAGEOFFSET+RR-1

DO{10:}

BEGIN FOR C:=0 TO CC-1 DO IF ROWOFFSET+C*RR<=

M THEN WRITE(P[ROWOFFSET+C*RR]:WW);WRITELN;

END{:10};PAGE;END{:9};

PAGENUMBER:=PAGENUMBER+1;

PAGEOFFSET:=PAGEOFFSET+RR*CC;END;END{:8}{:3};

END.{:2}{:1}

Figure 3. PASCAL program generated from the WEB file.

G. ADDITIONAL BELLS AND WHISTLES

A system like WEB can be successful only if it is capa-

ble of handling large programs as well as small ones,

and only if it is complete enough to take care of all

the practical requirements that arise when many differ-

ent kinds of programs are considered. A small example

like PRIMES.WEB is a satisfactory vehicle for illustrat-

ing the general ideas, but it cannot be convincing as a

demonstration of WEB’s ability to produce quality soft-

ware in the “real world.” My original design of WEB

in September, 1981, was followed by a year of exten-

sive experiments, so that by the time Version 1 was

released in September, 1982, I could be fairly confident

that the language was reasonably complete. Since then

only one or two small extensions have proved to be nec-

essary; and although numerous enhancements can eas-

ily be imagined, I believe that a useful stopping point

for a working system called WEB83 has been reached.

A full description of WEB83 appears in a Stanford

report,

4

which also contains the complete WEB programs

for WEAVE and TANGLE. The full language contains only

8 submitted to THE COMPUTER JOURNAL

---