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
_______________________________________________
[email protected] mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "[email protected]"
