From owner-freebsd-doc@FreeBSD.ORG Sun Jul 14 12:52:34 2013 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id DF49D95D for ; Sun, 14 Jul 2013 12:52:34 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 87EFEFCF for ; Sun, 14 Jul 2013 12:52:34 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id r6ECqXmV060969; Sun, 14 Jul 2013 06:52:33 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id r6ECqWgj060966; Sun, 14 Jul 2013 06:52:33 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Sun, 14 Jul 2013 06:52:32 -0600 (MDT) From: Warren Block To: =?ISO-8859-15?Q?G=E1bor_K=F6vesd=E1n?= Subject: Re: RFC: Upgrading to DocBook 5.0 In-Reply-To: <51E25FCE.9020405@t-hosting.hu> Message-ID: References: <519FA4FE.4030305@FreeBSD.org> <51E25FCE.9020405@t-hosting.hu> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; BOUNDARY="3512871622-1022815614-1373806353=:60846" X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Sun, 14 Jul 2013 06:52:33 -0600 (MDT) Cc: doc@freebsd.org 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 12:52:34 -0000 This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --3512871622-1022815614-1373806353=:60846 Content-Type: TEXT/PLAIN; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 8BIT On Sun, 14 Jul 2013, Gábor Kövesdán wrote: > 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. Admonitions are overused in some places. They are visually jarring, often moreso than the tip or warning deserves. A link to an example of this particular problem would be helpful to see what you mean, though. > - 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. Please expand--what is the problem with differing fonts in titles? I can see this both ways, but the text of a title being consistent with the rendering in the body seems like an advantage. > - 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? An example would be useful here, also. For compatibility with the rest of the world, we should probably stick with the most common usage. > - 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? Please give an example here, also. All of these suggestions seem to be style changes that are not necessarily tied to the change to DocBook 5, or maybe changes that are not possible until after the conversion. Unless they're required, it may be best to wait until after the conversion. --3512871622-1022815614-1373806353=:60846--