Re: BUG #13966: Documentation. 'Select' description

David G. Johnston wrote:
> On Wed, Feb 17, 2016 at 8:03 AM, <iurii(dot)i(dot)popov(at)gmail(dot)com> wrote:

> > There is the description mismatch at documentation.
> >
> > 1. http://www.postgresql.org/docs/9.5/static/sql-select.html (SELECT)
> >
> > Each subquery can be a SELECT, TABLE, VALUES, INSERT, UPDATE or DELETE
> > statement.
> >
> > 2. http://www.postgresql.org/docs/9.5/static/queries-with.html (7.8. WITH
> > Queries (Common Table Expressions))
> >
> > Each auxiliary statement in a WITH clause can be a SELECT, INSERT, UPDATE,
> > or DELETE;
> >
> > Where is TABLE and VALUES?
>
>
> While being thorough is admirable the SELECT documentation you reference
> is official (and thus complete) command reference. The WITH section
> referenced is more descriptive in nature and doesn't have to specify/repeat
> knowledge provided elsewhere.

I'm not sure I agree with your rationale. Listing some keywords but not
all seems confusing -- it's easy to get the impression that the list is
exhaustive. I wonder if we can say something like "any of the SELECT
variants", instead of just SELECT. On the other hand, WITH itself is
sometimes seen as one of the SELECT variants (in fact if you do "man
WITH" you get the SELECT page, just like you do if you do "man TABLE" --
though curiously enough "man VALUES" is a different page), so that might
misled people into thinking that you can put one WITH clause inside
another. It seems easier to just add TABLE and VALUES to the list.

BTW I think we should add generate_series() to the SEE ALSO section of
the VALUES manpage.

--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services