From: Fabien COELHO <coelho@cri.ensmp.fr>
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
Date: Wed, 6 May 2020 07:52:08 +0200 (CEST)
Message-ID: <alpine.DEB.2.22.394.2005060740030.3077@pseudo> (raw)
In-Reply-To: <20976.1588688873@sss.pgh.pa.us>
References: <12984.1588643549@sss.pgh.pa.us>
<alpine.DEB.2.22.394.2005050743340.175044@pseudo>
<20976.1588688873@sss.pgh.pa.us>
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.
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: coelho@cri.ensmp.fr, tgl@sss.pgh.pa.us, pgsql-hackers@lists.postgresql.org
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
In-Reply-To: <alpine.DEB.2.22.394.2005060740030.3077@pseudo>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox