From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
To: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Bruce Momjian <bruce@momjian.us>
Cc: Tom Lane <tgl@sss.pgh.pa.us>
Cc: PostgreSQL-documentation <pgsql-docs@postgresql.org>
Subject: Re: Adding xreflable
Date: Thu, 4 Jun 2020 19:11:41 +0200
Message-ID: <928c6fe4-ae7d-eea2-92ef-ff48f13f060e@2ndquadrant.com> (raw)
In-Reply-To: <20200603223814.GA7455@alvherre.pgsql>
References: <20200603223814.GA7455@alvherre.pgsql>
On 2020-06-04 00:38, Alvaro Herrera wrote:
> On 2020-Jun-02, Bruce Momjian wrote:
>
>> I can adjust things, but what logic are we following? Before my patch,
>> sepgsql had an xreflabel, and vacuumlo did not. I would like to have a
>> documented policy of where we should have xreflabels, and where not, and
>> I can then adjust things to match. I don't mind using <link> but it is
>> confusing to be able to reference xreflabels in some places and be
>> required to use link in others.
>
> I think a possible rationale would be to *not* include xreflabel for
> elements that get numbered (so references become, e.g., "see Section 32.5"),
> and include them for those that don't -- so that they can be referenced
> at all.
Yes, basically everything that already has a generated label doesn't
need an xreflabel.
Also, if you apply xreflabels somewhere, it needs to be done
consistently across all siblings, so you don't get a different style of
text depending on which section you happen to link to.
And moreover, there should be some general utility for the xreflabel,
not just the linking needs of one particular source location.
The xreflabels used for the GUC variables are good examples of all three
of those points.
Generally, xreflabels are a bit of antipattern IMO, so there need to be
solid arguments in favor of adding more.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
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: peter.eisentraut@2ndquadrant.com, alvherre@2ndquadrant.com, bruce@momjian.us, tgl@sss.pgh.pa.us
Subject: Re: Adding xreflable
In-Reply-To: <928c6fe4-ae7d-eea2-92ef-ff48f13f060e@2ndquadrant.com>
* 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