knuth-literate-programs

Examples of literate programming by Knuth (by shreevatsa)

Knuth-literate-programs Alternatives

Similar projects and alternatives to knuth-literate-programs

NOTE: The number of mentions on this list indicates mentions on common posts plus user suggested alternatives. Hence, a higher number means a better knuth-literate-programs alternative or higher similarity.

knuth-literate-programs reviews and mentions

Posts with mentions or reviews of knuth-literate-programs. We have used some of these posts to build our list of alternatives and similar projects. The last one was on 2020-12-30.
  • Professor Donald Knuth on Writing and More, an Interview [pdf]
    4 projects | news.ycombinator.com | 30 Dec 2020
    So with that understanding in the comment above, I think one is supposed to glean that the following is the structure of the ADVENT program (http://literateprogramming.com/adventure.pdf or download from https://github.com/shreevatsa/knuth-literate-programs/blob/m... for working hyperlinks):

    - In "Introduction" (sections 1–3), the program's overall outline is given,

    - In "The Vocabulary" (sections 4–17), we have data structures for storing words (the hash table), how they map to motions and objects and other responses from the program,

    - In "Cave Data" (sections 18–20) there are the 100+ locations one can be in during the game,

    - In "Cave Connections" (sections 21–62) there's the game's "map" data: how you get around, what messages you get, etc,

    - In "Data structures for objects" (sections 63–68), there's data structures for the list of (game) objects at a given location, for groups of objects, and object properties (like its name and in-game note),

    - In "Object data" (sections 69–70) these are populated,

    - "Low-level input" (sections 71–73), is just asking yes/no questions and taking in commands,

    - The next chapter, "The main control loop" (sections 74–91) begins with some comments very revealing about the author's programming style / thinking:

    > Now we’ve got enough low-level mechanisms in place to start thinking of the program from the top down, and to specify the high-level control. […] Here is our overall strategy for administering the game. […] The execution consists of two nested loops: There are “minor cycles” inside of “major cycles.” Actions define minor cycles in which you stay in the same place and we tell you the result of your action. Motions define major cycles in which you move and we tell you what you can see at the new place.

    etc. And this chapter, in turn using many of the following ones, is what populates one of the main sections that were mentioned in the outline of the program on Page 2. There's parsing of the user's input, dealing with edge cases, until we figure out where to `goto`.

    - The next chapter, "Simple verbs" (sections 92–103) starts with “Let’s get experience implementing the actions by dispensing with the easy cases first” i.e. it's the start of several chapters implementing the action procedures we invoke (or to which we "goto") from the previously mentioned main control loop.

    - The next chapter, "Liquid assets" (sections 104–115) starts with something that I also find revealing: "Readers of this program will already have noticed that the BOTTLE is a rather complicated object, since it can be empty or filled with either water or oil" (so he expects that your reading will have noticed this already?)

    - Then "The other actions" (sections 116–139) is what you'd expect: "Now that we understand how to write action routines, we’re ready to complete the set" (must say, this whole game looks a lot of fun! Thanks Crowther and Woods!)

    - Then "Motions" (sections 140–153) (filling out a section referred to in the main control loop above), "Random Numbers" (sections 154–158, half a page), "Dwarf stuff" (sections 159–176), "Closing the Cave" (177–182), and "Death and Resurrection" (183–192), "Scoring" (193–199), and "Launching the program" (section 200).

    Well, with my hard-won familiarity with WEB/CWEB conventions (I bet you didn't expect the table of contents to be on the last page) and with Knuth's style (there's often a main control loop branching off to various action procedures), the above was what I understand of the overall structure of the program, and it took me about a second or two per page, maybe a bit more here and there, less than five minutes overall. But now I feel oriented enough that I can now understand the program as a whole, and I think literate programming (though I haven't even started actually reading it!) makes the program more helpful than if it was written in "for the compiler" order with the same soup of functions and gotos. But to reiterate, this is about better presentation of programs written in straightforward "just tell the computer what to do" style. It is conceivable that with modern programming conventions, with just the right abstractions and objects and whatnot, one could produce something more readable. But that's not relevant here, I think (and besides maybe that program too could be reordered, written literately?)

    Now, one could ask: why doesn't Knuth just write out this outline at the beginning? Why is the heart of how the program works, the main control loop, mentioned neither at beginning nor end but in the middle of the book, section 74 of 200? Is it fair to the reader to have so many conventions that are not explained in the program itself? Well, I have no end of frustrations with trying to read Knuth's literate programs (see my complaints and jokes in the page I linked above and in the slides), but still I think the answer would be: (1) Every house style has its conventions that must be learned (like: "variables ending with an underscore are private member variables in this codebase"), (2) It would be extra work to write this all out when the reader can just skim and find out, and for Knuth, literate programming (and programming in general) is supposed to be fun, not drudgery. So while I think Knuth-style literate programming has problems, I think the more interesting problems are not the surface-level ones.

Stats

Basic knuth-literate-programs repo stats
1
34
6.2
10 months ago

The primary programming language of knuth-literate-programs is CWeb.

SaaSHub - Software Alternatives and Reviews
SaaSHub helps you find the best software and product alternatives
www.saashub.com