Hello
I think, using literate programming techniques could be very useful. One
could produce all of the following from the same source file(s):
1. Interface (user-level) documentation,
2. User documentation, manuals.
3. The actual Haskell source code,
4. A heavily interlinked HTML version of the source code, for
code-browsing. (Btw, the Linux kernel is on the web this way.)
5. Indexes of identifiers.
6. Printable documentation of the developer-level code, or papers
containing the code.
Maintaining code and documentation at the same central place makes it much
easier to keep the docs accurate and up to date. Editing several files
each time one does a change, would be tedious.
The *web-family of literate programming tools typically address only 3.,
4., perhaps 5., and 6. Javadoc, or javadoc-like special comments as have
been suggested, address 1. The backends are typically restricted to TeX
and HTML. Some tools are programming language dependent.
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).
SGML lets you easily define markup languages (document type definitions,
DTDs). There's no limit in the sort of markup. Some possibilies are
semanitc, presentational and procedural markup. Procedural markup, such as
TeX's, tells the system what to do. Presentational markup describes what
the output should look like. Semantic markup describes the content of a
document.
There are good DTDs for semantic markup in wide use, such as Docbook or
the TEI-Guidelines (TEI-P3).
DSSSL is an accompanying standard. You could do 1.-6. with DSSSL
stylesheets, although for 3. it would be too slow. The term "stylesheet"
is a little misleading. DSSSL actually is a kind of functional programming
language, including side effect-free Scheme as a sublanguage!
A DSSSL program can do three things: 1. transform the input document,
conforming to a particual DTD, to another document conforming to another
DTD. 2. transform it to a standard presentational markup, DSSSL flow
objects, for printing. 3. Do complex, structure-driven queries on the
content of the document.
SGML/DSSSL usage has been increasing quickly in the open source community.
A (partial but useable) open source DSSSL implementation, Jade, is
available. Modern Linux distributions contain ready-to-use SGML/DSSSL
systems, packaged as RPMs! Much open source documentation (such as the
Linux HOWTOs or program documentation) is being done with SGML.
I have experiece with nuweb and javadoc. By coincidence, I have been
investigating literate programming with SGML, when the topic showed up on
this mailing list. As I have found out, discussion about LP with SGML (or
XML) is relatively new, and quite few on the web. Most LP ist done with
Knuth's web and successors.
However, there is the SWEB tag set. It has been adopted for internal use
by the TEI (Text Encoding Initiative), and has found its way into the DTD
the W3C uses for its specifications. SWEB is a set of SGML-tags for
literate programming. Its autor, C. M. Sperberg-McQueen, has extended the
TEI-Lite DTD with it. Docbook likewise has provisions for extending it.
There is also a fast LP tool called SWEB. It extracts the code scraps from
an SWEB-tagged document to produce source files, much like nuweb.
Alle Klarheiten beseitigt? :-)
bye
References
SWEB paper
http://www.uic.edu/~cmsmcq/tech/sweb/sweb.html
SWEB source code (accessable, but not released?)
http://www.uic.edu/~cmsmcq/tech/sweb/
OASIS : Organization for the Advancement of Structured Information
Standards
http://www.oasis-open.org/
