xmLP - Literate Programming in XML

Last updated: 11 August 2000
Version: Alpha 0.1
Comments to: tony.coates@reuters.com

"Literate programming"[1] is a programming method where the various code sections are written inside a descriptive document, and appear in the order that makes them easiest for humans to understand. More typically, computer programs are written in the order that makes them easiest for computers to interpret, and comments in the code are insufficient for anyone (even the author) to clearly understand the intention and the workings. Note that while comment-based documentation generators like Javadoc do a good job of providing a hyperlinked way of navigating a large API, they are not literate programming tools.

Previous literate programming tools[3] have generally used their own custom markup formats (the exception being SWEB[3], which uses SGML), and produced documentation in TEX or LATEX which could then be viewed with a DVI viewer, or converted to PostScript, or perhaps converted to PDF (Acrobat). Eventually, some tools also offered HTML output, but the problem of each tool have its own document markup codes continued.

The xmLP tool demonstrates how XML can be used to convert any underlying document into a literate program. At present, xmLP uses a small number of XML tags which can be included in any XML document. The supplied sample shows the xmLP tags embedded in an HTML document (which could just as easily be an XHTML document or a DocBook document).

xmLP is heavily influenced by FunnelWeb[3], which is language-independent. FunnelWeb views all source code as plain text which is to be assembled into one or more source code files. This proves to be advantageous if you need to embed multiple file types in a document (e.g. source code + text resources).

xmLP consists of just two XSLT scripts: "xmLPtangle.xsl" is used to "tangle" (generate the source code), while "xmLPweave.xsl" is used to "weave" (generate the documentation - see example).


  • This is alpha software, so anything and everything may change without notice.
  • <