The idea behind literate programming is to erase the distinction between source code and documentation. The author writes a single narrative, describing algorithms, data structures, and design philosophy, and the source code is embedded at appropriate locations in this narrative.
The primary early proponent of literate programming was Dr. Donald E. Knuth. For a good summary of the history and current work in literate programming, see the Literate Programming website.
The author was inspired by recent work of his colleague, Dr. Allan M. Stavely, in devising lightweight approaches to literate programming. In the author's current toolchain, the input is written in a slightly customized dialect of DocBook. Automated tools produce the two primary forms of output:
Following is a list of completed projects done by the author in the literate style, with comments about points of interest in that product. All these projects also use The Cleanroom software development methodology. Size code is S for small projects (under 500 lines); M for medium projects (500-2000 lines); L for larger projects.
| Language(s) | Size | Project |
|---|---|---|
| Python | S | rational.py: An example Python class: An abstract data type for rational numbers. |
| Python | M | A skip list container class in Python: An abstract data type for sorting and searching ordered sets in O(log n) time. |
| LATEX | S | NMT Thesis Stylesheet: Internals: Stylesheet for the Writing a New Mexico Tech thesis with LaTeX. |
| Python | S | manweb: A CGI script to display man pages |
| Python | S | PathInfo: A file information object in Python. A small object-oriented systems programming example. |
| Python | M | sidereal.py: A Python package for astronomical calculations |
| Python | S | Python XML processing with lxml. Primarily a manual, but includes a literate module to help build XML files. |
| Python | M | huey: Internal maintenance specification. A sizeable Tkinter application for selecting colors and fonts. |
| Python | S | FontSelect: A Tkinter widget to select fonts |
| Python | S | ScrolledList: A Tkinter scrollable list widget. Example of a compound widget. |
| Python | S | pageturner.py: A Tkinter widget for turning pages |
| XSL | S | Customization of the 4.3 DocBook XSL Stylesheets for the TCC |
| Python | S | homelist.py: A Python script to generate a list of user homepages. Clickable list of all locally hosted homepages. |
| Python | M | hwscan3 IMS: TCC processor inventory report. Web presentation of user equipment configurations. |
| Python | M | Webstats 4.0: Internal Maintenance Specification. Web-based report showing access statistics for locally hosted Web pages. |
| Python | M | Blackboard 8.0 import tools: Imports Banner registration information into the Blackboard courseware system. |
| Python | S | tccpage2.py: Dynamic generation of TCC-style web pages with lxml |
| Python | S | pyrang: A single-sourcing tool for Python-XML applications. Extracts tag and attribute names from an XML schema for use in Python scripts. |
| Python | S | Scanning objects for Python: Scan and Log. Support for small recursive descent compilers, and a base class for the Singleton design pattern. |
| Python | S | A sudoku solver: A study in recursive puzzle-solving. |
| Python | M | kkck: A solver for Kriss Kross puzzles. A more sophisticated puzzle solver combining iterative and recursive stages. |
| Python | M | Bird taxonomy system: internal maintenance specification. Infrastructure for many different ornithology-related projects. |
| Relax NG | S | A system for encoding bird field notes, using XML. |
| CSS Python |
M | noteweb: Rendering bird field notes for the Web. Generates my online birdwatching field notes. |
| Python | S | The abalist program: computing American Birding Association list totals. Bookkeeping for bird records. |
| Python | S | birdnotes.py: Objects to represent bird note files. Infrastructure for the above. |
| CSS Python |
M | catweb: A Web-based bird photo catalog. Your author is a birdwatcher and has thousands of catalogued bird photos. You can see thumbnails of all of them. |
| Relax NG Python |
S | An XML-based bird image cataloging system. Infrastructure for the above application. |
| Relax NG Python |
S | archx: A program to index a photo archive. |
| Python | L | IBP banding data system: Internal maintenance specification. A complete data entry application with multiple scripts. |
| e-lisp | M | IBP banding data system: emacs customizations. Emulation of certain IBM 029 keypunch functions in the emacs text editor. |