Thread: Adding xreflable
You might know that while SGML's <link> requires you to specify link
text, <xref> can pull text from the "xreflabel" link site; our
doc/src/sgml/README.links file explains it:
<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
linkend=
controls the target of the link/xref, required
endterm=
for <xref>, allows the text of the link/xref to be taken from a
different link target title
<link>
use to supply text for the link, only uses linkend, requires </link>
http://www.oasis-open.org/docbook/documentation/reference/html/link.html
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.
I think I need to backpatch this so that minor release notes can use
them too. OK? I have also noticed that the comment headings at the top
of our ref/*.sgml files are inconsistent and will fix those too.
--
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:
> 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