From: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Cc: pgsql-docs@postgresql.org
Subject: Re: [HACKERS] switching documentation build to XSLT
Date: Tue, 22 Nov 2016 13:47:31 -0500
Message-ID: <11056.1479840451@sss.pgh.pa.us> (raw)
In-Reply-To: <31278.1479587695@sss.pgh.pa.us>
References: <2cdfe551-eb7b-b319-c96d-0d53cc0c2db8@2ndquadrant.com>
<1aff5a5f-64aa-91c4-41c4-7952afe8a792@2ndquadrant.com>
<31278.1479587695@sss.pgh.pa.us>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
I wrote:
> I notice that whereas <xref> used to generate text like
> Section 4.1.2.7
> now you get
> Section 4.1.2.7, “Constants of Other Types”
I also find that for some reason, the results are not formatted
consistently. Section cross-references are printed with quotes
as shown above, but chapter cross-references have no quotes and
instead the chapter title is italicized. See for example the
various cross-references for GiST about halfway down this page:
https://www.postgresql.org/docs/devel/static/indexes-types.html
TBH though, the more examples of this I look at, the less convinced
I am that it's an improvement at all. We have an awful lot of
parenthetical cross-references like "(see Section 1.2.3)", which
previously were easy to ignore while reading, but with long section
titles attached to them they quite interrupt the sentence flow.
I can kind of see the point when printing on dead trees, but in
any format where the reference is a hyperlink, I think I'd vote
for dropping the title and going back to the old output.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, peter.eisentraut@2ndquadrant.com
Subject: Re: [HACKERS] switching documentation build to XSLT
In-Reply-To: <11056.1479840451@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox