[Haskell-cafe] expanded standard lib

[Thomas Schilling]

On Tue, 2007-11-20 at 12:03 -0800, Keith Fahlgren wrote:
> 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?

Right.  I should have been more specific.  I certainly like the idea of
Docbook.  But in an open source project documentation is written in
small parts and by many different people.  I personally didn't care to
read a whole book just to be able write a few pages of documentation.
Thus I tried to use it as a reference.  This worked reasonably well, but
could have been a way more comfortable experience.  Some quick-access /
lookup table, would have been nicer.  Maybe also a little more pretty
than gray and standard link blue.  (Even the W3C specs look rather
nice.)

My point is, for a casual editor trying to write or edit DocBook
documents based on this book is rather tedious.  I think my Emacs mode
didn't do as nice completion as it should have (based on DTD and
everything.)

> 
> > 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.

The latter is not available for free (only trial).  The former seems to
be free for non-commercial use.  I haven't tried either (*Java Runtime
rant elided*).  The real problem remains:  Even if you were to install a
special program to (reasonably) edit a DocBook file, we still don't have
the immediacy of a Wiki.  

> > 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. 

There seem to be some.  But I could only find commercial ones.