[TYPO3-doc] DocBook: sample reference file

[Christian Kartnig]

Hi Francois,

> The advantage I see when using DocBook across the board is that the
> format used is consistent among all manuals, which makes it easier for
> people to contribute. It's all DocBook.

Thanks for pointing that out. It still wasn't that clear to me. For me 
that's a very good reason for using DocBook.
But, as DocBook isn't too "explicit" (e.g. having no attributes telling 
what is a type field and what is a description, etc.), you have to be 
really disciplined sticking to the structure we come up with, so that 
the DocBook File is still parseable. If many people contribute, chances 
are that this structure gets broken, which might be just visible in one 
of the transformations, so it doesn't get detected instantly.
So the whole thing might not be very robust.

Also I agree to what Stephan wrote, it could be hard to implement extra 
features such as comments and user generated examples.

I think if we use DocBook, it requires more than just a XSLT.
Probably we need a (db-based) application with importer and exporter 
anyway for the online tsref, but with DocBook, we need to be extremely 
careful building the importer, so we can assure nothing gets broken.

best regards,
Christian