Date: Mon, 15 Jul 2013 13:58:10 +0900 (JST) From: Hiroki Sato <hrs@FreeBSD.org> To: gabor@FreeBSD.org Cc: doc@FreeBSD.org Subject: Re: RFC: Upgrading to DocBook 5.0 Message-ID: <20130715.135810.1689066987888254665.hrs@allbsd.org> In-Reply-To: <51E2EA74.9070008@FreeBSD.org> References: <51E2A6C9.1070301@FreeBSD.org> <alpine.BSF.2.00.1307140923450.61543@wonkity.com> <51E2EA74.9070008@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
----Security_Multipart(Mon_Jul_15_13_58_10_2013_720)-- Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Gabor Kovesdan <gabor@freebsd.org> 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 <bold> 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 <replaceable> 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)----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130715.135810.1689066987888254665.hrs>