Literate Programming: Articles
literateprogramming.com
literateprogramming.com
* It messes with tooling. If you're lucky then your editor will be smart enough to syntax highlight inside code blocks, or can be taught to do so easily. It's unlikely that more advanced IDE-style features will work. Obviously tools could be adapted with custom plugins but literate programming isn't popular enough for these to already exist as far as I'm aware.
* It adds overhead to refactoring. Refactoring code now means editing and rewriting a book, doing a good job requires significantly more effort. If you have designed the program thoroughly ahead of time you can avoid this, but that's not generally the way most programmers work.
* The "includes" problem. Most language require you to include/import/require packages used in a file. These are usually all placed at the start. This means a lot of chapters will start with "here are all the includes we'll need" if you're using a linear format. More complex formats that rearrange the code to generate outputs can do a better job but it's still a little clunky.
Overall my conclusion was that literate programming works best if you write code like Donald Knuth: work solo, have a good idea of the entire design and a fixed scope which you can complete to declare both book and program "done forever". Unfortunately that doesn't cover most real world programming. I don't think it works well in the most common commercial/programming team style settings.
I’ve heard that org-babel [https://orgmode.org/worg/org-contrib/babel/intro.html] works pretty well for this, though I’ve never used it myself.
See https://emacs-lsp.github.io/lsp-mode/manual-language-docs/ls...
Real literate programming, rather than rich text comments, can order the code blocks in any order. You can add then at the very end of the book/chapter/section if you feel like it.
I did some literary programs about a previous generation of our program. Every new hire reads them and asks me for copies.
And yet Knuth still does it the other way. <http://akkartik.name/post/literate-programming>
The idea is more to break the code into parts you would explain and grok easily. Not every atomic part of the code.
When I've written literate programs, I almost always shuffle long lists of includes to the end. They add little or no value at the top and distract from the material I want to present. It's also a simple cut and paste to move them back to the top if I wanted to. The only time I leave them at the top is if there's something actually informative about having them at the top, or it's a short program, or I've not actually finished working on it (a lot of my literate programs start as traditional "live in source files" programs that I slurp into org files).
Yes.
> The primary purpose of using literate programming is expository.
Right. A big, zero-context block of includes prefaced with a comment that you should just "skip ahead" past it to the "interesting stuff" and offering no insight about the stuff that you're skipping over is the opposite of expository. The main program—what it actually does—is sufficient to serve as exposition for the includes that it ends up needing to be put it. So actually write it that way.
> That's the benefit of WEB[...] The presentation order is not dependent on the code order, it's dependent on what makes the most expository sense.
The argument is that it doesn't make expository sense to write the includes the way Knuth is. It's just yet another form, as taeric observes, of boilerplate—which makes us a slave to what the (LP-unaware) compiler expects, and which LP is supposed to liberating us from...
* * * *
It strikes me that there are probably only two ways to really deal with includes in the spirit of literate programming, which is to either (a) put them at the end after having already shown us why they're necessary (accompanied with with e.g. a comment along the lines of "Recall that our program is using printf—a part of the C standard library and defined in stdio.h—so it's necessary, therefore, that we include it in order for our program to compile") or (b) to use WEB/CWEB's appending facilities—after having written a routine that uses printf for the first time, you write an interlude not altogether different from what I just described that adds that include to the "running sum" of necessary includes, which the tangle step will take care of as part of the build.
(I say "only" because these are the only ways that occur to me that it can reasonably be done. I'm not committed to that being true—I'm open to the possibility of there being more—and it's not as if I started with that in mind, but it's hard for to imagine others. The only thing I'm really committed to is that what the article says about Knuth's two examples being wrong is accurate. I know Kartik has softened his stance since originally writing it, but I haven't. The examples given are individually each an awful way to demonstrate LP considering how antithetical that is to the whole thing. Totally indefensible.)
thr-nrg rightly pointed out in their comment that you can place the code wherever you want. You then say, "Knuth puts it at the top" (meant as a criticism of his style).
My point (so you don't miss it again): You can place the code wherever you want when doing a literate programming style. It also doesn't matter what Knuth does with his includes because his style does not dictate your style or my style or anyone else's style. So put it wherever you want. His style does not matter.
Your point doesn't make any sense. ("_You_ can place the code wherever _you_ want when doing a literate programming style.") Literate programs are supposed to be read. Of course a writer can write however they want. You could write a book where everything that isn't a proper noun ends with an uppercase letter, except for proper nouns, which are all lowercase. It will be shit.
Does it matter what Knuth does? Nope. I don't care for that aspect of his style. I already said I put the includes (when a text gets past the draft stage at least) toward the end. We're in violent agreement with respect to how we (if I understood you correctly) often or generally put them into LP texts.
You're just weirdly caught up on criticizing Knuth's style for some reason. Have fun shouting into the wind. The rest of us know, it doesn't matter. The goal is to communicate effectively and not whine about things that don't matter.
Exposition does matter. He's not doing it. That's the problem.
Dumping a big lump of include statements or defines at the beginning of the text and then saying don't worry about it isn't an example of someone who actually believes that exposition matters. It's incontrovertibly devoid of exposition—not just a matter of it being one's "style".
> What matters is the exposition.
> Does it matter what Knuth does? Nope.
Either it matters, or it doesn't. Pick one.
I agree. Here's an example I give of an emacs configuration in the typical style which I don't find especially useful versus one that does use exposition:
https://www.paretooptimal.dev/finding-the-best-style-of-lite...
Here's a sample:
* My emacs use-cases
** Version control with Git
*** use magit as a porcelain
#+begin_src elisp
(use-package magit)
#+end_src
*** enable easily showing history of a file
#+begin_src elisp
(use-package git-time-machine)
#+end_srcTo that end, the goal is to not have parts that can be the same between programs vary. That has pedagogical value. Is a type of stability that we don't really value much anymore.
Though, I also give a +1 to jtsummers' point. Knuth has a style of writing literate programs. And if you find some old videos of his reviewing student's code, he explicitly calls out points of style that he likes from different students and how they work together. He didn't necessarily want to push a "this is how you style your programs," but instead was working how you talk about programs into a way that you can also write them. While not having to relearn either, necessarily.
Lists of imports are not title pages.
> the goal is to not have parts that can be the same between programs vary
Lists of imports vary. (And in today's world of extreme software reuse, which other pieces of software a program depends on is of greater interest than ever.)
I'd take your point on boilerplate if it were necessary and unavoidable. I've already described, however, that it isn't and how.
I think the disconnect is still that you are writing a C program with CWEB. If I'm using a literate style to write JavaScript, I'm still writing a JavaScript program. As such, the point isn't to just throw any established norms out, but to rearrange for presentation. If some items go well together, might as well keep them together.
Most programming tools that can do this require you to "bundle" things such that you have to have well formed containers, if you will. Having the "add this to a section" constructs really help, as then you can say things like "add this to the imports" the first time you have need of a new import. But, if you don't add any non-standard imports, you can forego doing that.
The other approach is to try and make everything implied, such that new users can skip any of the boilerplate and jump straight to programming. That is fine, for what it is, but does little to build understanding of the programs as a whole.
That said, I may have missed your described solution. I'm kind of scattershot today and not keeping fully on top of this. Apologies if I'm talking past you.
I think it's a worthy goal for nearly all readers. However I also believe that literate programmers should be written with many different readers in mind.
So you could have one version that is written in a "typical code" style like:
* library 1
** module 1
*** source file 1
** module 2
*** source file 2
For example:
* typical program style
** library 1
*** module 1
**** source file 1
*** module 2
**** source file 2
* new to language X presentation of program
** link to various parts of library 1 alongside prose to describe concepts to language newcomer
* typical hire presentation of program
** business domain focused exposition presenting code via transclusion as needed from typical program styleSee also this conversation about the unreadability of Knuth's .web files: <https://news.ycombinator.com/item?id=29203798#29205840>
Web and its derivatives are sufficiently advanced that they suffer from the lisp curse. What in other systems are major fundamental engineering problems - try adding an include in the middle of a c file - in Web derivates are a matter of taste. Do you have a chunk that picks up includes as you need them? Is it a big one at the front or back? It's up to you.
And nothing. For programs that are ostensibly meant to be read, Knuth's examples are poor ones.
> in Web derivates are a matter of taste
Dumping a bunch of includes at the top and saying the equivalent of "don't worry about this boring stuff for now; you can skip it if you want" (and thereby compromising the entire LP experiment) is a matter of taste in the way that putting beef in a vegan casserole is.
Note the end of the sentence you quoted: “if you feel like it” — Knuth clearly doesn't feel like it in these programs. (BTW, it appears he generally adds a comment next to each #include mentioning why it's being included.)
Literate programming, for Knuth, is supposed to be a fun way to write programs that leads to them being easier to write and read and debug and maintain; it's not some sort of purity discipline that requires everything to be maximally expository.
I don't buy it. The same explanation can be used to excuse the use of traditional (non-LP) programming systems—raising questions about why make a fuss about LP at all at that point if an LP text is going to treat the same types of shortcomings as a given.
As the commenters on Ward's wiki pointed out, Knuth's examples come across as still being written for the compiler—what he's mostly succeeded at is just coming up for a different syntax for it to consume in a roundabout way.
> Depending on the reader you're targeting (e.g., yourself a few years from now), and how polished you're trying to make your presentation, you may well choose to take it for granted and not bother explaining that a C program will have some obvious #includes at the top.
But of all the things that Knuth could explain, that's the one thing he does explain. It's not a lack of an explanation that the program will have some includes that is the problem. It's the impertinence of immediately dumping a list of includes on the reader, in a total failure in exposition.
We don't have to focus exclusively on the includes to see this problem. The define at the top of the Symmetric Hamiltonian cycles exhibits the same thing just as clearly.
I have another theory that I've floated, which is that Knuth realized that there's something wrong with how traditional Pascal and C compilers force you to write/read your programs bottom-up, but by the time he came up with literate programming he was already so warped and tainted from years of doing work in the bottom-up tradition to satisfy the compiler that it ends up clouding his vision, even when he knows that's the mindset he's trying to actively work against.
It seems that your main complaint is that in Knuth's literate programs, he does not explain enough. To which my answer is: Sure! LP doesn't mean you have to explain everything, you can choose to explain as much you want. It's not a "moralism" like "structured programming"; it's just a tool.
I think everything you're saying is along the same lines:
> The same explanation can be used to excuse the use of traditional (non-LP) programming systems—raising questions about why make a fuss about LP at all at that point if an LP text is going to treat the same types of shortcomings as a given.
Firstly, "excuse" seems to suggest an accusation that something is wrong with non-literate programming, which has not been made except as a joke — LP is just presented as a tool, with the expectation that it won't work for everyone. (Knuth is against moralism in programming style, and has often complained about it, e.g. in the context of defending GOTO and comparing pointers and what not.) So your question is basically asking: why attempt to explain at all, if one is not going to explain everything? The answer is, even without explaining everything, explaining as much as he does seems to work for him; he's been doing this for 40 years now and continues to rave about it.
> But of all the things that Knuth could explain, that's the one thing he does explain.
(I didn't understand this part.)
> immediately dumping a list of includes on the reader
As a rule of thumb, Knuth has said somewhere (maybe in the early days of LP, for TeX), that he targeted around 12 lines per LP section. So I would imagine that if he ever wrote a program that had more than about 12 includes (which is pretty hard to imagine :-)), he would split up the list of includes into multiple sections, presented separately. Below that (like the four or five includes in these examples), there's not much value in splitting it up further. I guess there's a lesson/hint here that splitting something up into sections is not "free" and below some threshold starts having more cost than benefit. (Just like the cost with having lots of short functions in modern-day non-LP programs: Ousterhout's A Philosophy of Software Design has some succinct words about that: https://web.stanford.edu/~ouster/cgi-bin/aposd2ndEdExtract.p....)
In any case, not having separate sections for #includes is not a failure of imagination: if you look at the programs on his webpage, the very first example ("used as a handout for a lecture on literate programming") has #includes separated out: https://shreevatsa.github.io/knuth-literate-programs/program... — note that in section 2, after a self-mocking joke ("First we brush up our Shakespeare by quoting from The Merchant of Venice … This makes the program literate."), he uses printf, and in the next section includes stdio.h ("Since we’re using the printf routine"), and then in section 7 he has another include, with the words "UNIX’s localtime function does most of the work for us, but we need to include another system header file before we can use it." So the fact that he presented includes like this in his early demonstration program (October 1992), and does not bother to do so in later programs (including last week: May 2023) seems worth thinking about.
> The define at the top of the Symmetric Hamiltonian cycles exhibits the same thing just as clearly.
As mentioned before, this is one of the programs that "use the conventions and library of The Stanford GraphBase". If you look at the program (https://shreevatsa.github.io/knuth-literate-programs/program...), it starts with "We use a utility field to record the vertex degrees" and then has "#define deg u.I". This is in fact part of those conventions — in the SGB book index, there's an entry for "utility fields" pointing to pages 38–39 and 284, where this is explained:
> Every Vertex record contains eight subfields. We have already mentioned name and arcs; the other six subfields are called utility fields because they can be used for many different purposes. […] The six utility fields are named u, v, w, x, y, z, and their five possible interpretations are distinguished by adding one of the respective suffixes .I, .S, .G, .V, .A; thus, for example, v->w.I stands for the integer in utility field w of the Vertex record pointed to by v.
> Utility field names are usually given meaningful aliases by means of macro definitions. For example, GB-GAMES defines nickname to mean y.S.
and so on, and the book is full of definitions like "#define source a.V" and "#define back_arcs z.A" — so when the SHAM program begins with "we use a utility field" and then "#define deg u.I", this is established convention, not some wild thing pulled out of nowhere. When Kartik says “presumably a struct whose definition — whose very type name — we haven't even seen yet. (The variable name for the struct is also hard-coded in”, all of these presumptions are wrong: `u` is not a hard-coded variable name but the name of a field in Vertex (over the course of the program we can see v->deg, x->deg, u->deg, a->tip->deg: there's an index entry for "deg"), and the Vertex struct's definition and type name are well-documented (in a published book). I find it easy to take at face value that this was really the order in which Knuth thought of things, and also the level of exposition that he finds most useful (for his intended audience, which is himself).
This points at a problem with literate programming, that I also mentioned in the other thread: because it can be so personal, everyone who uses LP has their own idea of what is most worth explaining, and even ends up building their own LP tools. (Similar things are said about every Lisp programmer ending up with their own idioms and mini-languages.)
> he was already so warped and tainted from years of doing work in the bottom-up tradition to satisfy the compiler that it ends up clouding his vision
Another way of saying this is that Knuth never believes in hiding the fact that you're writing code that a compiler will read and that a computer will execute — in fact he continues to annotate variables with "register" even though compilers ignore it, simply because he likes to be conscious about what instructions the (ideal) machine will execute — he's not a big believer in abstraction and hiding the details by passing to a higher level; he believes in (and somehow manages) constantly being aware of all levels at once.
Yet another way of saying this (my theory) is that when machine code / assembly programs became too hard to maintain, the rest of the world solved the problem by, over time, settling on abstraction, interfaces, higher-level languages, style conventions, information-hiding, and all that. Instead, Knuth has forged his own programming path/style, still basically writing machine-sympathetic programs, but "explaining to human beings what we want a computer to do". It is up to others to merge LP's human-orientation with mainstream ideas… if it will ever happen.
Anyway, it seems that the criticisms we're discussing are mostly based on first impressions. While they are valuable (and indicative of what others' first impressions will be), ultimately I think criticisms based on studying these programs more closely would be more interesting. E.g. has his LP style evolved over time? What can we learn from studying recent programs (there are over a dozen since 2020 alone, like the program above or others posted on his webpage and which I just typeset yesterday at https://shreevatsa.github.io/knuth-literate-programs/program...) — what can we learn from what he chooses to explain and not; why does he make those choices; what way does this seem to help him: can we use these insights (not the same style) for our own programming practice? Things like that.
HN gives you 14 days.
(I wish it had a feature to "mark" a comment in lieu of writing a reply then and there. When 12 or 13 days have passed, it'd send you an email reminding you that this is your last chance to add what you have to say to the record. In this way, it would favor people going away and coming back to leave more thoughtful comments instead of impelling them to reply instantaneously i.e. to avoid the risk of not being heard.)
I suppose the hack would be to set your delay in your profile to 60 × 24 × 12.5 = 18000 (minutes), post your reply, then reset it to its initial value. You'd progressively edit your comment as the opportunity comes up, and then it will be autoposted in whatever form its in when the delay elapses. You can only edit posts for up to an hour (or something), though, and I'm not sure whether that timer starts from the time you hit submit or when it appears in the comments (i.e. after the delay has elapsed).
I do this with Typescript (deno) and a neovim plugin called sniprun.
In my opinion, this is a good thing. The problem with ordinary refactoring is that it's too easy to just shuffle things around until they work/seem nicer/do whatever you want to. However, with literate programming, you have to think why you're refactoring, and how does it reflect in the explanation.
Probably a niche example and the exception that proves the rule, but in Racket, the included literate programming (Scribble/LP2) is itself a language implemented in Racket. Racket’s IDE and tools for exposing and inspecting syntax work just as well in that environment as in any other Racket-implemented language.
Since all of this work is in a git repo, it is nice to pass around documents so folks understand the thinking behind things.
Also, (and the main reason I went towards it) is that when I pull what I need from the markdown files, I have steps built around to lint, test, and do additional checks to ensure the required naming, labeling, etc.
It has worked well and reduced many `silly' errors when other folks use the images.
Is it for everybody? Nope. But it works here.
I also did LP many years ago when I worked at a place that produces custom software for embedded systems. Providing them with a friggin' novel about the program was also fun. But, we never .. once .. were told we needed to provide more documentation.
LP has good points, but it isn't a one-size-fits-all.
When asked to send some coding samples, it is fun to have a PDF file that starts 'Chapter 3: And Now, Security! Encryption and Other Pain Points!'
Is it "notebook" style programming, like Mathematica, matlab, Jupyter, and markdown-based stuff like R/python + Quarto? In this mode, I think the focus is more on creating a document or communicating stuff typically with data analysis. And actually, "literate" is a very apt adjective for something that's ultimately intended to be a document of some kind.
Or is it more general intended for writing arbitrary software applications and having everything in the source code? In other words, to understand the source, you just read the source and there are no other documents.
The latter mode, I think, is still very much not around as far as I know (academic proof-of-concepts for papers don't count :-) ). Will it ever really exist?
There is Stanford GraphBase, and a really good MP3 book that are full programs. Not to mention TeX.
The overwhelming popularity of TeX all too often makes people forget about METAFONT. The type of computer fonts advocated by the latter has unfortunately failed to gain popularity, and its descendant MetaPost has a lot of competition, but I think the language itself is much nicer (while remaining true to its macroexpander roots), and it’s another literate program of about the same size.
[1] Gratis at https://pbr-book.org/
[2] Gratis at http://craftinginterpreters.com/contents.html
You're thinking of LCC. PCC is AT&T's compiler and the work of Johnson who also did yacc.
Then we might hope for support in most tooling to appear quite quickly.
I think one reason why literate programming is less attractive nowadays (compared to the days of Pascal) is that programming languages have got better at letting you arrange your code in whatever way you like. So maybe something like the above is enough to get 90% of the advantages of a full literate programming system.
It's not especially useful. For literate programming you really need the ability to move blocks of code around without the ceremony of function signatures.
Similarly, if I preview such a file on github I get syntax highlighting for the code but I don't get rendering for the markdown.
So I think the advantage of an 'official' way of saying you're using this arrangement would be communicating intent to more-or-less generic tools.
You could probably even do it with Markdown directly, using fenced code blocks as part of your begin/end lines.
I think you'll find that this approach offers very little benefit over either traditional commentary or linear notebook-style inline code blocks.
[0] https://wiki.haskell.org/Literate_programming#Haskell_and_li...
[1] https://okmij.org/ftp/Haskell/class-based-dispatch.lhs
[2] https://okmij.org/ftp/Computation/lightweight-guarantees/eli...
I wrote more about this at <https://news.ycombinator.com/item?id=35985835> and <https://john-millikin.com/software/anansi#history>.
Jef Raskin wrote and thought about this. The sentiment sounds like it would fit best in his piece "Comments are More Important than Code" (2005), but there's another Raskin article "The Woes of IDEs" that contains the most explicit agreement:
> In my method, program segments are embedded in the midst of a word processor document--like raisins in cake--so that the emphasis is on the explanation rather than the code.
<https://queue.acm.org/detail.cfm?id=864034>
> maybe something like the above is enough to get 90% of the advantages of a full literate programming system
If you're doing JS, then you can actually get pretty far with browser-based notebooks that just use vanilla HTML (and CSS), which notably doesn't require any ex ante setup/configuration for runtime support in the vein of e.g. Jupyter notebooks. (The problem being that not everyone writes JS and even most programmers these days who think they're writing JS really aren't and have no idea how to, so this won't work for them, either.)
Pandoc is a nice swiss army knife that can do a similar conversion with some custom lua filters. It could even do wackier stuff like convert word or odt files to code if you were really diving into prose-first coding.
I've also heard it referred to as 'semi-literate programming' because it skips the reorganization functionality and just gives you nice prose to code conversion.
VS code is getting pretty smart about code notebooks too, it has native support for a few different formats of markdown + code blocks (hydrogen, jupyter, etc) and applies all the right syntax highlighting, analysis, etc. to each block automatically.
The tooling can be a bit clunky -- though JupyterLab and some plugins can go a long way. Importing notebooks into other notebooks or modules is still kind of weird even with the `ipynb` library.
However, on the otherside of it all, you have a collection of documents that contain documentation, code, and tests, all side by side and storable with proof of past execution.
I'll take this arrangement over someone's unit test and CI suite every day of the week.
For decades, I searched for literate tooling for personal projects, but nothing stuck. Something about the design space seems to make it easy to hit design choices that are uncomfortable fits for one's use case, or personal taste, or preferences for tooling extension and customization. It reminds me of the personal information manager space.
My most recent foray seemed more promising. poly-markdown permits editing polylingual md files, and is permissive towards markdown dialects. So I could use a custom literate markdown, normalize it for rich-but-restrictive pandoc, then get the pandoc ast and emit custom html. With Julia's MLStyle[3] for pattern matching, and a bit of front-end pretty, it was unexpectedly easy to reach something comfortable.
Perhaps for literate tooling to gain greater traction, it helps that software dev progress permits folks to more easily cook their own?
[1] https://github.com/polymode/polymode [2] https://pandoc.org/filters.html [3] https://thautwarm.github.io/MLStyle.jl/latest/
Knuth's Programming Pearls entries are good reading as well.
> In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source.
http://literateprogramming.com/lpfaq.pdf#page11
By this litmus test, the Go standard library qualifies as literate programming. Document production tools are go doc or godoc. The .go files are themselves already compilable source.
It might be worth checking through the PDF the sister comment to yours linked - http://literateprogramming.com/knuthweb.pdf - you'll see what I mean.
https://en.wikipedia.org/wiki/Axiom_(computer_algebra_system...
That is an excellent resource. Thanks very much for posting [and thanks to everyone involved in the original compilation].