Re: [Haskell-cafe] expanded standard lib

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