BUG #13966: Documentation. 'Select' description

On Wed, Feb 17, 2016 at 8:03 AM, <iurii.i.popov@gmail.com> wrote:

The following bug has been logged on the website:

Bug reference: 13966
Logged by: Iurii Popov
Email address: iurii.i.popov@gmail.com
PostgreSQL version: 9.5.1
Operating system: Ubuntu
Description:

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. In the particular case the previous section
discusses "VALUES" and says that VALUES can be used in any place that
SELECT can be used. Thus, while reading the WITH section and seeing SELECT
the documentation is allowed to assume that the reader has the knowledge
that VALUES could replace SELECT in this situation.

Likewise, the only place TABLE is documented is within the context of
SELECT and there it is spelled out where one is allowed to use TABLE.
Stating the same here would be repeating information defined elsewhere.
While that may be desirable the use of TABLE is so uncommon that it
inclusion in this section would, IMO, just introduce the reader to a
concept that they have not previously seen nor likely need to be aware of
in order to understand how WITH/CTEs work.

So, I would say the level of detail given in the CTE/WITH section is just
right. Adding more for the sake of being precise just takes away from the
main goal which is to familiarize the reader with how this clause works.

David J.

David G. Johnston wrote:

On Wed, Feb 17, 2016 at 8:03 AM, <iurii.i.popov@gmail.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

--
Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-bugs