Literate Programming in Lisp

Literate programming
Literate programming (LP) is the practice of writing code and documentation as an integrated whole, with the view that computer programs are not only for implementation, but also communication. Typically, a programmer writes the program and documentation in a single file, usually interweaving the two in a meaningful way, then uses an LP tool such as noweb to produce either the documentation (with embedded code) or the code, which can then be compiled and run. The source file has a set of markup conventions that tell the LP tool how to typeset the documentation, usually producing output in a typesetting language such as LaTeX.

Interpreted languages
The usual model of literate programming, while very good for compiled languages, such as C, does not fit how users of interpreted languages, such as Lisp and Python, create, debug, and maintain code. An interpreted language facilitates rapid prototyping and incremental development in part by allowing portions of the program to be written or modified and evaluated by the interpreter separately from the rest. Typically, a programmer using an interpreted language will make changes to the source code and evaluate only the changed parts – often directly from the file being changed, and often only a small portion of that file. Source-level debuggers and other parts of the language’s integrated development environment (IDE) interact with the interpreter, the programmer, and the source file as well to help quickly identify and correct errors. In such an environment, injecting the additional step of untangling the LP source file to produce a Lisp or Python source file is cumbersome and counterproductive.

The LP/Lisp (Literate Programming for Lisp) project is an implementation of a literate programming tool for Lisp, implemented in Lisp. The Lisp source file is the LP source file: documentation lives in the comments. However, LP/Lisp is more than simply a comment extract-and-prettify program. It has most of the features of other LP tools to mark up documentation, reorder the source code and other “chunks” in the documentation, and so forth. The result is an LP system that seamlessly works with the way programmers interact with interpreted languages.

LP/Lisp is a project of the Maine Software Agents/Artificial Intelligence Laboratory (MaineSAIL).