Missing links between system catalog documentation pages

Hi hackers,

While browsing the system catalog docs earlier I noticed that a lot of
them mention other catalogs or views in the introductory paragrah
without hyperlinking them. Now, most of these are linked in the
"references" column in the table, but some, like pg_proc's mention of
pg_aggregate have no direct links at all.

The attached patch makes the first mention of another system catalog or
view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier
navigation.

- ilmari
--
- Twitter seems more influential [than blogs] in the 'gets reported in
the mainstream press' sense at least. - Matt McLeod
- That'd be because the content of a tweet is easier to condense down
to a mainstream media article. - Calle Dybedahl

ilmari(at)ilmari(dot)org (Dagfinn Ilmari Mannsåker) writes:

> The attached patch makes the first mention of another system catalog or
> view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier
> navigation.

bump...

- ilmari
--
"A disappointingly low fraction of the human race is,
at any given time, on fire." - Stig Sandbeck Mathisen

ilmari(at)ilmari(dot)org (Dagfinn Ilmari Mannsåker) writes:

> ilmari(at)ilmari(dot)org (Dagfinn Ilmari Mannsåker) writes:
>
>> The attached patch makes the first mention of another system catalog or
>> view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier
>> navigation.
>
> bump...

Added to the current commitfest:

https://commitfest.postgresql.org/28/2599/

- ilmari
--
- Twitter seems more influential [than blogs] in the 'gets reported in
the mainstream press' sense at least. - Matt McLeod
- That'd be because the content of a tweet is easier to condense down
to a mainstream media article. - Calle Dybedahl

Hello Dagfinn,

>> The attached patch makes the first mention of another system catalog or
>> view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier
>> navigation.

Why only the first mention? It seems unlikely that I would ever read such
chapter linearly, and even so that I would want to jump especially on the
first occurrence but not on others, so ISTM that it should be done all
mentions?

--
Fabien.

Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> writes:

> Hello Dagfinn,
>
>>> The attached patch makes the first mention of another system catalog or
>>> view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier
>>> navigation.
>
> Why only the first mention? It seems unlikely that I would ever read
> such chapter linearly, and even so that I would want to jump especially
> on the first occurrence but not on others, so ISTM that it should be
> done all mentions?

It's the first mention in the introductory paragraph of _each_ catalog
table/view page, not the first mention in the entire catalogs.sgml file.
E.g. https://www.postgresql.org/docs/current/catalog-pg-aggregate.html
has two mentions of pg_proc one word apart:

Each entry in pg_aggregate is an extension of an entry in pg_proc. The
pg_proc entry carries the aggregate's name, …

I didn't think there was much point in linkifying both in that case, and
other similar situations.

- ilmari
--
"A disappointingly low fraction of the human race is,
at any given time, on fire." - Stig Sandbeck Mathisen

Hello Dagfinn,

>>>> The attached patch

applies cleanly, doc generation is ok. I'm ok with adding such links
systematically.

>>>> makes the first mention of another system catalog or view (as well as
>>>> pg_hba.conf in pg_hba_file_lines) a link, for easier navigation.
>>
>> Why only the first mention? It seems unlikely that I would ever read
>> such chapter linearly, and even so that I would want to jump especially
>> on the first occurrence but not on others, so ISTM that it should be
>> done all mentions?
>
> It's the first mention in the introductory paragraph of _each_ catalog
> table/view page, not the first mention in the entire catalogs.sgml file.
> E.g. https://www.postgresql.org/docs/current/catalog-pg-aggregate.html
> has two mentions of pg_proc one word apart:
>
> Each entry in pg_aggregate is an extension of an entry in pg_proc. The
> pg_proc entry carries the aggregate's name, …
>
> I didn't think there was much point in linkifying both in that case, and
> other similar situations.

The point is that the user reads a sentence, attempts to jump but
sometimes can't, because the is not the first occurrence. I'd go for all
mentions of another relation should be link.

Alse, ISTM you missed some, maybe you could consider adding them? eg
pg_database in the very first paragraph of the file, pg_attrdef in
pg_attribute description, quite a few in pg_class…

--
Fabien.

Hi Fabien,

Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> writes:

>> It's the first mention in the introductory paragraph of _each_ catalog
>> table/view page, not the first mention in the entire catalogs.sgml file.
>> E.g. https://www.postgresql.org/docs/current/catalog-pg-aggregate.html
>> has two mentions of pg_proc one word apart:
>>
>> Each entry in pg_aggregate is an extension of an entry in pg_proc. The
>> pg_proc entry carries the aggregate's name, …
>>
>> I didn't think there was much point in linkifying both in that case, and
>> other similar situations.
>
> The point is that the user reads a sentence, attempts to jump but
> sometimes can't, because the is not the first occurrence. I'd go for all
> mentions of another relation should be link.

Okay, I'll make them all links, except the pg_aggregate aggfnoid column,
which I've changed from "pg_proc OID of the aggregate function" to just
"OID of the agregate function", since pg_proc is linked immediately
prior in the "references" section, and we generally don't mention the
catalog table again in similar cases elsehwere.

> Alse, ISTM you missed some, maybe you could consider adding them? eg
> pg_database in the very first paragraph of the file, pg_attrdef in
> pg_attribute description, quite a few in pg_class…

Yes, I only looked at the intro paragraphs of the per-catalog pages, not
the overview section nor the text after the column tables. I've gone
through them all now and linked them. Updated patch attached.

- ilmari
--
"A disappointingly low fraction of the human race is,
at any given time, on fire." - Stig Sandbeck Mathisen

Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> writes:
>> I didn't think there was much point in linkifying both in that case, and
>> other similar situations.

> The point is that the user reads a sentence, attempts to jump but
> sometimes can't, because the is not the first occurrence. I'd go for all
> mentions of another relation should be link.

That has not been our practice up to now, eg in comparable cases in
discussions of GUC variables, only the first reference is xref-ified.
I think it could be kind of annoying to make every reference a link,
both for regular readers (the link decoration is too bold in most
browsers) and for users of screen-reader software.

There is a fair question as to how far apart two references should
be before we <xref> both of them. But I think that distance
does need to be more than zero, and probably more than one para.

regards, tom lane

On 2020-Jun-21, Tom Lane wrote:

> That has not been our practice up to now, eg in comparable cases in
> discussions of GUC variables, only the first reference is xref-ified.
> I think it could be kind of annoying to make every reference a link,
> both for regular readers (the link decoration is too bold in most
> browsers) and for users of screen-reader software.

In the glossary I also changed things so that only the first reference
of a term in another term's definition is linked; my experience reading
the originals as submitted (which did link them all at some point) is
that the extra links are very distracting, bad for readability. So +1
for not adding links to every single mention.

> There is a fair question as to how far apart two references should
> be before we <xref> both of them. But I think that distance
> does need to be more than zero, and probably more than one para.

Nod.

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

Alvaro Herrera <alvherre(at)2ndquadrant(dot)com> writes:

> On 2020-Jun-21, Tom Lane wrote:
>
>> That has not been our practice up to now, eg in comparable cases in
>> discussions of GUC variables, only the first reference is xref-ified.
>> I think it could be kind of annoying to make every reference a link,
>> both for regular readers (the link decoration is too bold in most
>> browsers) and for users of screen-reader software.
>
> In the glossary I also changed things so that only the first reference
> of a term in another term's definition is linked; my experience reading
> the originals as submitted (which did link them all at some point) is
> that the extra links are very distracting, bad for readability. So +1
> for not adding links to every single mention.

There were only three cases of multiple mentions of the same table in a
single paragraph, I've removed them in the attached patch.

I've also added a second patch that makes the SQL commands links. There
were some cases of the same commands being mentioned in the descriptions
of multiple columns in the same table, but I've left those in place,
since that feels less disruptive than in prose.

>> There is a fair question as to how far apart two references should
>> be before we <xref> both of them. But I think that distance
>> does need to be more than zero, and probably more than one para.
>
> Nod.

I tend to agree.

- ilmari
--
"A disappointingly low fraction of the human race is,
at any given time, on fire." - Stig Sandbeck Mathisen

Hello Tom,

>>> I didn't think there was much point in linkifying both in that case,
>>> and other similar situations.
>
>> The point is that the user reads a sentence, attempts to jump but
>> sometimes can't, because the is not the first occurrence. I'd go for
>> all mentions of another relation should be link.
>
> That has not been our practice up to now, eg in comparable cases in
> discussions of GUC variables, only the first reference is xref-ified.
> I think it could be kind of annoying to make every reference a link,
> both for regular readers (the link decoration is too bold in most
> browsers)

Hmmm. That looks like an underlying CSS issue, not that links are
intrinsically bad.

I find it annoying that the same thing appears differently from one line
to the next. It seems I'm the only one who likes things to be uniform,
though.

> and for users of screen-reader software.

I do not know about those, and what constraints it puts on markup.

--
Fabien.

On 2020-06-21 19:49, Dagfinn Ilmari Mannsåker wrote:
> There were only three cases of multiple mentions of the same table in a
> single paragraph, I've removed them in the attached patch.
>
> I've also added a second patch that makes the SQL commands links. There
> were some cases of the same commands being mentioned in the descriptions
> of multiple columns in the same table, but I've left those in place,
> since that feels less disruptive than in prose.

Committed after some rebasing and tweaking.

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

Hi Peter,

Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com> writes:

> On 2020-06-21 19:49, Dagfinn Ilmari Mannsåker wrote:
>> There were only three cases of multiple mentions of the same table in a
>> single paragraph, I've removed them in the attached patch.
>>
>> I've also added a second patch that makes the SQL commands links. There
>> were some cases of the same commands being mentioned in the descriptions
>> of multiple columns in the same table, but I've left those in place,
>> since that feels less disruptive than in prose.
>
> Committed after some rebasing and tweaking.

Thanks!

I just noticed that both this and the command link patch modified the
same sentence about CREATE DATABASE and pg_database, so those changes
seem to have been lost in the merge. Attached is a follow-up patch that
adds them both.

- ilmari
--
"The surreality of the universe tends towards a maximum" -- Skud's Law
"Never formulate a law or axiom that you're not prepared to live with
the consequences of." -- Skud's Meta-Law

On 2020-09-03 17:40, Dagfinn Ilmari Mannsåker wrote:
> I just noticed that both this and the command link patch modified the
> same sentence about CREATE DATABASE and pg_database, so those changes
> seem to have been lost in the merge. Attached is a follow-up patch that
> adds them both.

I think in those cases I would leave off the link. The mentions there
are just examples of the relationship between a catalog and a command.
It doesn't mean you are meant to look up the specific catalog and command.

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