Literate Programming

---

Literate Programming

Donald E. Knuth

Computer Science Department, Stanford University, Stanford, CA 94305, USA

The author and his associates have been experimenting for the past several years with a program-

ming language and documentation system called WEB. This paper presents WEB by example, and

discusses why the new system appears to be an improvement over previous ones.

A. INTRODUCTION

The past ten years have witnessed substantial improve-

ments in programming methodology. This advance,

carried out under the banner of “structured program-

ming,” has led to programs that are more reliable and

easier to comprehend; yet the results are not entirely

satisfactory. My purpose in the present paper is to

propose another motto that may be appropriate for the

next decade, as we attempt to make further progress

in the state of the art. I believe that the time is ripe

for significantly better documentation of programs, and

that we can best achieve this by considering programs

to be works of literature. Hence, my title: “Literate

Programming.”

Let us change our traditional attitude to the con-

struction of programs: Instead of imagining that our

main task is to instruct a computer what to do, let us

concentrate rather on explaining to human beings what

we want a computer to do.

The practitioner of literate programming can be re-

garded as an essayist, whose main concern is with ex-

position and excellence of style. Such an author, with

thesaurus in hand, chooses the names of variables care-

fully and explains what each variable means. He or she

strives for a program that is comprehensible because its

concepts have been introduced in an order that is best

for human understanding, using a mixture of formal

and informal methods that re¨ınforce each other.

I dare to suggest that such advances in documenta-

tion are possible because of the experiences I’ve had

during the past several years while working intensively

on software development. By making use of several

ideas that have existed for a long time, and by applying

them systematically in a slightly new way, I’ve stumbled

across a method of composing programs that excites me

very much. In fact, my enthusiasm is so great that I

must warn the reader to discount much of what I shall

say as the ravings of a fanatic who thinks he has just

seen a great light.

Programming is a very personal activity, so I can’t

be certain that what has worked for me will work for

everybody. Yet the impact of this new approach on my

own style has been profound, and my excitement has

continued unabated for more than two years. I enjoy

the new methodology so much that it is hard for me to

refrain from going back to every program that I’ve ever

written and recasting it in “literate” form. I find myself

unable to resist working on programming tasks that

I would ordinarily have assigned to student research

assistants; and why? Because it seems to me that at last

I’m able to write programs as they should be written.

My programs are not only explained better than ever

before; they also are better programs, because the new

methodology encourages me to do a better job. For

these reasons I am compelled to write this paper, in

hopes that my experiences will prove to be relevant to

others.

I must confess that there may also be a bit of mal-

ice in my choice of a title. During the 1970s I was

coerced like everybody else into adopting the ideas of

structured programming, because I couldn’t bear to be

found guilty of writing unstructured programs. Now I

have a chance to get even. By coining the phrase “liter-

ate programming,” I am imposing a moral commitment

on everyone who hears the term; surely nobody wants

to admit writing an illiterate program.

B. THE WEB SYSTEM

I hope, however, to demonstrate in this paper that the

title is not merely wordplay. The ideas of literate pro-

gramming have been embodied in a language and a

suite of computer programs that have been developed

at Stanford University during the past few years as part

of my research on algorithms and on digital typography.

This language and its associated programs have come

to be known as the WEB system. My goal in what fol-

lows is to describe the philosophy that underlies WEB,

to present examples of programs in the WEB language,

and to discuss what may be the future implications of

this work.

I chose the name WEB partly because it was one of

the few three-letter words of English that hadn’t al-

ready been applied to computers. But as time went on,

I’ve become extremely pleased with the name, because

I think that a complex piece of software is, indeed, best

regarded as a web that has been delicately pieced to-

gether from simple materials. We understand a compli-

cated system by understanding its simple parts, and by

understanding the simple relations between those parts

and their immediate neighbors. If we express a pro-

gram as a web of ideas, we can emphasize its structural

properties in a natural and satisfying way.

WEB itself is chiefly a combination of two other lan-

guages: (1) a document formatting language and (2) a

programming language. My prototype WEB system uses

submitted to THE COMPUTER JOURNAL 1

---

D. E. KNUTH

TEX as the document formatting language and

PAS-

CAL

as the programming language, but the same prin-

ciples would apply equally well if other languages were

substituted. Instead of TEX, one could use a language

like Scribe or Troff; instead of

PASCAL

, one could use

ADA

,

ALGOL

,

LISP

,

COBOL

,

FORTRAN

,

APL

,

C

, etc.,

or even assembly language. The main point is that WEB

is inherently bilingual, and that such a combination of

languages proves to be much more powerful than either

single language by itself. WEB does not make the other

languages obsolete; on the contrary, it enhances them.

I naturally chose TEX to be the document formatting

language, in the first WEB system, because TEX is my

own creation;

1

I wanted to acquire a lot of experience

in harnessing TEX to a variety of different tasks. I chose

PASCAL

as the programming language because it has

received such widespread support from educational in-

stitutions all over the world; it is not my favorite lan-

guage for system programming, but it has become a

“second language” for so many programmers that it

provides an exceptionally effective medium of commu-

nication. Furthermore WEB itself has a macro-processing

ability that makes

PASCAL

’s limitations largely irrele-

vant.

Document formatting languages are newcomers to

the computing scene, but their use is spreading rapidly.

Therefore I’m confident that we will be able to expect

each member of the next generation of programmers to

be familiar with a document language as well as a pro-

gramming language, as part of their basic education.

Once a person knows both of the underlying languages,

there’s no trick at all to learning WEB, because the WEB

user’s manual is fewer than ten pages long.

A WEB user writes a program that serves as the source

language for two different system routines. (See Fig-

ure 1.) One line of processing is called weaving the

web; it produces a document that describes the pro-

gram clearly and that facilitates program maintenance.

The other line of processing is called tangling the web;

it produces a machine-executable program. The pro-

gram and its documentation are both generated from

the same source, so they are consistent with each other.

TEX

TEX

−−−−→

DVI

WEAVE

WEB

TANGLE

PAS

−−−−→

REL

PASCAL

Figure 1. Dual usage of a WEB file.

Let’s look at this process in slightly more detail. Sup-

pose you have written a WEB program and put it into

a computer text file called COB.WEB (say). To gener-

ate hardcopy documentation for your program, you can

run the WEAVE processor; this is a system program that

takes the file COB.WEB as input and produces another file

COB.TEX as output. Then you run the TEX processor,

which takes COB.TEX as input and produces COB.DVI as

output. The latter file, COB.DVI, is a “device-independent”

binary description of how to typeset the documenta-

tion, so you can get printed output by applying one

more system routine to this file.

You can also follow the other branch of Figure 1, by

running the TANGLE processor; this is a system program

that takes the file COB.WEB as input and produces a new

file COB.PAS as output. Then you run the

PASCAL

com-

piler, which converts COB.PAS to a binary file COB.REL

(say). Finally, you can run your program by loading

and executing COB.REL. The process of “compile, load,

and go” has been slightly lengthened to “tangle, com-

pile, load, and go.”

C. A COMPLETE EXAMPLE

Now it’s time for me to stop presenting general plat-

itudes and to move on to something tangible. Let us

look at a real program that has been written in WEB.

The numbered paragraphs that follow are the actual

output of a WEB file that has been “woven” into a doc-

ument; a computer has also generated the indexes that

appear at the program’s end. If my claims for the ad-

vantages of literate programming have any merit, you

should be able to understand the following description

more easily than you could have understood the same

program when presented in a more conventional way.

However, I am trying here to explain the format of WEB

documentation at the same time as I am discussing the

details of a nontrivial algorithm, so the description be-

low is slightly longer than it would be if it were written

for people who already have been introduced to WEB.

Here, then, is the computer-generated output:

Printing primes: An example of WEB . . . . . . . . . . . . . . §1

Plan of the program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . §3

The output phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . §5

Generating the primes . . . . . . . . . . . . . . . . . . . . . . . . . . §11

The inner loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . §22

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . §27

1.

Printing primes: An example of WEB.

The

following program is essentially the same as Edsger

Dijkstra’s “first example of step-wise program composi-

tion,” found on pages 26–39 of his Notes on Structured

Programming,

2

but it has been translated into the WEB

language.

[[Double brackets will be used in what follows to en-

close comments relating to WEB itself, because the chief

purpose of this program is to introduce the reader to

the WEB style of documentation. WEB programs are al-

ways broken into small sections, each of which has a

serial number; the present section is number 1.]]

Dijkstra’s program prints a table of the first thou-

sand prime numbers. We shall begin as he did, by re-

ducing the entire program to its top-level description.

[[Every section in a WEB program begins with optional

commentary about that section, and ends with optional

program text for the section. For example, you are now

reading part of the commentary in §1, and the program

text for §1 immediately follows the present paragraph.

Program texts are specifications of

PASCAL

programs;

they either use

PASCAL

language directly, or they use

angle brackets to represent

PASCAL

code that appears

2 submitted to THE COMPUTER JOURNAL

---