Noweb – A Simple, Extensible Tool for Literate Programming
(BTW, Norman&#x27;s server seems to be suffering under the load; <a href="https:&#x2F;&#x2F;web.archive.org&#x2F;web&#x2F;20210223015500&#x2F;https:&#x2F;&#x2F;www.cs.tufts.edu&#x2F;~nr&#x2F;noweb&#x2F;" rel="nofollow">https:&#x2F;&#x2F;web.archive.org&#x2F;web&#x2F;20210223015500&#x2F;https:&#x2F;&#x2F;www.cs.tu...</a> has your (Way)Back if you&#x27;re suffering problems in accessing it.)<p>I&#x27;ve been interested in literate programming for a long time; for my self-bootstrapping PEG parser <a href="https:&#x2F;&#x2F;github.com&#x2F;kragen&#x2F;peg-bootstrap&#x2F;blob&#x2F;master&#x2F;peg.md" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;kragen&#x2F;peg-bootstrap&#x2F;blob&#x2F;master&#x2F;peg.md</a> I wrote my own noweb-like system called HandAxeWeb in Lua (5.x) <a href="https:&#x2F;&#x2F;github.com&#x2F;kragen&#x2F;peg-bootstrap&#x2F;blob&#x2F;master&#x2F;handaxeweb.md" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;kragen&#x2F;peg-bootstrap&#x2F;blob&#x2F;master&#x2F;handaxew...</a>.  It accepts input in Markdown, HTML, ReStructuredText, etc., and it&#x27;s only a couple hundred lines of Lua.<p>For HandAxeWeb (named following the convention of StoneKnifeForth—the intent was to make it simple enough that even fairly early stages of a bootstrap could be literate programs), I wanted to be able to include multiple versions of a program in the same document, because I think it&#x27;s often helpful to see the temporal development of a program from a simpler version to a more complex version.  The simpler version is easier to understand and helps you focus on the most fundamental aspects of the program.  <a href="https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=KoWqdEACyLI" rel="nofollow">https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=KoWqdEACyLI</a> is a 5&#x27;30&quot; screencast (not by me) of explaining the development of a Pong program in this fashion.  I think it&#x27;s usually easier to understand a program in this fashion than by trying to understand the final complete version bit by bit, the way something like &quot;TeX: The Program&quot; forces you to do.<p>๛<p>Still, generally speaking, <i>soi-disant</i> literate programming tools—including my own—generally fail to take advantage of the most compelling aspect of the computer as a communication medium: its ability to simulate.  When I dive into a new code base, it&#x27;s never entirely by reading it—whether top-down, bottom-up, or in any other order.  The cross-reference links added by things like CWEB (or, you know, ctags) are helpful, of course, but invariably I want to <i>see the output of the program</i>, which CWEB doesn&#x27;t support at all!  (Although Knuth&#x27;s <i>TeX: The Program</i> does manage to include TeX output despite being written in CWEB, that&#x27;s in a sense sort of a coincidence; this is not a feature CWEB can provide for any programs other than TeX and METAFONT.)<p>Books like <i>Algorithms</i>, by Knuth&#x27;s student Sedgewick, are full of graphical representations of the outputs of the algorithms being discussed, and this is enormously helpful—perhaps even more so than the source code; see <a href="https:&#x2F;&#x2F;algs4.cs.princeton.edu&#x2F;22mergesort&#x2F;" rel="nofollow">https:&#x2F;&#x2F;algs4.cs.princeton.edu&#x2F;22mergesort&#x2F;</a> for some examples from the current version of the book, which is lamentably in Java.  It&#x27;s better still, though, when you can <i>edit</i> the code and see the results—when diving into a new code base, I tend to execute modified versions of the code a lot, whether in the debugger or with extra logging or what.  Paper books can&#x27;t do this, but that&#x27;s no excuse for not doing it when we&#x27;re writing for readers who have computers.<p>Philip Guo&#x27;s Python Tutor <a href="http:&#x2F;&#x2F;pythontutor.com&#x2F;" rel="nofollow">http:&#x2F;&#x2F;pythontutor.com&#x2F;</a> provides <i>dynamic</i> visualization of the memory contents of, in theory, arbitrary code (in the supported languages, including of course Python, but also C, C++, Java, JS, and Ruby).  There are things you can display with animation that you can&#x27;t display in a static page, but <i>Algorithms</i> gets quite far with static printed images, and I think static visualization is better when you can make it work, for reasons explored at length in Bret Victor&#x27;s <a href="http:&#x2F;&#x2F;worrydream.com&#x2F;MagicInk&#x2F;" rel="nofollow">http:&#x2F;&#x2F;worrydream.com&#x2F;MagicInk&#x2F;</a>.<p>Python Tutor doesn&#x27;t scale to large programs, but Dorothea Lütkehaus and Andreas Zeller&#x27;s DDD can control GDB to create such visualizations for anything you can run under GDB (or JDB, Ladebug, pydb, or perl -d).  Unfortunately there&#x27;s no way to share the output of either DDD or Python Tutor, except maybe a screencast, and despite having been around since 01995, DDD has never been popular, I suspect because its Motif UI is clumsy to use.  <a href="https:&#x2F;&#x2F;edoras.sdsu.edu&#x2F;doc&#x2F;ddd&#x2F;article20.html" rel="nofollow">https:&#x2F;&#x2F;edoras.sdsu.edu&#x2F;doc&#x2F;ddd&#x2F;article20.html</a> shows what it looked like in 02002 and <a href="https:&#x2F;&#x2F;youtu.be&#x2F;cKQ1qdo79As?t=106" rel="nofollow">https:&#x2F;&#x2F;youtu.be&#x2F;cKQ1qdo79As?t=106</a> shows what it looked like in 02015.<p>๛<p>Of course, spreadsheets are by far the most popular programming environment, and they have always displayed the program&#x27;s output when you open it—even to the exclusion of the code, mostly.  I&#x27;ve experimented with this sort of thing in the past, with things like <a href="http:&#x2F;&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;bwt" rel="nofollow">http:&#x2F;&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;bwt</a> an interactive visualization of the Burrows–Wheeler transform, and so it&#x27;s been heartening to see modern software development moving in this direction.<p>The simplest version of this is things like Python&#x27;s doctest, where you manually paste textual snippets of output in the code itself, and a testing tool automatically verifies that they&#x27;re still up-to-date; Darius Bacon&#x27;s Halp <a href="https:&#x2F;&#x2F;github.com&#x2F;darius&#x2F;halp" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;darius&#x2F;halp</a> is a more advanced version of this, where the example output updates automatically, so you can make changes to the program and see how they affect the results.<p>๛<p>The most polished versions of this approach seem to have adopted the name &quot;explorable explanations&quot;, and many of the best examples are Amit Patel&#x27;s, which he has at different times termed &quot;interactive illustrations&quot; <a href="https:&#x2F;&#x2F;simblob.blogspot.com&#x2F;2007&#x2F;07&#x2F;interactive-illustrations.html" rel="nofollow">https:&#x2F;&#x2F;simblob.blogspot.com&#x2F;2007&#x2F;07&#x2F;interactive-illustratio...</a>, &quot;active essays&quot; (I think?  Maybe I&#x27;m misremembering and that term was current in Squeak around 02003: <a href="http:&#x2F;&#x2F;wiki.squeak.org&#x2F;squeak&#x2F;1125" rel="nofollow">http:&#x2F;&#x2F;wiki.squeak.org&#x2F;squeak&#x2F;1125</a>), and &quot;interactive visual explanations&quot;.   I wrote a previous comment about this on here in 02019: <a href="https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=20954056" rel="nofollow">https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=20954056</a>.<p>However, Amit&#x27;s explorables, like  many other versions of the genre, de-emphasize the underlying code to the point where they both don&#x27;t display the actual code and don&#x27;t let you edit it.  They&#x27;re intended to visualize an algorithm, not a codebase.<p>Mike Bostock, d3.js&#x27;s original author, has created <a href="https:&#x2F;&#x2F;bl.ocks.org&#x2F;" rel="nofollow">https:&#x2F;&#x2F;bl.ocks.org&#x2F;</a> for sharing explorable explanations made with d3, and is doing a startup called ObservableHQ which makes things like this a lot easier to build: <a href="https:&#x2F;&#x2F;beta.observablehq.com&#x2F;d&#x2F;e639659056145e88" rel="nofollow">https:&#x2F;&#x2F;beta.observablehq.com&#x2F;d&#x2F;e639659056145e88</a> but at the expense of a certain amount of polish and presentational freedom.  Also, unfortunately, ObservableHQ programs seem to be tied to the company&#x27;s website—you can download their output, but very much unlike TeX, the programs will only be runnable until the company goes out of business.  So if you aspire to make a lasting contribution to human intellectual heritage, like TeX, GCC, or d3.js itself, ObservableHQ is not for you.<p>๛<p>R Markdown (by JJ Allaire—yes, the Cold Fusion dude—and Yihui Xie, among others) is one of the more interesting developments here; as with noweb or HandAxeWeb, you edit something very close to the &quot;woven&quot; version of the source code (in a dialect of Markdown); but, in a separate file alongside, RStudio maintains the results of executing the code, which are included in the &quot;woven&quot; output, and may be textual or graphical.  Moreover, as with Halp or ObservableHQ, these results are displayed in a notebook-style interface as you&#x27;re editing the code. <a href="https:&#x2F;&#x2F;bookdown.org&#x2F;yihui&#x2F;rmarkdown&#x2F;notebook.html" rel="nofollow">https:&#x2F;&#x2F;bookdown.org&#x2F;yihui&#x2F;rmarkdown&#x2F;notebook.html</a> has a variety of examples, and Xie is rightly focused on <i>reproducibility</i>, which is very challenging to achieve with the existing tooling.  <a href="https:&#x2F;&#x2F;bookdown.org&#x2F;" rel="nofollow">https:&#x2F;&#x2F;bookdown.org&#x2F;</a> lists a number of books that have been written with R Markdown, and <a href="https:&#x2F;&#x2F;github.com&#x2F;rstudio&#x2F;rmarkdown" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;rstudio&#x2F;rmarkdown</a> explains the overall project.<p>Of course the much more common notebook-style interface, and the one that popularized the interaction style, is Jupyter (influenced by SageMath), which mixes input and output indiscriminately in the same file and peremptorily makes backward-incompatible changes in file formats; the result is a lot of friction with version-control systems.  Nevertheless, it supports inline LaTeX, it&#x27;s easy to use and compatible with a huge variety of existing software, and it can include publication-quality visualizations, so there&#x27;s a <i>lot</i> of code out there in Jupyter notebooks now, far more than in any system that purports to be a &quot;literate programming&quot; system.  Notable examples include Peter Norvig&#x27;s œuvre (there&#x27;s a list at <a href="https:&#x2F;&#x2F;github.com&#x2F;norvig&#x2F;pytudes#pytudes-index-of-jupyter-ipython-notebooks" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;norvig&#x2F;pytudes#pytudes-index-of-jupyter-i...</a>).  I find this a very comfortable and powerful medium for this form of literate programming; recent examples include <a href="https:&#x2F;&#x2F;nbviewer.jupyter.org&#x2F;url&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;dev3&#x2F;clock-and-data-recovery.ipynb" rel="nofollow">https:&#x2F;&#x2F;nbviewer.jupyter.org&#x2F;url&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;de...</a>, <a href="https:&#x2F;&#x2F;nbviewer.jupyter.org&#x2F;url&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;dev3&#x2F;max-power-divider.ipynb" rel="nofollow">https:&#x2F;&#x2F;nbviewer.jupyter.org&#x2F;url&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;de...</a>, and <a href="https:&#x2F;&#x2F;nbviewer.jupyter.org&#x2F;url&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;dev3&#x2F;secantmin.ipynb" rel="nofollow">https:&#x2F;&#x2F;nbviewer.jupyter.org&#x2F;url&#x2F;canonical.org&#x2F;~kragen&#x2F;sw&#x2F;de...</a>, which are maybe sort of embarrassingly bad but I think demonstrate the potential of the medium for vernacular expression of vulgar software, as well as lofty Norvig-type things.<p>๛<p>Konrad Hinsen has written about the reproducibility and lock-in problems introduced by Jupyter, for example in <a href="https:&#x2F;&#x2F;khinsen.wordpress.com&#x2F;2015&#x2F;09&#x2F;03&#x2F;beyond-jupyter-whats-in-a-notebook&#x2F;" rel="nofollow">https:&#x2F;&#x2F;khinsen.wordpress.com&#x2F;2015&#x2F;09&#x2F;03&#x2F;beyond-jupyter-what...</a>, and has been using Tudor Gîrba&#x27;s Glamorous Toolkit <a href="https:&#x2F;&#x2F;gtoolkit.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;gtoolkit.com&#x2F;</a> to explore what comes next.  He&#x27;s been hitting the reproducibility problem pretty hard in <a href="http:&#x2F;&#x2F;www.activepapers.org&#x2F;" rel="nofollow">http:&#x2F;&#x2F;www.activepapers.org&#x2F;</a> but the primary intent there is, as with the explorable-explanations stuff, code as a means to producing research (&quot;How should we package and publish <i>the outcomes of</i> computer-aided research&quot;), rather than maintainability and understandability of code itself.  I think this is a promising direction for literate programming as such, too.