Literate Programming

LITERATE PROGRAMMING

\input webmac

\font\ninerm=cmr9

.

.

.

syntactically correct \PASCAL\ program will

be obtained.\]

\Y\P$\4\X2:Program to print the first

thousand prime numbers\X\S$\6

\4\&{program}\1\

\37$\\{print\_primes}(%

\\{output})$;\6

\4\&{const} \37$\|m=1000$;\5

\X5:Other constants of the program\X\6

\4\&{var} \37\X4:Variables of the program\X\6

\&{begin} \37\X3:Print the first \|m prime

numbers\X;\6

\&{end}.\par

\U section~1.\fi

.

.

.

The first three macro definitions here are

parametric; the other two are simple.\]

\Y\P\D \37$\\{print\_string}(\#)\S\\{write}(%

\#)$\C{put a given string into the %

\\{output} file}\par

.

.

.

\inx

\:{Bertrand, Joseph, postulate}, 21.

\:\\{boolean}, 15.

.

.

.

\:\.{WEB}, 1.

\:\\{write}, 6.

\:\\{write\_ln}, 6.

\:\\{ww}, \[5], 6.

\fin

.

.

.

\:\X4, 7, 12, 15, 17, 23, 24:Variables of

the program\X

\U section~2.

\con

Figure 4. TEX program generated from the WEB file.

a few features that do not show up in the PRIMES ex-

ample considered above:

1) There are facilities to override WEAVE’s automatic for-

matting of

PASCAL

programs. For example, it is pos-

sible to force a statement to begin on a new line, or to

force several statements to appear on the same line, or

to suggest a desirable breakpoint in the middle of a long

expression. In unusual cases, WEAVE must parse pro-

gram fragments that are not syntactically complete—

for example, there may be a begin without a matching

end—so a WEB user must be given a chance to control

the results. Furthermore there is a facility for chang-

ing WEAVE’s formatting rules by declaring that a cer-

tain identifier should be treated as a certain

PASCAL

reserved word, or by declaring that a certain reserved

word should be treated as an ordinary identifier.

2) There is a way to force TANGLE to omit a space be-

tween two adjacent pieces of text, so that a name like

‘x3 ’ can be manufactured from ‘x’ and ‘3 ’. Similarly,

there is a way to pass an arbitrary sequence of char-

acters through TANGLE so that the same sequence will

appear “verbatim” in the

PASCAL

file; and there is a

way to force beginning-of-line in that file. The latter

extensions have proved to be necessary to deal with

various nonstandard conventions of different

PASCAL

compilers. When a comment in braces is sent to the

PASCAL

file, TANGLE is careful not to introduce further

braces inside the comment.

3) There are facilities for octal and hexadecimal con-

stants in WEB thees. TANGLE converts such constants to

decimal form; WEAVE gives them an appropriate typo-

graphic treatment.

4) There is a facility for dealing with alphabetic con-

stants. When a program contains a double-quoted char-

acter like "A", TANGLE converts this to an integer be-

tween 0 and 127 that equals the corresponding

ASCII

code (in this case 65). The use of

ASCII

code facilitates

the construction of software that is readily portable

from one machine to another, independent of the ac-

tual character set in use.

5) Furthermore, if a double-quoted constant is a string

of several characters, like "cat", TANGLE converts it into

a unique integer that is 128 or more. A special string

pool file is written, containing all of the strings that

have been specially encoded in this way. I have used

this general mechanism only in large programs, but

experience has shown that it makes quite a nice sub-

stitute for the string-processing capabilities that

PAS-

CAL

lacks. (Incidentally, I noticed after several months

that a program needs to have some indication that the

string-pool file it is reading contains the same strings

that TANGLE generated when the program itself was tan-

gled. Therefore a “check sum” is included in the string

pool file; each program is able to refer to its own check

sum and to compare it with the value in the file. This

check-sum extension was one of the last features to be

added to WEB.)

6) The PRIMES example illustrates macros with param-

eters and macros without parameters. WEB also allows

“numeric” macros, which are small integer constants;

TANGLE is capable of doing simple arithmetic on such

constants. This feature of WEB was introduced specifi-

cally to overcome

PASCAL

’s unfortunate inability to do

compile-time arithmetic. For example, it is impossible

to have a

PASCAL

array whose bounds are ‘0 . . n − 1’,

or to write ‘20 + 3 :’ as the label of one of the cases in

‘case x + y’; WEB’s numeric macros make it possible for

TANGLE to preprocess such constants.

H. OCCAM’S RAZOR

I would also like to mention several things that were

intentionally left out of WEB, since I have tried to keep

the language as simple as I could.

There are no “conditional macros,” nor does TANGLE

evaluate Boolean expressions that might influence the

output. I found that everything I needed could be done

satisfactorily by commenting out the optional code.

For example, a system program is often designed

to gather statistics about its own operation, but such

submitted to THE COMPUTER JOURNAL 9

---