From: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> |
---|---|
To: | Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com> |
Cc: | pgsql-docs(at)postgresql(dot)org |
Subject: | Re: [HACKERS] switching documentation build to XSLT |
Date: | 2016-11-22 18:47:31 |
Message-ID: | 11056.1479840451@sss.pgh.pa.us |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs pgsql-hackers |
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
From | Date | Subject | |
---|---|---|---|
Next Message | Bruce Momjian | 2016-11-22 22:31:44 | Re: Example error in createdb doc |
Previous Message | Tom Lane | 2016-11-22 16:18:22 | Re: [HACKERS] switching documentation build to XSLT |
From | Date | Subject | |
---|---|---|---|
Next Message | Peter Geoghegan | 2016-11-22 18:56:07 | Re: amcheck (B-Tree integrity checking tool) |
Previous Message | Alvaro Herrera | 2016-11-22 18:37:45 | Re: [RFC] Should we fix postmaster to avoid slow shutdown? |