Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What is “literate programming”? (2024)

pqnelson.github.io

Post reply on HN
Print view View original

31–40 of 57 posts

Re: What is “literate programming”? (2024)

#32

Post by Nevermark »

d-lisp wrote: post #12
em500 wrote: post #4

This essay seems to be missing the main primary references for literate programming: https://www.cs.tufts.edu/~nr/cs257/archive/literate-programm... https://www-cs-faculty.stanford.edu/~knuth/lp.html Knuths intention seems clear enough in his own writing: Literate programming is a methodology that combines a programming language with a documentation language, thereby making programs more robust, more portable, more e…

I dream of a world where the Knuth idea of programming and mathematics are naturally embedded in our cultures, like novels are. I find it weird to not be able to find linux source code and commentaries or even math/physics/science masterpieces in libraries where you can find Finnegan's Wake easily (at least where do I live), and not be able to talk about the GHC in between two discussion about romance or the weather…

> I find it weird to not be able to find linux source code and commentaries

That one statement is a great concise explanation/motivation for "literate programming".

Explanations with code, that explain code design choices, in a way that enables the code to be understood better, and the ideas involved to be picked up and applied flexibly to reading and writing other code.

Another way to view it is: Developers are "compilers" from ideas to source. Documenting the ideas along with the "generated" source, is being "open source" about the origin and specific implementation of the source.

Re: What is “literate programming”? (2024)

#33

Post by WillAdams »

There are lot of texts which were left out of this post --- I've been trying to collect literate programs published as books here:

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

Not sure where the author got the contention that there are only a few tools for literate programming --- it's a straight-forward enough task that many programmers do this --- heck, even I managed to (w/ a bit of help on tex.stackexchange): https://github.com/WillAdams/gcodepreview/blob/main/literati... --- if it were more complex, and wasn't so implementation-specific (filenames need to be specified in multiple places), I'd write it up as a Literate Program and put it up on CTAN as a package.

One classic bit of advice for writing is, ‘It is perfectly okay to write garbage as long as you edit brilliantly.’ --- the great thing about a Literate Program is that it makes the act of editing far simpler, which has made feasible every program I've ever written which got past the 1K lines mark --- including an AppleScript for InDesign which Olav Martin Kvern, then the "Scripting Evangelist" for Adobe Systems declared to be impossible (my boss had promised a system for creating a four-level deep index from XML embedded in the text of pages in an InDesign document, while OMK averred that it was impossible to create an index entry for more than the main level of the index --- one has to have code which tracks the existence of an entry at each level of the index and where it does not exist, starting at the top-level, insert it, then work down and add the sub-index-entry to the index-entry it is beneath).

Re: What is “literate programming”? (2024)

#36

Post by Jtsummers »

Perhaps the most prominent example of literate programming missed by the author: https://www.pbrt.org/ Physically Based Rendering by Pharr, Jakob, and Humphreys.

Responding directly to a couple things the author wrote:

> When programming, it’s not uncommon to write a function that’s “good enough for now”, and revise it later. This is impossible to adequately do in literate programming.

It's not impossible in literate programming. There's nothing about LP that impedes this, I do it all the time. I have a quick obvious implementation (perhaps a naive recursive solution) and throw it in to get things working. I revisit it later when I need to make that naive recursive one faster (memoization, DP, or just another algorithm all together). It's no harder than what I'd do with an ordinary approach to programming.

> Unit testing is not supported one bit in WEB, but you can cobble something together in CWEB.

WEB was designed for use with Pascal and CWEB for C and C++. At the time the tools were developed, "unit testing" as it means today was not really a widespread thing. Use other tools if you find that WEB is impeding your use of unit tests in your Pascal programs. With other tools (org-mode and org-babel are what I use), it's easy to do. Like with writing good enough functions, you just do it, and it's done. You write a unit test in a block of code and when it gets tangled you execute your unit tests. This can be more cumbersome in some languages than with others, but in Python it's as easy as:

  #+BEGIN_SOURCE python :noweb yes :tangle test/test_foo.py
    from hypothesis import ...
    from pytest import ...
    >
    >
  #+END_SOURCE

  #+NAME: name_of_specific_test
  #+BEGIN_SOURCE
    def test_frob(...):
        ...
  #+END_SOURCE
When I used LP regularly I had a little script I wrote that would tangle source from my org files, and because I had the names and paths specified everything would end up in the right place. This is followed by running `pytest` (or whatever test utility) as normal. I used this in makefiles and other scripts. This is only slightly harder than the normal approach, but not hard. I added a `tangle` step into my build and test process and it was good to go.

If your unit test system requires more ceremony then you'll need to include that as well, but you'd have to include that in your conventionally written code as well.

Re: What is “literate programming”? (2024)

#37

Post by WillAdams »

antiquark wrote: post #25

I seriously looked into it many years ago... One problem with "literate programming" is it assumes that good coders are also good writers, and the good writers are also good coders. Another problem is that the source files for the production code will have to be "touched" for documentation changes. Which IMHO is an absolution no-no for production code. Once the code has been validated, no more edits! If you want to e…

I would turn this around --- it acknowledges the fact that if one needs to write a complex program, and to maintain it over the long term, one will need not just the raw code, but also documentation for how that code was written, and how changes to it should be approached.

As I noted elsethread, the big thing which Literate Programming has netted me is that it makes editing easier/manageable, even for long and complex projects spread across multiple files --- having the single point of control/interaction where I can:

- make the actual change to the code to implement a new feature

- change the optional library which exposes this project to a secondary language

- update the documentation to note the new interface

- update the sample template files (one for the main implementation, the other for the secondary) to reflect the new feature

- update an on-going notes.txt file where the need for the new feature was originally noted

is _huge_ and ensures that no file is missed in the update.

Re: What is “literate programming”? (2024)

#39

Post by GrantMoyer »

js8 wrote: post #8

Maybe I am weird, but I would like to see/program in a formal, yet fuzzy/modal language, which could serve as a metalanguage that describes (documents) the program. This metalanguage must have some kind of constructs to describe unknown things, or things that are deliberately simplified in favor of exposition. So basically eschew natural language completely in favor of fully formalized description, that could be mani…

> This metalanguage must have some kind of constructs to describe unknown things, or things that are deliberately simplified in favor of exposition.

Perhaps you're thinking of mathematics.

If you have to be able to represent arbitrary abstract logical constructs, I don't think you can formalized the whole language ahead of time. I think the best you can do is allow for ad-hoc formalization of notation while trying to keep any newly introduced notation reasonably consitent with previously introduced notation.

Re: What is “literate programming”? (2024)

#40

Post by froh »

Is there some literate programming LSP server around, which under the hood tangles the code chunks for language specific child LSP servers, and proxies those? so you have LSP support in the litprog source?

it would probably also semi-weave the source into a standard, say, markdown or latex or asciidoc and proxy that LSP server on those woven files.

Post reply on HN