Thread: Re: [HACKERS] switching documentation build to XSLT

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> If you find any changes in the output that bother you, let pgsql-docs know.

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”

This is probably an improvement in most places, but there may be some
places where the text now reads awkwardly and we need to rephrase or
re-punctuate to make it non-confusing.  Keep an eye out for that ...

            regards, tom lane

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

Hello,

The attached patch fixes this.

Best regards,
Alexander

22.11.2016 21:47, Tom Lane пишет:
> 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
>
>