Is literate programming in Haskell really "literate programming"?

Question

I'm new to the concept of literate programming. I was reading Donald Knuth's paper (PDF) concerning this subject, and in the very beginning, in the Introduction, he says:

Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

He or she [the practitioner of literate programming] strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

Then, reading further:

A thing about a program is its structural relationships. A complex piece of software consists of simple parts and simple relations between those parts; the programmer’s task is to state those parts and those relationships, in whatever order is best for human comprehension— not in some rigidly determined order like top-down or bottom-up.

(...)

Top-down programming gives you a strong idea of where you are going, but it forces you to keep a lot of plans in your head; suspense builds up because nothing is really nailed down until the end. programming has the advantage that you continually wield a more and more powerful pencil, as more and more subroutines have been constructed; but it forces you to postpone the overall program organization until the last minute, so you might flounder aimlessly.

Thus the WEB language allows a person to express programs in a “stream of consciousness” order. TANGLE is able to scramble everything up into the arrangement that a PASCAL compiler demands^†. This feature of WEB is perhaps its greatest asset;

The above excerpt make me interested in the subject, so I investigated a bit more. It's not difficult to see in the results provided by any search engine the relation between Haskell and literate programming, but I don't see the that “order best for human understanding”. Rather I see a very well done documentation while keeping the order that the computer requires in order to work.

• Can you use the term “literate programming” taking away that order issue?
• Is there any other definition of literate programming that do not requires the "stream of consciousness" order feature?
• Is Haskell really literate programming capable (using Knuth’s definition)?

Last, I have to say as a personal opinion, that even what Haskell does (and probably many other languages do) is not Knuth's literate programming, I still like the idea when it comes to exhaustive descriptions of methods and algorithms. When the comments exceed by far the code it serves a great purpose.

---

^† WEB and TANGLE are part of the system that originally D. Knuth used in his first implementation of the literate programming concept.

Answer 1

Haskell is, for the most part, very flexible when it comes to ordering. Within a Haskell module, all declarations and definitions may occur in any order. Thanks to referential transparency, it is also very easy to extract subproblems in order to implement them somewhere else.

The main area where order matters is pattern matching. All equations of a function have to be together and since they are matched in order, they cannot always be re-ordered. However, I do not feel that this is a significant limitation since (a) this is usually very localized and (b) big functions with lots of equations can (and probably should) be refactored into smaller parts which are then easier to re-order.

The perhaps most annoying constraint is that import declarations have to be at the top of the module. This does break the stream of consciousness a little, and many literate programs written in Haskell begin with a statement like "don't mind these imports, you'll see where we need them later". It would have been more consistent with Knuth's definition of literate programming to be able to name imports at more natural points during the text where it is clear from the context why they are needed.

That aside, I think Haskell works well for literate programming. It may not fit Knuth's definition perfectly, but I think it comes close enough.