Adding xreflable

Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Adding xreflable

Bruce Momjian
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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Tom Lane-2
Bruce Momjian <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Bruce Momjian
On Fri, May 15, 2020 at 09:37:30AM -0400, Tom Lane wrote:
> Bruce Momjian <[hidden email]> 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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Tom Lane-2
Bruce Momjian <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

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

> Bruce Momjian <[hidden email]> 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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Tom Lane-2
Bruce Momjian <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

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

> Bruce Momjian <[hidden email]> 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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Bruce Momjian
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 <[hidden email]> 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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Peter Eisentraut-6
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 <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Bruce Momjian
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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Peter Eisentraut-6
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


Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Bruce Momjian
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  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

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



Reply | Threaded
Open this post in threaded view
|

Re: Adding xreflable

Alvaro Herrera-9
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