[TYPO3-doc] A few DocBook questions

[François Suter]

Hi,

I'm trying to come up with a sample DocBook document that reflect our 
current template file (currently based on OpenOffice). I thought I would 
wrap it up before asking some questions, but I find myself stuck on some 
points, so here goes with the questions first.

1) there are a number of structures which exist in both formal and 
informal variants. Is there any recommendation about which to use. Is it 
advisable to limit the choice to formal structures to... err, well, be 
formal? Or should we just keep the freedom?

2) some of our manuals are language references, in particular TypoScript 
which is a kind of parametrization language with which templates are 
built in TYPO3 (to give a (very) short explanation to Tom, our visiting 
DocBook expert). The traditional structure we used for such reference 
was a table with four columns, describing the name of the property, its 
data type, a description (which can sometimes be quite long, including 
code samples, lists, etc.) and its default value (if any). An example 
table can be found in the documentation template:

https://svn.typo3.org/TYPO3v4/Documentation/official_template/trunk/OpenOffice/official_documentation_template.pdf

How should we do this with DocBook? I naively tried out with a table 
(HTML), but the "td" element cannot contain block elements. This makes 
it insufficient with regards to the needs for the description.

Cheers

-- 

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