From owner-freebsd-doc@FreeBSD.ORG Sun Jul 14 18:14:20 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 694E65BE for ; Sun, 14 Jul 2013 18:14:20 +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 0682FC72 for ; Sun, 14 Jul 2013 18:14:19 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id C292014D2514; Sun, 14 Jul 2013 20:14:17 +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 DsOdJfl8V4wu; Sun, 14 Jul 2013 20:14:15 +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 E35F814D242C; Sun, 14 Jul 2013 20:14:14 +0200 (CEST) Message-ID: <51E2EA74.9070008@FreeBSD.org> Date: Sun, 14 Jul 2013 20:14:12 +0200 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Thunderbird/24.0a2 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> <51E2A6C9.1070301@FreeBSD.org> 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 18:14:20 -0000 On 2013.07.14. 18:02, Warren Block wrote: > On Sun, 14 Jul 2013, Gabor Kovesdan wrote: > >> 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. > > I see what you mean. But if we say "don't use admonitions in lists > because they are visually ugly, that becomes markup for appearance and > not for semantics. It is not appearance, it is structure, which is part of semantics. From a semantic point of view, what's an admonition? Imo, it is a piece of additional information that (1) is related to the wider context, (2) is more or less self-contained and (3) does not fit into the main text flow so its position is more or less flexible. It is usually rendereded with a border or a background color that clearly separates it from the main flow of the text. Because of these characteristics, it semantically doesn't fit into the notion of lists. Nor tables should be embedded into lists. > > Some tweaking of the CSS may help, like reducing the size of the > admonition title so it is not so much larger than the surrounding > text. docbook.css is something I've been meaning to look at, hopefully > soon. It may help but that break of information flow still shouldn't be there. > >>>> - 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. > > Again, doesn't this break the semantics versus appearance separation? > If the standard is to show titles in a single font and size, then that > should be done when rendering. Semantically, a filename is a filename > whether it is in a title or body text. You are calling appearance what is in fact structure. We could talk about appearance if we wrote or something like that. The semantics of a title could be defined like a plain text title and that would be a valid semantics, too. True, it is also possible to solve it when rendering but if we decide that we don't want such in titles, why not just changing the semantics and sparing some stylesheet code? Both the docs and the stylesheets would be more simple. > > I find different fonts for filenames and commands to be useful, even > in titles. The O'Reilly style guide doesn't mention anything about > title styles, and in a quick search I did not find anything else. Ok, it doesn't specify it explicitly but can you show me a technical book that has such titles? A real, published book, please, not online docs. > >>>> - 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. > > For reference, here are links: > > http://www.docbook.org/tdg5/en/html/cals.table.html > http://www.docbook.org/tdg5/en/html/html.table.html > > Changing the source documents could be scripted, but would also > require modifications to the FDP Primer. > > I can't tell if HTML tables have all the same capabilities as CALS > tables. The same information is stored so theoretically it is possible to do the same with them. HTML table markup is more simple and the stock stylesheets implement more features. > >>>> - 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. > > The previous toolchain rendered that title in bold: > http://docs.freebsd.org/doc/9.0-RELEASE/usr/share/doc/freebsd/en_US.ISO8859-1/books/handbook/bsdinstall-pre.html > > > Agreed, that title does not look very good. Adding a colon to list > titles when rendering would help. Removing all list titles be too > severe. Having a colon at the end of the paragraph and another one at the end of the list title? It seems even more confusing to me. Why is to severe removing them? Do they add any extra information that helps you understanding the content? I think it makes the comprehension more difficult and is just counter-productive. Can you find a published book with such list titles? Gabor