Literate Programming Interests

What is Literate Programming?

Literate Programming is a technique developed by Donald Knuth, and described in his seminal paper in Computer Journal, 1984. It is both a software process and a suite of tools for supporting that process. Programs written as literate programs go through two (conceptually) independent processes known as tangling and weaving. Tangling creates the actual source code for input to a compiler; weaving creates a documentation file suitable for processing by a document system such as TeX.

More modern versions of literate program tools have attempted to decouple the N x M combinatorial explosion created by the choice of N programming languages and M documentation systems, by restricting the markup and presentational mechanisms. The tool currently in use in the work described here is such a tool: the markup of source documents is done in XML, and the documentation device is handled by XML translators. This reduces the problem from an N x M to an N + M one, where N = 1.

XLP: Literate Programming in XML

XLP is a literate programming tool developed from nuweb, and modified to develop XML code rather than LaTeX or HTML. I currently use it for a range of software that I use on a daily basis. Most of what follows has been written in XLP.

If you want to use XLP for yourself, then download this xlp.tgz file. (Use the Download Linked File pulldown on your rightmost mouse key.) It contains:

  1. The warp phase translator, litprog.xsl.
  2. The weft phase translators, lit2html.xsl and lit2tex.xsl.
  3. The Document Type Definition file for literate programs written in XLP, litprog.dtd.
  4. and finally, the literate program itself, used to generate all the above documents: xlp.xlp
  5. Also included are the TeX macro libraries used by the Tex weft phase: mytexMacros.tex, litprogverb.tex, crossref.tex; and the output documentation files xlp.html, xlp.tex, and xlp.pdf.
The last group of items are not specifically required for the literate programs themselves, but are used a) to convert the TeX output from the lit2tex.xsl translator, and b) to provide documentation of the literate programming suite itself.

To use the system, you will also need an XSLT translator program, such as XSLTPROC (available for download at XSLT C library for GNOME). Run

        xsltproc litprog.xsl xlp.xlp >xlp.xml
to perform the warp phase, and
        xsltproc lit2html.xsl xlp.xml >xlp.html
to perform the weft phase to generate HTML output, and
        xsltproc lit2tex.xsl xlp.xml >xlp.tex
        pdftex xlp.tex
to perform the weft phase to generate TeX and then pdf output. Note that the latter requires the TeX macros included in the above gzip file.

Current Projects in Literate Programming

Web Page Delivery

This is a Python program that handles all HTTP requests, calling XSLT translators as required on XML source pages, and delivering them to the client.

Root Image Display

This is a multithreaded Python program to display a background or "root" image under various constraints.

Make Files

I found that my makefiles were getting out of control a bit, so I rationalised them all into this one literate program.

My photo collection

I have written a Python program that generates web page photo albums.

My family web

I have written a Python program that explores the genealogical links between a collection of people. This operates against a database of XML files, one for each person.

My web appointment maker: ajhdiary

A web script that displays my current timetable, and allows the web user to book an appointment to see me. The complete literate program is available on-line.

The Unit Description avatar: MonAtar

This program is a web script that maintains unit description for the Faculty of Information Technology. Users are required to authenticate using the Monash Directory Service, and they can then edit and approve unit descriptions as appropriate. The complete literate program is available on-line.


Setup is a literate program to define all my login stuff. Login profiles and the like are programs that you need to keep coming back to, in order to revise them, perhaps several months since the last revision. Literate Programming does wonders for one's ability to pick up old programs were they were last left off, since with careful documentation, you can easily reconstruct the train of thought that led to the original design.


Emacs is such a fully featured editor that the options file for it needs careful management! This program describes how my .emacs file is created and maintained across a range of machines that I use. Much the same comments that I wrote above for setup apply here, particularly given the occasional nature of revisions and updates.

Previous Projects in Literate Programming

Literate Programming as an Aid in Marking Student Assignments

Literate Programming has been used in 2 third year subjects to handle the automatic processing and marking of student assignments. The paper Literate Programming as an Aid in Marking Student Assignments has details.

Obsolete Documents

These are documents that have not been brought up to date, consequently some of the links may not be operational.


I currently use sawfish as my Linux-based window manager. Like other sensible window managers, it allows a certain amount of customization, established through writing a Lisp-based configuration file. My Sawfish Configuration File is written as a literate program, because, like setup above, I edit it infrequently enough that I forget the program design, but frequently enough that relearning the design from scratch each time is very frustrating! Literate Programming allows one respite from that syndrome!


Axe is a program written by me to translate XML files to arbitrary output formats. It is described further in the documentation.

process is a procmail script that I have used in the past for filtering email. I've switched to an IMAP server, so this is now unused. But some people may find the documentation helpful.

This is a (literate) program that maintains a hierarchical database of information, with associated (hence the name) key words that allow retrieval of record information either by following a hierarchy, or by entering association terms.

The use of the program is described within this document.


I have rewritten the support macros for use with plain TeX under noweb. These allow indexing and cross referencing, in the same manner as the LaTeX versions written by Norman Ramsey. You can browse the code, but the source is currently inaccessible.


I have also rewritten nuweb from the CTAN archives to generate plain TeX output, rather than LaTeX. This is a rather subjective thing; I just happen to prefer to write my own macros, rather than use the LaTeX style.

Nutweb has been extended to allow side-by-side code and document sections ( v1.5), and parameterized macros (v1.6). The latest version 1.12 has a number of "improvements", including the specification of macro parameters on the command line. This feature allows multiple versions of the same software to be generated from the one literate program file.

Literate Programming for Napier

Napier is a persistent programming language that allows arbitrary program objects to outlive their creating environment. When such program objects are stored for any length of time, it is essential that related documentation be also retrievable at the same time that the object is retrieved. We have explored how best to do this, using the literate programming model.

Parts of the Napier system itself have been encoded as literate programs. See for example, the Magic component, written using noweb and presented using the html output format from noweb.

This page is copyright, and maintained by John Hurst. 0 accesses since
24 May 2022
My PhotoMy PhotoTrain Photo

Local servers: Localhost Newport Burnley Jeparit Spencer (accessible only on local network.)
Public Web Servers: (not all may be active.)
Dynamically generated at 20220524:1813 from an XML file modified on 20220106:0027, by version 1.4.7.

20220524:1813: MESSAGES GENERATED BY: /home/ajh/www/research/literate/index.xml

20220524:1813: b'warning: failed to load external entity "file:///home/ajh/local/"'
20220524:1813: b'warning: failed to load external entity "file:///home/ajh/local/"'
20220524:1813: b'No template for ajhwebdoc'

Please forward these details to John Hurst