Hi Koen,
I think that literate programming is a great idea, but I don't
think Haskell does it justice. I'll suggest a simple solution
to your problem at the end of this message. You can skip there
now if you want ... or else read on while I rant about this some
more and describe what seems to me to be a better solution to
your problem.
The literate programming conventions using leading '>'s (also known
as "Bird tracks" or the "inverted comment convention") go back to
Orwell, a delightfully elegant language that I had the privilege to
use in my own introduction to functional programming. (Alas, it was
never widely distributed.) The requirement that there be a blank line
between text and code served two purposes. The first was to catch
errors that (really do) occur when the leading ">" on a line of
code has been forgotten. The second was to introduce some visible
space between code and text that made the document easier to read
on a terminal screen. This was the only commenting convention in
Orwell. It was simple, elegant, and quite different to anything
that I had seen before. Some folks were not open to new ways of
doing things (one of the same reasons that FP does not get more
widely used perhaps?), but those of us who were found that it worked
very well.
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*.
We do not (normally) write executable files directly, but instead use
a compiler or assembler to generate them from higher-level sources.
In the same way, I would prefer not to clutter my Haskell programs with
html or LaTeX junk that makes it harder to read, while also limiting
its portability. I think you should write code as a clean, simple,
literate script. And then write, as a separate but more general tool,
a utility that will convert those literate scripts into whatever form you
need. For example, Such a tool might replace the blank line preceding
a ">" line with a single "<pre>" tag, while a blank line after a ">" line
would be replaced with "</pre>". Perhaps it trims out the leading ">"s
too, because they're not needed now that you've moved to multiple fonts.
You write: You get:
+---------------------+ +----------------------+
| Blah blah blah | | Blah blah blah |
| | | <pre> |
| > foo = bar + zub | | foo = bar + zub |
| | | </pre> |
| and so on. | | and so on. |
+---------------------+ +----------------------+
(Markup is often required for text too; use whatever seems appropriate
(and sufficiently general) for the application you have in mind.)
There was never any need whatsoever for \begin{code}...\end{code}; a
simple preprocessor would have served just as well for those who needed
it, without cluttering language specifications and implementations with
unnecessary junk!
Tools like this are not difficult to write. Indeed, they make great
exercises for introductory functional programming classes. Previous
versions of the Haskell report used to include the code for one such
tool in an appendix. It was dropped in later versions, perhaps so that
it could be set as an exercise in FP classes (that was my only non-serious
comment in this email; in truth, I think it might have had more to do with
switching to monadic I/O and with reducing the length of the report).
I use exactly the kind of techniques described here in my work. For
example, I use literate programming for the "Typing Haskell in Haskell"
project (http://www.cse.ogi.edu/~mpj/thih). From a single source, I
generate LaTeX source (from which dvi, ps, and pdf forms can be obtained)
as well as two different executable versions (a single file version and
a multiple file version). It all works pretty well.
Oh yes, the simple solution that I promised: try the command line
option -e, which turns off the test for non-blank lines next to
program code. It's a short term hack, but it will do what you want.
All the best,
Mark
----------------------------------------------------------------------------
[EMAIL PROTECTED] Pacific Software Research Center, Oregon Graduate Institute
Long live literate programming!! \begin{code} ... \end{code}? Just say No!
