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.
http://www.xmlmind.com/xmleditor/ 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:
http://click.apache.org/docs/user-guide.html
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:
http://svn.apache.org/repos/asf/click/trunk/click/documentation/
and build with the steps I described above in the "xdocs" subdirectory.
Adrian.
