Some more small improvements in response to 7.4 interactive docs comments.

6 files changed, 112 insertions, 24 deletions

diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml
index 7934230859e..16cdba76814 100644
--- a/doc/src/sgml/ref/create_table_as.sgml
+++ b/doc/src/sgml/ref/create_table_as.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.28 2005/01/05 14:22:39 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.29 2005/01/09 05:57:45 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -158,6 +158,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
  </refsect1>
 
  <refsect1>
+  <title>Examples</title>
+
+  <para>
+   Create a new table <literal>films_recent</literal> consisting of only
+   recent entries from the table <literal>films</literal>:
+
+<programlisting>
+CREATE TABLE films_recent AS
+  SELECT * FROM films WHERE date_prod &gt;= '2002-01-01';
+</programlisting>
+  </para>
+ </refsect1>
+
+ <refsect1>
   <title>Compatibility</title>
 
   <para>
diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index d0ef47d2c9f..6b6c8bf66d8 100644
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.21 2005/01/04 00:39:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.22 2005/01/09 05:57:45 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -101,6 +101,33 @@ DELETE <replaceable class="parameter">count</replaceable>
  </refsect1>
 
  <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <productname>PostgreSQL</productname> lets you reference columns of
+   other tables in the <literal>WHERE</> condition.  For example, to
+   delete all films produced by a given producer, one might do
+<programlisting>
+DELETE FROM films
+  WHERE producer_id = producers.id AND producers.name = 'foo';
+</programlisting>
+   What is essentially happening here is a join between <structname>films</>
+   and <structname>producers</>, with all successfully joined
+   <structname>films</> rows being marked for deletion.
+   This syntax is not standard.  A more standard way to do it is
+<programlisting>
+DELETE FROM films
+  WHERE producer_id IN (SELECT id FROM producers WHERE name = 'foo');
+</programlisting>
+   In some cases the join style is easier to write or faster to
+   execute than the sub-select style.  One objection to the join style
+   is that there is no explicit list of what tables are being used,
+   which makes the style somewhat error-prone; also it cannot handle
+   self-joins.
+  </para>
+ </refsect1>
+
+ <refsect1>
   <title>Examples</title>
 
   <para>
@@ -122,7 +149,9 @@ DELETE FROM films;
   <title>Compatibility</title>
 
   <para>
-   This command conforms to the SQL standard.
+   This command conforms to the SQL standard, except that the ability to
+   reference other tables in the <literal>WHERE</> clause is a
+   <productname>PostgreSQL</productname> extension.
   </para>
  </refsect1>
 </refentry>
diff --git a/doc/src/sgml/ref/drop_group.sgml b/doc/src/sgml/ref/drop_group.sgml
index cabe908877c..10f513ebbdc 100644
--- a/doc/src/sgml/ref/drop_group.sgml
+++ b/doc/src/sgml/ref/drop_group.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.9 2005/01/04 00:39:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.10 2005/01/09 05:57:45 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -29,7 +29,7 @@ DROP GROUP <replaceable class="PARAMETER">name</replaceable>
 
   <para>
    <command>DROP GROUP</command> removes the specified group.  The
-   users in the group are not deleted.
+   users in the group are not removed.
   </para>
  </refsect1>
   
diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index afcfc80a332..a3d03a745af 100644
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.28 2005/01/04 00:39:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.29 2005/01/09 05:57:45 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -162,7 +162,7 @@ INSERT INTO films VALUES
   </para>
 
   <para>
-   In this second example, the <literal>len</literal> column is
+   In this example, the <literal>len</literal> column is
    omitted and therefore it will have the default value:
 
 <programlisting>
@@ -172,7 +172,7 @@ INSERT INTO films (code, title, did, date_prod, kind)
   </para>
 
   <para>
-   The third example uses the <literal>DEFAULT</literal> clause for
+   This example uses the <literal>DEFAULT</literal> clause for
    the date columns rather than specifying a value:
 
 <programlisting>
@@ -184,11 +184,20 @@ INSERT INTO films (code, title, did, date_prod, kind)
   </para>
 
   <para>
-   This example inserts several rows into table
-   <literal>films</literal> from table <literal>tmp</literal>:
+   To insert a row consisting entirely of default values:
 
 <programlisting>
-INSERT INTO films SELECT * FROM tmp;
+INSERT INTO films DEFAULT VALUES;
+</programlisting>
+  </para>
+
+  <para>
+   This example inserts some rows into table
+   <literal>films</literal> from a table <literal>tmp_films</literal>
+   with the same column layout as <literal>films</literal>:
+
+<programlisting>
+INSERT INTO films SELECT * FROM tmp_films WHERE date_prod &lt; '2004-05-07';
 </programlisting>
   </para>
 
diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml
index e0fdd47b918..11389d190b4 100644
--- a/doc/src/sgml/ref/select_into.sgml
+++ b/doc/src/sgml/ref/select_into.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.32 2005/01/04 03:58:16 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.33 2005/01/09 05:57:45 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -106,6 +106,19 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
  </refsect1>
 
  <refsect1>
+  <title>Examples</title>
+
+  <para>
+   Create a new table <literal>films_recent</literal> consisting of only
+   recent entries from the table <literal>films</literal>:
+
+<programlisting>
+SELECT * INTO films_recent FROM films WHERE date_prod &gt;= '2002-01-01';
+</programlisting>
+  </para>
+ </refsect1>
+
+ <refsect1>
   <title>Compatibility</title>
 
   <para>
@@ -120,6 +133,14 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
    new code.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-createtableas" endterm="sql-createtableas-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 3fc3144dfe8..d8a662c13f9 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.31 2005/01/04 03:58:16 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.32 2005/01/09 05:57:45 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -114,8 +114,9 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replacea
       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.
+      statement.  Note that the target table must not appear in the
+      <replaceable>fromlist</>, unless you intend a self-join (in which
+      case it must appear with an alias in the <replaceable>fromlist</>).
      </para>
     </listitem>
    </varlistentry>
@@ -154,10 +155,13 @@ UPDATE <replaceable class="parameter">count</replaceable>
   <title>Notes</title>
 
   <para>
-   When joining the target table to other tables using a <replaceable
-   class="PARAMETER">fromlist</replaceable>, be careful that the join
+   When a <literal>FROM</> clause is present, what essentially happens
+   is that the target table is joined to the tables mentioned in the
+   <replaceable>fromlist</replaceable>, and each output row of the join
+   represents an update operation for the target table.  When using
+   <literal>FROM</> you should ensure that the join
    produces at most one output row for each row to be modified.  In
-   other words, a target row mustn't join to more than one row from
+   other words, a target row shouldn't join to more than one row from
    the other table(s).  If it does, then only one of the join rows
    will be used to update the target row, but which one will be used
    is not readily predictable.
@@ -210,15 +214,18 @@ UPDATE employees SET sales_count = sales_count + 1 WHERE id =
 </programlisting>
 
    Attempt to insert a new stock item along with the quantity of stock. If
-   the item exists, update the stock count of the existing item. To do this,
-   use savepoints.
+   the item already exists, instead update the stock count of the existing
+   item. To do this without failing the entire transaction, use savepoints.
 <programlisting>
 BEGIN;
+-- other operations
 SAVEPOINT sp1;
 INSERT INTO wines VALUES('Chateau Lafite 2003', '24');
--- Check for unique violation on name
+-- Assume the above fails because of a unique key violation,
+-- so now we issue these commands:
 ROLLBACK TO sp1;
-UPDATE wines SET stock = stock + 24 WHERE winename='Chateau Lafite 2003';
+UPDATE wines SET stock = stock + 24 WHERE winename = 'Chateau Lafite 2003';
+-- continue with other operations, and eventually
 COMMIT;
 </programlisting>
   </para>
@@ -228,10 +235,18 @@ COMMIT;
   <title>Compatibility</title>
 
   <para>
-   This command conforms to the <acronym>SQL</acronym> standard.  The
-   <literal>FROM</literal> clause is a
+   This command conforms to the <acronym>SQL</acronym> standard, except
+   that the <literal>FROM</literal> clause is a
    <productname>PostgreSQL</productname> extension.
   </para>
+
+  <para>
+   Some other database systems offer a <literal>FROM</> option in which
+   the target table is supposed to be listed again within <literal>FROM</>.
+   That is not how <productname>PostgreSQL</productname> interprets
+   <literal>FROM</>.  Be careful when porting applications that use this
+   extension.
+  </para>
  </refsect1>
 </refentry>