Literate programming
Knuth's 1984 inversion: a program is written as an essay for a human reader, and the machine's copy is extracted from it afterwards. His statement of it, quoted in org-mode-literate-programming:
"Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do."
The author is meant to work "as an essayist, whose main concern is with exposition and excellence of style."
The two views, and the one that defines the technique
A literate-programming tool produces two things from one source file:
- Weaving — typeset prose with the code blocks marked up, for people.
- Tangling — a plain source file, for the compiler.
The load-bearing part is that these two can be in different orders. The author introduces ideas
to the reader in the order that explains them, and the tool reassembles the blocks into the order the
compiler needs, following named references between blocks. org-mode-literate-programming uses this
as the pass/fail line: tools that embed code in prose but cannot reorder it — Javadoc, Perl's POD,
Haskell's .lhs, and Sweave — are only partially literate, however well they do everything else.
The lineage
Knuth's own WEB (1984, Pascal → TeX) with its TANGLE and WEAVE programs; cweb (Knuth &
Levy 1994) for C; noweb (Johnson & Johnson 2000), which dropped the single-language assumption
and whose block-reference syntax org-mode later adopted verbatim. None of these three execute
anything — code is tangled out and handed to a compiler. Running the code inside the document is the
other tradition's idea (reproducible-research), and the two only met later.
Why the spoke holds it
It is the earliest member of the lineage this wiki keeps calling the "document that runs" — the thread from the memex through executable-markdown to LLM-maintained notes. Literate programming is the point where a file stops being about a computation and starts containing it, and it predates every tool on the tools-for-thought page by decades.
It also carries a diffusion story the spoke cares about. Forty years on, the technique is admired and little used. org-mode-literate-programming blames the tools — "typically prescriptive and difficult to use" — and argues that an adoption path with no cliff (edit plain text; add a code block when you want one) is what a literate system actually needs. That is a claim about how an idea spreads, not about whether it is good, and it is unmeasured.
Open
- Nobody in this corpus has counted anything here: no adoption figures, no evidence that literate code is better maintained, no cost estimate for writing it. The case has been argued from taste since 1984.
- Whether the notebook generation (Jupyter and its descendants) counts as literate programming or quietly dropped the reordering that defines it. The corpus has no source on this.
Related
reproducible-research · org-mode-literate-programming · org-mode · executable-markdown · tools-for-thought · wiki-compiler