Literate programming on a team project

Abstract

We used literate programming on a team project to write a 33,000 line program for the Synthesizer Generator. The program, Penelope, was written using WEB, a tool designed for writing literate programs. Unlike other WEB programs, many of which have been written by WEB's developer or by individuals, Penelope was not intended to be published. We used WEB in the hope that both our team and its final product would benefit from the advantages often attributed to literate programming. The WEB source served as good internal documentation throughout development and maintenance, and it continues to document Penelope's design and implementation. Our experience also uncovered a number of problems with WEB.

Software documentation with markdoc 5.0

“…Therefore, programs that facilitate writing and updating documentation, such as Javadoc (Kramer 1999;Leslie 2002) and Doxygen (van Heesch 1997), are favorable. These programs implement a procedure called literate programming (Knuth 1992;Cordes and Brown 1991;Ramsey and Marceau 1991;Leisch 2002). In this approach, the documentation is written within code files using special comment signs.…”

Rethinking Literate Programming in Statistics

“…Software engineers advocate literate programming because it eases the effort needed to update the software documentation and it makes the source more comprehensible for maintenance programmers. In addition, it preserves the connection between the code and the documentation (Sametinger and Pomberger 1992;Ramsey and Marceau 1991;Cordes and Brown 1991), although its applications are not merely limited to software documentation (Shum and Cook 1994;Ruys and Brinksma 1998).…”

Theme-based literate programming

“…Although research suggests [71,20] suggest that LP is an effective means for software development, and can help to reduce the learning curve required to understand programs, the wider programming community has been reluctant to adopt LP. This in itself does not suggest that LP is an ineffective programming medium.…”

“…Ramsey and Marceau [71] note that the "difficultly reading the source and the marked difference between source and listing complicate editing". Some LP tools place great emphasis on the final document's presentation.…”