Re: Adding xreflable

On 2020-05-15 18:47, Bruce Momjian wrote:
> On Fri, May 15, 2020 at 11:30:34AM -0400, Bruce Momjian wrote:
>> On Fri, May 15, 2020 at 11:06:58AM -0400, Tom Lane wrote:
>>> Bruce Momjian <bruce(at)momjian(dot)us> writes:
>>>> Well, I would like both the SQL command references and the application
>>>> man pages to have xreflabel text.
>>>
>>> I guess my point is that in the other several thousand pages of the docs,
>>> we just use <xref linkend="sql-whatever"/> or <xref
>>> linkend="app-whatever"/>, and it looks fine and works fine. Why are you
>>> insisting on doing it differently in the release notes?
>>>
>>> (I also have a vague memory that we used to use special xref labels for
>>> SQL commands, and got rid of it. So this seems like undoing history
>>> with no solid reasoning. That was with the previous doc toolchain of
>>> course, but it's still the case that we don't seem to need this.)
>>
>> I think I see it now. Our README.links says:
>>
>> <xref>
>> use to get chapter/section number from the title of the target
>> --> link, or xreflabel if defined at the target, or refentrytitle if target
>> --> is a refentry; has no close tag
>> http://www.oasis-open.org/docbook/documentation/reference/html/xref.html
>>
>> I was not aware that refentry can pull from refentrytitle. I just
>> tested it for pg_upgrade, and it worked fine. I will adjust the release
>> notes now to use them. Thanks.
>
> Done. Thanks for the tips.

This doesn't seem right. By adding xreflabels you are changing the
appearance for all links pointing to the target, not only from the
release notes. For example, if you now do

see <xref linkend="vacuum-basics"/> and <xref linkend="autovacuum"/>

which are both sect2s in the same chapter, then you get a rendered text of

see Section 24.1.1 and autovacuum

which is bizarre.

If you want the link appearance to change only in the release notes,
then the right approach is to use the <link> tag, as was done before.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services