Adding xreflable

Bruce Momjian <bruce@momjian.us> writes:

I have noticed that our ref/*.sgml pages don't have such labels. I
would like to add them and use them for our release notes. Some of our
extensions need them too.

Why? Our convention generally is to refer to the command, not to the ref
page as such.

regards, tom lane

On Fri, May 15, 2020 at 09:37:30AM -0400, Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

I have noticed that our ref/*.sgml pages don't have such labels. I
would like to add them and use them for our release notes. Some of our
extensions need them too.

Why? Our convention generally is to refer to the command, not to the ref
page as such.

Uh, for the release notes, I am referencing the doc page about the
feature, and without the xref, I have to mention it twice, e.g.:

This allows efficient btree indexing of low cardinality columns
by storing duplicate keys only once. Users upgrading with <link
linkend="pgupgrade"><application>pg_upgrade</application></link>
will need to use <link
linkend="sql-reindex"><command>REINDEX</command></link> to make use
of this feature.

I am guessing I will have to put the <command> tags around the <xref>.
As you can see, pg_upgrade, is also missing an xreflabel.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Bruce Momjian <bruce@momjian.us> writes:

On Fri, May 15, 2020 at 09:37:30AM -0400, Tom Lane wrote:

Why? Our convention generally is to refer to the command, not to the ref
page as such.

Uh, for the release notes, I am referencing the doc page about the
feature, and without the xref, I have to mention it twice, e.g.:

Oh, you're talking about the application man pages not the SQL command
ones. I'd still be inclined to solve it with something paralleling
the way we handle SQL command references.

Quickly comparing the pgupgrade page to a couple of SQL commands,
it's not real obvious what is missing. Maybe there's something
in the stylesheet support, not the ref pages as such?

regards, tom lane

On Fri, May 15, 2020 at 10:09:06AM -0400, Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

On Fri, May 15, 2020 at 09:37:30AM -0400, Tom Lane wrote:

Why? Our convention generally is to refer to the command, not to the ref
page as such.

Uh, for the release notes, I am referencing the doc page about the
feature, and without the xref, I have to mention it twice, e.g.:

Oh, you're talking about the application man pages not the SQL command
ones. I'd still be inclined to solve it with something paralleling
the way we handle SQL command references.

Well, I would like both the SQL command references and the application
man pages to have xreflabel text.

Quickly comparing the pgupgrade page to a couple of SQL commands,
it's not real obvious what is missing. Maybe there's something
in the stylesheet support, not the ref pages as such?

I would like to change this:

<refentry id="pgupgrade">

to

<refentry id="pgupgrade" xreflabel="pg_upgrade">

so I can do this in the release notes:

<xref linkend="pgupgrade"/>

and not:

<link linkend="pgupgrade"><application>pg_upgrade</link>

All the other extensions already do this:

<sect1 id="sepgsql" xreflabel="sepgsql">

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Bruce Momjian <bruce@momjian.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.)

regards, tom lane

On Fri, May 15, 2020 at 11:06:58AM -0400, Tom Lane wrote:

Bruce Momjian <bruce@momjian.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.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

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@momjian.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.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

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@momjian.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

On Fri, May 22, 2020 at 12:09:18PM +0200, Peter Eisentraut wrote:

On 2020-05-15 18:47, Bruce Momjian wrote:

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.

Ugh, I see what you mean. I have read doc/src/sgml/README.links many
times and still get confused. What you are saying is that if there is
no xreflabel on a target, you can get the chapter/section via <xref> or
specify text via <link>. But, if there is an xreflabel on the target,
you can't get the chapter/section anymore --- you can only get the
xreflabel via <xref>, or specify text via <link>, right?

I added 13 xreflabels in commits 85af628da5 and 75fcdd2ae2. What I am
thinking of doing is to look at all references to the id's associated
with those xreflabels and remove the xreflabel if the chapter/section
is required, and if not, convert <link> to <xref> where the link text
matches the xreflabel. Does that sound like a good plan?

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On 2020-05-22 18:45, Bruce Momjian wrote:

Ugh, I see what you mean. I have read doc/src/sgml/README.links many
times and still get confused. What you are saying is that if there is
no xreflabel on a target, you can get the chapter/section via <xref> or
specify text via <link>. But, if there is an xreflabel on the target,
you can't get the chapter/section anymore --- you can only get the
xreflabel via <xref>, or specify text via <link>, right?

I think that's right.

I added 13 xreflabels in commits 85af628da5 and 75fcdd2ae2. What I am
thinking of doing is to look at all references to the id's associated
with those xreflabels and remove the xreflabel if the chapter/section
is required, and if not, convert <link> to <xref> where the link text
matches the xreflabel. Does that sound like a good plan?

Both of those commits should be reverted.

I don't quite understand your plan, but if you mean, check whether
anyone else links to the id in question, that doesn't sound sustainable.
A new link could be added at any time in the future.

I think the release notes should either just use a plain <xref> to link
and use whatever generated text it gets, or if you don't like that, use
<link>. Which is basically what it was before, IIRC.

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

On Tue, May 26, 2020 at 01:41:41PM +0200, Peter Eisentraut wrote:

On 2020-05-22 18:45, Bruce Momjian wrote:

Ugh, I see what you mean. I have read doc/src/sgml/README.links many
times and still get confused. What you are saying is that if there is
no xreflabel on a target, you can get the chapter/section via <xref> or
specify text via <link>. But, if there is an xreflabel on the target,
you can't get the chapter/section anymore --- you can only get the
xreflabel via <xref>, or specify text via <link>, right?

I think that's right.

I added 13 xreflabels in commits 85af628da5 and 75fcdd2ae2. What I am
thinking of doing is to look at all references to the id's associated
with those xreflabels and remove the xreflabel if the chapter/section
is required, and if not, convert <link> to <xref> where the link text
matches the xreflabel. Does that sound like a good plan?

Both of those commits should be reverted.

I don't quite understand your plan, but if you mean, check whether anyone
else links to the id in question, that doesn't sound sustainable. A new
link could be added at any time in the future.

I think the release notes should either just use a plain <xref> to link and
use whatever generated text it gets, or if you don't like that, use <link>.
Which is basically what it was before, IIRC.

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.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

The usefulness of a cup is in its emptiness, Bruce Lee

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.

--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

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

On 2020-06-02 18:07, 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.

One reason for that difference specifically is that vacuumlo is refentry
which can generate its own link text like "vacuumlo(1)", and sepgsql is
a sect1, which by default creates text like "Section 23.2", which
perhaps someone wanted to override.

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

On Thu, Jun 4, 2020 at 07:11:41PM +0200, Peter Eisentraut wrote:

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.

OK, I have reverted the patches that added xreflabels and added this
text to the bottom of README.links:

- xreflabels added to tags prevent the chapter/section for id's from being
referenced; only the xreflabel is accessible. Therefore, use xreflabels
only when linking is common, and chapter/section information is unneeded.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

The usefulness of a cup is in its emptiness, Bruce Lee

On Thu, Jun 4, 2020 at 07:14:17PM +0200, Peter Eisentraut wrote:

On 2020-06-02 18:07, 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.

One reason for that difference specifically is that vacuumlo is refentry
which can generate its own link text like "vacuumlo(1)", and sepgsql is a
sect1, which by default creates text like "Section 23.2", which perhaps
someone wanted to override.

Yes, that makes sense, thanks.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

The usefulness of a cup is in its emptiness, Bruce Lee