2026-08-17
I've recently adopted emacs and discovered the delights of Org Mode. I'd say it even has a positive cognitive effect. To get there, it's a bit of a journey, which winds through working method superstitions, text editor wars and comparisons to Don Bluth movies.
So how did I get started with emacs? I wanted to try Literate Programming (LP). It's a "programming as essay writing" paradigm Donald Knuth proposed in 1984. The format inverts the relation of comments and code. Source documents for the programmer are expository prose sections punctuated by blocks of executable code. The source document is transpired in two ways: It's 'woven' into documentation, and also 'tangled' into code recognizable by the interpreter or compiler.
In his interview in the book Coders at Work, Knuth effused about his home-rolled paradigm
What I try to work on is units that correspond to the way I have it in my head, rather than the way a logician might want it to be in some formal system. My programs are supposed to match my intuition more than somebody else’s rigid framework.
Of course, eventually it has to go into a computer, which is rigid, which has its precise rules of understanding. But to me the idea of the right kind of program is something that matches the way I think as closely as possible rather than something that matches the machine as closely as possible. I have to find the way to do the conversion, but my source text tries to stay closer to my brain than to the machine.
Coding by intuition is an out-there idea. I don't mean "vibe coding" where you argue with Claude code for three hours and transform into a reverse centaur. I mean whatever mystical semi-transcendent state the inventor of the Potrzebie System was talking about. Will sampling some of this special blend expand my mind and make me a better programmer?
I don't know, but it seemed like an idea too crazy not to try.
The closest thing to a generalizable implementation of LP is emacs' Org Mode. Variants of Knuths's .web files transpile to C or Pascal. Computerized notebooks like Jupyter can replicate the work style, but they're bound to specific languages and use cases. Some poking around about LP brought me to Howard Abrams who confidently (perhaps suspiciously so?) asserts that cross-language literate programming can be done in Org Mode.
Org Mode is primarily a note-taking mode on steroids. The primary feature is the ability to represent information in a heiarcy (in this case, headers, sub-headers and nested lists) and slide those blocks around the tree with a minimum of fuss.
Org Mode plugins are available for other editor, but the necessary tangle relies on Org Babel.
I wasn't looking to write to-do lists, I was looking to program. It looked like for the purposes of this experiment, I'd need to install emacs.
Historically, I'm used to vim, emacs' ancient blood rival. Fans of these platforms get really passionate about the inherent values of their tools. I initially had picked up vim because I wanted to invest in learning an evergreen text editor, and didn't give it much thought after that. I felt a little guilty about breaking ranks.
Setting up emacs is exactly as fun as it sounds. The process entailed flagellation by configuration, pursuits of wild ornithoids without cause, false starts, and learning additional emacs commands on top of my vim motions.
If I was worried about betraying the holy cause of vim, I believe my suffering has sufficiently paid for my sins.
Rather than take a first experiment with a full-featured application,n I figured I'd test LP on configuring a blog with a framework I haven't used before. This blog is a statically generated site using zola.
The single source of truth for the zola configuration is an .org file so I can build the site via Literate Programming
(My emacs configuration is also an .org file so I can adjust the emacs settings via Literate Programming ... turtles all the way down).
Zola has a simple tutorial. Would I gain any insight by implementing it LP?
The plan was to write it like a prose document: two drafts and a polish.
Draft one was "write everything down and make it work". I'd write down notes set the basic .html and .toml syntax in src blocks in the .org file.
If a block of text or code was too large, I'd just set it under a header and fold it.
I never touched zola before so there were conventions and jargon that made no sense, why where there documents formatted with '_**.md'?
Why did some .toml describe site content and others describe some kind of information schema? What the heck were "sessions"?
I wrote down all my musings, brain farts and questions and kept going.
Once the output worked, I revisited the big messy .org file to clean it up.
Writing is rewriting. If there was any magic to LP, it would emerge from the second draft.
While sliding around fold-able blocks of text, I read over my ramblings about "sessions" and other zola conventions. I had my Secret of NIMH moment. Like the cartoon lab rat-turned-wizard recalling his mental awakening....
I looked at the words on the cage, and I understood them
Looking over my notes from earlier, I found I could answer these questions... explain them in my own words,
and leave my explanation there while the rationale was still fresh.
I used the .org file as a living scratch-pad, and that expanded my context window.
My world exploded; I knew what the hell I was doing.
The easy reshuffling Org Mode facilitates is awesome, but the jury's still out on Literate Programming. It's extremely unlikely to be adopted as a standard in developing commercial applications. Most programmers don't want to write technical essays. Also, Donald Knuth has many outstanding traits, but "speed" isn't one of them; TeX was a 10 year side project. Using emacs' org mode for LP means learning a whole new meta-syntax for a language-agnostic framework. Most languages that have their own conventions for comments and macros.
Given some more shakedown time, Literate Programming could prove to be well worth the hassle. If more work at the top means fewer bugs later, that's added value. If the woven-in documentation is clear, usable and superior to the (often-skipped) annotation style, that's added value. If the process produces a very clear understanding with the programmer, that's added value.
So far I got one out of three.
I find org mode to primarily be an attention management system useful for arranging and internalizing ideas.
When working "straight ahead" in that stream-of-consciousness mode,
you can add headers to massive walls of text (stack traces from a src'd out shell command) and fold them from view.
So you can expand your context window when troubleshooting command-line issues.
Most importantly, when you revise your notes, you farm out the insights from the free-form brain dumps.
I can't say I'm an emacs convert, but it's worth getting beat into the gang to try out Org Mode.