minor doc improvements

I've applied the attached patch to HEAD. It does the following:

Add a few more cross-references where appropriate, add more text about
the FROM clause and an example to the UPDATE reference page, and make
a few other SGML tweaks.

Suggestions for further improvement (for example, to the UPDATE ref
page) are welcome.

-Neil
Index: doc/src/sgml/queries.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/queries.sgml,v
retrieving revision 1.28
diff -c -r1.28 queries.sgml
*** a/doc/src/sgml/queries.sgml    29 Nov 2003 19:51:37 -0000    1.28
--- b/doc/src/sgml/queries.sgml    3 Mar 2004 21:57:00 -0000
***************
*** 108,115 ****
     <title>The <literal>FROM</literal> Clause</title>

     <para>
!     The <literal>FROM</> clause derives a table from one or more other
!     tables given in a comma-separated table reference list.
  <synopsis>
  FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_reference</replaceable> <optional>,
...</optional></optional>
  </synopsis>
--- 108,116 ----
     <title>The <literal>FROM</literal> Clause</title>

     <para>
!     The <xref linkend="sql-from" endterm="sql-from-title"> derives a
!     table from one or more other tables given in a comma-separated
!     table reference list.
  <synopsis>
  FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_reference</replaceable> <optional>,
...</optional></optional>
  </synopsis>
***************
*** 677,683 ****
     </indexterm>

     <para>
!     The syntax of the <literal>WHERE</> clause is
  <synopsis>
  WHERE <replaceable>search_condition</replaceable>
  </synopsis>
--- 678,685 ----
     </indexterm>

     <para>
!     The syntax of the <xref linkend="sql-where"
!     endterm="sql-where-title"> clause is
  <synopsis>
  WHERE <replaceable>search_condition</replaceable>
  </synopsis>
***************
*** 783,795 ****
  </synopsis>

     <para>
!     The <literal>GROUP BY</> clause is used to group together those rows in
!     a table that share the same values in all the columns listed. The
!     order in which the columns are listed does not matter.  The
!     purpose is to reduce each group of rows sharing common values into
!     one group row that is representative of all rows in the group.
!     This is done to eliminate redundancy in the output and/or compute
!     aggregates that apply to these groups.  For instance:
  <screen>
  <prompt>=></> <userinput>SELECT * FROM test1;</>
   x | y
--- 785,798 ----
  </synopsis>

     <para>
!     The <xref linkend="sql-groupby" endterm="sql-groupby-title"> is
!     used to group together those rows in a table that share the same
!     values in all the columns listed. The order in which the columns
!     are listed does not matter.  The purpose is to reduce each group
!     of rows sharing common values into one group row that is
!     representative of all rows in the group.  This is done to
!     eliminate redundancy in the output and/or compute aggregates that
!     apply to these groups.  For instance:
  <screen>
  <prompt>=></> <userinput>SELECT * FROM test1;</>
   x | y
***************
*** 1058,1064 ****
  <synopsis>
  SELECT DISTINCT <replaceable>select_list</replaceable> ...
  </synopsis>
!     (Instead of <literal>DISTINCT</> the word <literal>ALL</literal>
      can be used to select the default behavior of retaining all rows.)
     </para>

--- 1061,1067 ----
  <synopsis>
  SELECT DISTINCT <replaceable>select_list</replaceable> ...
  </synopsis>
!     (Instead of <literal>DISTINCT</> the key word <literal>ALL</literal>
      can be used to select the default behavior of retaining all rows.)
     </para>

Index: doc/src/sgml/trigger.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/trigger.sgml,v
retrieving revision 1.34
diff -c -r1.34 trigger.sgml
*** a/doc/src/sgml/trigger.sgml    22 Jan 2004 19:50:21 -0000    1.34
--- b/doc/src/sgml/trigger.sgml    3 Mar 2004 22:08:16 -0000
***************
*** 449,457 ****

     <para>
      The function <function>trigf</> reports the number of rows in the
!     table <literal>ttest</> and skips the actual operation if the
      command attempts to insert a null value into the column
!     <literal>x</>. (So the trigger acts as a not-null constraint but
      doesn't abort the transaction.)
     </para>

--- 449,457 ----

     <para>
      The function <function>trigf</> reports the number of rows in the
!     table <structname>ttest</> and skips the actual operation if the
      command attempts to insert a null value into the column
!     <structfield>x</>. (So the trigger acts as a not-null constraint but
      doesn't abort the transaction.)
     </para>

Index: doc/src/sgml/ref/select.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/select.sgml,v
retrieving revision 1.74
diff -c -r1.74 select.sgml
*** a/doc/src/sgml/ref/select.sgml    14 Dec 2003 00:15:03 -0000    1.74
--- b/doc/src/sgml/ref/select.sgml    3 Mar 2004 22:00:04 -0000
***************
*** 174,180 ****
     </para>

     <para>
!     <literal>FROM</literal>-clause elements can contain:

      <variablelist>
       <varlistentry>
--- 174,181 ----
     </para>

     <para>
!     The <literal>FROM</literal> clause can contain the following
!     elements:

      <variablelist>
       <varlistentry>
***************
*** 289,304 ****
          A <literal>JOIN</literal> clause combines two
          <literal>FROM</> items.  Use parentheses if necessary to
          determine the order of nesting.  In the absence of parentheses,
!     <literal>JOIN</literal>s nest left-to-right.  In any case
!     <literal>JOIN</literal> binds more tightly than the commas
!     separating <literal>FROM</> items.
         </para>

         <para>
          <literal>CROSS JOIN</> and <literal>INNER JOIN</literal>
          produce a simple Cartesian product, the same result as you get from
          listing the two items at the top level of <literal>FROM</>,
!     but restricted by the join condition (if any).
          <literal>CROSS JOIN</> is equivalent to <literal>INNER JOIN ON
          (TRUE)</>, that is, no rows are removed by qualification.
          These join types are just a notational convenience, since they
--- 290,305 ----
          A <literal>JOIN</literal> clause combines two
          <literal>FROM</> items.  Use parentheses if necessary to
          determine the order of nesting.  In the absence of parentheses,
!         <literal>JOIN</literal>s nest left-to-right.  In any case
!         <literal>JOIN</literal> binds more tightly than the commas
!         separating <literal>FROM</> items.
         </para>

         <para>
          <literal>CROSS JOIN</> and <literal>INNER JOIN</literal>
          produce a simple Cartesian product, the same result as you get from
          listing the two items at the top level of <literal>FROM</>,
!         but restricted by the join condition (if any).
          <literal>CROSS JOIN</> is equivalent to <literal>INNER JOIN ON
          (TRUE)</>, that is, no rows are removed by qualification.
          These join types are just a notational convenience, since they
***************
*** 647,653 ****
      <literal>INTERSECT</>, or <literal>EXCEPT</> clause may only
      specify an output column name or number, not an expression.
     </para>
!
     <para>
      If an <literal>ORDER BY</> expression is a simple name that
      matches both a result column name and an input column name,
--- 648,654 ----
      <literal>INTERSECT</>, or <literal>EXCEPT</> clause may only
      specify an output column name or number, not an expression.
     </para>
!
     <para>
      If an <literal>ORDER BY</> expression is a simple name that
      matches both a result column name and an input column name,
Index: doc/src/sgml/ref/update.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/update.sgml,v
retrieving revision 1.27
diff -c -r1.27 update.sgml
*** a/doc/src/sgml/ref/update.sgml    29 Nov 2003 19:51:39 -0000    1.27
--- b/doc/src/sgml/ref/update.sgml    3 Mar 2004 22:20:39 -0000
***************
*** 32,39 ****
    <para>
     <command>UPDATE</command> changes the values of the specified
     columns in all rows that satisfy the condition. Only the columns to
!    be modified need be mentioned in the statement; columns not explicitly
!    <literal>SET</> retain their previous values.
    </para>

    <para>
--- 32,39 ----
    <para>
     <command>UPDATE</command> changes the values of the specified
     columns in all rows that satisfy the condition. Only the columns to
!    be modified need be mentioned in the <literal>SET</literal> clause;
!    columns not explicitly modified retain their previous values.
    </para>

    <para>
***************
*** 44,49 ****
--- 44,57 ----
    </para>

    <para>
+    There are two ways to modify a table using information contained in
+    other tables in the database: using sub-selects, or specifying
+    additional tables in the <literal>FROM</literal> clause. Which
+    technique is more appropriate depends on the specific
+    circumstances.
+   </para>
+
+   <para>
     You must have the <literal>UPDATE</literal> privilege on the table
     to update it, as well as the <literal>SELECT</literal>
     privilege to any table whose values are read in the
***************
*** 99,105 ****
      <listitem>
       <para>
        A list of table expressions, allowing columns from other tables
!       to appear in the <literal>WHERE</> condition and the update expressions.
       </para>
      </listitem>
     </varlistentry>
--- 107,118 ----
      <listitem>
       <para>
        A list of table expressions, allowing columns from other tables
!       to appear in the <literal>WHERE</> condition and the update
!       expressions. This is similar to the list of tables that can be
!       specified in the <xref linkend="sql-from"
!       endterm="sql-from-title"> of a <command>SELECT</command>
!       statement; for example, an alias for the table name can be
!       specified.
       </para>
      </listitem>
     </varlistentry>
***************
*** 139,145 ****

    <para>
     Change the word <literal>Drama</> to <literal>Dramatic</> in the
!    column <structfield>kind</> of the table <literal>films</literal>:

  <programlisting>
  UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama';
--- 152,158 ----

    <para>
     Change the word <literal>Drama</> to <literal>Dramatic</> in the
!    column <structfield>kind</> of the table <structname>films</structname>:

  <programlisting>
  UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama';
***************
*** 148,154 ****

    <para>
     Adjust temperature entries and reset precipitation to its default
!    value in one row of the table <literal>weather</literal>:

  <programlisting>
  UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT
--- 161,167 ----

    <para>
     Adjust temperature entries and reset precipitation to its default
!    value in one row of the table <structname>weather</structname>:

  <programlisting>
  UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT
***************
*** 156,168 ****
  </programlisting>
    </para>

   </refsect1>

   <refsect1>
    <title>Compatibility</title>

    <para>
!    This command conforms to the SQL standard.  The
     <literal>FROM</literal> clause is a
     <productname>PostgreSQL</productname> extension.
    </para>
--- 169,198 ----
  </programlisting>
    </para>

+   <para>
+    Increment the sales count of the salesperson who manages the
+    account for Acme Corporation, using the <literal>FROM</literal>
+    clause syntax:
+ <programlisting>
+ UPDATE employees SET sales_count = sales_count + 1 FROM accounts
+   WHERE accounts.name = 'Acme Corporation'
+   AND employees.id = accounts.sales_person;
+ </programlisting>
+
+    Perform the same operation, using a sub-select in the
+    <literal>WHERE</literal> clause:
+ <programlisting>
+ UPDATE employees SET sales_count = sales_count + 1 WHERE id =
+   (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation');
+ </programlisting>
+   </para>
   </refsect1>

   <refsect1>
    <title>Compatibility</title>

    <para>
!    This command conforms to the <acronym>SQL</acronym> standard.  The
     <literal>FROM</literal> clause is a
     <productname>PostgreSQL</productname> extension.
    </para>