From owner-freebsd-doc@FreeBSD.ORG Mon Jul 15 08:46:49 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 834E97A3; Mon, 15 Jul 2013 08:46:49 +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 3FFD1920; Mon, 15 Jul 2013 08:46:48 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 1B8CB14D243A; Mon, 15 Jul 2013 10:46:48 +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 D8Dk7Um-CmdB; Mon, 15 Jul 2013 10:46:43 +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 B536214D2403; Mon, 15 Jul 2013 10:46:43 +0200 (CEST) Message-ID: <51E3B6F0.9010908@FreeBSD.org> Date: Mon, 15 Jul 2013 10:46:40 +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: Hiroki Sato Subject: Re: RFC: Upgrading to DocBook 5.0 References: <51E2A6C9.1070301@FreeBSD.org> <51E2EA74.9070008@FreeBSD.org> <20130715.135810.1689066987888254665.hrs@allbsd.org> In-Reply-To: <20130715.135810.1689066987888254665.hrs@allbsd.org> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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 08:46:49 -0000 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 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