[hzhou321]

What are the key differences between a human audience and a machine interpreter? It is not the language or prose. It is the structure and order. For machines, details comes first. You declare all the actors and types with every non-forgiving annotations first. You may tuck the details into a header, but it still needs be ordered according to compilers and structured in the way that machines gets the details first. On the other hand, for human, it is top-down context oriented. The details are important, but not after we establish the right context.

So for literate programming, if you just think it is how you write the code (e.g. self-documenting or not), or you think it is the amount of commenting (e.g. doc string or not), if you are not first and constantly thinking about how to structure your code and establish context, you are not getting literate programming.

Now, once you understand your ends, the means (tangle or weave), will come along. It is easy to invent one if you don't have one. On the other hand, getting your coworkers to agree and work together, that's hard. It is easy to get machines to work together and it is easy for human to cope.

[syntaxfree]

Context can be expresses with thin, somewhat redundant interfaces that group code around how they map to desiderata. Eg the meat in “matrix pseudoinverse” and “linear regression” is the same, but you can expose domain-meaningful abstractions. Regular OOP does “tangle and weave” without the messy text transformation mechanics.

[hzhou321]

I guess the word "context" has been misused in computer science. An interface is a computer context. In particular, an interface is full of non-negotiating details. A human context is about why (we need it), what (we want), and how (to achieve the goal at high level). Most details at high level is understood as the ways things can go wrong. This understanding provides context when we later dive into the details.

An interface with all its details is an end product. With literate programming, that shouldn't show up as a single piece up-front. It should be developed with layers, each layer with its context (why, what, how), each layer with design and implementation.

Certainly we still want a view of complete interface with all its details in one place. This is the same as the compiler still wants the entire code in its expected structure and order. That's the job of tangle.