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).

Notes

  • This is alpha software, so anything and everything may change without notice.
  • xmLP has only been tested with the Xerces XSLT engine. In the future, it is hoped to support all commonly-used XSLT engines.
  • xmLP currently uses a set of tags (elements) to define code sections. However, it would probably be better to use attributes rather than tags in the same way that XLink does. This will almost certainly happen in a future version.
  • xmLP currently lacks a user guide, but this will not happen until the tag versus attribute question is decided one way or another. Comments via e-mail are welcome.
  • xmLP currently treats all code sections as plain text (i.e. CDATA), similar to FunnelWeb. It would probably be useful to allow code sections which are actually XML (e.g. for XSLT stylesheets, XML schemas, or even XML encodings of existing programming languages), but this would require some restrictions, such as the code sections having to contain balanced XML (i.e. all open tags in a code section would have to have matching close tags, and vice-versa).

References

  1. www.literateprogramming.com
  2. Literate programming was first thought of by Donald Knuth, who has written a book about it. He wrote the first literate programming tool, WEB, which is Pascal-specific.
  3. To mention just some of the available literate programming tools:
    FunnelWeb, noweb, SWEB, WEB, CWEB, FWEB.
  4. Literate programming resources (in English) at LORIA.
  5. "xml-litprog-l" is an independent mailing list for discussion of literate programming using XML.

Download

This software is not a product. It is provided for demonstration purposes only. Reuters makes no guarantees, express or implied, and accepts no liability for consequences arising from the use of this software. You are welcome to use this software, but doing so is entirely at your own discretion and risk.

By downloading this software, you acknowledge your acceptance of the aforementioned terms and conditions.