| The joys of literate programming were greatly diluted in Haskell and
| its kitchen sink of commenting conventions. And the later addition
| of \begin{code}...\end{code}, for the benefit of LaTeX hackers, was
| a further mistake based on a misunderstanding of literate programming.
| In particular, the goal is not to have a single document that *does*
| everything, serving simultaneously as plain text, LaTeX source, html,
| postscript(!), etc. The real goal is to have a single source document
| that contains both program text and comments, and from which any of
| the other forms that you want can be *generated*.
Let me leap (briefly but with spirit) to Will Partain's defence! I agree
with the
last sentence of the above paragraph, and that is indeed precisely the model
embodied in Will's literate-programming system, which is where GHC's
\begin{code}
markup originated. It's a pre-preprocessor that generates vanilla Haskell,
or Latex, or whatever. It supports multiple code "ribbons" that can be
interleaved in the text, but are accumulated separately in the generated
code.
It generate indexes and cross references. Etc. The source is emphatically
not a single document that does everything.
In short, it embodies precisely the sentiments that Mark proposes.
(The markup is done with Latex-like commands rather than
bird-track like commands, but that's a separate matter.)
Will's implementation was all written in Perl, and it didn't really catch
on, so in truth no one (not even us) really uses it. But the idea was
right, and I hate to see him maligned!
The trouble with literate programming is that there isn't a de-facto
standard. The great merit of bird tracks is their extreme simplicity.
Maybe we should try Norman Ramsey's noweb.
Simon
