cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "caleb racey" <>
Subject RE: [RT] The Cocoon Handbook
Date Thu, 24 Jun 2004 12:13:10 GMT

>> >> The Solution <<
>> I propose we create a free, high-quality electronic book (entitled
>> _The_Cocoon_Handbook_), which will eventually replace the mess of
>> we currently have.  It will be in DocBook (possibly simplified)
>> We can integrate the eventual book with user-added notations, similar
>> to how PHP lets people log in and annotate the existing docs.
>> - The Wiki.
>>   We need to be able to allow people to annotate or refine the docs
>> with ease.  How can this be done?

I too wish to see docbook as a documentation format for cocoon and a
whole host of other projects.

PHPs model of how to get user input into documents is the best I have
seen. The comments section is inspired.  

I've recently been trying to find tools for team based docbook editing.
I have experimented with the php doc book wiki (see  for the project home page)
Unfortunately it is not very highly functional (though much better that
nothing) and the installation is a PITA and involves measures that leave
me not happy with the security aspect (wrapper runs web invoked
processes as root). I haven't seen anything for collaborative editing of
docbook that I thought would be useable by anyone without a decent
understanding of docbook itself.

Even for a single user desktop type experience the main barrier to
docbook is the editing  tools. Most of them are super power user stuff
(emacs, command line etc). There are some nice xml editors like xmlmind
that can give a wysiwig-ish type experience (there is also which has out of the box
support for docbook and has a  free trial).  However even these are ugly
when you want to do complex stuff. e.g. try putting a helpful screenshot
image in your document, I spent half an hour and failed completely even
when resorting to hand editing xml. 

I dream of a cocoon/forrest or lenya based docbook wiki.  I think all
the constituent parts required are there they just need tied together
into an app. However I don't have the time at the moment to do anything
about this dream. 

I suppose what I'm driving at is that an ideal communal editing app
would support  wiki style editing of simple content (for an average user
adding simple paragraphs of content). It would also have to support
users of desktop powertools because I can't see anyone achieving more
complex editing feats (images etc) via a wiki. 

>> That's about all that my brain can spew out for now.  I really think
>> this is a good idea, and I've been throwing the idea around in my
>> for a while now.

Undoubtedly and if you can get it right I can see many projects using
it. The ability for an editor to post a bare bones structured docbook
and then have wiki style community flesh it out would be awesome.   

Unfortunately I can't offer any real practical help as my cocoon
knowledge it too shallow and I'm too busy at the moment. 

View raw message