Literate programming

What Hacker News says

1. 20after4Oct 2026
   This is pretty cool. I've been interested in runnable code in markdown for a long time. It's a kind of "literate programming¹" which I've always thought was one of Knuth's best ideas.

   More prior art: xcfile²

   I've used xc³ for a long time now and it's fairly solid. The idea of runnable markdown is definitely useful. A lot of projects have attempted it and none that I've seen have achieved what I'd call perfection, however, xc gets close enough for my needs.

   I'll check out Ledge a bit more thoroughly and give some feedback if I can think of anything constructive. I think xc is probably more suited for my uses, however, I do like electrobun and that seems like a good runtime to build something like this.

   Here's what I like about xc:

   1. It's built with GO and brings all the power of go's template engine. The portability of go's runtime means that it is just one binary and doesn't have any crazy runtime dependencies.

   2. It has a built in dependency system so that each block of code can be predicated on another block completing. It can also ensure that each block in a dependency chain runs just once.

   I've built a sort of configuration management system for my home infrastructure with config files in a git repo and all the deployment scripts and dependencies directly in the readme. I use it to maintain and deploy changes to my router, firewall rules, dhcp and dns, git repositories, and various containers.

   1. https://en.wikipedia.org/wiki/Literate_programming

   2. https://xcfile.dev/

   3. https://github.com/joerdav/xc

   Show morethread
2. WillAdamsApr 2025
   Powerful argument for Literate Programming:

   http://literateprogramming.com/

   The two best programmers I worked with had well-thumbed copies of Knuth's TAoCP....

   thread
3. WillAdamsFeb 2025
   Knuth?

   He has argued in the past that the concept of Literate Programming

   http://literateprogramming.com/

   is the most important work he has done, and I highly recommend his various collections of lecture notes/papers including:

   https://www.goodreads.com/book/show/112245.Literate_Programm...

   Show morethread
4. schaeferJan 2025
   > I was probably not alive the last time anyone would have learned that you should read existing code in some kind of linear order, let alone programming.

   If you want to dive all the way down that rabbit hole, can I recommend you check out the wikipedia article for the book Literate Programming [1] by Donald Kunth [2].

   [1]: https://en.wikipedia.org/wiki/Literate_programming [2]: https://en.wikipedia.org/wiki/Donald_Knuth

   Show morethread
5. WillAdamsNov 2024
   Every time this comes up, I am mystified by why very few programmers I have met are aware of the concept of Literate Programming:

   http://literateprogramming.com/

   as developed by Dr. Donald Knuth to create the programs TeX and METAFONT.

   The big thing here is that writers need different tools than programmers --- but one thing which wasn't acknowledged for TeX was that the woven .web files documented a low level of the programs in question, one which was so low that the woven documentation wasn't really useful to most folks --- arguably, what should have happened is plain.tex and plain.mf should have been plaintex.web and plainmf.web and included the text of _The TeX Book_ and _The METAFONT Book_ respectively (perhaps one day Dr. Knuth will allow that, or take the time to do this).

   The mention in this podcast of TypeSpec is interesting, but the proposed application seems a very narrow one.

   A better option maybe would be a collaborative approach where it is acknowledged that code which cannot be easily explained/documented maybe needs to be re-written:

   https://www.folklore.org/Inside_Macintosh.html

   Just watched MIT's OCW for Introductory Python, and one of the suggestions there for debugging was describing the code to a child (or kitten, or stuffed animal) --- of course the best code is that which never needs to be written (using a library), but arguably second-best is the code which is correct and doesn't need to be debugged, so third-best would be code which is documented well enough that it may be debugged/re-written easily.

   When I looked for Literate Programming tools for my current project, I didn't find anything which seemed a good fit, so resorted to asking on tex.stackexchange.com https://tex.stackexchange.com/questions/722886/how-to-write-... which allowed me to create:

   https://github.com/WillAdams/gcodepreview/blob/main/literati...

   which I've been using in:

   https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...

   (which is currently being re-written in Python)

   Quite simplistic, but working with the linear .tex file is way better than my previous approach of tiling 3 different files open in 3 different OpenPythonSCAD instances and using a fourth window to test the code. I'd be very interested in suggestions of other tools and resources to consider. I've been collecting LP texts at:

   https://www.goodreads.com/review/list/21394355-william-adams...

   (in particular, while not an LP text, Ousterhout's _A Philosophy of Software Design_ was quite striking and reading through it and then reviewing my code to apply its principles one chapter at a time helped immeasurably)

   The idea that they have here of using AI to make a first automated pass at documentation and then editing it by hand seems like a lot of extra work, and likely to create the possibility of introducing some subtle misunderstanding in the text which is then difficult to ferret out.

   Show morethread
6. misja111Oct 2024
   Thanks for the hint about Knuth's literate programming! I hadn't heard about it before but it immediately looks great. (For those of us who hadn't heard about it before either, here is a link: https://en.wikipedia.org/wiki/Literate_programming)

   About your other point: I have experienced exactly the same. It just seems impossible to instill the belief into most developers that readable tests lead to faster solving of bugs. And by the way, it makes tests more maintainable as well, just like readable code makes the code more maintainable anywhere else.

   Show morethread