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 dislike all the extensions to XML though (Schemas in particular :),
and I worry that in a few years, the XML technologies will be more
complex and ugly than SGML ever was.
I think most of your points against SGML holds for XML as well, am I
wrong?
Anyway, I don't think the choice of markup is all that crucial, but I
think markup for documenting Haskell should also be as functional and
elegant as possible. Is Lout a thing to consider?
> I think that, either: a formatting language for literate Haskell
> should have a concrete syntax which makes it easy to edit using
> standard tools, something lightweight and intuitive like the Wiki
> web syntax; or, we need to write some editing tools in Haskell so
> that they are relatively portable and readily available and
> accessible to all Haskell programmers.
Or both! A lightweight and intuitive markup syntax, with support from
editing tools. The first alternative is the most crucial, IMHO, since
people will really really resent being forced into some particular
editor. And if the syntax is Haskell-like, so much the better.
[The average user]
> * is likely to be intimidated by the massive infrastructure (programs:
> Jade, DocBook stylesheets, Haskell-specific stylesheets, probably
> also PDFlatex; concepts: SGML, DocBook, DSSSL) that is required to
> handle his literate code;
To some extent, yes. But the end user really only needs to understand
how to insert the proper tags, and run hs2ps or the like.
> as if installing GHC wasn't hard enough? :)
What, you mean "apt-get install ghc4" is too hard?
To conclude, I think it is important to determine what we want with a
literate documentation system, aiming for too many targets is bound to
end in disaster.
My favorite environment is Emacs lisp. The programming model sucks,
but the help system is really excellent and interactive, and it's
really easy to get to know the standard (or not) libraries.
Clearly, a Haskell programming environment could provide the
definitions (i.e. type signatures for functions) in scope at any
point, identifying which module they come from, and their value (that
is, <function> or a constant). Something equivalent of a docstring
would be great, but I don't see quite how to incorporate that (in
Lisp, as you all know, the first statement of a function is
customarily a string, which evaluates to itself and is subsequently
ignored, but which may be searched or browsed interactively by the
programmer). On would probably need a global docstring for a
function, as well as docstrings for each pattern to match.
Thinking a bit further from this, I think one of the reasons why Lisp
(and I suspect Smalltalk) have such nice development environments, is
that the environment interacts a lot with the compiler or
interpreter. I.e. the editor can access data structures more or less
internal to the compiler. Or put another way, the program text (in
particular for Lisp) is treated as data by the compilation/development
system. Could this be achieved with Haskell?
This is only to aid development, of course, it won't necessarily give
you nice hard copy, or help you out if you're writing a book with
Haskell code here and there.
Anyway, this looks like a rant, I'll do some more contemplating before
I dig myself even deeper in :-)
-kzm
--
If I haven't seen further, it is by standing in the footprints of giants
