The documentation for SELECT is incorrect in a sense: the syntax for a

join is defined as:

from_item [ NATURAL ] join_type from_item
    [ ON join_condition | USING ( join_column_list ) ]

However, if the join_type is an INNER or OUTER join, an ON, USING, or
NATURAL clause *must* be specified (it's not optional, as that segment
of the docs suggest).

I'm not exactly sure what the best way to fix this is, so I've attached
a patch adding a FIXME comment to the relevant section of the SGML. If
anyone has any ideas on the proper way to outline join syntax, please
speak up.

Neil Conway <neilc@samurai.com> || PGP Key ID: DB3C29FC

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 0f8a3db..42281e5 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.64 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.65 2003/03/20 19:00:01 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -46,6 +46,11 @@ where <replaceable class="PARAMETER">from_item</replaceable> can be:
 <replaceable class="PARAMETER">table_function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] )
     AS ( <replaceable class="PARAMETER">column_definition_list</replaceable> )
 |
+<!-- 
+   FIXME: this syntax is incorrect if the join type is an INNER or
+   OUTER join (in which case one of NATURAL, ON ..., or USING ... is
+   mandatory, not optional). What's the best way to fix this?
+-->
 <replaceable class="PARAMETER">from_item</replaceable> [ NATURAL ] <replaceable class="PARAMETER">join_type</replaceable> <replaceable class="PARAMETER">from_item</replaceable>
     [ ON <replaceable class="PARAMETER">join_condition</replaceable> | USING ( <replaceable class="PARAMETER">join_column_list</replaceable> ) ]
   </synopsis>