Literate programming

Reviewer: Olivier Louis Marie Lecarme

Any paper authored by Knuth is worth reading, and often entertaining, even when somewhat irritating. This one is exactly in that mood, as exemplified by its provocative title. The paper describes and assesses, mainly by way a long example, a programming language and documentation system called WEB. Input text contains both a complete program and its documentation in a disciplined and systematic form. Depending upon the system component into which this text is fed, the output is a source PASCAL program, ready to be compiled into an executable program, or a source T EX text, ready to be compiled into a phototypesetter script. The sections are as follows: introduction, the WEB system, a complete example, how the example was specified, the tangled output (the PASCAL text), the woven output (the T EX text), additional bells and whistles, Occam's razor (WEB macros), portability, programs as webs, stylistic issues, econimic issues, related work, and retrospect and prospects. The paper is phototypeset using the WEB system (of course). It is very well presented, although somewhat too sumptuous in its use of various fonts, as is generally the case in texts typeset by programmers instead of typographers. Using at least ten different fonts in a 15:Upage text is really too much. However, the paper is very easy and pleasant to read, and almost free of typos. On the positive aide, I found the whole idea extremely interesting and fruitful. Since the program is hidden in its documentation, it becomes impossible to modify it without changing the documentation at the same time. (In fact, the program is a byporduct of the documentation.) More importantly, in my opinion the order in which the program is designed and written no longer needs to be related to the order in which it will be compiled. What is good for a compiler is not necessarily good for a programmer, and vice:Uversa. It is time to consider as abvious that the text by the compiler is the result of come preprocessing (collecting scattered pieces, reordering them, macroprocessing, etc.) Another very important point is that the WEB idea is entirely independent independent of the supporting languages: T EX and PASCAL in this case, but TROFF/NROFF and C in another experiment. On the negative side, most offensive is the lack of readability and writeability of the input text: to be forced to write character sequences like :02\def\]{$]\]]$\}” is really unbearable. The blame mainly lies with T EX, but TROFF/NROFF would not be better. As demonstrated by Knuth's unfortunate choice of MIX in his opus magnum, he is not really interested in the cosmetics of the support languages of his worke. Here the difficulty is incoreased by the extreme dissimilarity between input and output. In order to modify the output result, users must modify something unreadable and very far from the result they see. This is a customary problem in most text processing systems, although there exist at least three possibilities: the input text is the reference text, upon which all modifications are made; (2) the output text is the reference text, and modifications are made in terms of pages, columns, sections, paragraphs, sentences, words, etc.; and (3) input and output are very similar, the visible structure of the input text being the natural way to describe the final appearance of the output text. Solution 3 is extremely infrequent, although the easiest to use. Solution 2, equally infrequent, has at least the immense merit of uniformity. Solution 1 is presently the rule in text processing systems, simply because it is easier to implement and does not necessitate a specialized text editor; but this is really unfortunate. Another important shortcoming of WEB, which is in fact inherent in the idea, is that the graph structure of the program and of its documentation is hardly visible, although this structure would be the best tool for mastering program complexity. Maybe this is the major point where an improvement would be needed. Finally, it is regrettable that phototypeset output is so slow and expensive that the user normally does not work on an up:Uto:Udate version of the output text, or uses the unreadable input as the support of modifications. This inconvenience is strongly related to the criticism I made about the distance between input and output forms. Here too, much progress has to be done in text processing. It is time that designers take interest in less primitive input languages, and find idea other than interspersing unreadable code sequences among the material to be typeset.