public inbox for [email protected]  

help / color / mirror / Atom feed

From: Tom Lane <[email protected]>
To: [email protected]
Cc: Joe Conway <[email protected]>
Subject: Proposal for documenting 8.2 VALUES syntax
Date: Fri, 15 Sep 2006 17:14:51 -0400
Message-ID: <[email protected]> (raw)

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

view thread (3+ messages)  latest in thread

reply

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: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: Proposal for documenting 8.2 VALUES syntax
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox