Literate Programming in the Large
Why Hacker News recommends it
HN recommends it in literate programming threads as a rare look at applying the idea to a huge, complex codebase, though some find it meandering.
What it is
Timothy Daly, an original author of the Axiom computer algebra system, talks about turning a large Common Lisp codebase into a literate program. He argues code should be written as readable manuals, and the talk was given at Write the Docs 2013.
Recommended by 3 HN commenters across 4 different months, 2014 to 2024.
What Hacker News said
Recommends sparkie · 2014-04 · on “You Don't Read Code, You Explore It”
I like Tim Daly's viewpoint that we shouldn't just be writing code , but we should write manuals - giving high level overviews of our problems and specifying their implementation details inside the manuals. His talk "Literate Programming in the Large"[1] covers why. The example he gives in his talk is the Axiom algebra system[2], which was revised to use literate programming style - the source code, with usage examples, is contained entirely within the books. [1]: [this video] , [sldes]: [LINK] [2]: [LINK]
Recommends e12e · 2016-05 · on “Final “STEPS Toward the Reinvention of Programming” Paper [pdf]”
I think there are two sound approaches to communicating complex systems between humans (which is the main goal here, a computer might be a bit slow compiling 200M LOC - but the real problem is that no human can read that much code, let alone understand it): 1) Write documentation that is also code. That is the idea of literate programming. I recently came across: "Literate Programming in the Large": [this video] which is a bit of a wandering talk, but well worth watching: it talks about real, huge comolex systems, and how lp can help bring them back under control. 2) The other approach is to shift your perspective, so you don't have a complex solution to a compkex problem; but rather a few small
Recommends e12e · 2016-05 · on “Literate programming: Two beefs with the classic version (2014)”
I found this talk about re-structuring and bringing back to life a 1.2 MLOC lisp codebase with classical LP interesting (it's a bit meandering, but INHO well worth a watch): "Literate Programming in the Large": [this video] The reorganization is still ongoing, as can been seen at: [LINK]
Recommends e12e · 2016-07 · on “Literate programming: presenting code in human order”
There's a (somewhat rambling, but interesting) talk on the effort to rewrite the lisp symbolic math system Axiom[a] as a literate program (spanning several books) - precisely in order to make it possible to refactor and maintain the code: "Literate Programming in the Large": [this video] [a] [LINK]
Recommends elviejo · 2017-05 · on “Show HN: Legion, an as-simple-as-possible blockchain server written in Haskell”
"Programs should be written for people to read, and only incidentally for machines to execute." (Structure and Interpretation of Computer Programs" by Abelson and Sussman) The idea is that you write a "Book" and the program is extracted, from the book. Literate Programming Wikipedia: [LINK] A nice talk about it: [this video]
Cites daly · 2015-08 · on “Ask HN: Why did literate programming not catch on?”
I've been using literate programming for 15 years on many projects. The largest and most visible one is Axiom ( [LINK] ) which currently has many thousands of pages with embedded code. I've talked to Knuth. He claims he could not have implemented MMIX without literate programming. Literate programming is really valuable but you only understand that once you really try it. I gave a talk on this subject at the WriteTheDocs conference: [this video] You can write a literate program in any language, for instance, in HTML: [LINK] There are some "gold standard" literate programs: "Physically Based Rendering" by Pharr and Humphreys won an academy award. "Lisp in Small Pieces" contains a complete lisp imp
Cites daly · 2022-01 · on “Literate programming: Knuth is doing it wrong (2014)”
You wrote "There's a fundamental problem with generating a beautifully typeset document for a codebase: it's dead. It can't render inside just about any actual programming environment (editor or IDE) on this planet, and so we can't make changes to it while we work on the codebase." Sorry, that's not correct. When writing a literate program you should also include a chunk containing a Makefile. Extract the Makefile and let it construct the program. I did this with the whole Clojure programming language. The whole source code for all of Clojure, as well as the test cases, are in the PDF. The sequence (from scratch is): Extract the Makefile from the Latex document. Run the Makefile. This: 1) ex
Cites daly · 2024-01 · on “Axiom – A scientific computation system”
Thanks for the "all the work" complement. Despite all, it is more fun than work. Computer algebra algorithms are basically functions. Axiom is unique in that it organizes the functions based on a group theory scaffold. Thus you can know that certain matrices commute but rectangular ones don't. Algorithms that know how to commute live in the commutative "category" in Axiom. So the game is to distribute LEAN's commutative axioms in their proper place in the group theory inheritance scaffold so they are available when they apply. Axiom arranges the world into "categories" (not category theory stuff) and "domains". The LEAN structure is a third structure (actually fourth but...) built in paralle