Mailing-List: contact dev-help@cayenne.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cayenne.apache.org
Received-SPF: pass (athena.apache.org: domain of
 gcjcd-cayenne-devel-890-moved1@m.gmane.org designates 80.91.229.12 as
 permitted sender)
To: dev@cayenne.apache.org
From: "Adrian A." <a.adrian.tech@gmail.com>
Subject: Re: wiki pages design
Date: Wed, 17 Feb 2010 12:06:23 +0100
Lines: 52
Message-ID: <hlgijf$30h$1@ger.gmane.org>
References: <ee04ee7f1002120357u5741ad3r4aaacfff65c7de3e@mail.gmail.com>
 <6C86227C-4602-4E2E-898B-F3BAF8A00EBA@objectstyle.org>
 <4B772D6B.4080608@maniatis.org>
 <BB873239-A88F-4E48-A5CB-83BA1B772C9C@objectstyle.org>
 <4B7BAE8F.7070205@maniatis.org>
 <59A02079-98E4-4F61-8185-2E7E00243C68@objectstyle.org>
 <hlgdub$jcv$1@ger.gmane.org> <4B7BBBE8.9000401@maniatis.org>
 <hlgepa$ml0$1@ger.gmane.org>
 <18DFE219-DFF6-4DD5-8520-CB275779BC30@objectstyle.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US;
 rv:1.9.1.7) Gecko/20100111 Thunderbird/3.0.1
In-Reply-To: <18DFE219-DFF6-4DD5-8520-CB275779BC30@objectstyle.org>
Sender: news <news@ger.gmane.org>

>> 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.