cayenne-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aristedes Maniatis <>
Subject Re: docbook
Date Thu, 26 May 2011 00:30:29 GMT
On 26/05/11 10:25 AM, Andrus Adamchik wrote:
>> I've tried some html to docbook converters, but the effort to clean up the result
was about equal to the effort in just copying the text over by hand.
> I am fine with that. Aside from the lack of time factor, I wouldn't mind going through
all docs and reorganizing them to match the modern version of Cayenne.

Yes, I actually think step one should be to create the whole documentation from top to bottom
but just the section headings, without content. Some of the structure needs a rethink to make
it easier to find.

Docbook has:

* parts
* chapters
* sections (nested as deep as we like)

We don't need to use parts if we don't want, but that is useful perhaps to separate:

Part I: Designing your structure
Part II: Using Cayenne in code
Part II: ROP

Each chapter should be in a separate docbook XML file. (It doesn't have to, but that is easiest.)
And then we should agree that sections should be at most 3 deep. But probably mostly 2 deep.

>> >  The thing with docbook is that there are 10 ways to do anything. We need to
write our own style guide for the choices we make and keep it consistent. For example, there
are about 6 different types of list.
> So can you take a lead on that?

Very happy to. Once we have consensus that docbook is the future for us. See other emails
about Apache CMS, etc, etc


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

View raw message