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:
- The warp phase translator, litprog.xsl.
- The weft phase translators, lit2html.xsl and
lit2tex.xsl.
- The Document Type Definition file for literate programs
written in XLP, litprog.dtd.
- and finally, the literate program itself, used to
generate all the above documents: xlp.xlp
- 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
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.
This is a multithreaded Python program to display a
background or "root" image under various constraints.
I found that my makefiles were getting out of control a bit,
so I rationalised them all into this
one literate program.
I have written a
Python program
that generates web page photo albums.
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.
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.
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 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.
-
sawfish
-
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
-
Axe is a program written by me to translate XML files to
arbitrary output formats. It is described further in the
documentation.
-
process
-
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.
-
assoc
-
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.
-
noweb
-
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.
-
nutweb
-
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.
