commit 4f5f5c6bfc964d9c136b0d3490ddaa6a53a4c25c
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Wed Oct 21 23:23:33 2020 +0000

    Some word-smithing to go along with my email comments

diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index 413763691e..bc42381427 100644
--- a/doc/src/sgml/query.sgml
+++ b/doc/src/sgml/query.sgml
@@ -440,13 +440,12 @@ 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 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>
+    Queries which access multiple tables (including repeats) at once are called
+    <firstterm>join</firstterm> queries.  They internally combine
+    each row from one table with each row of a second table.  A expression is
+    specified to then limit which pairs of rows are returned.
+    For example, to return all the weather records together with the location of the
+    associated city, the database 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>
     table, and select the pairs of rows where these values match.
@@ -466,8 +465,8 @@ 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
+    After the keyword <command>ON</command> follows the
+    expression comparing 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>.
@@ -483,14 +482,8 @@ JOIN   cities ON (city = name);
    </para>
 
    <para>
-    Observe some things about the result set:
+    Observe two 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
@@ -546,13 +539,15 @@ JOIN   cities ON (cities.name = weather.city);
 <programlisting>
 SELECT *
 FROM   weather, cities
-WHERE  weather.city = cities.name;
+WHERE  city = name;
 </programlisting>
 
-    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.
+    This syntax pre-dates the <literal>JOIN</literal> and <literal>ON</literal>
+    keywords.  The tables are simply listed in the <literal>FROM</literal>,
+    comma-separated, and the comparison expression added to the
+    <literal>WHERE</literal> clause.  As join expressions serve a specific
+    purpose in a multi-table query it is preferable to make them stand-out
+    by using join clauses to introduce additional tables into the query.
    </para>
 
    <indexterm><primary>join</primary><secondary>outer</secondary></indexterm>
@@ -565,8 +560,8 @@ WHERE  weather.city = cities.name;
     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 <firstterm>inner joins</firstterm>.)  The command looks
-    like this:
+    joins we have seen so far are <firstterm>inner joins</firstterm>.)
+    The command looks like this:
 
 <programlisting>
 SELECT *