Re: [Haskell-cafe] expanded standard lib

On 11/20/07 7:35 AM, Thomas Schilling wrote:

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

...

Thomas Schilling writes:

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

Hi, [Disclosure: I'm a large part of O'Reilly's re-adoption of DocBook internally and a member of the OASIS DocBook SubCommittee for Publishers] I'm particularly surprised by this last sentence on the lack of documentation, as the DocBook standard has a definitive, comprehensive, freely available manual at http://www.docbook.org/tdg/en/html/docbook.html that I've always found very usable. Were there particular things that you missed?

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.

The state of GUI XML editors has advanced significantly over the last year with the continued work on both XXE (http://www.xmlmind.com/xmleditor/) and oXygen's latest release (http://www.oxygenxml.com/docbook_editor.html), for example. That said, there are not as many tools for editing DocBook XML as HTML, for example.

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?

Not that I've found. I'd be delighted to hear about possibilities. Most web-based attempts start with the desire of writing in a plain-text wiki language and getting to XML. These seem to always fail on complex markup (tables, nested lists, code with internal markup).

Do we need more features from DocBook for GHC or the libraries, or both?

I'd be delighted to help anyone interested in extending GHC's docs to allow the sort of flexible commenting system Simon has outlined. Please don't hesitate to contact me directly. Regards, Keith