Re: psql: bogus descriptions displayed by \d+ - Mailing list pgsql-hackers

On Wed, Jul 27, 2011 at 5:19 PM, Peter Eisentraut <peter_e@gmx.net> wrote:
> On tis, 2011-07-26 at 09:53 -0400, Robert Haas wrote:
>> On Mon, Jul 25, 2011 at 10:29 PM, Josh Kupershmidt
>> <schmiddy@gmail.com> wrote:
>> > That seems like a good way to document this; patch for master
>> updated.
>> > I avoided mucking with the documentation for COMMENT ON RULE and
>> > COMMENT ON TRIGGER this time; they both say "table" when they really
>> > mean "table or view", but maybe trying to differentiate between
>> > "table", "table_or_view", and "relation" will make things overly
>> > complicated.
>>
>> I think this is basically the right approach but I found what you did
>> here a bit wordy, so I simplified it, committed it, and back-patched
>> to 9.0 with suitable adjustment.  Hopefully I didn't simplify it into
>> a form you don't like.
>
> I would like to argue for reverting this.  If you want to word-smith
> details like this, "relation" doesn't carry any additional meaning.  PG
> hackers know that internally, a "relation" is a table, view, index,
> sequence, etc., but for the user, it doesn't mean anything.

The original page used "table_name" in the synopsis in three places:
COMMENT ON {COLUMN, CONSTRAINT, and RULE}. If you're suggesting that
it's intuitively obvious what's meant by "table" in each of those
three cases, I respectfully disagree: I only think I know now because
I bothered to test all of these recently, and read a bit of comment.c.
(Hint: "table" means different things in all three cases).

I'll also note that you included "index" in your list of what a
"relation" is, and omitted "composite type" -- this is exactly the
confusion I was trying to avoid. COMMENT ON COLUMN no longer supports
indexes, and does support composite types. Plus, I don't think we
should be designing docs so that only "PG hackers" know what's really
meant. That hasn't seemed to be the modus operandi of maintaining the
rest of the docs.

> Note that we don't use relation_name anywhere else in SQL command
> synopses.  So far, no one has complained that we don't mention that
> views are allowed in the SELECT command or the GRANT command.

I actually complained upthread about CREATE RULE using the term
"table" in its synopsis, when it really means "table or view", but I
thought that was OK because there was an immediate clarification right
below the synopsis.

> I think table_name is fine, and if you are very worried, add below that
> a table_name also includes views (or whatever).

It includes tables, views, composite types, and foreign tables. Is
"table" really an appropriate description for all those objects?

> As a side note, backpatching this creates additional translation work in
> backbranches.  So please keep it to a minimum if it's not outright
> wrong.

That's a legitimate concern; I don't have a strong opinion about
whether stuff like this ought to be backpatched.

Josh