The purpose of 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 idea is that you do not document programs (after the fact), but write documents that contain the programs. [John Max Skaller]
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. We have a peer-reviewed journal article on the subject:
Stavely, Allan, Lynda Walsh, and John Shipman. Lightweight literate programming: a documentation practice. Technical Communication 55(1), Feb. 2008.
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 numerous 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 our local thesis style, documented in Writing a New Mexico Tech thesis with LaTeX. |
| LATEX | S | A LaTeX template for NMT Student Research Symposium Extended Abstracts |
| Python | S | Graphics transformations with homogeneous coordinates. Examples of matrix algebra using numpy, Numeric Python; includes formulas written in LaTeX. |
| Python | M | sidereal.py: A Python package for astronomical calculations |
| Python | S | A Python module to generate a Key Word In Context (KWIC) index |
| Python | S | homelist2: A Python script to generate a list of user homepages. Clickable list of all locally hosted homepages; uses the KWIC module. |
| Python | S | tracecase: Trace table coverage checker. |
| Python | S | manweb: A CGI script to display man pages |
| Python, Relax NG | S | The ISO 9573-2003 Unicode entity group. Demonstrates reading and writing XML. |
| Python | S | PathInfo: A file information object in Python. A small object-oriented systems programming example. |
| Python | M | huey: Internal maintenance specification. A sizeable Tkinter application for selecting colors and fonts. |
| Python, Relax NG | L | Blackboard 8.0 import tools: Imports Banner registration information into Blackboard and Moodle courseware systems. |
| Python | S | Python XML processing with lxml. Primarily a manual, but includes a literate module to help build XML files. |
| Python, XSL-FO | S | docbookindex: ID indexer for DocBook. Direct generation of PDF using XSL Formatting Objects. |
| Python, XSL-FO | S | listext2: A text file listing utility. More direct generation of PDF. |
| Python, XSL-FO | M | fohelpers: XSL-FO helper functions for Python. Used by docbookindex and listext2. |
| Python, XML | S | sox.py: Sequential output of XML for Python. For generating XML files too large to fit in memory. |
| 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 | 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 | 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, Tkinter | S | mazeratty: A rattier maze generator |
| 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. |
| XML, Relax NG, Python | M | xnomo3: A system for representing bird taxonomy. Infrastructure for many ornithology-related projects. The code is exihibited in xnomo3.py: Internal maintenance specification. |
| Python | M | nomcompile: Build a set of nomenclature files. Compiler for the bird taxonomy system. |
| Python, SQLAlchemy | M | pycbc: A Python interface to the Christmas Bird Count database. Demonstrates an object-relational database mapper. |
| Python, SQLAlchemy, CSS | M | Christmas Bird Count history report system. CGI front end for pycbc, generates a report showing the complete history of any circle or circles. |
| 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. |