More updates and copy-editing. Rearrange order of sections a little bit

to put more widely useful info before less widely useful info.

doc/src/sgml/extend.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.28 2004/06/07 04:04:47 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.29 2004/12/30 03:13:56 tgl Exp $
 -->
 
  <chapter id="extend">
@@ -152,8 +152,8 @@ $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.28 2004/06/07 04:04:47 tgl Exp $
 
     <para>
      Domains can be created using the <acronym>SQL</> command
-     <command>CREATE DOMAIN</command>.  Their creation and use is not
-     discussed in this chapter.
+     <xref linkend="sql-createdomain" endterm="sql-createdomain-title">.
+     Their creation and use is not discussed in this chapter.
     </para>
    </sect2>
 
@@ -221,7 +221,7 @@ $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.28 2004/06/07 04:04:47 tgl Exp $
      Thus, when more than one argument position is declared with a polymorphic
      type, the net effect is that only certain combinations of actual argument
      types are allowed.  For example, a function declared as
-     <literal>foo(anyelement, anyelement)</> will take any two input values,
+     <literal>equal(anyelement, anyelement)</> will take any two input values,
      so long as they are of the same data type.
     </para>
 

doc/src/sgml/postgres.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.71 2004/12/29 23:36:47 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.72 2004/12/30 03:13:56 tgl Exp $
 -->
 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
@@ -192,18 +192,19 @@ $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.71 2004/12/29 23:36:47 tgl Exp
     user-defined functions, data types, triggers, etc.  These are
     advanced topics which should probably be approached only after all
     the other user documentation about <productname>PostgreSQL</> has
-    been understood.  This part also describes the server-side
+    been understood.  Later chapters in this part describe the server-side
     programming languages available in the
     <productname>PostgreSQL</productname> distribution as well as
-    general issues concerning server-side programming languages.  This
-    information is only useful to readers that have read at least the
-    first few chapters of this part.
+    general issues concerning server-side programming languages.  It
+    is essential to read at least the earlier sections of <xref
+    linkend="extend"> (covering functions) before diving into the
+    material about server-side programming languages.
    </para>
   </partintro>
 
   &extend;
-  &rules;
   &trigger;
+  &rules;
 
   &xplang;
   &plsql;

doc/src/sgml/rules.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/rules.sgml,v 1.36 2004/11/15 06:32:14 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/rules.sgml,v 1.37 2004/12/30 03:13:56 tgl Exp $ -->
 
 <Chapter Id="rules">
 <Title>The Rule System</Title>
@@ -142,7 +142,7 @@
     <Para>
         For <command>INSERT</command>, <command>UPDATE</command>, and
         <command>DELETE</command> commands, the result relation is the table
-	(or view!) where the changes take effect.
+        (or view!) where the changes are to take effect.
     </Para>
     </ListItem>
     </VarListEntry>
@@ -322,7 +322,7 @@ CREATE RULE "_RETURN" AS ON SELECT TO myview DO INSTEAD
     Currently, there can be only one action in an <literal>ON SELECT</> rule, and it must
     be an unconditional <command>SELECT</> action that is <literal>INSTEAD</>. This restriction was
     required to make rules safe enough to open them for ordinary users, and
-    it restricts <literal>ON SELECT</> rules to real view rules.
+    it restricts <literal>ON SELECT</> rules to act like views.
 </Para>
 
 <Para>
@@ -1875,14 +1875,15 @@ GRANT SELECT ON phone_number TO secretary;
 </Para>
 
 <Para>
-    For the things that can be implemented by both,
-    it depends on the usage of the database, which is the best.
+    For the things that can be implemented by both, which is best
+    depends on the usage of the database.
     A trigger is fired for any affected row once. A rule manipulates
-    the query tree or generates an additional one. So if many
+    the query or generates an additional query. So if many
     rows are affected in one statement, a rule issuing one extra
-    command would usually do a better job than a trigger that is
+    command is likely to be faster than a trigger that is
     called for every single row and must execute its operations
-    many times.
+    many times.  However, the trigger approach is conceptually far
+    simpler than the rule approach, and is easier for novices to get right.
 </Para>
 
 <Para>

doc/src/sgml/trigger.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/trigger.sgml,v 1.38 2004/12/13 18:05:09 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/trigger.sgml,v 1.39 2004/12/30 03:13:56 tgl Exp $
 -->
 
  <chapter id="triggers">
@@ -58,6 +58,15 @@ $PostgreSQL: pgsql/doc/src/sgml/trigger.sgml,v 1.38 2004/12/13 18:05:09 petere E
     respectively.
    </para>
 
+   <para>
+    Statement-level <quote>before</> triggers naturally fire before the
+    statement starts to do anything, while statement-level <quote>after</>
+    triggers fire at the very end of the statement.  Row-level <quote>before</>
+    triggers fire immediately before a particular row is operated on,
+    while row-level <quote>after</> triggers fire at the end of the statement
+    (but before any statement-level <quote>after</> triggers).
+   </para>
+
    <para>
     Trigger functions invoked by per-statement triggers should always
     return <symbol>NULL</symbol>. Trigger functions invoked by per-row
@@ -110,6 +119,21 @@ $PostgreSQL: pgsql/doc/src/sgml/trigger.sgml,v 1.38 2004/12/13 18:05:09 petere E
     triggers are not fired.
    </para>
 
+   <para>
+    Typically, row before triggers are used for checking or
+    modifying the data that will be inserted or updated.  For example,
+    a before trigger might be used to insert the current time into a
+    timestamp column, or to check that two elements of the row are
+    consistent. Row after triggers are most sensibly
+    used to propagate the updates to other tables, or make consistency
+    checks against other tables.  The reason for this division of labor is
+    that an after trigger can be certain it is seeing the final value of the
+    row, while a before trigger cannot; there might be other before triggers
+    firing after it.  If you have no specific reason to make a trigger before
+    or after, the before case is more efficient, since the information about
+    the operation doesn't have to be saved until end of statement.
+   </para>
+
    <para>
     If a trigger function executes SQL commands then these
     commands may fire triggers again. This is known as cascading
@@ -140,6 +164,20 @@ $PostgreSQL: pgsql/doc/src/sgml/trigger.sgml,v 1.38 2004/12/13 18:05:09 petere E
     trigger.
    </para>
 
+   <para>
+    Each programming language that supports triggers has its own method
+    for making the trigger input data available to the trigger function.
+    This input data includes the type of trigger event (e.g.,
+    <command>INSERT</command> or <command>UPDATE</command>) as well as any
+    arguments that were listed in <command>CREATE TRIGGER</>.
+    For a row-level trigger, the input data also includes the
+    <varname>NEW</varname> row for <command>INSERT</command> and
+    <command>UPDATE</command> triggers, and/or the <varname>OLD</varname> row
+    for <command>UPDATE</command> and <command>DELETE</command> triggers.
+    Statement-level triggers do not currently have any way to examine the
+    individual row(s) modified by the statement.
+   </para>
+
   </sect1>
 
   <sect1 id="trigger-datachanges">
@@ -373,7 +411,7 @@ typedef struct TriggerData
         the row being inserted, updated, or deleted.  If this trigger
         was fired for an <command>INSERT</command> or
         <command>DELETE</command> then this is what you should return
-	to from the function if you don't want to replace the row with
+        from the function if you don't want to replace the row with
         a different one (in the case of <command>INSERT</command>) or
         skip the operation.
        </para>

doc/src/sgml/xplang.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.26 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.27 2004/12/30 03:13:56 tgl Exp $
 -->
 
  <chapter id="xplang">
@@ -29,10 +29,16 @@ $PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.26 2003/11/29 19:51:38 pgsql Exp
   <para>
    Writing a handler for a new procedural language is described in
    <xref linkend="plhandler">.  Several procedural languages are
-   available in the standard <productname>PostgreSQL</productname>
+   available in the core <productname>PostgreSQL</productname>
    distribution, which can serve as examples.
   </para>
 
+  <para>
+   There are additional procedural languages available that are not
+   included in the core distribution. <xref linkend="external-projects">
+   has information about finding them.
+  </para>
+
   <sect1 id="xplang-install">
    <title>Installing Procedural Languages</title>