I thought literate program was a farsical esoterica that was only born because of it's ivory tower surroundings, and would've stillborn had it come into the world any other way.
Until I found org-mode it really is world changing if I had picked up Doom Emacs for no other reason than org mode it would've been well worth it. I have now seriously considered trying to do literate program with org mode.
It's already seeped into every project I work on now has a notes.org where I keep kind of a stream of consciousness notes of what I am doing and copy and paste any code or command I have into it for future reference and it has already multipled my productivity.
I love org mode and for any person that is already a vimmer I recommend highly you pick up Doom Emacs and spend some time getting to become familiar with it, especially org mode and magit it really is world changing. I can't imagine ever going back.
I always liked the idea, but I was a pure math major, CS minor. Turns out I was better at programming that proof-writing, but Literate Programming is associated with the "Ivory Tower Academic Elite" because it really is handy.
Jupyter notebooks can provide a literate programming experience as well, but the plain-text experience of Org is something special.
These are exactly the types of things I wish I could get myself to spend the time to learn, but unless I can force myself to learn something as an actual part of building somethings that interests me, I'll never actually pick it up :(
I know what you mean. I was paid to write the API, and the documentation, which provided the necessary motivation to try to write it "literate". I had already been using `restclient` instead of Postman to interact with other APIs I work on. It was just a matter of being paid to take it to the next level.
Can you compare feature sets from magit to vim fugitive? I’ve always heard nice things about magit but nobody has verbalized it in comparison to what vim offers.
They're not in the same league, although this isn't a knock on fugitive as they have different goals.
If you don't want to try magit¹ itself, then vimagit² is a reasonable approximation within vim. It gives you the same kind of workflow as magit, but doesn't quite feel as polished IME.
¹ You don't need to be an emacs user to use magit, you can treat magit as a standalone application.
I wrote something similar at my last job. Mostly because the frontend devs wanted good documentation, and the docs kept falling out of sync with the codebase. So I integrated it with a test framework: https://github.com/savantgroup/literate_integration
I love literate programming. But it requires 3 skillets: writing well, programming well and a little DevOps in order to automate the execution of the literate program.
So it is actually very difficult to do... But the results are Worth it to have software you can understand forever
The experience completely cured me of Knuth-style literate programming, fwiw. It's really great for making a lasting artifact about a program that's completely done. But I can count the number of programs I've worked on like that on zero fingers. Even this one isn't really done, but the cost of updating the essay along with the code discouraged me from working on it any more.
> If it's not too much to ask, do you mind sharing some of the pain points?
To me, the point of literate programming is that you have a coherent (literate, if you well) document that explains how the program actually works, and the reason it's put together how it is. This is NOT an easy thing to write. It takes as much organization as the program itself. I found the document structure to be continuously in flux, as I updated the program to deal with new requirements. So either document would poorly structured, or I would spend a LOT of time keeping it good.
Note that Knuth has written dozens of books and is perpetually making edits and corrections to them (not just typos, but often extensive rewrites while making sure that the book remains coherent as a whole): this is an activity that comes easily to him, so one can see how he can do it with programs too. The rest of us may find it harder.
But then again, we can ask: if we cannot keep the program's document structure as a whole up-to-date, then are we really editing the program properly? A major risk of introducing bugs is that one may edit a part of a program without taking into account the broader context, such that the integrity of the program is lost, and literate programming (which forces us to update "the whole program" every time) can be considered a mitigation of this risk… so IMO the greater time that it takes to update the whole program could actually be a good thing, saving time in debugging or whatever.
Edit: Also, part of the trick is to put only as much as you think is really relevant in the "text" part: literate programming does not necessarily mean over-commenting everything (Knuth doesn't either), it's just an orientation that what you're doing is writing a document. It's ok for most of that document to be code, as long as you think you've presented it well enough.
Yeah, I encountered this difficulty while writing the "literate" API documentation that my blog post was based on. The example in my post is very simplistic. The real thing makes numerous database queries to set up data, then creates an entire mock "client" with a mock employee, mock location, mock services, appointments, etc., by making successive requests to the (local dev) API. Order matters. And it's still a pretty simple example of literate programming (if, as someone mentioned earlier, it could be called "literate programming" at all in the sense that Knuth meant it).
In that regard, I'd say it is. True, we don't tangle and weave to separate artifacts. In fact, it doesn't tangle at all. However, I'd argue that in this case that isn't the point of the program. It's essentially a TUI to build an HTML artifact. Obviously we can't tangle `restclient` source blocks, but nor are we just dumping the results of `restclient` requests. Everything is piped into bash and post-processed by `jq` to clean up the final result for display.
That said, I accept that it's still not really "literate programming". It's literate API documentation.
I’ve experimented with NOWEB in the past and it’s cool. I would imagine it being good for teaching. Like “these are the steps we have to take to accomplish the desired result” and then break down every step with the ability to actually build the code at the end.
I don't know how to properly version documentation, and how to prevent accidentally documenting responses for the wrong version number. Any recommendations?
Maybe including API version in the response so errors of that kind become very obvious ?
From everything I've seen, Org Mode is basically everything that I've ever wanted in a productivity/note-taking app. The only problem is that I would have to use Emacs...
I know Org Mode is extremely tied in to Emacs' core, but if someone could figure out how to separate it into a vscode extension or something, that'd be really cool
That'd be difficult since org isn't super well defined, though there is an orgdown project that aims to fix that by having levels of compatibility.
You don't need much emacs for org-mode, especially if you keep the (admittedly dated) context-sensitve toolbar. Here's a cool (but short) infographic that gives you more than enough to go off of:
lol just get a pdf cheat-sheet for common commands and learn emacs! it is really not that big of a deal. i think you need few hours before you can start using it effectively and independently. ignore the hype. it is just a tool
Great summary! I use restclient to produce example calls for READMEs and stuff but I hadn’t thought to export an html view.
While this really exercises the markup features of org-mode and org-babel, wouldn’t literate programming have all this interleaved with the implementation at the API you’re documentating?
This approach would work just as well to document and develop, for example, a local Python API. Instead of using `restclient` source blocks, we'd be using Python blocks. Otherwise, it's the same idea.
In my case, I'm documenting RESTful APIs for clients who want to write their own client code.
The WOW for me is that a couple of days ago I was looking for info on exactly how to do this, so tyvm for writing this. The links on the article seem off btw.
Until I found org-mode it really is world changing if I had picked up Doom Emacs for no other reason than org mode it would've been well worth it. I have now seriously considered trying to do literate program with org mode.
It's already seeped into every project I work on now has a notes.org where I keep kind of a stream of consciousness notes of what I am doing and copy and paste any code or command I have into it for future reference and it has already multipled my productivity.
I love org mode and for any person that is already a vimmer I recommend highly you pick up Doom Emacs and spend some time getting to become familiar with it, especially org mode and magit it really is world changing. I can't imagine ever going back.