Ah, and it seems the literate programming criticism post by @akkartik has popped up again too on HN.

akkartik.name/post/literate-pr

Any new thoughts since you've written that?

I'm splitting hairs a bit, but I would argue that there's too much emphasis on typesetting here.

Reading Knuth's original paper on literate programming, TeX was both an arbitrary and obvious choice for WEB, since that was his tool as well. He also mentions Scribe and Troff as alternatives for "document formatting languages". The thing thay these all have in common is that they target dead trees rather than screens. This was the simply the way at the time. Keep in mind that this was years away from things like hypertext or any dynamic content like that.

But to be clear, if you're fixated on typesetting your literate programs in 2022, you are objectively stuck in a 70s mode of thinking about literate programming. There are very few contemporary systems where this still makes sense.

Compared to Knuth era software, modern day software is:

Designed to change/pivot a lot. In both structure and scope.

Maintained by groups of people instead of one person.

It'd be pretty miserable to write most contemporary software in literate style. It's just not compatible.

Note that I don't consider this to be a fault with literate programming, but rather the way we tend to write software now.

Programs that lend themselves well to literate programs are things that are complex, well defined, and that change slowly. Anytime I'm building some kind of core system or architecture, I like to do it in a literate style. Not only does it serve as a good reference document later, but it also forces me to think more carefully about what I'm doing.

To be clear: inline comments in code are *not* literate programming, no matter how thoughtful you get with them. Never will be. It feels very different from writing code blocks in a markup language. A true literate programming system has the ability to write code out of order as well.

A nice consequence of using a markup language is that you can write and outline structure before producing any actual code. Many of my own literate programs started this way, and I believe they turned out to be better because of it.

@paul Have you got an example of what your code looks like?

@penguin42

I'll throw out mine as well: https://github.com/akkartik/mu/tree/main/linux/bootstrap

Here's some more detail about how it's built: http://akkartik.name/post/four-repos

I'd like to reiterate from my original post: "If you have spent time reading somebody else's literate programs, I want to hear about your experiences!"

@paul

Follow

@akkartik I've got hard copies of TeX and Metafont the program on my bookshelf. It hits differently than if you were to read it as a PDF.

Nothing even resembling dharma transmission for either of these programs (maybe that's okay?) But it's enjoyable to flip around and read the prose. I wish things were written in a more modular, self contained way like PBRT.

Knuth has consistency in structure in writing, and it's actually inspired me to rethink the way I communicate about program structure:

pbat.ch/wiki/verbs_in_metafont

@penguin42

@paul I really need to maintain a list of people describing what it's like to read other people's Literate programs. I think I've had 3 people respond to my call to say yes, they have read Literate programs. I'm going to start it now and add yours.

I'm particularly interested in usability reports. What gave you the most trouble in understanding some Literate program written by someone else.

@penguin42

Sign in to participate in the conversation
post.lurk.org

Welcome to post.lurk.org, an instance for discussions around cultural freedom, experimental, new media art, net and computational culture, and things like that.

<svg xmlns="http://www.w3.org/2000/svg" id="hometownlogo" x="0px" y="0px" viewBox="25 40 50 20" width="100%" height="100%"><g><path d="M55.9,53.9H35.3c-0.7,0-1.3,0.6-1.3,1.3s0.6,1.3,1.3,1.3h20.6c0.7,0,1.3-0.6,1.3-1.3S56.6,53.9,55.9,53.9z"/><path d="M55.9,58.2H35.3c-0.7,0-1.3,0.6-1.3,1.3s0.6,1.3,1.3,1.3h20.6c0.7,0,1.3-0.6,1.3-1.3S56.6,58.2,55.9,58.2z"/><path d="M55.9,62.6H35.3c-0.7,0-1.3,0.6-1.3,1.3s0.6,1.3,1.3,1.3h20.6c0.7,0,1.3-0.6,1.3-1.3S56.6,62.6,55.9,62.6z"/><path d="M64.8,53.9c-0.7,0-1.3,0.6-1.3,1.3v8.8c0,0.7,0.6,1.3,1.3,1.3s1.3-0.6,1.3-1.3v-8.8C66,54.4,65.4,53.9,64.8,53.9z"/><path d="M60.4,53.9c-0.7,0-1.3,0.6-1.3,1.3v8.8c0,0.7,0.6,1.3,1.3,1.3s1.3-0.6,1.3-1.3v-8.8C61.6,54.4,61.1,53.9,60.4,53.9z"/><path d="M63.7,48.3c1.3-0.7,2-2.5,2-5.6c0-3.6-0.9-7.8-3.3-7.8s-3.3,4.2-3.3,7.8c0,3.1,0.7,4.9,2,5.6v2.4c0,0.7,0.6,1.3,1.3,1.3 s1.3-0.6,1.3-1.3V48.3z M62.4,37.8c0.4,0.8,0.8,2.5,0.8,4.9c0,2.5-0.5,3.4-0.8,3.4s-0.8-0.9-0.8-3.4C61.7,40.3,62.1,38.6,62.4,37.8 z"/><path d="M57,42.7c0-0.1-0.1-0.1-0.1-0.2l-3.2-4.1c-0.2-0.3-0.6-0.5-1-0.5h-1.6v-1.9c0-0.7-0.6-1.3-1.3-1.3s-1.3,0.6-1.3,1.3V38 h-3.9h-1.1h-5.2c-0.4,0-0.7,0.2-1,0.5l-3.2,4.1c0,0.1-0.1,0.1-0.1,0.2c0,0-0.1,0.1-0.1,0.1C34,43,34,43.2,34,43.3v7.4 c0,0.7,0.6,1.3,1.3,1.3h5.2h7.4h8c0.7,0,1.3-0.6,1.3-1.3v-7.4c0-0.2,0-0.3-0.1-0.4C57,42.8,57,42.8,57,42.7z M41.7,49.5h-5.2v-4.9 h10.2v4.9H41.7z M48.5,42.1l-1.2-1.6h4.8l1.2,1.6H48.5z M44.1,40.5l1.2,1.6h-7.5l1.2-1.6H44.1z M49.2,44.6h5.5v4.9h-5.5V44.6z"/></g></svg>