0002-query.patch

diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index e73e805ec4..413763691e 100644
--- a/doc/src/sgml/query.sgml
+++ b/doc/src/sgml/query.sgml
@@ -441,11 +441,11 @@ SELECT DISTINCT city
    <para>
     Thus far, our queries have only accessed one table at a time.
     Queries can access multiple tables at once, or access the same
-    table in such a way that multiple rows of the table are being
-    processed at the same time.  A query that accesses multiple rows
-    of the same or different tables at one time is called a
-    <firstterm>join</firstterm> query.  As an example, say you wish to
-    list all the weather records together with the location of the
+    table several times. Such queries &mdash; they are called
+    <firstterm>join</firstterm> queries &mdash; combine
+    rows of one table in some way with rows of the other table
+    and return a single row per combination. An example may be a
+    list of all the weather records together with the location of the
     associated city.  To do that, we need to compare the <structfield>city</structfield>
     column of each row of the <structname>weather</structname> table with the
     <structfield>name</structfield> column of all rows in the <structname>cities</structname>
@@ -461,10 +461,17 @@ SELECT DISTINCT city
 
 <programlisting>
 SELECT *
-    FROM weather, cities
-    WHERE city = name;
+FROM   weather
+JOIN   cities ON (city = name);
 </programlisting>
 
+    The keyword <command>JOIN</command> connects the two tables.
+    Behind the keyword <command>ON</command> follows the
+    definition how to compare their rows. In this case, the
+    column <varname>city</varname> of table <varname>weather</varname>
+    must be equal to the column <varname>name</varname>
+    of table <varname>cities</varname>.
+
 <screen>
      city      | temp_lo | temp_hi | prcp |    date    |     name      | location
 ---------------+---------+---------+------+------------+---------------+-----------
@@ -476,8 +483,14 @@ SELECT *
    </para>
 
    <para>
-    Observe two things about the result set:
+    Observe some things about the result set:
     <itemizedlist>
+     <listitem>
+      <para>
+       The resulting rows contain values from both tables.
+      </para>
+     </listitem>
+
      <listitem>
       <para>
        There is no result row for the city of Hayward.  This is
@@ -499,23 +512,14 @@ SELECT *
        <literal>*</literal>:
 <programlisting>
 SELECT city, temp_lo, temp_hi, prcp, date, location
-    FROM weather, cities
-    WHERE city = name;
+FROM   weather
+JOIN   cities ON (city = name);
 </programlisting>
       </para>
      </listitem>
     </itemizedlist>
    </para>
 
-   <formalpara>
-    <title>Exercise:</title>
-
-    <para>
-     Attempt to determine the semantics of this query when the
-     <literal>WHERE</literal> clause is omitted.
-    </para>
-   </formalpara>
-
    <para>
     Since the columns all had different names, the parser
     automatically found which table they belong to.  If there
@@ -526,8 +530,8 @@ SELECT city, temp_lo, temp_hi, prcp, date, location
 <programlisting>
 SELECT weather.city, weather.temp_lo, weather.temp_hi,
        weather.prcp, weather.date, cities.location
-    FROM weather, cities
-    WHERE cities.name = weather.city;
+FROM   weather
+JOIN   cities ON (cities.name = weather.city);
 </programlisting>
 
     It is widely considered good style to qualify all column names
@@ -537,15 +541,18 @@ SELECT weather.city, weather.temp_lo, weather.temp_hi,
 
    <para>
     Join queries of the kind seen thus far can also be written in this
-    alternative form:
+    form:
 
 <programlisting>
 SELECT *
-    FROM weather INNER JOIN cities ON (weather.city = cities.name);
+FROM   weather, cities
+WHERE  weather.city = cities.name;
 </programlisting>
 
-    This syntax is not as commonly used as the one above, but we show
-    it here to help you understand the following topics.
+    This syntax is mainly used in legacy applications. It dates back
+    to the first days of SQL, avoids the <literal>JOIN</literal>
+    keyword, and uses the <literal>WHERE</literal> clause instead of the
+    <literal>ON</literal> clause.
    </para>
 
    <indexterm><primary>join</primary><secondary>outer</secondary></indexterm>
@@ -558,7 +565,7 @@ SELECT *
     found we want some <quote>empty values</quote> to be substituted
     for the <structname>cities</structname> table's columns.  This kind
     of query is called an <firstterm>outer join</firstterm>.  (The
-    joins we have seen so far are inner joins.)  The command looks
+    joins we have seen so far are <firstterm>inner joins</firstterm>.)  The command looks
     like this:
 
 <programlisting>
@@ -593,10 +600,9 @@ SELECT *
     </para>
    </formalpara>
 
+   <indexterm><primary>join</primary><secondary>self</secondary></indexterm>
+   <indexterm><primary>alias</primary><secondary>for table name in query</secondary></indexterm>
    <para>
-    <indexterm><primary>join</primary><secondary>self</secondary></indexterm>
-    <indexterm><primary>alias</primary><secondary>for table name in query</secondary></indexterm>
-
     We can also join a table against itself.  This is called a
     <firstterm>self join</firstterm>.  As an example, suppose we wish
     to find all the weather records that are in the temperature range
@@ -610,10 +616,10 @@ SELECT *
 
 <programlisting>
 SELECT w1.city, w1.temp_lo AS low, w1.temp_hi AS high,
-    w2.city, w2.temp_lo AS low, w2.temp_hi AS high
-    FROM weather w1, weather w2
-    WHERE w1.temp_lo &lt; w2.temp_lo
-    AND w1.temp_hi &gt; w2.temp_hi;
+       w2.city, w2.temp_lo AS low, w2.temp_hi AS high
+FROM   weather w1
+JOIN   weather w2 ON (w1.temp_lo &lt; w2.temp_lo AND
+                      w1.temp_hi &gt; w2.temp_hi);
 </programlisting>
 
 <screen>
@@ -630,8 +636,8 @@ SELECT w1.city, w1.temp_lo AS low, w1.temp_hi AS high,
     queries to save some typing, e.g.:
 <programlisting>
 SELECT *
-    FROM weather w, cities c
-    WHERE w.city = c.name;
+FROM   weather w
+JOIN   cities  c ON (w.city = c.name);
 </programlisting>
     You will encounter this style of abbreviating quite frequently.
    </para>