Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1jVyYI-0008S6-1z
	for pgsql-hackers@arkaria.postgresql.org; Tue, 05 May 2020 14:28:06 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1jVyYG-0003DC-UB
	for pgsql-hackers@arkaria.postgresql.org; Tue, 05 May 2020 14:28:04 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jVyYG-0003D1-NX; Tue, 05 May 2020 14:28:04 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jVyYE-0006yA-J2; Tue, 05 May 2020 14:28:03 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id 045ERrCp020977;
	Tue, 5 May 2020 10:27:53 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Fabien COELHO <coelho@cri.ensmp.fr>
cc: pgsql-docs@lists.postgresql.org,
        PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
In-reply-to: <alpine.DEB.2.22.394.2005050743340.175044@pseudo>
References: <12984.1588643549@sss.pgh.pa.us>
 <alpine.DEB.2.22.394.2005050743340.175044@pseudo>
Comments: In-reply-to Fabien COELHO <coelho@cri.ensmp.fr>
	message dated "Tue, 05 May 2020 07:52:08 +0200"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <20975.1588688873.1@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit
Date: Tue, 05 May 2020 10:27:53 -0400
Message-ID: <20976.1588688873@sss.pgh.pa.us>
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Precedence: bulk

Fabien COELHO <coelho@cri.ensmp.fr> writes:
> My 0.02€: I'm wondering whether the description could/should match SQL 
> syntax, eg:

>    oid OID
>    adrelid OID REFERENCES pg_class(oid)
>    adnum INT2 REFERENCES pg_attribute(attnum)
>    …

> Or maybe just uppercase type names, especially when repeated?

Meh.  I'm not a fan of overuse of upper case --- it's well established
that that's harder to read than lower or mixed case.  And it's definitely
project policy that type names are generally treated as identifiers not
keywords, even if some of them happen to be keywords under the hood.

The markup I had in mind was <structfield> for the field name
and <type> for the type name, but no decoration beyond that.

As for the references, it seems to me that your notation would lead
people to think that there are actual FK constraints in place, which
of course there are not (especially not on the views).  I'm not
hugely against it but I prefer what I suggested.

> I guess that reference targets would still be navigable.

Yeah, they'd still have <link> wrappers --- if I recall what those
look like in the documentation sources, they don't need any change
except for addition of the "(references ...)" text.

			regards, tom lane