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

From: ilmari(at)ilmari(dot)org (Dagfinn Ilmari Mannsåker )
To: Alvaro Herrera <alvherre(at)2ndquadrant(dot)com>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>, PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Re: [PATCH] Missing links between system catalog documentation pages
Date: 2020-06-21 17:49:46
Message-ID: 87imfknwat.fsf@wibble.ilmari.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

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

Attachment Content-Type Size
v3-0001-Add-missing-cross-links-in-system-catalog-documen.patch text/x-diff 23.3 KB
v3-0002-Make-SQL-command-names-in-the-catlog-documentatio.patch text/x-diff 17.6 KB

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Odin Ugedal 2020-06-21 19:51:11 Re: [PATCH] Add support for choosing huge page size
Previous Message Jonathan S. Katz 2020-06-21 17:45:36 Re: SIGSEGV from START_REPLICATION 0/XXXXXXX in XLogSendPhysical () at walsender.c:2762