[TYPO3-doc] A few DocBook questions

[François Suter]

Hi,

> Well, the difference is the title: it's only allowed on figure, example, table
> etc. The informal* elements don't have any titles at all.

OK, that's what I had understood.

> To sum it up: If you want your titles of your tables, examples, etc to appear
> in the "table of contents" then use the elements with the respective names. If
> you don't need an entry in the TOC, use the informal* variant.

So I guess there's no reason to force editors to use the formal 
variants, but it should probably be encouraged. In general it's probably 
better to have formal structures I would say.

> It is possible. Before I will show you how, I should mention that DocBook 5
> allows two table models:
>
>   a) CALS tables
>   b) (X)HTML tables

I read about that. I would tend to favor HTML tables, as they will 
already be familiar to our contributors, unless there's a real incentive 
to use CALS tables.

> Both are sufficient for your table issue. I've tested both.
>        <td>
>          <para>If property RO is set (see below) then ...</para>
>          <cmdsynopsis>
>            <group>
> [snip]
>        </td>
>        <td/>
>      </tr>
>    </table>

So it could work... Funnily enough XMLMind doesn't allow me to put block 
elements inside a td tag. Maybe it's a bug. I double checked the DocBook 
reference and paragraph elements are clearly allowed. Weird.

> Your above data reminds me of reference material. So why not use refentry[1]
> for that? This makes it easier to group your different colums into different
> refsections. If you use refentry, you completely avoid the need to push your
> data into tables. Just another strange idea from me. ;-)

refentry could be much cleaner indeed. As Philipp already said it would 
probably be a lot of work to transform the existing references, but it 
might lead to other opportunities of usage for such data, if it is 
better structured. I will have to take a deeper look into this. I wonder 
if we can really cover our use case with the existing tags (if we want 
to be really formal).

Cheers

-- 

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