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
