xmLP - A Literate Programming Tool for XML

Anthony B. Coates

Tony.Coates@reuters.com

xmLP & Literate Programming

xmLP is a literate programming tool written in XSL-T. It is heavily influenced by experience with FunnelWeb, a non-XML literate programming tool. Literate programming is about being able to getting away from having to write computer programs (or any other files for programmatic consumption) in a fashion that makes sense only to the compiler (or other applications) rather than to the humans, who really need to be the ones in charge of the process.

A literate program is a human readable document which is written and ordered so that it can be understood most easily by people. Source code fragments (or any text/XML fragments) can appear in the literate document in any order, and are assembled in the order required for computer use by tangling the document, to introduce the terminology of Donald Knuth, who came up with the idea of literate programming in the first place. The literate document is also woven to convert it into a final documentation format (traditionally TeX or LaTeX, but these days likely to be HTML or PDF).

xmLP differs from traditional literate programming tools when it comes to weaving. Traditionally, weaving involves both generating cross-reference information and producing formatted output. However, tools like XSL-T make it unnecessary for an XML literate programming tool to deal with display rendering. Hence the xmLP weaver is intentionally minimalist, and does nothing except add cross-reference information to the original literate document. This additional cross-reference information makes it much easier to build cross-reference hyperlinks using a simple rendering XSL-T stylesheet (rule of thumb: always try to separate business logic and display rendering into separate XSL-T stylesheets).

xmLP is released under version 2.1 of the Lesser GNU Public License.

Using xmLP

This first release is xmLP is very bare bones, and has almost no documentation. Documentation will come with a future release. However, the test files test-1-html.xml and doc-test-1.html should help. There are two main elements that xmLP requires to be embedded in an XML literate program:

  1. lp:macro is used to define a named xmLP macro (code fragment). It can contain either lp:text or lp:xml elements, but best practice is not to mix both within a single macro (or within the macros used to build a single file);
  2. lp:file is similar to a macro definition, but provides binding to a filename for use by the xmLP tangler.

The way that xmLP is used is:

  1. Write your XML literate program containing lp:file, lp:macro, etc.;
  2. Use xmLPtange.xsl (or xalan-tangle.xsl) to tangle your literate program and produce the raw source files;
  3. Use xmLPweave.xsl to add cross-reference information to your literate program;
  4. Use an XSL-T stylesheet (or other mechanism) to convert your woven literate program into a presentation format (e.g. (X)HTML, XSL-FO, RTF). An example is weave-xhtml.xsl.

Contents

README.html
This file.
lgpl-2.1.html
The licence. xmLP is released under the Lesser GNU Public License, version 2.1.
xmLPtangle.xsl
The xmLP tangler for XSL-T 1.1. This works with Saxon.
xalan-tangle.xsl
The xmLP tangler for Xalan.
xmLPweave.xsl
The xmLP weaver.
weave-xhtml.xsl
Sample XSL-T stylesheet for taking a woven XHTML+xmLP literate document and converting it into ready-to-display XHTML document. If you want to use this yourself, you may find it better to add your own XSL-T styling by applying a separate stylesheet before or after this one, rather than by editing this one (it's a little complicated only because it renders XML into a readable HTML format).
xmLPvalidate.xsl
Common validation code (sanity checking) used by xmLP.
xmLPcommon.xsl
Other common code used by xmLP during both tangling and weaving.
test-1-html.xml
Literate program used for regression testing. Also provides an initial sample of how xmLP constructs are used.
tangled-test-1-part-*.*
Tangled sources constructed from test-1-html.xml.
woven-test-1-html.xml
Modified version of test-1-html.xml with cross-references added by weaver. Note that the adding of cross-references will typically invalidate the DTD/Schema/etc. governing the original literate document, but this should be OK, as the woven form is just an intermediate form used to make it simpler to construct the final display transformation.
doc-test-1.html
The final woven and rendered documentation constructed from test-1-html.xml. Please use a browser with good CSS support (Netscape 4/6, IE 5/6, and Opera 5/6 should all be OK).
make.bat
A Windows batch file for running the regression tests. A Linux/Unix version will be provided in a future release.
build.xml
An "Ant" build file for the regression tests, which is currently specifies Apache Xalan directly. A more generic version with Saxon/Oracle XSL-T support will be provided in a future release.
bin (directory)
Contains Windows batch files used in running the regression tests. Linux/Unix versions of these scripts will be provided in a future release (but the scripts are so simple that you won't have trouble converting them anyway, and if/when you do, please donate a copy to the author).
css (directory)
Contains a sample CSS stylesheet for rendering xmLP-generated documentation in a colour-coded fashion in HTML.
dtd (directory)
Contains DTDs/modules which may be useful when writing xmLP literate programs using a DTD-sensitive editor. The module xmLP.mod contains the elements that xmLP expects and understands. However, xmLP does not require literate documents to be valid against this module or against any DTD/Schema/etc. The module is provided for convenience only.
expected (directory)
Expected output from the regression tests.

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.
  6. xmLP home page.

Last updated: 31st December, 2001.