cayenne-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Adrian A." <a.adrian.t...@gmail.com>
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. 
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.


Mime
View raw message