Horton

Thread

Commits

  1. doc: Add missing cross-links in system catalog documentation

  2. doc: Make SQL command names in the catalog documentation links

  1. Missing links between system catalog documentation pages

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2020-05-24T21:05:30Z

    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

  2. [PATCH] Missing links between system catalog documentation pages

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2020-06-15T18:47:43Z

    ilmari@ilmari.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

  3. Re: [PATCH] Missing links between system catalog documentation pages

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2020-06-15T18:52:31Z

    ilmari@ilmari.org (Dagfinn Ilmari Mannsåker) writes:

> ilmari@ilmari.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

  4. Re: [PATCH] Missing links between system catalog documentation pages

    Fabien COELHO <coelho@cri.ensmp.fr> — 2020-06-16T04:44:45Z

    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.

  5. Re: [PATCH] Missing links between system catalog documentation pages

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2020-06-17T13:55:18Z

    Fabien COELHO <coelho@cri.ensmp.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

  6. Re: [PATCH] Missing links between system catalog documentation pages

    Fabien COELHO <coelho@cri.ensmp.fr> — 2020-06-21T07:01:12Z

    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.

  7. Re: [PATCH] Missing links between system catalog documentation pages

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2020-06-21T14:02:07Z

    Hi Fabien,

Fabien COELHO <coelho@cri.ensmp.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

  8. Re: [PATCH] Missing links between system catalog documentation pages

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-06-21T14:03:33Z

    Fabien COELHO <coelho@cri.ensmp.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

  9. Re: [PATCH] Missing links between system catalog documentation pages

    Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-06-21T15:08:02Z

    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

  10. Re: [PATCH] Missing links between system catalog documentation pages

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2020-06-21T17:49:46Z

    Alvaro Herrera <alvherre@2ndquadrant.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

  11. Re: [PATCH] Missing links between system catalog documentation pages

    Fabien COELHO <coelho@cri.ensmp.fr> — 2020-06-21T21:52:37Z

    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.

  12. Re: [PATCH] Missing links between system catalog documentation pages

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-09-03T11:38:21Z

    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

  13. Re: [PATCH] Missing links between system catalog documentation pages

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2020-09-03T15:40:28Z

    Hi Peter,

Peter Eisentraut <peter.eisentraut@2ndquadrant.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

  14. Re: [PATCH] Missing links between system catalog documentation pages

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-09-10T14:04:31Z

    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