Literate Programming: the book

Donald Knuth's book Literate Programming is a collection of articles about what he did in the the TexBook and in various other programs. I read it around 1995, while working on qdoc, and thought it was terribly naïve. I reread it in portions this year (the same copy, which found its way to me from Trolltech's once-extensive library — better to me than wherever Nokia is going) and this time I wanted to write down my thoughts. I wish I'd had a blog in 1995.

The book is all about writing two things at the same time, in two separate languages, not connected, merely adjacent in a single file. 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 other languages obsolete; on the contrary, it enhances them. (p101) Yes, no, no. WEB does not enhance either of the two languages (relevantly, at least). The Τεχ source is just that, it doesn't receive anything from WEB. You cannot access the list of Pascal variables in the Τεχ part, nothing in Pascal is visible to either the WEB or the Τεχ processors.

The other language is invisible to the Τεχ source. That's why WEB is correctly described as inherently bilingual. (WEB is Knuth's top-level language, TANGLE produces compilable Pascal from WEB and WEAVE produces a text in Τεχ format.)

The example starting on page 144 shows how the WEB sections link to each other. The section which defines the global variables has links to sections that define more globals, and to the point where the definitions are inserted. All that is inside WEB. But there are no links to the sections that use each variable. That's because variables are used only in the Pascal parts of the source, and the Pascal parse tree is inaccessible when the exposition (documentation) is generated.

I find it very comfortable to write about code without having to change into a different editor. Over to Word or even Powerpoint, back to Visual Studio. And I also agree that a combination is more powerful, but Knuth's book does little to explit the power. He doesn't mention bilingual error diagnostics or any kind of difference analysis (that was extremely valuable at Trolltech), and in many cases it's possible to generate various special sections automatically (such as this API overview page) and generate text output from mixed sources (such as in the Qt tutorial). All WEAVE does is really to generate something like the Τεχbook, and leaves much undone.

The third great benefit is one Knuth understands and describes: There are many senses in which a program can be considered good, of course. In the first place, a program is especially good if it works correctly. Secondly, a program is often good if it is easy to change, when the time for adaptation arises. Both of these goals are achieved when the program is easily readable and understandable to a person who knows the appropriate language. Well put. Knuth writes better than I.

But I doubt it's really so adaptable. The tool does nothing to discourage the material written in the the two languages creeping apart as time passes, and in my experience that's lethal. Code review would help, but Knuth's book doesn't mention it.

A pedantic note. Despite what I wrote above, WEB does improve on some deficiencies of Pascal, such as allowing variables to be declared near their first use instead of all in a single block. I consider that relevant to Pascal and not relevant to either WEB or to literate programming, so I don't regard it as a significant feature.