From owner-freebsd-doc@FreeBSD.ORG Mon Jul 15 04:58:53 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 C4315429; Mon, 15 Jul 2013 04:58:53 +0000 (UTC) (envelope-from hrs@FreeBSD.org) Received: from mail.allbsd.org (gatekeeper.allbsd.org [IPv6:2001:2f0:104:e001::32]) by mx1.freebsd.org (Postfix) with ESMTP id 54A16878; Mon, 15 Jul 2013 04:58:53 +0000 (UTC) Received: from alph.d.allbsd.org (p2049-ipbf1102funabasi.chiba.ocn.ne.jp [122.26.101.49]) (authenticated bits=128) by mail.allbsd.org (8.14.5/8.14.5) with ESMTP id r6F4waIH020101 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 15 Jul 2013 13:58:46 +0900 (JST) (envelope-from hrs@FreeBSD.org) Received: from localhost (localhost [IPv6:::1]) (authenticated bits=0) by alph.d.allbsd.org (8.14.5/8.14.5) with ESMTP id r6F4wYtB029676; Mon, 15 Jul 2013 13:58:35 +0900 (JST) (envelope-from hrs@FreeBSD.org) Date: Mon, 15 Jul 2013 13:58:10 +0900 (JST) Message-Id: <20130715.135810.1689066987888254665.hrs@allbsd.org> To: gabor@FreeBSD.org Subject: Re: RFC: Upgrading to DocBook 5.0 From: Hiroki Sato In-Reply-To: <51E2EA74.9070008@FreeBSD.org> References: <51E2A6C9.1070301@FreeBSD.org> <51E2EA74.9070008@FreeBSD.org> X-PGPkey-fingerprint: BDB3 443F A5DD B3D0 A530 FFD7 4F2C D3D8 2793 CF2D X-Mailer: Mew version 6.5 on Emacs 24.3 / Mule 6.0 (HANACHIRUSATO) Mime-Version: 1.0 Content-Type: Multipart/Signed; protocol="application/pgp-signature"; micalg=pgp-sha1; boundary="--Security_Multipart(Mon_Jul_15_13_58_10_2013_720)--" Content-Transfer-Encoding: 7bit X-Virus-Scanned: clamav-milter 0.97.4 at gatekeeper.allbsd.org X-Virus-Status: Clean X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7 (mail.allbsd.org [133.31.130.32]); Mon, 15 Jul 2013 13:58:46 +0900 (JST) X-Spam-Status: No, score=-89.3 required=13.0 tests=CONTENT_TYPE_PRESENT, DIRECTOCNDYN,DYN_PBL,RCVD_IN_PBL,RCVD_IN_RP_RNBL,SPF_SOFTFAIL, USER_IN_WHITELIST autolearn=no version=3.3.2 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on gatekeeper.allbsd.org 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: Mon, 15 Jul 2013 04:58:53 -0000 ----Security_Multipart(Mon_Jul_15_13_58_10_2013_720)-- Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Gabor Kovesdan wrote in <51E2EA74.9070008@FreeBSD.org>: ga> >> It breaks the list. It is even worse in PDF rendering since there are ga> >> page boundaries and it breaks the page up to two parts. ga> > ga> > I see what you mean. But if we say "don't use admonitions in lists ga> > because they are visually ugly, that becomes markup for appearance and ga> > not for semantics. ga> It is not appearance, it is structure, which is part of ga> semantics. From a semantic point of view, what's an admonition? Imo, ga> it is a piece of additional information that (1) is related to the ga> wider context, (2) is more or less self-contained and (3) does not fit ga> into the main text flow so its position is more or less flexible. It ga> is usually rendereded with a border or a background color that clearly ga> separates it from the main flow of the text. Because of these ga> characteristics, it semantically doesn't fit into the notion of ga> lists. Nor tables should be embedded into lists. I agree that admonition in a list/table does not make sense semantically. Probably people abuse it as a replacement of footnote. ga> > Again, doesn't this break the semantics versus appearance separation? ga> > If the standard is to show titles in a single font and size, then that ga> > should be done when rendering. Semantically, a filename is a filename ga> > whether it is in a title or body text. ga> You are calling appearance what is in fact structure. We could talk ga> about appearance if we wrote or something like that. ga> ga> The semantics of a title could be defined like a plain text title and ga> that would be a valid semantics, too. True, it is also possible to ga> solve it when rendering but if we decide that we don't want such in ga> titles, why not just changing the semantics and sparing some ga> stylesheet code? Both the docs and the stylesheets would be more ga> simple. I like to solve this upon rendering and I think it will be simpler because a policy of plain text title (in markup) practically does not work without DTD change, and elements such as can be included in title elements via entity references or so in any way. Forcing a consistent style for title elements looks easy to me. ga> >> Examples: just google for CALS table and HTML table, both are ga> >> documented extensively. ga> > ga> > For reference, here are links: ga> > ga> > http://www.docbook.org/tdg5/en/html/cals.table.html ga> > http://www.docbook.org/tdg5/en/html/html.table.html ga> > ga> > Changing the source documents could be scripted, but would also ga> > require modifications to the FDP Primer. ga> > ga> > I can't tell if HTML tables have all the same capabilities as CALS ga> > tables. ga> The same information is stored so theoretically it is possible to do ga> the same with them. HTML table markup is more simple and the stock ga> stylesheets implement more features. I am neutral about this. The difference in their capability is quite small. XHTML table model may be better for people who are familiar with XHTML. ga> > The previous toolchain rendered that title in bold: ga> > http://docs.freebsd.org/doc/9.0-RELEASE/usr/share/doc/freebsd/en_US.ISO8859-1/books/handbook/bsdinstall-pre.html ga> > Agreed, that title does not look very good. Adding a colon to list ga> > titles when rendering would help. Removing all list titles be too ga> > severe. ga> Having a colon at the end of the paragraph and another one at the end ga> of the list title? It seems even more confusing to me. ga> Why is to severe removing them? Do they add any extra information that ga> helps you understanding the content? I think it makes the ga> comprehension more difficult and is just counter-productive. ga> ga> Can you find a published book with such list titles? I think removing title is fine. Although there are some exmaples for such an informal title like this: Pros: - A - B Cons: - C - D they are items, not "title" actually. If we really need it, it should be a caption. -- Hiroki ----Security_Multipart(Mon_Jul_15_13_58_10_2013_720)-- Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.13 (FreeBSD) iEYEABECAAYFAlHjgWIACgkQTyzT2CeTzy35sQCdF3/fZ74UsN8fzCl9TSBgd0CV BucAn15Lqi6SelJYAx3DMo6iPpYg/YGB =aqXZ -----END PGP SIGNATURE----- ----Security_Multipart(Mon_Jul_15_13_58_10_2013_720)----