[TYPO3-doc] DocBook: first sample manual

[François Suter]

Hi all,

I got side-tracked by all kind of things, but here we finally go. I have 
a first sample DocBook-based manual for starting the discussion about 
document structure. I based myself on the current OpenOffice template 
and (more or less) reproduced that structure in DocBook. I tried to use 
all the tags/structure that we might reasonably use.

The best is that you get the stuff from the SVN repository directly:

https://svn.typo3.org/TYPO3v4/Documentation/official_template/trunk/DocBook/

and check out the "manual.xml" file. I made most of my remarks inside 
the file itself, so please read it through and comment here (sorry if 
you find this a bit lazy, but I really didn't want to repeat everything).

The most important thing to note is that you will see no example 
TypoScript reference in this file. Indeed I have created a separate file 
for this (reference.xml), which is not fully ready yet and that I will 
submit for discussion in a separate thread. I find it uneasy to achieve 
a satisfying structure for a TypoScript reference in DocBook and this 
will probably be a large topic unto itself. The good news is that will 
probably also help with the online reference topic.

So please just concentrate on "manual.xml" for now and make your 
comments/remarks/etc., on anything you find good, bad, missing, could be 
improved and what not.

I haven't yet toyed with id's and cross-references, but it's a topic 
that we will have to broach on very soon. As far as I understand it, it 
will be closely related to the structure of our document repository, 
which is also a hot topic to solve.

As a kind of conclusion to this very first step, I would like to say 
that I pretty much enjoyed working with DocBook. There a few rare cases 
where the structure is not quite obvious and the refusal of the editor 
to do what you want it to is both vexing and puzzling, but on the whole 
it was a very smooth experience and the learning curve is really gentle. 
I think it won't be much of an effort for most contributors to learn to 
use DocBook. And it was an immense pleasure not to have to worry about 
styling. I'm eagerly looking forward to ditching OpenOffice for this 
kind of task :-)

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch