# Literate Programming [Wikipedia Link](https://en.wikipedia.org/wiki/Literate_programming) ( Type: Discipline ) ## Description A programming methodology introduced by Donald Knuth (WEB, 1981) that interleaves natural-language explanation with source code in the order that best serves a human reader, rather than the order a compiler requires — the code is "tangled" out of the document to run, and a readable document is "woven" out of it to publish. Its core concerns — code as narrative, output kept beside the reasoning that produced it, and a run being reproducible from the document itself — bear directly on how to keep interpretable/executable code like SuperCollider `.scd` sketches ([[Supercollider]]) documented inside this vault rather than as opaque links to an external repository. ## Key Tags #literate-programming #reproducible-research ## Essential Works - Knuth, Donald E. "Literate Programming." *The Computer Journal* 27.2 (1984): 97–111. - the founding essay coining the term and describing WEB - [Org Babel: literate programming](https://orgmode.org/worg/org-contrib/babel/) - the best-known contemporary implementation, already in reach via [[emacs]]'s Org mode ## Details %% add a brief description of the practice, and why it appears in my research. %% ### Notes #### 2026-09-03 - Applying literate programming to SuperCollider notes Prompted by looking at [wtkns/supercollider](https://github.com/wtkns/supercollider) as source material for [[Supercollider]]/`320 - Supercollider` pages. An `.scd` file is already close to a literate document — it's read as a sequence of parenthesized blocks evaluated one at a time, functionally a REPL transcript — which makes it a natural fit rather than a stretch. Approaches considered: - **Pin and transclude, don't duplicate.** Link vault notes to an exact commit of the source file (`.../blob/<sha>/...`), not a moving branch, so a note explains one specific, reproducible version of the code rather than silently drifting from the live repo. For material worth browsing locally rather than just linking, a git submodule/subtree of the source repo under the vault's code folder keeps the real files present without copy-paste duplication. - **Cell-structured notes with audio as output.** Treat each `(...)` block as a cell: prose above explaining intent, a fenced code block for the block itself, and — the SC-specific move — an embedded audio render immediately after, since SC's actual output is sound, not stdout. This matters more here than in most literate-programming contexts because [[Obsidian]] Publish renders a static snapshot: no community plugin executes for a visitor, so nobody but me can "run it themselves" — anything a reader should get out of a page has to be baked in as markdown and embedded media. - **Reproducibility metadata in frontmatter.** Fields like SC version, quark/dependency list, server/audio-driver settings, and hardware requirements (borrowed from R Markdown/Quarto's environment headers) are what make "why doesn't this sound the same anymore" answerable later, since the audio server's defaults and quark APIs drift across SC versions more than most languages' standard libraries do. - **Tangle/detangle automation, as a later step.** The org-mode-babel/jupytext pattern of pairing a plain-text source with a literate doc and regenerating one from the other could be approximated by marking prose blocks in `.scd` comments and scripting extraction into a matching markdown page — worth building only once there's a real backlog of files to keep in sync, not upfront. ### Concepts and Theories - [[Practice as Research]] - shares literate programming's premise that the record of process — code plus the reasoning behind it — is itself a legitimate part of the output, not just a means to it ### Related Practices - [[Supercollider]] - primary candidate domain in this vault: `.scd` files are already cell-structured, close to a REPL transcript - [[emacs]] - Org mode's Babel is the best-known living implementation of literate programming, already referenced in the Emacs cheatsheet - [[Obsidian]] - the vault's own publishing platform; any literate-programming pattern here has to work within Publish's static rendering rather than live plugin execution - [[Python]] - the Jupyter/jupytext ecosystem is the dominant literate/reproducible-research pattern outside Lisp-family tooling, and a useful point of comparison ### Key Practitioners %% none yet %% ### Institutional Affiliations %% none yet %% ## References ### Primary Sources Bibliography Knuth, Donald E. *Literate Programming*. CSLI Lecture Notes, 1992. - collects Knuth's key essays on the method, including the original 1984 paper ### Secondary Sources Bibliography %% none yet %%