I wasn't sure exactly where to jump into this, but this looks like
as good a place as any:
On 20 Mar 2000, Ketil Malde wrote:
>
> Frank Atanassow <[EMAIL PROTECTED]> writes:
>
> I used to work with this in a previous life, so mind if I chime in?
> I'm by no means an expert, though.
>
> > First, I agree with Phil, that if you are going to use a markup
> > language, you should be using an XML/XSL solution instead.
>
> I like XML's stricter requirements for well-formedness. Nobody in
> this decade will use an editor that can't close tags automatically for
> you.
I'm not a "big league" Haskell programmer in any way, and I'm unlikely to
contribute much to the Haskell effort, what with that pesky "getting
tenure" thing hanging in the background. But I do detect something really
weird in the Haskell culture as far as human factors and programming/
documenting issues go. I already posted something about the possibility
of better composition operators, and the fact that the current record
syntax is... well, I already said that.
But as far as the text and of the code, comments, and now possibly
metacomments go, we simultaneously have:
1) Haskell code uses white-space as a delimiter by default, presumably
because it's clean and intuitive.
However: it seems like once a month (or even more often), it gets
pointed out that the "offsides" rule that Haskell
compilers/interpreters have to use is, uh, pretty hideous. And
a slew of Haskell bugs often boil down to finding a misindented
"where" clause 200-and-something lines up the file.
Also however: Every idea I've seen so far about (re)doing literate
programming in Haskell seem to recognize the fact that ending
delimiters are a reasonable price to pay for a lot of reasons. So
Haskell could end up being a language where you could have a program
whose documentation is exquisitely and verifiably well-formed despite
the fact the code itself has been ruined by incorrect indentation.
Am I the only person who finds that really, really weird?
3) People in the Haskell programming community seem to appreciate
the benefits of abstraction. Wow, what a surprise. Nonetheless,
I've seen documentation for Haskell projects presented in formats
that range from plain text to LaTex to HTML to postscript generated
by a word processor that shall remain nameless...all over the place,
with the one commonality apparently being that, as far as formats go,
the statement "You can't get there from here" is true for many if not
values of "You", "there", and "here". As far as I can tell, the best
stab so far seems to be LaTeX, just because you probably could get
to some other format from there on almost any machine.
However: this is not just a problem for Haskell, *and it's a very
hard problem if you want it to be*. There are maybe a thousand
computer languages out there and fifty thousand systems
for semi-literate programming. As far as I can tell, the one that
is used by the widest variety of people who don't share the same
lab or office is the "pod" format used by Perl. Now, nobody is going
to hold that one out as a model of the ideal anything, but, weirdly
enough, it works well enough, because it doesn't try to over-reach,
but *does* provide translators and converters *to* the formats that
people really need. Number one being html, number two being text,
and number three being man. Everything else seems to be window
dressing these days.
There's probably a lesson there. You can stipulate any old format
you like, but if it won't easily produce HTML (like lout), or
produces a psychotic approximation to HTML (like W**d), you're hosed.
Any browser on the planet can dump HTML to text or postscript, and
no, it won't be artsy, but, gosh, it might just be good enough.
Sorry if that sounded a bit too harsh, but I think the Haskell community
should accept the fact that, right now, there are so relatively few users
of the language that the big incentive for a documentation format is that
it gets stuff into as many hands as quickly as possible. Anything else is
academic. (And I'm not slamming academic, but pointing out that the
number of people who end up initially caring about this stuff outside a
small circle of friends is not large.)
jking
