Subject: Re: Adding xreflable
To: Alvaro Herrera <alvherre@2ndquadrant.com>,
 Bruce Momjian <bruce@momjian.us>
References: <20200603223814.GA7455@alvherre.pgsql>
Cc: Tom Lane <tgl@sss.pgh.pa.us>,
 PostgreSQL-documentation <pgsql-docs@postgresql.org>
From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Organization: 2ndQuadrant
Message-ID: <928c6fe4-ae7d-eea2-92ef-ff48f13f060e@2ndquadrant.com>
Date: Thu, 4 Jun 2020 19:11:41 +0200
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:52.0)
 Gecko/20100101 Thunderbird/52.9.1
MIME-Version: 1.0
In-Reply-To: <20200603223814.GA7455@alvherre.pgsql>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

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