I saw https://news.ycombinator.com/item?id=17483242 ("Literate Programming: Empower Your Writing with Emacs Org-Mode") and figured HN might be interested in a real-world attempt to use literate programming for a larger project (Haskell implementation of D-Bus).
Not misused -- I think I gave a pretty good shot at writing literate code as Knuth originally intended it. It's just that the goal of literate programming, the transformation of source code into a document that can be read like a book, doesn't seem to be useful.
It's worth noting that Knuth wrote WEB in 1981, ten years before the web. There's no way he could have known at the time that hyperlinks and search would be a far more useful interaction model for reference documentation.
It's important to remember that for Knuth, the typeset documentation is the “real” program; neither the input you type (the .web or .w file) nor the code generated (the .pas or .c file) are intended to be looked at much. (You may look at them sometimes, the same way you may sometimes look at the generated assembly of your C program for debugging, but that should be rare.) He writes programs on paper; he programmed the whole of TeX and Metafont by writing them with pen/pencil on notepads for several months, before approaching a computer and typing it all in. He also reads a lot of programs written by others, something most programmers today don't really do. (http://www.gigamonkeys.com/code-reading/) When he wants to understand or remember what some program does, he pulls out the printout, reads it like a book, etc. As a scholar, reading and writing books is his natural activity, so everything is optimized for that.
I read a few of Knuth's programs (https://github.com/shreevatsa/knuth-literate-programs/tree/m...) a while ago, the intended way: printed them out and read them while sitting at a table, pen in hand, no computers nearby. The 60s/70s style is quite different — since then a bunch of solutions to the challenges in programming have evolved (abstraction, structured programming, modules with information hiding, OOP, etc), but instead Knuth has evolved his own different solutions, which takes some getting used to. But after a while it was fine and illuminating; you understand there are different ways of doing things, and they can be effective too.
This is the consistent message I've gotten from his writings: the goal is to communicate to other people. "Transformation of source code into a document that can be read like a book" feels far more low-level than that.
> Knuth wrote WEB in 1981, ten years before the web. There's no way he could have known at the time that hyperlinks and search would be a far more useful interaction model for reference documentation.
Knuth certainly knew about hyperlinks. On the same page, Knuth says:
"The program is also viewed as a hypertext document, rather like the World Wide Web. (Indeed, I used the word WEB for this purpose long before CERN grabbed it!)"
There's a pleasing non-linearity to Knuth's creations, both in the source (with fragments being named and referring to each other) and in typeset form (with all the attention to the index of fragments, to showing with each fragment all the places that refer to it).
---
In any case, we may be splitting hairs here. I'm not a scholar of Knuth's work, and maybe your interpretation is correct. I agree that if you define Literate Programming as "transformation of source code into a document that can be read [linearly] like a book", then that goal is not useful. If you define it as "better communicating programs to other people," then I think that goal is still relevant. All programmers should keep this goal in mind, while loosening their grips a tad on the precise details of how they happen to aim for the goal at a specific point in time. There's still lots of room for improvement.
I tried writing some Java code with noweb - and at least for Java 1.3 - the ability to reuse code at any level (like a while loop working with an ADT) helped avoid some of java's tedious verbosity. This helped keep the narrative / document to a manageable length - but it lead to rather confusing Java output (only really a problem if people try to read just the code, ignoring the document).
Overall, I've come to feel that with more powerful languages - some doctests and block comments can go a long way in achieving similar results.
Although for reading proper laid out text with a nice font and good support for mathematical notation does help.
But with a language with rich abstractions, and a sane use of Unicode (from the simple case of using π as a constant, to the more sophisticated of having arrows and actual not-equal signs) - along with a freedom of ordering, so you can do:
And not get a reference error, because simple_subtask1 is referenced before it's declared - all go a long way in facilitating source code that reads more like prose than code.
[ed: I should add, that I don't really think simple text formats are the best way to offer rich editing experiences - we see this with most IDEs - that "understand" code - but I think the lisp/smalltalk idea of images and being able to go back and forth between byte code and text form really is the way forward.
Like word processors, spreadsheets and image editors all use rich file formats for their working sets.
