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