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
Date: Tue, 05 May 2020 10:27:53 -0400
Message-ID: <20976.1588688873@sss.pgh.pa.us> (raw)
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>
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
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-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, coelho@cri.ensmp.fr, pgsql-hackers@lists.postgresql.org
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
In-Reply-To: <20976.1588688873@sss.pgh.pa.us>
* 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