Literate programming is a venerable technique invented in the early 1980s by Don Knuth.
There are four approaches to documenting programs:
No documentation at all. Common, but highly unprofessional.
Documentation separate from the program's source code.
Although almost any documentation is better than no documentation, this approach limits the toolkit of the documentation writer rather severely, bereft of tools for such features as figures and serious tables.
With literate programming, the program source code is inside the document, embedded within a narrative that explains the author's thought processes. This gives you the full toolset of your documentation system, and allows you to use pictures, diagrams and tables to explain your design.
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
element with this general form:
your source code here</programlisting
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:
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
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, “
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
tag is indented, the output will include the indentation
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
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>