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-docs-owner+archive@lists.postgresql.org>)
	id 1jWCyh-00010z-Pv
	for pgsql-docs@arkaria.postgresql.org; Wed, 06 May 2020 05:52:19 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jWCyg-0003Px-JR
	for pgsql-docs@arkaria.postgresql.org; Wed, 06 May 2020 05:52:18 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <coelho@cri.ensmp.fr>)
	id 1jWCyg-0003Pn-Dp; Wed, 06 May 2020 05:52:18 +0000
Received: from courriel-2.mines-paristech.fr ([77.158.173.19]
 helo=antispam-1.ensmp.fr)
	by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <coelho@cri.ensmp.fr>)
	id 1jWCyZ-0008BV-Fp; Wed, 06 May 2020 05:52:17 +0000
Received: from smtp-5.mines-paristech.fr (smtp.mines-paristech.fr
 [77.158.173.146])
	(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by antispam-1.ensmp.fr (antispam.mines-paristech.fr) with ESMTPS id
 B04DE5724D;
	Wed,  6 May 2020 07:52:09 +0200 (CEST)
Received: from pseudo (27.237.219.88.rev.sfr.net [88.219.237.27])
	(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
	(No client certificate requested)
	by smtp-5.mines-paristech.fr (Postfix) with ESMTPSA id 4ABA120057;
	Wed,  6 May 2020 07:52:09 +0200 (CEST)
Date: Wed, 6 May 2020 07:52:08 +0200 (CEST)
From: Fabien COELHO <coelho@cri.ensmp.fr>
X-X-Sender: fabien@pseudo
To: Tom Lane <tgl@sss.pgh.pa.us>
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: <20976.1588688873@sss.pgh.pa.us>
Message-ID: <alpine.DEB.2.22.394.2005060740030.3077@pseudo>
References: <12984.1588643549@sss.pgh.pa.us>
 <alpine.DEB.2.22.394.2005050743340.175044@pseudo>
 <20976.1588688873@sss.pgh.pa.us>
User-Agent: Alpine 2.22 (DEB 394 2020-01-19)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII; format=flowed
X-CLAMAV-SCAN: ok
X-VRSPAM-SCORE: 0
X-VRSPAM-STATE: legit
X-VRSPAM-CAUSE: 
 gggruggvucftvghtrhhoucdtuddrgeduhedrjeejgdduvdeiucetufdoteggodetrfcurfhrohhfihhlvgemucggtfgfnhhsuhgsshgtrhhisggvnecuuegrihhlohhuthemuceftddtnecunecujfgurhepfffhvffujgfkfhgfgggtsehttdertddtredvnecuhfhrohhmpefhrggsihgvnhcuvefqgffnjffquceotghovghlhhhosegtrhhirdgvnhhsmhhprdhfrheqnecuggftrfgrthhtvghrnhepveefgfeuhfegfeffueeljeefjeevgfffleevleekgfduieeftdfgudffledvjeeinecukfhppeekkedrvdduledrvdefjedrvdejnecurfgrrhgrmhepmhhouggvpehsmhhtphhouhht
X-VRSPAM-EXTCAUSE: mhhouggvpehsmhhtphhouhht
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk


Hello Tom,

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

I found "oid oid" stuttering kind of strange, hence an attempt at 
suggesting something that could distinguish them.

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

Ok. If they are displayed a little differently afterwards that'd may help.

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

In practice the system ensures that the target exists, so it is as-if 
there would be a foreign key enforced?

My point is that using differing syntaxes for the more-or-less the same 
concept does not help user understand the semantics, but maybe that is 
just me.

> I'm not hugely against it but I prefer what I suggested.

Ok!

-- 
Fabien.