LP/Lisp
What is LP/Lisp?
LP/Lisp is a software tool to provide literate programming support for Lisp programmers. Literate programming is the idea that the code and the documentation for a program should form a coherent whole, a work of literature with two audiences, the computer and humans. The idea was originated by Donald Knuth, who created the WEB system (using TeX and Pascal). This has been expanded upon since then, with literate programming (LP) tools such as cweb, fweb, noweb, and so forth.
Unfortunately, the model used by these tools is not the one we usually use when programming in Lisp. Since we don’t have a write-compile-execute cycle with Lisp, these tools inject an artificial step into the process, interfering with the natural way Lisp is used.
LP/Lisp is a new LP tool that is meant to allow Lisp programmers to use LP without interfering with the normal way they program. The LP file is the Lisp file itself. Documentation and LP markup reside in the comments. Markup exists to do the usual LP-like things (definition of and reference to chunks of code, syntactic sugaring for sections and formatting, etc.). The documentation is stripped out of the comments by LP/Lisp, with code reordered and formatted as needed, to form a LaTeX file.
There have been other approaches to LP in Lisp as well (e.g., CLWEB, Scribble, pbook, etc.). These are discussed in the technical report listed below.
What is written about it?
- LP/Lisp: Literate programming for Lisp, Roy M. Turner, in Proceedings of the International Lisp Conference (ILC), Reno, NV, 2010.
- Literate Programming in Lisp: LP/Lisp, Roy M. Turner (2010). Technical report 2010-02, Department of Computer Science, University of Maine, 5752 Neville Hall, Orono, ME 04469-5752.
What is available now?
The Lisp code is available here. It has only been tested under Allegro Common Lisp, and it is unlikely to work under other Lisps at the moment, since it requires ACL’s regexp2 package. See below.
A very simple variant is also available that piggybacks on Emacs’ Org Mode’s literate programming capabilities. While one can set up an Org Mode file to function as a literate programming source file (including executing embedded source blocks, etc.), it’s not useful for general distribution (e.g., to those not using Org Mode). Consequently, the simple variant of LP/Lisp just translates Org Mode files into Lisp and vice versa, with Org content embedded in Lisp comments when translating to Lisp and with Lisp in Org Mode code blocks when translating the other direction. The simple variant is also available here and should work on most Common Lisps.
What is coming?
The next version is in the works, but progress is very slow. It will fix some of the syntax oddness of the current version, and it will work in multiple Lisps. It will be a complete, object-oriented rewrite. An alternate, more Lisp-y, syntax will be supported as well. It will be posted here when it’s ready. But I wouldn’t hold my breath, if I were you! ☺
Stay in touch
If you are using LP/Lisp, drop me a line to let me know, so I can send you mail when there are changes, the next version is ready, etc. Also let me know of bugs you discover or features you would like to see–this isn’t my primary project by a long-shot, but I’ll try to respond as soon as possible!
Thanks for your interest in LP/Lisp, and I hope it is useful for you.