Lambda the Ultimate

Scribble: Closing the Book on Ad Hoc Documentation Tools. Matthew Flatt, Eli Barzilay, and Robert Bruce Findler. ICFP '09.

Scribble is a new system for writing library documentation, user guides, and tutorials. Scribble builds on PLT Scheme’s technology for language extension, and at its heart is a new approach to connecting prose references with library bindings. We have built Scribble libraries that support standalone documentation and papers, JavaDoc-style API documentation, and literate programming. Thanks in large part to Scribble’s flexibility and the ease with which we can cross-reference information across different levels, the documentation that is distributed with PLT Scheme now runs into the thousands of pages. This paper reports on the use of Scribble and on its design as both an extension and extensible part of PLT Scheme.

This introduces a cute and well thought out syntax for writing technical prose and for escaping back into the PL for typesetting operations and cross-references to PL values. It looks reminiscent of TeX, but has a direct transformation to S-expressions. Scribble also makes great use of PLT Scheme's modular and polyglot programming facilities.

A nice twist on the classic Scheme ploy:

A documentation language should be designed not by piling escape conventions on top of a comment syntax, but by removing the weaknesses and restrictions of the programming language that make a separate documentation language appear necessary. Scribble demonstrates that a small number of rules for forming documentation, with no restrictions on how they are composed, suffice to form a practical and efficient documentation language that is flexible enough to support the major documentation paradigms in use today.

(P.S. To which I'd like to add, somewhat OT, that compared to PLT Scheme, Common Lisp is starting to look teeny.)