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

From: ilmari(at)ilmari(dot)org (Dagfinn Ilmari Mannsåker )
To: Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>
Cc: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Re: [PATCH] Missing links between system catalog documentation pages
Date: 2020-06-21 14:02:07
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

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

Attachment Content-Type Size
v2-0001-Add-missing-cross-links-in-system-catalog-documen.patch text/x-diff 23.5 KB

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Tom Lane 2020-06-21 14:03:33 Re: [PATCH] Missing links between system catalog documentation pages
Previous Message Ranier Vilela 2020-06-21 13:54:09 Re: Possible NULL pointer deferenced (src/interfaces/libpq/fe-exec.c (line 563)