Date: Sun, 14 Jul 2013 10:22:38 +0200 From: =?ISO-8859-1?Q?G=E1bor_K=F6vesd=E1n?= <gabor@t-hosting.hu> To: doc@freebsd.org Subject: Re: RFC: Upgrading to DocBook 5.0 Message-ID: <51E25FCE.9020405@t-hosting.hu> In-Reply-To: <519FA4FE.4030305@FreeBSD.org> References: <519FA4FE.4030305@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?51E25FCE.9020405>