DBLP: DocBook-based Literate Programming

DBLP provides an extension of the SGML DocBook DTD and DSSSL scripts that together allow computer programs to be written and documented using the rich descriptive language of the DocBook markup scheme. This style of programming is called literate programming, and was pioneered by Professor Donald Knuth of Stanford University.

The DBLP core consists of a set of extensions to the SGML DocBook DTD. These extentions provide attributes on the <programlisting> to allow for file output sections, definition sections, and the continuation of sections across multiple scraps.

Additionally, DBLP includes implementations in DSSSL of both "tangle" (creation of computer usable source code) and "weave" (creation of human readable documentation) processors. These style sheets are based on James Clark's JADE DSSSL processor and, in the case of the "weave" part, Norman Walsh's Modular DocBook Style Sheets. The "tangle" processor depends on the specific implementation of Jade in that it makes use of some of JADE's extensions to the basic DSSSL system. These implementations are functional in themselves (DBLP itself has been written in DBLP since version 2.0), and also serve as examples of writing "tangle" and "weave" processors for the DBLP DTD.

The current version of DBLP is documented here; the documentation includes a description of the goals and background of literate programming in SGML. The system can be obtained as follows:

In all cases, you will need an appropriate SGML system such as Jade (see below).

The revision history of the system is available here .  Note that it includes versions which were not released, as it is simply a copy of the rlog output. and RCS saved versions do not necessarily correspond to released versions.

Style Sheets

The DSSSL style sheets included in DBLP are minimal customizations of DocBook. As such, they include no customizations of the actual output style. An example of further customization, the style sheet dblp.dsl is an example of what can be done. This style sheet is the one actually used to produce the DBLP documentation.

The dblp.dsl style-sheet is constructed using Norman Walsh's DTD for literate programming of DSSSL style sheets. The basic DTD for this is included in the DocBook distribution (although some minor modifications were needed to make it usable with DocBook 4.1; it appears to have been written for one of the 3.x versions and not updated). This makes it interesting as a literate program itself based on DocBook. The method used, however, does not appear generalizable to other programming languages, since it is based on the fact that a DSSSL style sheet is itself an SGML document, which is not generally true of other programming languages.

Historical Notes

The DBLP system was originally written in nuweb.  For historical reasons, the woven output of the last nuweb version is retained in dblp.pdf; you maay be interested in comparing the current version with that older version.

The original "proof of prinicple" experiment which demonstrated that the concept of creating a simple SGML/DSSSL literate programming system was practical (at my level of programming skill) is documented here, with the nuweb literate programming source also available.

Mailing List

There is a mailing list intended to support DBLP users.  To subscribe, send a message with the body "SUBSCRIBE DBLP" to <maiser@astrid.upland.ca.us>.  At this point, this is a very low volume list.

The author can be contacted at <mark@astrid.upland.ca.us>.

Useful Links

This page last updated 23 April 2001