From owner-freebsd-doc@FreeBSD.ORG Sun Jul 14 08:22:50 2013 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id D47E54F2 for ; Sun, 14 Jul 2013 08:22:50 +0000 (UTC) (envelope-from gabor@t-hosting.hu) Received: from server.mypc.hu (server.mypc.hu [87.229.73.95]) by mx1.freebsd.org (Postfix) with ESMTP id 8EE53938 for ; Sun, 14 Jul 2013 08:22:49 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 573C514D2403 for ; Sun, 14 Jul 2013 10:22:42 +0200 (CEST) X-Virus-Scanned: amavisd-new at !change-mydomain-variable!.example.com Received: from server.mypc.hu ([127.0.0.1]) by server.mypc.hu (server.mypc.hu [127.0.0.1]) (amavisd-new, port 10024) with LMTP id RFCsfs-QivS9 for ; Sun, 14 Jul 2013 10:22:41 +0200 (CEST) Received: from [192.168.1.117] (catv-80-99-23-232.catv.broadband.hu [80.99.23.232]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by server.mypc.hu (Postfix) with ESMTPSA id 2FC6414D2400 for ; Sun, 14 Jul 2013 10:22:41 +0200 (CEST) Message-ID: <51E25FCE.9020405@t-hosting.hu> Date: Sun, 14 Jul 2013 10:22:38 +0200 From: =?ISO-8859-1?Q?G=E1bor_K=F6vesd=E1n?= User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:23.0) Gecko/20100101 Thunderbird/23.0a2 MIME-Version: 1.0 To: doc@freebsd.org Subject: Re: RFC: Upgrading to DocBook 5.0 References: <519FA4FE.4030305@FreeBSD.org> In-Reply-To: <519FA4FE.4030305@FreeBSD.org> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 14 Jul 2013 08:22:50 -0000 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