Re: BUG #5968: DOCUMENTATION: SELECT synopsis omits RETURNING keyword

On 09/04/11 02:42, Tom Lane wrote:
> Gavin Flower<GavinFlower@archidevsys.co.nz>  writes:
>> I found were RETURNING is defined, so I was confused...
>> ...
>> However, may be it would still be good to mention it on the SELECT page?
> It is mentioned --- the subsection on the WITH clause points out that
> you typically want to use RETURNING on an INSERT/UPDATE/DELETE in WITH.
>
> I thought about providing an example, but couldn't come up with one that
> was both simple and compelling.  There's no strong reason to do WITH
> (something RETURNING) SELECT ... --- you might as well just do the work
> in a straight "something RETURNING" statement.  To do something that
> actually requires the more complex syntax, you'd need to join the
> RETURNING result to another table or another RETURNING result.
> Creating an easily understandable example that involves that is beyond
> my powers at this time of the morning.
>
>             regards, tom lane
I think it may be useful to explain how I looked for explanations of
RETURNING, as I am sure some other people adopt the same approach.

I located the page for 'SELECT', then I used the search function of the
browser to look for the word 'RETURNING'.  Partly because I have poor
eyesight, I did not pay as much attention to context, as perhaps I
should.  Often I use the table of conbtents, and sometimes I also use
the index.

I hope this is a useful perspective on how documentation is sometimes
accessed.

I often find the examples very helpful, so I am glad you added an
example to the page for 'SELECT'. (I had an appreciative chuckle, when I
saw my name in the newsletter!)


Regards,
Gavin