Re: [PATCH] Missing links between system catalog documentation pages - Mailing list pgsql-hackers

From Tom Lane
Subject Re: [PATCH] Missing links between system catalog documentation pages
Date
Msg-id 1881597.1592748213@sss.pgh.pa.us
Whole thread Raw
In response to Re: [PATCH] Missing links between system catalog documentationpages  (Fabien COELHO <coelho@cri.ensmp.fr>)
Responses Re: [PATCH] Missing links between system catalog documentation pages  (Alvaro Herrera <alvherre@2ndquadrant.com>)
Re: [PATCH] Missing links between system catalog documentationpages  (Fabien COELHO <coelho@cri.ensmp.fr>)
List pgsql-hackers
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



pgsql-hackers by date:

Previous
From: ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Subject: Re: [PATCH] Missing links between system catalog documentation pages
Next
From: ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Subject: vs for command line tools in the docs