Re: docs: syntax.sgml patch - Mailing list pgsql-patches

"Robert B. Easter" <reaster@comptechnews.com> writes:
> I've made an attempt to better describe the FROM clause and table expressions
> in general for the SQL Syntax: Expressions page in the User's Guide.

A good start.  Here are some suggestions for improving it.

1. I think this material should be moved out of the "Expressions"
section and made into its own level-1 section.  In the first place,
it's now larger than the rest of the section put together, and in the
second place table expressions are not the same kind of expression that
the rest of the section is talking about.  (Perhaps the "Expressions"
section should be retitled "Arithmetic Expressions" or some such.)
The mention of scalar subqueries does belong under arithmetic
expressions, but ISTM the rest of this doesn't.

Another possibility is to make a new level-1 section that talks about
the syntax of the SELECT statement in general, with subsections along
the lines of
    Target list
        [take this part out of Expressions]
    Source table (FROM/WHERE/GROUP BY/HAVING)
        [most of what you wrote]
    Display constraints (ORDER BY/LIMIT)
        [last part of what you wrote]
    UNION/INTERSECT/EXCEPT
        [to be written]

2. I don't much like the way you use the term "input table"; that seems
to me to connote a real table that is being used as one of the initial
inputs to a SELECT.  Perhaps use something like "final derived table" to
refer to the output of the table expression, with "output table" being
the result of the SELECT itself.

3. The references to scope seem to just be confusing here.  I'd leave
them out of this discussion and plan to develop a separate section
discussing name scope and outer references.

4. Your practice of showing several examples in a group and then
explaining them seems confusing, because it's not always clear which
example any particular sentence is referring to.  I'd say keep to a
strict one-example, one-commentary alternation.

5. In some places you have {curly braces} around syntactic variables.
Don't do that, use the appropriate markup.

6. Both SQL92 and Postgres allow a HAVING clause without GROUP BY.
It's kinda pointless, perhaps, but it's allowed.

7. It's not correct to say that standard SQL only allows ORDER BY in
cursors; there's also

         <direct select statement: multiple rows> ::=
              <query expression> [ <order by clause> ]

            regards, tom lane