Date: Mon, 15 Jul 2013 10:46:40 +0200 From: Gabor Kovesdan <gabor@FreeBSD.org> To: Hiroki Sato <hrs@FreeBSD.org> Cc: doc@FreeBSD.org Subject: Re: RFC: Upgrading to DocBook 5.0 Message-ID: <51E3B6F0.9010908@FreeBSD.org> In-Reply-To: <20130715.135810.1689066987888254665.hrs@allbsd.org> References: <51E2A6C9.1070301@FreeBSD.org> <alpine.BSF.2.00.1307140923450.61543@wonkity.com> <51E2EA74.9070008@FreeBSD.org> <20130715.135810.1689066987888254665.hrs@allbsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2013.07.15. 6:58, Hiroki Sato wrote: > 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. I thought of adding some Schematron constraints for the problematic cases but I'll go for the rendering customization if this is better accepted. I agree that this may work better for entity references. > 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. I believe these are already rendered as normal paragraphs between two itemizedlists but I'll verify this. Gabor
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?51E3B6F0.9010908>