Programs must be written for people to read, and only incidentally for machines to execute.
|-- Structure and interpretation of computer programs, Harold Abelson and Gerald Jay Sussman, p. xvii|
By literate programming, we mean programs that are intended to be readable. The idea comes from Dr. Donald E. Knuth and has a long history. For background, see the Literate Programming web site.
cweb system interweaves narrative about the
program with the actual source code of the program. One then
runs a tool named ctangle to generate
the source code and a different tool named
cweave to generate the online
The present effort was inspired by similar efforts of Dr. Allan M. Stavely, who suggested using DocBook as a general framework for literate programming. Refer to Writing documentation with DocBook-XML 5.0 for more information on DocBook.
Stavely's idea was to use DocBook's existing
programlisting element to hold the program
fragments, using the application-reserved
attribute to that element to distinguish executable source code
from other uses of the
This means that the regular processing of DocBook into HTML and
PDF forms is the equivalent of Knuth's
The remaining half of the problem, the extraction of the executable code from the DocBook source file, is the subject of this document.
The litdocbook5 script is embedded in this document. Relevant online files include:
See also the author's literate programming site for more discussion of the practice and several dozen examples in assorted languages and sizes.