cayenne-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aristedes Maniatis <...@maniatis.org>
Subject Re: Cayenne site
Date Mon, 02 May 2011 00:19:12 GMT
On 2/05/11 12:21 AM, Aristedes Maniatis wrote:
> Oh, I've just committed a starting point for the docbook.

Some notes for anyone reviewing this:

1. You need to generate the output to see how it works. Little tricks like <?eval ${project.version}?>
only show up in the output.

2. I highly recommend Oxygen Author as the best editor tool (with an almost WYSIWYG view)
for dealing with docbook. Go and download the free 28 day trial (either standalone or Eclipse
plugin)

3. Docbook is huge. We need to agree on a subset of elements that we will use. That will help
with consistency.


We could alternatively use Markdown or some other markup language for the documentation. The
downsides of that approach:

* no pdf output
* focussed on presentation rather than content (we'll be scattering the markup with divs to
get it looking the way we want)
* href links between pages will be specific to the html output choices, URLs, etc That is,
the output will not be as portable. In docbook I've chosen to identify each section with an
unique id for the purpose of linking.

The positive of markdown is simplicity. Docbook is OK once you get used to it, but it is more
complex to hand code.


Ari




-- 
-------------------------->
Aristedes Maniatis
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A

Mime
View raw message