As I’ve mentioned before, I’m ambivalent about literate programming. I love the idea of it and absolutely agree with all its claimed strengths but I’ve never been able to embrace it in practice. The major problem, I think, is that when I’m reading code—and particularly when I’m debugging it—I like to be able to see everything in context and not have related parts scattered throughout the narrative. I don’t think that’s just me waving my cane but perhaps I’m deceiving myself.
One of the common use cases I see for literate programming is in Emacs configuration files. It make’s it easy to explain why you want things to be configured in a particular way and follow the explanation with a code block that implements it. Usually that results in a fairly coarse division of the code and you can see everything relevant at a glance. Even better, using Org-mode means you can fold the sections making it easy to find and open just what you want.
Hsin-Hao Yu has a nice post on his experiments with literate programming. Like me, he thinks that WEB-style literate programming in Knuth’s sense is overkill for his uses. He decided to experiment a bit using Org-mode with his configuration file. So far that sounds like what lots of other folks have done but Yu pushed the idea a little further by using the noweb feature to restructure the code and make the code layout more logical—at least more logical in the literate programming sense.
The example he gives for this is illustrative. He starts with his definition of org-capture-templates that defines 3 templates. Yu says he finds it hard to read and even harder to add another template in the right place. He fixes that by putting each template in a separate code block and using noweb to pull them all into the setq for org-capture-template. That makes it easy to add another template, of course, but he pushes the idea even further by suggesting that the templates could be moved to the section with which they’re related: the journal capture template could be moved to the section that configures his journal, for example.
That last point is where I become ambivalent again. I agree it makes perfect sense and all but I can’t get over the idea the templates should be defined in the same place. Yu’s opinion in this is as good as mine, of course, and as usual Emacs lets us have it our way but if you come down on Yu’s side of the debate, the example shows you how to implement it.
If you have any interest at all in literate programming, take a look at Yu’s post.