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

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

> The following bug has been logged on the website:
>
> Bug reference: 13966
> Logged by: Iurii Popov
> Email address: iurii(dot)i(dot)popov(at)gmail(dot)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.