"David G. Johnston" <david.g.johnston@gmail.com> writes:
> Looking again at the SELECT Reference page while helping a novice user I
> was once again annoyed but how the most common query syntax form for the
> FROM clause is buried within a bunch of "how to generate a table" detail.
Hmm ... I'm good with the concept of making JOIN syntax more prominent,
but I don't much like this patch. I think it's fundamentally wrong to
describe from_item as disjoint from join_expression, and you're
going to make people more confused not less so by doing that.
IMO there's nothing really wrong with the synopsis. The problem is
in the "FROM Clause" section, which dives headfirst into the weedy
details without any context. What do you think of adding an
introductory para or two in that section, saying that the FROM
clause is built from base tables possibly joined into join expressions?
You sort of have that here, but it's pretty terse still. Maybe it
would be helpful also to separate the subsequent list of syntax
details into base-table options and join syntax.
Not sure what I think about moving LATERAL up. That's a sufficiently
weird/obtuse thing that I think we're best off dealing with it last,
even if that means we need a forward reference or two. I'd almost
put it into its own sub-section of "FROM Clause".
There's also an argument that the reference page *should* be terse
and the place to cater to novices is 7.2's "Table Expressions"
discussion (which we could, but don't, link from the ref page).
I'm not sure if there's any good way to rework that material to make
it clearer, but there are definitely bits of it that I don't find
very well-written. There might be an argument for jettisoning
some details (like the obsolete "table*" notation) from 7.2
altogether and covering those only in the ref page.
regards, tom lane