So with that understanding in the comment above, a case study of the ADVENTURE program (http://literateprogramming.com/adventure.pdf http://literateprogramming.

So with that understanding in the comment above, a case study of the ADVENTURE program (http://literateprogramming.com/adventure.pdf http://literateprogramming.com/adventure.pdf or download from https://github.com/shreevatsa/knuth-literate-programs/blob/master/programs/advent.pdf https://github.com/shreevatsa/knuth-literate-programs/blob/m... for working hyperlinks). I think that even though the program was written in the order it's written (and he thinks best read that way), the following is the structure of the ADVENT program (and one is supposed to glean that first). The whole program is divided into numbered sections, grouped into what I'll call "chapters". They are: - 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 of font choice and numbering and so on (I bet you didn't expect the table of contents to be on the last page!) and with Knuth's style (one can often expect a main control loop branching off to various action procedures), the above is what I understand of the overall structure of the program after a quick reading taking about a second or two per page, maybe a bit more here and there, less than five minutes overall. After that, I feel oriented enough that I can now start reading the program, and I think literate programming (though I haven't even started actually reading it!) makes it easier to understand than if it had been written in "for the compiler" order with the same soup of functions and gotos. But to reiterate, LP in this case is about better presentation of programs written in straightforward old-style "just tell the computer what to do" idiom. It is conceivable that with modern programming conventions, with just the right abstractions and objects and whatnot, one could produce something more readable, and which did not have so many global variables and so on. But that's not the relevant comparison here, I think (and besides maybe that program too could be reordered, written literately?) Now, the main question that arises is: why not just write out this outline at the beginning? Why is the heart of how the program works, the main control loop, described neither at the beginning nor the 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 for the programmer 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 there are more interesting problems than the surface-level ones. (For example, someone's observation that there are approximately as many LP systems as programmers practising LP: no one is comfortable using others' tools and ultimately wants to write their own tool.)