cayenne-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Adrian A." <>
Subject Re: wiki pages design
Date Wed, 17 Feb 2010 11:06:23 GMT
>> If you decide to use Docbook, I would gladly help with the conversion
>> of the Cayenne documentation.
> Before we decide, I guess somebody has to build a prototype showing how
> that would work using a few pages from the User Guide. I am interested
> in the following aspects. Ari or Adrian could you please comment:
> * Authoring process (do we have to edit XML by hand?)
The authoring process can be done in many ways - from manual XML edit 
with smart assistance from the IDE (or various IDE plug-ins), to using 
various WYSIWYG tools.

There are a few commercial WYSIWYG tools, but fortunately all I've 
tried, had also free licenses for open source projects. E.g. was very efficient for me.

Even OpenOffice seems to have some Docbook support.

Regarding the typical workflow, I would differentiation:
1. Writing allot of documentation at once in one place (e.g. one entire 
chapter, or at least more than one page), gives the WYSIWYG tool
an advantage (but I suppose this would be rare for Cayenne now).
2. Making small (one or two phrases, or even a few words) 
additions/chanegs, makes the direct edit in the IDE faster.

> * Maven support
I can't tell much about Maven, but with ANT for the Click like template 
(that I'm reusing allot for it's simplicity), it requires just typing:
%> ant get-deps
%> ant
and everything gets generated.

> * I assume the same doc source can be published as HTML on the web, and
> as PDF for the release.
Yes. For Click it generates 3 types of files (2 HTML and 1 PDF). See 
here the results 3 type of results:

> What does it take to wrap HTML in our site
> template? A Velocity template I guess?
Yes, Velocity would do it too.
XSite and SiteMesh are also good, but there are many
tools that can 're-decorate' HTML content statically or dynamically.

Also, if you would like to see a "prototype Docbook" it in action, I 
would suggest taking a look at the Click documentation - since it's a 
very good prototype (IMHO), and build it from source to see the process. 
You can checkout from here:
and build with the steps I described above in the "xdocs" subdirectory.


View raw message