[Haskell-cafe] expanded standard lib

[Keith Fahlgren]

On 11/20/07 7:35 AM, Thomas Schilling wrote:
> On Tue, 2007-11-20 at 16:00 +0100, Ketil Malde wrote:
>> Thomas Schilling <nominolo at googlemail.com> 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