Re: psql: bogus descriptions displayed by \d+

On Wed, Jul 27, 2011 at 5:19 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> 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.

Well, I don't think we're going to do very well trying to get by
without a generic term of some sort. Calling it a table is more
confusing, because the user might easily be forgiven for thinking that
he knows what the word "table" means and reading no further. If you
say relation, then either (a) the user knows what that means, or (b)
he'll read the text and find out. I am not very excited about the
idea of documenting "table_name" as "either a table name, or the name
of some kind of object that isn't a table"; I think that's just weird.

Also, while it may be true that we haven't used the term specifically
in SQL sypnoses, it's been extensively used in other parts of the
documentation, in the names of system functions such as
pg_relation_size(), and in user-visible error messages (cd
src/backend/po; git grep relation), so I think you may be trying to
close the barn door after the horse has got out.

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

Well, for the record, I have previously been *extremely* confused by
both that documentation and the actual syntax.

> I think table_name is fine, and if you are very worried, add below that
> a table_name also includes views (or whatever).
>
> 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.

I was on the fence about whether this was important enough to
back-patch, and I'll add translation effort to my list of things to
worry about in future cases. We do pretty commonly back-patch
documentation corrections to the then-current major release, though.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company