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: noweb and cweb.
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.
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.
© 2007 Scott Prahl