pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedAdding xreflable
17+ messages / 4 participants
[nested] [flat]
Commits from this thread:
2020-06-11 59fa7eb603 doc: document problems with using xreflabel in XML docs
2020-06-11 db680fd82e doc: remove xreflabels used in PG 13 relnotes
2020-06-11 0dd1eb3aea dede9a6ada 84febc6bdf f6ee4c39ac 81cd796b82 da0a60c3d7 c046120401 doc: remove xreflabels from commits 75fcdd2ae2 and 85af628da5
* Adding xreflable
@ 2020-05-15 12:39 Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 17+ messages in thread
From: Bruce Momjian @ 2020-05-15 12:39 UTC (permalink / raw)
To: pgsql-docs
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 +
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-05-15 13:37 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Tom Lane @ 2020-05-15 13:37 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
@ 2020-05-15 13:49 ` Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 17+ messages in thread
From: Bruce Momjian @ 2020-05-15 13:49 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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 +
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-05-15 14:09 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Tom Lane @ 2020-05-15 14:09 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
@ 2020-05-15 14:22 ` Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 17+ messages in thread
From: Bruce Momjian @ 2020-05-15 14:22 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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 +
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-05-15 15:06 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Tom Lane @ 2020-05-15 15:06 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
@ 2020-05-15 15:30 ` Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Bruce Momjian @ 2020-05-15 15:30 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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 +
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-05-15 16:47 ` Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 17+ messages in thread
From: Bruce Momjian @ 2020-05-15 16:47 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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 +
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-05-22 10:09 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Peter Eisentraut @ 2020-05-22 10:09 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
@ 2020-05-22 16:45 ` Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 17+ messages in thread
From: Bruce Momjian @ 2020-05-22 16:45 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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 +
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-05-26 11:41 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-02 16:07 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Peter Eisentraut @ 2020-05-26 11:41 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
@ 2020-06-02 16:07 ` Bruce Momjian <bruce@momjian.us>
2020-06-03 22:38 ` Re: Adding xreflable Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-04 17:14 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 2 replies; 17+ messages in thread
From: Bruce Momjian @ 2020-06-02 16:07 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-02 16:07 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-06-03 22:38 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-04 17:11 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 1 reply; 17+ messages in thread
From: Alvaro Herrera @ 2020-06-03 22:38 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-02 16:07 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-06-03 22:38 ` Re: Adding xreflable Alvaro Herrera <alvherre@2ndquadrant.com>
@ 2020-06-04 17:11 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-11 22:38 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Peter Eisentraut @ 2020-06-04 17:11 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@2ndquadrant.com>; Bruce Momjian <bruce@momjian.us>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-02 16:07 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-06-03 22:38 ` Re: Adding xreflable Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-04 17:11 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
@ 2020-06-11 22:38 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 17+ messages in thread
From: Bruce Momjian @ 2020-06-11 22:38 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Alvaro Herrera <alvherre@2ndquadrant.com>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-02 16:07 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
@ 2020-06-04 17:14 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-11 22:38 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
1 sibling, 1 reply; 17+ messages in thread
From: Peter Eisentraut @ 2020-06-04 17:14 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Adding xreflable
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Re: Adding xreflable Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-02 16:07 ` Re: Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-06-04 17:14 ` Re: Adding xreflable Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
@ 2020-06-11 22:38 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 17+ messages in thread
From: Bruce Momjian @ 2020-06-11 22:38 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
end of thread, other threads:[~2020-06-11 22:38 UTC | newest]
Thread overview: 17+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-05-15 12:39 Adding xreflable Bruce Momjian <bruce@momjian.us>
2020-05-15 13:37 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 13:49 ` Bruce Momjian <bruce@momjian.us>
2020-05-15 14:09 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 14:22 ` Bruce Momjian <bruce@momjian.us>
2020-05-15 15:06 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-15 15:30 ` Bruce Momjian <bruce@momjian.us>
2020-05-15 16:47 ` Bruce Momjian <bruce@momjian.us>
2020-05-22 10:09 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-05-22 16:45 ` Bruce Momjian <bruce@momjian.us>
2020-05-26 11:41 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-02 16:07 ` Bruce Momjian <bruce@momjian.us>
2020-06-03 22:38 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-04 17:11 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-11 22:38 ` Bruce Momjian <bruce@momjian.us>
2020-06-04 17:14 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2020-06-11 22:38 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox