[Haskell-cafe] expanded standard lib
nominolo at googlemail.com
Tue Nov 20 10:35:00 EST 2007
On Tue, 2007-11-20 at 16:00 +0100, Ketil Malde wrote:
> Thomas Schilling <nominolo at googlemail.com> writes:
> >> I would advocate using a comment system that is similar to the one
> >> at http://djangobook.com/.
> > I'm pretty sure Brian O'Sullivan has written a Haskell implementation of
> > this for the Real World Haskell book.
> While the technology is there (or will be), I worry if this is the
> right solution for something else than soliciting comments on a
> (fixed, non-editable) text.
> I can all to easily imagine a situation where any documentation is
> riddled with a plethora of notes, questions, answers, comments etc,
> with nobody to clean up the mess every now and then. For user-edited
> documentation, a wiki seems a much better fit - where each author
> make some effort to leave pages as self-contained consistent
Hm. The GHC user's guide currently is generated from a DocBook
(XML-based) language, but when I extended the Cabal documentation (which
also is DocBook) I wasn't very impressed by DocBook. It isn't
particularly well-documented and editing raw XML is never fun, even with
the right Emacs mode. One could hope that a standard format would come
with many tools, but I didn't get the impression that the tools are
great, either. They're also not easy to set up. (On Mac OS I had to
manually add a symlink to fix a script. Installation only worked with
fink, not with Macports. I wouldn't be surprised if it were even harder
to set up on Windows. Ubuntu worked fine, though.)
Using DocBook, however, has some nice advantages. For example, the
possibility to generate documentation in different formats. Something
more easily accessible (from the internet) would certainly be much more
convenient, though. It would be nice, though, to preserve semantic
markup. Aren't there some usable web-based WYSIWYG editors that edit
XML rather than HTML? Also, it should be possible to have branches in
this wiki-system, so that you can associate it with a particular
release, but still update when necessary. (I.e., just linking to a
particular version is not sufficient.)
Does anyone know of a system that comes close to those requirements?
Do we need more features from DocBook for GHC or the libraries, or both?
More information about the Haskell-Cafe