Literate: A Modern Literate Programming System
literate.zbyedidia.webfactional.com
literate.zbyedidia.webfactional.com
One of the great features of Knuth and Levy's CWEB is that errors are reported in terms of locations in the literate source. This feature, which works by way of line pragmas, is essential for proper debugger support and, in my opinion, sanity while coding larger projects.
If it is missing, it is often better to skip the "tangle" step entirely and have the literate source map directly to the program source line for line. Trying to "pattern-match" the compiler errors against tags in the source file is a painful waste of time. The 1-1 mapping is quite practical for more functional languages if one writes code in a style more like SICP than the TeX sources.
There's not much of a trade off there. Either you use the tools that generated the code and edit their inputs, or the first time you update the code and rebuild your changes get clobbered.
And if people really find that literate programming makes the code that much harder to follow that they'd rather not use it, maybe it's not a great idea to use it.
Looking at your examples, it doesn't strike me as very markdown-ish. There are @ symbols, and dashes to delineate code blocks. For me, markdown uses # Headings and uses tabs or ``` for code fences. I prefer the tab approach, but fences allow for language syntax highlighting for those who like that kind of thing.
{Print "hello world" 2} ≡
printf("Hello world"); This code is used in section 1.
...is not exactly it. It feels more like program-in-program Matrixy thing than a document to be read.
Of course, there are advantages of Literate's output compared with CWEB's; it's more flexible in that you can embed arbitrary HTML in the output, so you can easily put images into your explanations, and you can put as many code blocks and text blocks as you like in each paragraph.
By the way, does anybody know of an automated way to "grade" the quality of code documentation? I think this is what we need on repositories such as github, as it could stimulate the production of documentation of better quality (in most cases the documentation of OSS projects is rather poor).
I guess what I mean by that is that as software scales out, your code will be more along the lines of "do this logic whenever this function/method happens to be invoked". So it would be great for documenting the workings of a function/method, but it would be poor for actually documenting the lifecycle of a logic path, like the lifecycle of a request. I certainly wouldn't have one file where I handle a request, do some business logic, and interact with a database, even though that is how you might document a lifecycle the request.
My tool takes the approach of more of a literate-project approach where one file may generate multiple files (and multiple files could generate one file). The idea is that the organization is completely up to the author with no boundaries between how they want to organize it.
And referring to earlier comment, I would write the same flow of logic for a single thought in the same place. There is the flow of a single process and there are commonalities across processes. I think a good literate programming allows the uniqueness of a single flow to be put into one place and the commonalities to be extracted and applies to such a flow.
I mean, regardless of whether literate programming is viable for "enterprise software" or whatever, that's a wonderfully interesting cultural artifact... Inspiring!
Some implementations of Unix were also published as books, as well as the original source code for PGP (as a free speech trump card to defeat cryptography export restrictions).
These books, I presume, are archived by the Library of Congress, and will be around for a long time. Maybe one day we'll need them. Like if GitHub suddenly explodes and all the world's software is lost!
How to read and write programs is still something of an open question, as far as I'm concerned. The effort involved in caring for a "literate" code base, and indeed the literacy required, is probably too much for most projects. I don't think that makes it a "bad" model. It seems good to have tools available, and for people to try it out.
The Haskell world does a bit of literate programming, and tools like lhs2TeX are quite nice for preparing papers and such. There's something very beautiful about carefully written code that makes enough sense to be published as a "literate" paper.
A program has history, which, by the way, is stored in VCS, planning tool and communication, not the source code it self,
So how about a literate VCS?
Maybe you start with a tree structure to outline release planning and done branches, and break it down to individual updates against the current state of the source.
Might even keep contextual history like annotated repl invocations and throw away test code around.