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

diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml
index 7934230859ed22fbcd03ec90adeb68ac2cb9bc2a..16cdba76814daa921dd3dbe372355fb3b3a57a73 100644 (file)
--- a/doc/src/sgml/ref/create_table_as.sgml
+++ b/doc/src/sgml/ref/create_table_as.sgml
@@ -1,5 +1,5 @@
 
 
@@ -157,6 +157,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name
   
  
 
+ 
+  Examples
+
+  
+   Create a new table films_recent consisting of only
+   recent entries from the table films:
+
+
+CREATE TABLE films_recent AS
+  SELECT * FROM films WHERE date_prod >= '2002-01-01';
+
+  
+ 
+
  
   Compatibility
 

diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index d0ef47d2c9f6115e7e7948fc899e2d403528235d..6b6c8bf66d8672bfdf58c2d7b5b0ff1623233716 100644 (file)
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -1,5 +1,5 @@
 
 
@@ -100,6 +100,33 @@ DELETE count
   
  
 
+ 
+  Notes
+
+  
+   PostgreSQL lets you reference columns of
+   other tables in the WHERE condition.  For example, to
+   delete all films produced by a given producer, one might do
+
+DELETE FROM films
+  WHERE producer_id = producers.id AND producers.name = 'foo';
+
+   What is essentially happening here is a join between films
+   and producers, with all successfully joined
+   films rows being marked for deletion.
+   This syntax is not standard.  A more standard way to do it is
+
+DELETE FROM films
+  WHERE producer_id IN (SELECT id FROM producers WHERE name = 'foo');
+
+   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.
+  
+ 
+
  
   Examples
 
@@ -122,7 +149,9 @@ DELETE FROM films;
   Compatibility
 
   
-   This command conforms to the SQL standard.
+   This command conforms to the SQL standard, except that the ability to
+   reference other tables in the WHERE clause is a
+   PostgreSQL extension.
   
  
 

diff --git a/doc/src/sgml/ref/drop_group.sgml b/doc/src/sgml/ref/drop_group.sgml
index cabe908877c80ec82cc7b0d46926862dde2776af..10f513ebbdc8dc7fc8afae55468b281a19995b8b 100644 (file)
--- a/doc/src/sgml/ref/drop_group.sgml
+++ b/doc/src/sgml/ref/drop_group.sgml
@@ -1,5 +1,5 @@
 
 
@@ -29,7 +29,7 @@ DROP GROUP name
 
   
    DROP GROUP removes the specified group.  The
-   users in the group are not deleted.
+   users in the group are not removed.
   
  
   

diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index afcfc80a332ae62ee06f78a61b735e88db675ad1..a3d03a745afd0b3c8f4d1060a4d500417d6c287e 100644 (file)
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -1,5 +1,5 @@
 
 
@@ -162,7 +162,7 @@ INSERT INTO films VALUES
   
 
   
-   In this second example, the len column is
+   In this example, the len column is
    omitted and therefore it will have the default value:
 
 
@@ -172,7 +172,7 @@ INSERT INTO films (code, title, did, date_prod, kind)
   
 
   
-   The third example uses the DEFAULT clause for
+   This example uses the DEFAULT clause for
    the date columns rather than specifying a value:
 
 
@@ -184,11 +184,20 @@ INSERT INTO films (code, title, did, date_prod, kind)
   
 
   
-   This example inserts several rows into table
-   films from table tmp:
+   To insert a row consisting entirely of default values:
 
 
-INSERT INTO films SELECT * FROM tmp;
+INSERT INTO films DEFAULT VALUES;
+
+  
+
+  
+   This example inserts some rows into table
+   films from a table tmp_films
+   with the same column layout as films:
+
+
+INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';
 
   
 

diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml
index e0fdd47b918188b3ca7e23164c0eca3120bfbafd..11389d190b4224a2280f2f49469b5006fa439e7c 100644 (file)
--- a/doc/src/sgml/ref/select_into.sgml
+++ b/doc/src/sgml/ref/select_into.sgml
@@ -1,5 +1,5 @@
 
 
@@ -105,6 +105,19 @@ SELECT [ ALL | DISTINCT [ ON ( expression
   
  
 
+ 
+  Examples
+
+  
+   Create a new table films_recent consisting of only
+   recent entries from the table films:
+
+
+SELECT * INTO films_recent FROM films WHERE date_prod >= '2002-01-01';
+
+  
+ 
+
  
   Compatibility
 
@@ -120,6 +133,14 @@ SELECT [ ALL | DISTINCT [ ON ( expression
    new code.
   
  
+
+ 
+  See Also
+
+  
+   
+  
+ 
 
 
 
 
@@ -114,8 +114,9 @@ UPDATE [ ONLY ] table SET 
       expressions. This is similar to the list of tables that can be
       specified in the 
       endterm="sql-from-title"> of a SELECT
-      statement; for example, an alias for the table name can be
-      specified.
+      statement.  Note that the target table must not appear in the
+      fromlist, unless you intend a self-join (in which
+      case it must appear with an alias in the fromlist).
      
     
    
@@ -154,10 +155,13 @@ UPDATE count
   Notes
 
   
-   When joining the target table to other tables using a 
-   class="PARAMETER">fromlist, be careful that the join
+   When a FROM clause is present, what essentially happens
+   is that the target table is joined to the tables mentioned in the
+   fromlist, and each output row of the join
+   represents an update operation for the target table.  When using
+   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 =
 
 
    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.
 
 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;
 
   
@@ -228,10 +235,18 @@ COMMIT;
   Compatibility
 
   
-   This command conforms to the SQL standard.  The
-   FROM clause is a
+   This command conforms to the SQL standard, except
+   that the FROM clause is a
    PostgreSQL extension.
   
+
+  
+   Some other database systems offer a FROM option in which
+   the target table is supposed to be listed again within FROM.
+   That is not how PostgreSQL interprets
+   FROM.  Be careful when porting applications that use this
+   extension.
+