Adding xreflable

[Bruce Momjian]

You might know that while SGML's  requires you to specify link
text,  can pull text from the "xreflabel" link site;  our
doc/src/sgml/README.links file explains it:


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 , allows the text of the link/xref to be taken from a
different link target title


use to supply text for the link, only uses linkend, requires 


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  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 +

Re: Adding xreflable

[Tom Lane]

Bruce Momjian  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

Re: Adding xreflable

[Bruce Momjian]

On Fri, May 15, 2020 at 09:37:30AM -0400, Tom Lane wrote:
> Bruce Momjian  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 pg_upgrade
 will need to use REINDEX to make use
 of this feature.

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

-- 
  Bruce Momjian  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 +

Re: Adding xreflable

[Tom Lane]

Bruce Momjian  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

Relnotes for 13: There is word missing in UUID generation sentence

[Daniel Westermann (DWE)]

Hi,

"Previously UUID generation functions were only available external modules 
uuid-ossp or 
pgcrypto were installed."

Shouldn't that be:
Previously UUID generation functions were only available if external modules 
uuid-ossp or 
pgcrypto were installed.

Regards
Daniel

Re: Adding xreflable

[Bruce Momjian]

On Fri, May 15, 2020 at 10:09:06AM -0400, Tom Lane wrote:
> Bruce Momjian  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:



to



so I can do this in the release notes:



and not:

pg_upgrade

All the other extensions already do this:



-- 
  Bruce Momjian  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 +

Re: Relnotes for 13: There is word missing in UUID generation sentence

[Bruce Momjian]

On Fri, May 15, 2020 at 02:09:32PM +, Daniel Westermann (DWE) wrote:
> Hi,
> 
> "Previously UUID generation functions were only available external modules
> uuid-ossp or pgcrypto were installed."
> 
> Shouldn't that be:
> Previously UUID generation functions were only available if external modules
> uuid-ossp or pgcrypto were installed.

Oh, yes, fixed.

-- 
  Bruce Momjian  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 +

Re: Adding xreflable

[Tom Lane]

Bruce Momjian  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  or , 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

Re: Adding xreflable

[Bruce Momjian]

On Fri, May 15, 2020 at 11:06:58AM -0400, Tom Lane wrote:
> Bruce Momjian  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  or  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:


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  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 +

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  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  or  > 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:
> 
> 
> 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  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 +