Literate Programming

LITERATE PROGRAMMING

by y

1

. . . y

n

. An error message is given if the m lines

replaced did not match x

1

. . . x

m

perfectly.

For example, the program PRIMES.WEB invokes a page

procedure to begin a new page; but page was not pres-

ent in Wirth’s original

PASCAL

and it is defined rather

vaguely in the

PASCAL

standard. Therefore a system-

dependent change may be needed here. A change file

PRIMES.CH could be made by copying the line

@d new_page==page

from Figure 2c and specifying one or more appropriate

replacement lines.

The program TANGLE itself contains about 190 sec-

tions, and a typical installation will have to change

about 15 of these. If you want to transport TANGLE

to a new environment, you therefore need to create a

suitable file TANGLE.CH that modifies 15 or so parts of

TANGLE.WEB. (Examples of TANGLE.CH are provided to

all people who receive TANGLE.WEB, so that each imple-

mentor has a model of what to do.) You need to insert

your changes by hand into TANGLE.PAS, until you have a

TANGLE program that works sufficiently well to support

further bootstrapping. But you never actually change

the master file TANGLE.WEB.

This approach has two important advantages. First,

the same master file TANGLE.WEB is used by everybody,

and it contains the basic logic of TANGLE that really

defines the essence of tangling. The system-dependent

changes do not affect any of the subtle parts of TANGLE’s

control structures or data structures. Second, when the

official TANGLE has been upgraded to a newer version,

a brand new TANGLE.WEB will almost always work with

the old TANGLE.CH, since changes are rarely made to

the system-dependent parts. In other words, this dual-

input-file scheme works when the WEB file is constant

and the CH file is modified, and it also works when the

CH file is constant but the WEB file is modified.

Change files were added to WEB about three months

after the system was initially designed, based on our

initial experiences with people who had volunteered

to participate in portability experiments. We realized

about a year later that WEAVE could be modified so that

only the changed parts of a program would (optionally)

be printed; thus, it’s now possible to document the

changes by listing only the sections that are actually

affected by the CH file that WEAVE has processed. We

also generalized the original format of CH files, which

permitted only changes that extended to the end of a

section. These two important ideas were among the

final enhancements incorporated into WEB83.

J. PROGRAMS AS WEBS

When I first began to work with the ideas that even-

tually became the WEB system, I thought that I would

be designing a language for “top-down” programming,

where a top-level description is given first and succes-

sively refined. On the other hand I knew that I of-

ten created major parts of programs in a “bottom-up”

fashion, starting with the definitions of basic proce-

dures and data structures and gradually building more

and more powerful subroutines. I had the feeling that

top-down and bottom-up were opposing methodologies:

one more suitable for program exposition and the other

more suitable for program creation.

But after gaining experience with WEB, I have come to

realize that there is no need to choose once and for all

between top-down and bottom-up, because a program

is best thought of as a web instead of a tree. A hi-

erarchical structure is present, but the most important

thing about a program is its structural relationships. A

complex piece of software consists of simple parts and

simple relations between those parts; the programmer’s

task is to state those parts and those relationships,

in whatever order is best for human comprehension—

not in some rigidly determined order like top-down or

bottom-up.

When I’m writing a longish program like TANGLE.WEB

or WEAVE.WEB or TEX.WEB, I invariably have strong feel-

ings about what part of the whole should be tackled

next. For example, I’ll come to a point where I need to

define a major data structure and its conventions, be-

fore I’ll feel happy about going further. My experiences

have led me to believe that a person reading a program

is, likewise, ready to comprehend it by learning its var-

ious parts in approximately the order in which it was

written. The PRIMES.WEB example illustrates this prin-

ciple on a small scale; the decisions that Dijkstra made

as he composed the original program

2

appear in the WEB

documentation in the same order.

Top-down programming gives you a strong idea of

where you are going, but it forces you to keep a lot of

plans in your head; suspense builds up because noth-

ing is really nailed down until the end. Bottom-up

programming has the advantage that you continually

wield a more and more powerful pencil, as more and

more subroutines have been constructed; but it forces

you to postpone the overall program organization until

the last minute, so you might flounder aimlessly.

When I tear up the first draft of a program and start

over, my second draft usually considers things in almost

the same order as the first one did. Sometimes the

“correct” order is top-down, sometimes it is bottom-

up, and sometimes it’s a mixture; but always it’s an

order that makes sense on expository grounds.

Thus the WEB language allows a person to express

programs in a “stream of consciousness” order. TANGLE

is able to scramble everything up into the arrangement

that a

PASCAL

compiler demands. This feature of WEB

is perhaps its greatest asset; it makes a WEB-written

program much more readable than the same program

written purely in

PASCAL

, even if the latter program is

well commented. And the fact that there’s no need to

be hung up on the question of top-down versus bottom-

up—since a programmer can now view a large program

as a web, to be explored in a psychologically correct

order—is perhaps the greatest lesson I have learned

from my recent experiences.

Another surprising thing that I learned while using

WEB was that traditional programming languages had

been causing me to write inferior programs, although I

hadn’t realized what I was doing. My original idea was

that WEB would be merely a tool for documentation, but

I actually found that my WEB programs were better than

the programs I had been writing in other languages.

How could this be?

submitted to THE COMPUTER JOURNAL 11

---