Next / Previous / Contents / Shipman's homepage

17. Literate programming with DocBook

Literate programming is a venerable technique invented in the early 1980s by Don Knuth.

There are four approaches to documenting programs:

Lightweight literate programming is a simplification of Knuth's approach: instead of Knuth's cweb tool, you write your documentation and source code using a regular word processing system.

If you use DocBook as described in this document, you can easily embed source code for later extraction and use. Encode each fragment in a programlisting element with this general form:

<programlisting role='outFile:F'>
    your source code here    
</programlisting

where F is the name of the file to which you want this fragment written.

Here is an example. Suppose you are writing a C program that consists of two files, a header file named foo.h and a source code file named foo.c. Part of your XML documentation for this program might look like this:

<programlisting role='outFile:foo.h'>
    stuff to be written to foo.h
</programlisting>
   ...
<programlisting role='outFile:foo.c'>
    stuff to be written to foo.c
</programlisting>

If you name the same output file in more than one programlisting section, all the fragments will appear in the output file in the same order in which they occur in your document.

Once you have encoded your program in this way, you will build the HTML and PDF renderings in the usual way. To extract the code from the DocBook XML file, see : A source extractor for lightweight literate programming.

If you are using the Unix make application to build files in your document, see Section 19.2, “make-lit: A Makefile for literate programming”.

17.1. Controlling spurious blanks and blank lines

Every character after the opening <programlisting> tag, up to the closing </programlisting> tag, is written to the file. Hence, if the opening tag is on the line before the first line of your program fragment, the content written to the output file will start with an empty line.

Also, if your closing </programlisting> tag is indented, the output will include the indentation whitespace.

To avoid these extra spaces, move the closing “>” of the opening tag to just before the first line of your fragment, and place the closing tag in column 1 of your DocBook source file.

For example, here is how a two-line bash script must be encoded so that only these two lines will appear in the output. Suppose your XML is currently indenting four spaces in this section.

    <para>
      Here is the <code>whereami</code> script:
    </para>
    <programlisting role='outFile:whereami'
>#!/bin/bash
echo $HOSTNAME
</programlisting>
    <para>
      etc.
    </para>
    ...