From owner-freebsd-doc@FreeBSD.ORG Sun Jul 14 13:25:40 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 679E9C37 for ; Sun, 14 Jul 2013 13:25:40 +0000 (UTC) (envelope-from gabor@FreeBSD.org) Received: from server.mypc.hu (server.mypc.hu [87.229.73.95]) by mx1.freebsd.org (Postfix) with ESMTP id DEF1CFE for ; Sun, 14 Jul 2013 13:25:39 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 2343614D242C; Sun, 14 Jul 2013 15:25:38 +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 cnX916DOUQXN; Sun, 14 Jul 2013 15:25:36 +0200 (CEST) Received: from [192.168.1.106] (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 30C3B14D2403; Sun, 14 Jul 2013 15:25:36 +0200 (CEST) Message-ID: <51E2A6C9.1070301@FreeBSD.org> Date: Sun, 14 Jul 2013 15:25:29 +0200 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:23.0) Gecko/20100101 Thunderbird/23.0 MIME-Version: 1.0 To: Warren Block Subject: Re: RFC: Upgrading to DocBook 5.0 References: <519FA4FE.4030305@FreeBSD.org> <51E25FCE.9020405@t-hosting.hu> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 8bit 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 13:25:40 -0000 Em 14-07-2013 14:52, Warren Block escreveu: > 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. For example here: http://www.freebsd.org/doc/en/books/handbook/history.html It breaks the list. It is even worse in PDF rendering since there are page boundaries and it breaks the page up to two parts. > >> - 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. Apart from the ugly visual outlook, it is not conventional in books and as such, it is just bothering and confusing for the reader. It breaks the information flow. Typographyc conventions serve for nice visual outlook and usability. The typesetting should facilitate reading and not difficulting it. If we want to publish a high-quality print edition of Handbook, we must follow the conventions, otherwise it won't be a serious publication. > >> - 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. Most common is very relative. HTML uses exclusively the HTML table model, hence the name. CALS is older and quite common in the SGML/XML world. Both are supported in DocBook and we currently use CALS. Earlier there was no other option in DocBook. Using exclusively HTML tables would reduce the used table models to one. Examples: just google for CALS table and HTML table, both are documented extensively. > >> - 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. http://www.freebsd.org/doc/en/books/handbook/bsdinstall-pre.html Look at 2.3.3. There's a semicolon at the end of the last paragraph and list title is just floating there in the middle. This type of titles breaks the flow of the text and doesn't facilitate reading. > > 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. Not in theory but theory doesn't always match practice. I'm working on the DocBook 5 change to provide better rendering and support publishing print versions. I'm evaluating and customizing two different rendering methods and I have to see where we can get with each. Practically I can do it by eliminating the confusing and bothering factors. This is sometimes done by customizing the rendering and sometimes by feeding back the results to the concrete documents. Gabor