Re: [Haskell-cafe] expanded standard lib

On Tue, 2007-11-20 at 16:00 +0100, Ketil Malde wrote:

Thomas Schilling 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 documents.

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?