To: pgsql-docs@postgreSQL.org
cc: Joe Conway <mail@joeconway.com>
Subject: Proposal for documenting 8.2 VALUES syntax
Date: Fri, 15 Sep 2006 17:14:51 -0400
Message-ID: <6015.1158354891@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

I spent a bit of time thinking about the best way to document 8.2's more
powerful VALUES clause.  Here's the plan I came up with:

* There needs to be some introductory material in Part II, and the only
place it seems to fit at all is under Chapter 7, Queries.  I think there
should be a new <sect1> page covering VALUES.  We could add it at the
end of the chapter (ie, a new section 7.7) or we could insert it between
sections 7.3 Select Lists and 7.4 Combining Queries.  The argument for
the latter position is that VALUES is now syntactically parallel to
SELECT, and so you can use it as if it were SELECT in UNION/INTERSECT/
EXCEPT structures as described in 7.4, as well as attach the ORDER BY,
LIMIT, OFFSET clauses described in 7.5 and 7.6.  However that might be
putting too much emphasis on syntactic form as opposed to pedagogical
clarity.  I'm a bit inclined to put it at the end of the chapter and
then explain "by the way, you can also attach that other stuff to it".
Thoughts?

* The SELECT reference page is huge already, so I would rather add only
the minimum possible amount to it.  This leads to the conclusion that
we'd better create a new ref/ entry just for VALUES.  I think that's
appropriate anyway, since there is some material that doesn't seem like
it would fit anywhere else --- in particular, that we want to warn off
people from expecting umpteen-billion-row VALUES constructs to work
well.

* Joe's original draft docs patch added examples to the INSERT, UPDATE,
DELETE, etc reference pages.  While we obviously have got to update the
INSERT page, I'm inclined to use the rest of that material in the new
VALUES reference page.

Comments?

			regards, tom lane