RFC: Upgrading to DocBook 5.0

[Gábor Kövesdán]

Some more things:

- Admonitions (top, note, warning boxes) look quite strange in lists and 
such places. I think we should add a policy to avoid them and start 
changing the markup.

- We extensively use markup in titles, which later renders with a 
different font. E.g. we mark the X of 9.X as replaceable or we mark up 
root as a username. I think that such rendering should be avoided in 
titles and the easiest and cleanest way to do so would be not using such 
markup in titles.

- Currently, we use the CALS table model in the documentation, while 
DocBook also supports the HTML table model. It has a more simple syntax 
and more rendering features in the DocBook stylesheets. Another 
advantage is that by using it, we would have only one table semantics in 
docs + web. Any objection to changing to the HTML table model?

- Some lists have their own title, while the preceding text usually 
introduces well what is enumerated in the list. I find the rendered 
title quite strange between this text and the list. Besides, I don't 
remember having seen technical books that use such titles. My suggestion 
is to simple remove them. Any objection or better idea?

Thanks,
Gabor