On Wed, Jul 27, 2011 at 5:19 PM, Peter Eisentraut <pete...@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 >> <schmi...@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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers