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:
- 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);
- 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:
- Write your XML literate program containing lp:file,
lp:macro, etc.;
- Use xmLPtange.xsl (or
xalan-tangle.xsl) to tangle your literate
program and produce the raw source files;
- Use xmLPweave.xsl to add cross-reference
information to your literate program;
- 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
- www.literateprogramming.com
- 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.
- To mention just some of the available literate
programming tools:
FunnelWeb,
noweb,
SWEB, WEB,
CWEB,
FWEB.
- Literate programming resources (in English) at
LORIA.
- xml-litprog-l
is an independent mailing list for discussion of literate programming using
XML.
- xmLP home page.
Last updated: 31st December, 2001.