Literate programming

Last week I was on holiday, cycling of course, and after a little bit of careful planning I found a hotel that had a Biergarten, free wifi and to top it all off: free wifi in the Biergarten. There was therefore little reason to reject an offer from Jan Wielemaker to write a paper on PlDoc, the literate programming environment he has developed for SWI-Prolog. My contribution to the paper was minimal, writing a user experience section, providing mental help, and correcting some typo's :-).

Literate programming is an old idea, Donald Knuth proposed, practiced and propagated it more than 30 years ago through his work on TeX. Knuth's original idea is simple: you write the source code along with the documentation in a single file. That file is handed to the compiler to generate the program and to a document processor to generate the documentation. I met Knuth at the University College London when I was an intern working on computer networks in 1977. He wanted access to the network so he could read his mail, and I helped out. A lot has changed since then, 30 years later you just turn on your portable in a Biergarten with wifi ...

I think there are several reasons for literate programming to take off for real. One is open source. Open source without documentation will simply die. The second is that the wiki style of writing web content mixes rather well with source code. Just insert the documentation as a comment in the source code. A third point, which Jan Wielemaker wanted to stress in the paper, is that programmers should actually reap the benefits of writing documentation immediately. PlDoc does this in a rather clever way, taking advantage of the interpretive nature of Prolog, once the source code file has changed both the program and the documentation are immediately updated.

I have started documenting the internals of tOKo using PlDoc and perhaps should quote Knuth what this feels like:

The literate programmer can be regarded as an essayist that explains the solution to a human by crisply defining the components and delicately weaving them together into a complete artistic creation.

As Jan pointed out while I was enjoying a Hefe Weizen reading the latest draft, tOKo consists of 321 modules with about 130,000 lines of code. Wonder how many lines there will be after becoming a fluent literate programmer.

Reference: Jan Wielemaker and Anjo Anjewierden. "PlDoc: Wiki style Literate Programming for Prolog", 17th Workshop on Logic-Based Methods in Programming Environments (WLPE 2007), Porto, 2007. Submitted.