Literate programming tools should never enforce that the code in the woven (pdf/html output) view appear in the same order as it does in the original code view. Unfortunately, Alectryon requires definition-order documents. I would much prefer something like Torii where I can weave the code together in an order that makes pedagogical sense, but does not necessarily pass the proof checker. The writing style in this document is severely hampered by the need to present everything before it appears.

how do I get to this number between 0 and 1? Well, by simply reading on in the spec. There is some some pseudo code, which is easily translatable to Javascript (which I'm doing here in form of a literate program

We decided that we would like to see better documented code included within web pages for convenient browsing. The motivation behind this peculiar aim is to be able to include high quality documentation alongside working code, hopefully making it easier for programmers to produce more maintainable, readable programs.

This approach of interleaving documentation and source code is called literate programming and was first proposed by Donald Knuth in 1984. He argued that all code should be written in these linear, readable documents. See Chris Granger's Eve project for a beautiful example of mixing prose and code.

Colaroid’s unique ap-proach to literate programming is to bring together the rich textediting affordances of notebooks together with automated creationof contextualized code snippets showing code differences, and closeintegration of the literate document into an IDE where code can betinkered with.

I think that TANGLE-style reordering is a lot less important with modern programming languages: they don't do one-pass compilation and so can deal with forward references. Note that most of the cross-references in Knuth's program could be replaced with function calls or constant names

I felt he had just written the program where the default was comment without delimiters (i.e. most just changed the syntax for the compiler).

Literate programming worked beautifully until wegot to a stage where we wanted to refactor theprogram. The program structure was easy tochange, but it implied a radical change to thestructure of the book. There was no way we couldspend a great deal of time on restructuring thebook so we ended up with writing appendices andappendices to appendices that explained what wehad done. The final book became unreadable andonly fit for the dustbin.The lesson was that the textbook metaphor is notapplicable to program development. A textbook iswritten on a stable and well known subject whilea program is under constant evolution. Weabandoned literate programming as being toorigid for practical programming. Even if we got itright the first time, it would have failed in thesubsequent maintenance phases of the program’slife cycle.

A paper doesn’t even contain all the information and data required to reproduce a result. Because if it did, it would be the size of a book.

Knuth recommended getting familiar with the program by picking up one particular part and "navigating" the program to study just that part. (See https://youtu.be/D1jhVMx5lLo?t=4103 at 1:08:25, transcribed a bit at https://shreevatsa.net/tex/program/videos/s04/) He seems to find using the index (at the back of the book, and on each two-page spread in the book) to be a really convenient way of "navigate" the program (and indeed randomly jumping through code, as you said), and he thinks that one of the convenient things about the "web" format is that you can explore it the way you want. This is really strange (to us) as the affordances we're used to from IDEs / code browsers etc are really not there

This column will continue only if I hear from people who use literate-programming systems that they have not designed themselves. and it did not continue.

in other words, there would be no "weave" step

The SE server is also responsible for building ebooks when they get released or updated. This is done using our ebook production command line toolset.

Literate programs allow you to answer these questions naturally.

too many of the coders I know would not honestly attempt it; they are in too much of a hurry to get the code written

the guide shall be written in such a way that all we have to do is produce the guide itself and then a computer can do the heavy lifting—where we might otherwise expect a separate, possibly GUI-driven, "app" to be created for the end user to interact with, we accomplish the same effect by making the guide very detailed—in part also an attempt to evoke the style and quality of old equipment operation and repair manuals that used to be available, when such manuals could be expected to include e.g. full schematics. If done correctly, this should be sufficient for the guide itself to be interpretable by a machine.

In my method, program segments are embedded in the midst of a word processor document--like raisins in cake--so that the emphasis is on the explanation rather than the code.

Any language or system that does not allow full flowing and arbitrarily long comments is seriously behind the times. That we use escape characters to “escape” from code to comment is backwards. Ideally, comment should be the default, with a way to signal the occasional lines of code.

There are currently three implementations of the ActivePapers concept: the Python edition, the JVM edition, and the Pharo edition