Re: BUG #11325: Documentation Bug / RFE

Tom Lane-2 wrote
> thomas@

>  writes:
>> Two suggestions for "PostgreSQL 9.3.5 Documentation" (which is excellent
>> in
>> general, by the way :-)
>
>> 1) "Finally, NATURAL is a shorthand form of USING: it forms a USING list
>> consisting of all column
>> names that appear in both input tables."
>> Please clarify: All column names that appear in both input tables
>> (regardless of the SELECT clause), or all column names /listed in the
>> SELECT
>> clause/ that appear in both input tables?
>
> "All column names that appear in both input tables" seems perfectly
> clear to me.  Where would you get the idea that it had something to
> do with the SELECT list?
>
>> 2) "with the exception that if ON is used there will be two columns a, b,
>> and c in the result"
>> Hard to understand. Suggestion:
>> "if ON is used, each column a, b, and c will appear twice in the result."
>
> Yeah, that's fair, though perhaps it would be better as "each of the
> columns a, b, and c will appear twice in the result".

Agree on both counts.

Though the entire "Thus, USING (a,b,c) ..." seems superfluous given the
subsequent example section.  And given the 'furthermore' aspect of this it
isn't really "shorthand" for ON but it's own unique mechanic and syntax.

A comment in its own paragraph to the effect:

SELECT * output -
ON - all columns from T1 followed by all columns from T2
USING - all join columns, one copy each and in the listed order, followed by
non-join columns in T1 followed by non-join columns in T2

could be added while removing the "thus" paragraph in USING; as well as the
concept of shorthand.

David J.






--
View this message in context:
http://postgresql.1045698.n5.nabble.com/BUG-11325-Documentation-Bug-RFE-tp5817245p5817249.html
Sent from the PostgreSQL - bugs mailing list archive at Nabble.com.