Literate Programming is a system of programming pioneered by Donald Knuth that allows one to break programs into small chunks. Each chunk should be short enough (say less than ten lines of code) can be completely and clearly documented (html).

Literate Programming is a system of programming pioneered by Donald Knuth that allows one to break programs into small chunks. Each chunk should be short enough (say less than ten lines of code) can be completely and clearly documented. These chunks are assembled into a file and then run through a preprocessor to get either a documentation file (suitable for typesetting) or a just straight code.

A bunch of literate programming solutions exist, since there seems to be more interest in writing new literate programming systems than in actually using them. Everyone seems to have an opinion. Knuth’s ideas are set forth in an interview, a book, and published programs like the Stanford Graphbase. In my opinion only two systems are worth considering: noweband cweb.

noweb

noweb is an extensible system intended for a Unix environment written by Norman Ramsey. It is language independent and allows the creation of HTML documentation files automatically. Most people now use noweb. I really like the fact that chunks are numbered by page and then alphabetically by location on the page: “10c” refers to the third chunk on page 10.

I don’t use noweb because porting it to the Macintosh was hopeless. It is written in Icon and C. In fact, I was unable to get the existing noweb port for the Mac to work.

cweb

The philosophy behind CWEB is that programmers who want to provide the best possible documentation for their programs need two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself. But when both are appropriately combined, we obtain a system that is much more useful than either language separately. [Taken from the CWEB-3.0 User's Manual.] There are at least three variants of cweb available.

cweb

The original, canonical cweb by Donald E. Knuth and Silvio Levy. The cweb system consists a manual and the programs ctangle and cweave. No development is planned, but it is supported and bugs will still be fixed. It works and I use it.

cwebx

cweb was a translation of the original web system for Pascal. Something was lost in the translation. Marc van Leeuwen decided to rewrite it and add some rational features.

ctwill

ctwill was hacked by Donald Knuth and is an extension of cweave. It allows mini-indicies on every two page spread. This is great because every variable that is not defined on a two page spread is indexed and the relevant reference is available. It produces great documentation, at the cost of being a pain in the neck.

All this stuff is available your local TeX archive.

http://www.bme.ogi.edu/~prahl/

http://omlc.ogi.edu/software/lp/