Volker Wysk writes:
> With SGML, you could achieve all the goals in a systematic manner. You
> would write Haskell-scraps spread over an SGML- instead of a
> Latex-Document. But then, the resulting document *still* is an SGML
> document. You can do all processing a literate programming tool would do
> with a "web" file, directly in SGML/DSSSL. After all, a Haskell programm
> is just another type of text, and LP ist just another sort of text
> processing. SGML is designed to be suitable for (almost?) any conceivable
> way of text processing. And SGML is open, stable, widely used,
> non-proprietary. (And damn complicated for the implementors).
I have five years of experience with both SGML n industry, and I know DocBook
fairly well. I also know DSSSL really, really, really well, so please allow me
to vent some steam and explain why I think using SGML as a literate backend is
not such a great idea.
First, I agree with Phil, that if you are going to use a markup language, you
should be using an XML/XSL solution instead. The reason is simply that SGML is
rapidly being phased out, and XSL is destined to, or maybe already largely
has, replace(d) DSSSL. Even James Clark, who spent five years of his life
developing Jade, the most popular free DSSSL engine, and is mostly responsible
for the design of the DSSSL formatting spec, has given up on DSSSL. (And if
you don't believe me, I can point you to the historic :) message on DSSSList
where he said it.)
Second, SGML is hard to read and write. Part of the reason for putting code
and documentation in the same place is accessibility. When you change the
code, it is supposed to be easy to update the documentation. But with SGML it
is not so easy, because the tags are often long and noisy. SGML lacks some
things that we take for granted, for instance polymorphism and local
definitions, which has a tendency to inflate DTDs and lead to
repetitiveness in instances.
Also, SGML is essentially just a way of representing simple abstract syntax
trees, with some special allowances for text. There is a reason we use
concrete syntax for inputting programming languages. It is easier to read and
write, and we only need a single parsing or pretty-printing step to get us
from concrete to abstract syntax, or vice versa. So, in my mind, SGML is more
properly thought of as a target of some parsing transformation, rather than as
a source language. It is true that there are some tools like the free PSGML
for Emacs, or the commercial Adept products, which simplify the process of
inputting SGML directly, but we cannot expect the average Haskell user to have
such recourse.
The same holds for DSSSL. It is true that DSSSL is based on a sort-of
functional language, but 1) it isn't Haskell, 2) there are a lot of nitpicky
details which can make it difficult to use in practice. If you fix the DTD and
stylesheets, say DocBook, that's a different matter, but if you go that far,
what is the point of exposing the fact that you are using DSSSL to the
literate Haskell programmer at all?
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.
The third reason why I don't think SGML and DocBook are so suitable for
literate programming is that Haskell code is already in a machine-readable
format by definition. So we can generate identifier indices, interface
synopses, etc. directly. There is no need to use SGML for this. (I mention
this because half of your argument depended on using SGML tools for generating
such things.) We only need something like SGML to deal with the literate
portion, i.e., the documentation text.
The only advantage (for us) of SGML/DocBook is that by using DocBook (or
rather, by using DocBook + Jade + Norman Walsh's stylesheets) you get access
to several popular output formats like PS, PDF, RTF, HTML, etc. I agree that
that is a big advantage, but then the average user:
* will wonder why we are not leveraging the power of Haskell at all
("If Haskell is such a wonderful language, why do I need all this
other crud?")
* must learn DocBook + whatever extensions we add to the DTD
* 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; as if installing GHC wasn't hard enough? :)
--
Frank Atanassow, Dept. of Computer Science, Utrecht University
Padualaan 14, PO Box 80.089, 3508 TB Utrecht, Netherlands
Tel +31 (030) 253-1012, Fax +31 (030) 251-3791
