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 <[EMAIL PROTECTED]> 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. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
