More minor updates and copy-editing.

doc/src/sgml/ref/alter_database.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_database.sgml,v 1.13 2004/07/05 02:34:43 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_database.sgml,v 1.14 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -25,7 +25,7 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET <replacea
 
 ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
 
-ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable>new_owner</replaceable>
+ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable>newowner</replaceable>
 </synopsis>
  </refsynopsisdiv>
 
@@ -33,12 +33,12 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <repla
   <title>Description</title>
 
   <para>
-   <command>ALTER DATABASE</command> is used to change the attributes
+   <command>ALTER DATABASE</command> changes the attributes
    of a database.
   </para>
 
   <para>
-   The first two forms change the session default of a run-time
+   The first two forms change the session default for a run-time
    configuration variable for a <productname>PostgreSQL</productname>
    database. Whenever a new session is subsequently started in that
    database, the specified value becomes the session default value.
@@ -46,12 +46,14 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <repla
    in <filename>postgresql.conf</> or has been received from the
    <command>postmaster</command> command line.  Only the database
    owner or a superuser can change the session defaults for a
-   database.
+   database.  Certain variables cannot be set this way, or can only be
+   set by a superuser.
   </para>
 
   <para>
    The third form changes the name of the database.  Only the database
-   owner can rename a database, and only if he has the
+   owner or a superuser can rename a database; non-superuser owners must
+   also have the
    <literal>CREATEDB</literal> privilege.  The current database cannot
    be renamed.  (Connect to a different database if you need to do
    that.)
@@ -71,7 +73,7 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <repla
       <term><replaceable class="PARAMETER">name</replaceable></term>
       <listitem>
        <para>
-	The name of the database whose session defaults are to be altered.
+        The name of the database whose attributes are to be altered.
        </para>
       </listitem>
      </varlistentry>
@@ -81,14 +83,13 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <repla
       <term><replaceable>value</replaceable></term>
       <listitem>
        <para>
-        Set the session default for this database of the specified
-        configuration parameter to the given value.  If
+        Set this database's session default for the specified configuration
+        parameter to the given value.  If
         <replaceable>value</replaceable> is <literal>DEFAULT</literal>
         or, equivalently, <literal>RESET</literal> is used, the
-        database-specific variable setting is removed and the system-wide
-	default
+        database-specific setting is removed, so the system-wide default
         setting will be inherited in new sessions.  Use <literal>RESET
-        ALL</literal> to clear all settings.
+        ALL</literal> to clear all database-specific settings.
        </para>
 
        <para>
@@ -107,6 +108,15 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <repla
      </para>
     </listitem>
    </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">newowner</replaceable></term>
+    <listitem>
+     <para>
+      The new owner of the database.
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
  </refsect1>
 
@@ -114,9 +124,10 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <repla
   <title>Notes</title>
 
   <para>
-   Using <xref linkend="sql-alteruser" endterm="sql-alteruser-title">,
-   it is also possible to tie a session default to a specific user
-   rather than a database.  User-specific settings override database-specific
+   It is also possible to tie a session default to a specific user
+   rather than to a database; see
+   <xref linkend="sql-alteruser" endterm="sql-alteruser-title">.
+   User-specific settings override database-specific
    ones if there is a conflict.
   </para>
  </refsect1>
@@ -147,7 +158,6 @@ ALTER DATABASE test SET enable_indexscan TO off;
   <title>See Also</title>
 
   <simplelist type="inline">
-   <member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
    <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
    <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member>
    <member><xref linkend="sql-set" endterm="sql-set-title"></member>

doc/src/sgml/ref/alter_group.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.14 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.15 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -31,11 +31,12 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
   <title>Description</title>
 
   <para>
-   <command>ALTER GROUP</command> is used to change a user group.  The
-   first two variants add or remove users from a group. Only database
-   superusers can use this command.  Adding a user to a group does not
-   create the user. Similarly, removing a user from a group does not
-   drop the user itself.
+   <command>ALTER GROUP</command> changes the attributes of a user group.
+  </para>
+
+  <para>
+   The first two variants add users to a group or remove them from a group.
+   Only database superusers can use this command.
   </para>
 
   <para>
@@ -61,8 +62,9 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
     <term><replaceable class="PARAMETER">username</replaceable></term>
     <listitem>
      <para>
-      Users which are to be added or removed from the group. The users
-      must exist.
+      Users that are to be added to or removed from the group. The users
+      must already exist; <command>ALTER GROUP</> does not create or
+      drop users.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/alter_table.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.74 2004/10/22 17:20:04 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.75 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -129,7 +129,8 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <xref linkend="sql-analyze" endterm="sql-analyze-title"> operations.
       The target can be set in the range 0 to 1000; alternatively, set it
       to -1 to revert to using the system default statistics
-      target. For more information on the use of statistics by the
+      target (<xref linkend="guc-default-statistics-target">).
+      For more information on the use of statistics by the
       <productname>PostgreSQL</productname> query planner, refer to
       <xref linkend="planner-stats">.
      </para>
@@ -153,9 +154,9 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       compressible data. <literal>EXTERNAL</literal> is for external,
       uncompressed data, and <literal>EXTENDED</literal> is for external,
       compressed data.  <literal>EXTENDED</literal> is the default for all
-      data types that support it.  The use of <literal>EXTERNAL</literal> will, for example,
-      make substring operations on a <type>text</type> column faster, at the penalty of
-      increased storage space.
+      data types that support it.  Use of <literal>EXTERNAL</literal> will
+      make substring operations on <type>text</type> and <type>bytea</type>
+      columns faster, at the penalty of increased storage space.
      </para>
     </listitem>
    </varlistentry>
@@ -285,15 +286,15 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">name</replaceable></term>
       <listitem>
        <para>
-	The name (possibly schema-qualified) of an existing table to
-	alter. If <literal>ONLY</> is specified, only that table is
-	altered. If <literal>ONLY</> is not specified, the table and all
-	its descendant tables (if any) are updated. <literal>*</> can be
-	appended to the table name to indicate that descendant tables are
-	to be altered, but in the current version, this is the default
-	behavior.  (In releases before 7.1, <literal>ONLY</> was the
-	default behavior.  The default can be altered by changing the
-	configuration parameter <xref linkend="guc-sql-inheritance">.)
+        The name (possibly schema-qualified) of an existing table to
+        alter. If <literal>ONLY</> is specified, only that table is
+        altered. If <literal>ONLY</> is not specified, the table and all
+        its descendant tables (if any) are updated. <literal>*</> can be
+        appended to the table name to indicate that descendant tables are
+        to be altered, but in the current version, this is the default
+        behavior.  (In releases before 7.1, <literal>ONLY</> was the
+        default behavior.  The default can be altered by changing the
+        configuration parameter <xref linkend="guc-sql-inheritance">.)
        </para>
       </listitem>
      </varlistentry>
@@ -302,7 +303,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">column</replaceable></term>
       <listitem>
        <para>
-	Name of a new or existing column.
+        Name of a new or existing column.
        </para>
       </listitem>
      </varlistentry>
@@ -311,7 +312,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">new_column</replaceable></term>
       <listitem>
        <para>
-	New name for an existing column.
+        New name for an existing column.
        </para>
       </listitem>
      </varlistentry>
@@ -320,7 +321,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">new_name</replaceable></term>
       <listitem>
        <para>
-	New name for the table.
+        New name for the table.
        </para>
       </listitem>
      </varlistentry>
@@ -329,8 +330,8 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">type</replaceable></term>
       <listitem>
        <para>
-	Data type of the new column, or new data type for an existing
-	column.
+        Data type of the new column, or new data type for an existing
+        column.
        </para>
       </listitem>
      </varlistentry>
@@ -339,7 +340,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">table_constraint</replaceable></term>
       <listitem>
        <para>
-	New table constraint for the table.
+        New table constraint for the table.
        </para>
       </listitem>
      </varlistentry>
@@ -348,7 +349,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
       <listitem>
        <para>
-	Name of an existing constraint to drop.
+        Name of an existing constraint to drop.
        </para>
       </listitem>
      </varlistentry>
@@ -358,7 +359,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <listitem>
        <para>
         Automatically drop objects that depend on the dropped column
-	or constraint (for example, views referencing the column).
+        or constraint (for example, views referencing the column).
        </para>
       </listitem>
      </varlistentry>
@@ -368,7 +369,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <listitem>
        <para>
         Refuse to drop the column or constraint if there are any dependent
-	objects. This is the default behavior.
+        objects. This is the default behavior.
        </para>
       </listitem>
      </varlistentry>
@@ -377,7 +378,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">index_name</replaceable></term>
       <listitem>
        <para>
-	The index name on which the table should be marked for clustering.
+        The index name on which the table should be marked for clustering.
        </para>
       </listitem>
      </varlistentry>
@@ -386,7 +387,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">new_owner</replaceable></term>
       <listitem>
        <para>
-	The user name of the new owner of the table.
+        The user name of the new owner of the table.
        </para>
       </listitem>
      </varlistentry>
@@ -395,7 +396,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
       <term><replaceable class="PARAMETER">tablespace_name</replaceable></term>
       <listitem>
        <para>
-	The tablespace name to which the table will be moved.
+        The tablespace name to which the table will be moved.
        </para>
       </listitem>
      </varlistentry>
@@ -472,7 +473,8 @@ ALTER TABLE table ALTER COLUMN anycol TYPE anytype;
     though a <literal>USING</literal> clause is supplied.  In such cases,
     drop the default with <literal>DROP DEFAULT</>, perform the <literal>ALTER
     TYPE</>, and then use <literal>SET DEFAULT</> to add a suitable new
-    default.
+    default.  Similar considerations apply to indexes and constraints involving
+    the column.
    </para>
 
    <para>
@@ -593,7 +595,7 @@ ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
   </para>
 
   <para> 
-	To move a table to a different tablespace:
+        To move a table to a different tablespace:
 <programlisting>
 ALTER TABLE distributors SET TABLESPACE fasttablespace;
 </programlisting>

doc/src/sgml/ref/alter_user.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.34 2004/12/13 18:05:10 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -24,9 +24,9 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replace
 
 where <replaceable class="PARAMETER">option</replaceable> can be:
 
-    [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' 
-    | CREATEDB | NOCREATEDB
+    CREATEDB | NOCREATEDB
     | CREATEUSER | NOCREATEUSER 
+    | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' 
     | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
 
 ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
@@ -40,22 +40,21 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
   <title>Description</title>
 
   <para>
-   <command>ALTER USER</command> is used to change the attributes of a
+   <command>ALTER USER</command> changes the attributes of a
    <productname>PostgreSQL</productname> user account.  Attributes not
    mentioned in the command retain their previous settings.
   </para>
 
   <para>
-   The first variant of this command in the synopsis changes certain
-   global user privileges and authentication settings.  (See below for
-   details.)  Only a database superuser can change these privileges and
-   the password expiration with this command.  Ordinary users can only
-   change their own password.
+   The first variant of this command listed in the synopsis changes certain
+   per-user privileges and authentication settings.  (See below for
+   details.)  Database superusers can change any of these settings for any
+   user.  Ordinary users can only change their own password.
   </para>
 
   <para>
    The second variant changes the name of the user.  Only a database
-   superuser can rename user accounts.  The session user cannot be
+   superuser can rename user accounts.  The current session user cannot be
    renamed.  (Connect as a different user if you need to do that.)
    Because <literal>MD5</>-encrypted passwords use the user name as
    cryptographic salt, renaming a user clears their <literal>MD5</>
@@ -70,6 +69,8 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
    or has been received from the <command>postmaster</command> command line.
    Ordinary users can change their own session defaults.
    Superusers can change anyone's session defaults.
+   Certain variables cannot be set this way, or can only be
+   set by a superuser.
   </para>
  </refsect1>
 
@@ -81,55 +82,56 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
       <term><replaceable class="PARAMETER">name</replaceable></term>
       <listitem>
        <para>
-	The name of the user whose attributes are to be altered.
+        The name of the user whose attributes are to be altered.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">password</replaceable></term>
+      <term><literal>CREATEDB</literal></term>
+      <term><literal>NOCREATEDB</literal></term>
       <listitem>
        <para>
-	The new password to be used for this account.
+        These clauses define a user's ability to create databases.  If
+        <literal>CREATEDB</literal> is specified, the user
+        will be allowed to create his own databases. Using
+        <literal>NOCREATEDB</literal> will deny a user the ability to
+        create databases.  (If the user is also a superuser, then this
+        setting has no real effect.)
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>ENCRYPTED</literal></term>
-      <term><literal>UNENCRYPTED</literal></term>
+      <term><literal>CREATEUSER</literal></term>
+      <term><literal>NOCREATEUSER</literal></term>
       <listitem>
        <para>
-	These key words control whether the password is stored
-	encrypted in <literal>pg_shadow</>.  (See
-	<xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
-	for more information about this choice.)
+        These clauses determine whether a user will be permitted to
+        create new users himself. <literal>CREATEUSER</literal> will also make
+        the user a superuser, who can override all access restrictions.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>CREATEDB</literal></term>
-      <term><literal>NOCREATEDB</literal></term>
+      <term><replaceable class="PARAMETER">password</replaceable></term>
       <listitem>
        <para>
-	These clauses define a user's ability to create databases.  If
-	<literal>CREATEDB</literal> is specified, the user
-	will be allowed to create his own databases. Using
-	<literal>NOCREATEDB</literal> will deny a user the ability to
-	create databases.
+        The new password to be used for this account.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>CREATEUSER</literal></term>
-      <term><literal>NOCREATEUSER</literal></term>
+      <term><literal>ENCRYPTED</literal></term>
+      <term><literal>UNENCRYPTED</literal></term>
       <listitem>
        <para>
-	These clauses determine whether a user will be permitted to
-	create new users himself. This option will also make the user
-	a superuser who can override all access restrictions.
+        These key words control whether the password is stored
+        encrypted in <literal>pg_shadow</>.  (See
+        <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
+        for more information about this choice.)
        </para>
       </listitem>
      </varlistentry>
@@ -138,9 +140,9 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
       <term><replaceable class="PARAMETER">abstime</replaceable></term>
       <listitem>
        <para>
-	The date (and, optionally, the time)
-	at which this user's password is to expire.  To set the password
-	never to expire, use <literal>'infinity'</>.
+        The date (and, optionally, the time)
+        at which this user's password is to expire.  To set the password
+        never to expire, use <literal>'infinity'</>.
        </para>
       </listitem>
      </varlistentry>
@@ -149,7 +151,7 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
       <term><replaceable>newname</replaceable></term>
       <listitem>
        <para>
-	The new name of the user.
+        The new name of the user.
        </para>
       </listitem>
      </varlistentry>
@@ -163,9 +165,9 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
         parameter to the given value.  If
         <replaceable>value</replaceable> is <literal>DEFAULT</literal>
         or, equivalently, <literal>RESET</literal> is used, the
-        user-specific variable setting is removed and the user will
+        user-specific variable setting is removed, so the user will
         inherit the system-wide default setting in new sessions.  Use
-        <literal>RESET ALL</literal> to clear all settings.
+        <literal>RESET ALL</literal> to clear all user-specific settings.
        </para>
 
        <para>
@@ -194,9 +196,18 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
   </para>
 
   <para>
-   Using <xref linkend="sql-alterdatabase"
-   endterm="sql-alterdatabase-title">, it is also possible to tie a
-   session default to a specific database rather than a user.
+   The <literal>VALID UNTIL</> clause defines an expiration time for a
+   password only, not for the user account <foreignphrase>per se</>.  In
+   particular, the expiration time is not enforced when logging in using
+   a non-password-based authentication method.
+  </para>
+
+  <para>
+   It is also possible to tie a
+   session default to a specific database rather than to a user; see
+   <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">.
+   User-specific settings override database-specific
+   ones if there is a conflict.
   </para>
  </refsect1>
 
@@ -204,7 +215,7 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
   <title>Examples</title>
 
   <para>
-   Change a user password:
+   Change a user's password:
 
 <programlisting>
 ALTER USER davide WITH PASSWORD 'hu8jmn3';
@@ -212,7 +223,7 @@ ALTER USER davide WITH PASSWORD 'hu8jmn3';
   </para>
 
   <para>
-   Change a user's valid until date:
+   Change the expiration date of the user's password:
 
 <programlisting>
 ALTER USER manuel VALID UNTIL 'Jan 31 2030';
@@ -220,8 +231,8 @@ ALTER USER manuel VALID UNTIL 'Jan 31 2030';
   </para>
 
   <para>
-   Change a user's valid until date, specifying that his
-   authorization should expire at midday on 4th May 2005 using
+   Change a password expiration date, specifying that the password
+   should expire at midday on 4th May 2005 using
    the time zone which is one hour ahead of <acronym>UTC</>:
 <programlisting>
 ALTER USER chris VALID UNTIL 'May 4 12:00:00 2005 +1';
@@ -229,7 +240,7 @@ ALTER USER chris VALID UNTIL 'May 4 12:00:00 2005 +1';
   </para>
 
   <para>
-   Make a user valid forever:
+   Make a password valid forever:
 <programlisting>
 ALTER USER fred VALID UNTIL 'infinity';
 </programlisting>

doc/src/sgml/ref/checkpoint.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/checkpoint.sgml,v 1.12 2004/03/09 16:57:47 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/checkpoint.sgml,v 1.13 2005/01/04 00:39:53 tgl Exp $ -->
 
 <refentry id="sql-checkpoint">
  <refmeta>
@@ -37,7 +37,7 @@ CHECKPOINT
   <para>
    A checkpoint is a point in the transaction log sequence at which
    all data files have been updated to reflect the information in the
-   log.  All data files will be flushed to disk.  Refer to the
+   log.  All data files will be flushed to disk.  Refer to
    <xref linkend="wal"> for more information about the WAL system.
   </para>
 

doc/src/sgml/ref/close.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.21 2004/06/17 12:41:02 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.22 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -72,7 +72,8 @@ CLOSE <replaceable class="PARAMETER">name</replaceable>
   <para>
    <productname>PostgreSQL</productname> does not have an explicit
    <command>OPEN</command> cursor statement; a cursor is considered
-   open when it is declared.  Use the <command>DECLARE</command>
+   open when it is declared.  Use the
+   <xref linkend="sql-declare" endterm="sql-declare-title">
    statement to declare a cursor.
   </para>
  </refsect1>
@@ -95,6 +96,16 @@ CLOSE liahona;
    <command>CLOSE</command> is fully conforming with the SQL standard.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-declare" endterm="sql-declare-title"></member>
+   <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
+   <member><xref linkend="sql-move" endterm="sql-move-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/cluster.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.34 2004/11/15 06:32:15 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -184,7 +184,7 @@ CLUSTER emp;
   </para>
 
   <para>
-   Cluster all the tables on the database that have previously been clustered:
+   Cluster all tables in the database that have previously been clustered:
 <programlisting>
 CLUSTER;
 </programlisting>

doc/src/sgml/ref/comment.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.25 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.26 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -51,12 +51,6 @@ COMMENT ON
 
   <para>
    <command>COMMENT</command> stores a comment about a database object.
-    Comments can be
-    easily retrieved with the <application>psql</application> commands
-    <command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
-    Other user interfaces to retrieve comments can be built atop
-    the same built-in functions that <application>psql</application> uses, namely
-    <function>obj_description</> and <function>col_description</>.
   </para>
 
   <para>
@@ -66,6 +60,16 @@ COMMENT ON
     string.
     Comments are automatically dropped when the object is dropped.
   </para>
+
+  <para>
+    Comments can be
+    easily retrieved with the <application>psql</application> commands
+    <command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
+    Other user interfaces to retrieve comments can be built atop
+    the same built-in functions that <application>psql</application> uses, namely
+    <function>obj_description</> and <function>col_description</>
+    (see <xref linkend="functions-info-comment-table">).
+  </para>
  </refsect1>
 
  <refsect1>
@@ -141,7 +145,8 @@ COMMENT ON
     <term><replaceable class="parameter">text</replaceable></term>
     <listitem>
      <para>
-      The new comment.
+      The new comment, written as a string literal; or <literal>NULL</>
+      to drop the comment.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/copy.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/copy.sgml,v 1.62 2004/12/13 18:05:10 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/copy.sgml,v 1.63 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -131,8 +131,8 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
     <listitem>
      <para>
       Causes all data to be stored or read in binary format rather
-      than as text. You cannot specify the <option>DELIMITER</option>
-      or <option>NULL</option> options in binary mode.
+      than as text. You cannot specify the <option>DELIMITER</option>,
+      <option>NULL</option>, or <option>CSV</> options in binary mode.
      </para>
     </listitem>
    </varlistentry>
@@ -186,10 +186,7 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
     <term><literal>CSV</literal></term>
     <listitem>
      <para>
-      Enables Comma Separated Variable (<literal>CSV</>) mode. (Also
-      called Comma Separated Value). It sets the default
-      <literal>DELIMITER</> to comma, and <literal>QUOTE</> and
-      <literal>ESCAPE</> values to double-quote.
+      Selects Comma Separated Value (<literal>CSV</>) mode.
      </para>
     </listitem>
    </varlistentry>
@@ -232,9 +229,9 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
      <para>
       In <literal>CSV</> <command>COPY FROM</> mode, process each
       specified column as though it were quoted and hence not a
-      <literal>NULL</> value. For the default <literal>null string</> in
-      <literal>CSV</> mode (<literal>''</>), this causes a missing
-      values to be input as a zero-length strings.
+      <literal>NULL</> value. For the default null string in
+      <literal>CSV</> mode (<literal>''</>), this causes missing
+      values to be input as zero-length strings.
      </para>
     </listitem>
    </varlistentry>
@@ -304,13 +301,11 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
 
    <para>
     <command>COPY</command> input and output is affected by
-    <varname>DateStyle </varname>. For portability with other
-    <productname>PostgreSQL</productname> installations which might use
+    <varname>DateStyle</varname>. To ensure portability to other
+    <productname>PostgreSQL</productname> installations that might use
     non-default <varname>DateStyle</varname> settings,
     <varname>DateStyle</varname> should be set to <literal>ISO</> before
-    using <command>COPY</>. In <literal>CSV</> mode, use <literal>ISO</>
-    or a <varname>DateStyle</varname> setting appropriate for the
-    external application.
+    using <command>COPY TO</>.
    </para>
 
    <para>
@@ -332,9 +327,9 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
    <title>Text Format</title>
 
    <para>
-    When <command>COPY</command> is used without the <literal>BINARY</literal> option,
-    the data read or written is a text file with one line per table row,
-    unless <literal>CSV</> mode is used.
+    When <command>COPY</command> is used without the <literal>BINARY</literal>
+    or <literal>CSV</> options,
+    the data read or written is a text file with one line per table row.
     Columns in a row are separated by the delimiter character.
     The column values themselves are strings generated by the
     output function, or acceptable to the input function, of each
@@ -465,7 +460,7 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
 
    <para>
     This format is used for importing and exporting the Comma
-    Separated Variable (<literal>CSV</>) file format used by many other
+    Separated Value (<literal>CSV</>) file format used by many other
     programs, such as spreadsheets. Instead of the escaping used by
     <productname>PostgreSQL</productname>'s standard text mode, it
     produces and recognises the common CSV escaping mechanism.
@@ -484,7 +479,7 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
    </para>
 
    <para> 
-    In general, the <literal>CSV</> format has no way to distinguish a
+    The <literal>CSV</> format has no standard way to distinguish a
     <literal>NULL</> value from an empty string.
     <productname>PostgreSQL</>'s <command>COPY</> handles this by
     quoting. A <literal>NULL</> is output as the <literal>NULL</>
@@ -517,7 +512,7 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
      so the file format is more a convention than a standard. Thus you
      might encounter some files that cannot be imported using this
      mechanism, and <command>COPY</> might produce files that other
-     programs can not process.
+     programs cannot process.
     </para>
    </note>
     

doc/src/sgml/ref/create_aggregate.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.30 2004/04/21 21:52:41 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.31 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -233,7 +233,7 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
   <para>
    <command>CREATE AGGREGATE</command> is a
    <productname>PostgreSQL</productname> language extension.  The SQL
-   standard does not provide for user-defined aggregate function.
+   standard does not provide for user-defined aggregate functions.
   </para>
  </refsect1>
 

doc/src/sgml/ref/create_domain.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.19 2004/08/08 02:05:32 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.20 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -63,7 +63,7 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
       <term><replaceable class="parameter">name</replaceable></term>
       <listitem>
        <para>
-	The name (optionally schema-qualified) of a domain to be created.
+        The name (optionally schema-qualified) of a domain to be created.
        </para>
       </listitem>
      </varlistentry>
@@ -73,7 +73,7 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
       <listitem>
        <para>
         The underlying data type of the domain. This may include array
-	specifiers.
+        specifiers.
        </para>
       </listitem>
      </varlistentry>
@@ -196,6 +196,7 @@ CREATE TABLE us_snail_addy (
   <title>See Also</title>
 
   <simplelist type="inline">
+   <member><xref linkend="sql-alterdomain" endterm="sql-alterdomain-title"></member>
    <member><xref linkend="sql-dropdomain" endterm="sql-dropdomain-title"></member>
   </simplelist>
  </refsect1>

doc/src/sgml/ref/create_function.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.63 2004/11/27 21:27:07 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.64 2005/01/04 00:39:53 tgl Exp $
 -->
 
 <refentry id="SQL-CREATEFUNCTION">
@@ -62,8 +62,8 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
 
   <para>
    If you drop and then recreate a function, the new function is not
-   the same entity as the old; you will break existing rules, views,
-   triggers, etc. that referred to the old function.  Use
+   the same entity as the old; you will have to drop existing rules, views,
+   triggers, etc. that refer to the old function.  Use
    <command>CREATE OR REPLACE FUNCTION</command> to change a function
    definition without breaking objects that refer to the function.
   </para>
@@ -106,16 +106,8 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
      <listitem>
       <para>
        The data type(s) of the function's arguments (optionally 
-       schema-qualified), if any. The argument types may be base, complex, or 
-       domains, or copy the type of an existing column.
-      </para>
-      <para>
-       The type of a column is referenced by writing
-       <literal><replaceable
-       class="parameter">tablename</replaceable>.<replaceable
-       class="parameter">columnname</replaceable>%TYPE</literal>;
-       using this can sometimes help make a function independent from
-       changes to the definition of a table.
+       schema-qualified), if any. The argument types may be base, composite,
+       or domain types, or may reference the type of a table column.
       </para>
       <para>
        Depending on the implementation language it may also be allowed
@@ -123,6 +115,14 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
        Pseudotypes indicate that the actual argument type is either
        incompletely specified, or outside the set of ordinary SQL data types.
       </para>
+      <para>
+       The type of a column is referenced by writing
+       <literal><replaceable
+       class="parameter">tablename</replaceable>.<replaceable
+       class="parameter">columnname</replaceable>%TYPE</literal>.
+       Using this feature can sometimes help make a function independent of
+       changes to the definition of a table.
+      </para>
      </listitem>
     </varlistentry>
 
@@ -132,18 +132,22 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
      <listitem>
       <para>
        The return data type (optionally schema-qualified). The return type 
-       may be a base type, complex type, or a domain,
-       or may be specified to copy the type of an existing column. See the description
-       under <literal>argtype</literal> above on how to reference the type
-       of an existing column.
-      </para>
-      <para>
+       may be a base, composite, or domain type,
+       or may reference the type of a table column.
        Depending on the implementation language it may also be allowed
        to specify <quote>pseudotypes</> such as <type>cstring</>.
+      </para>
+      <para>
        The <literal>SETOF</literal>
        modifier indicates that the function will return a set of
        items, rather than a single item.
       </para>
+      <para>
+       The type of a column is referenced by writing
+       <literal><replaceable
+       class="parameter">tablename</replaceable>.<replaceable
+       class="parameter">columnname</replaceable>%TYPE</literal>.
+      </para>
      </listitem>
     </varlistentry>
 
@@ -155,8 +159,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
        The name of the language that the function is implemented in.
        May be <literal>SQL</literal>, <literal>C</literal>,
        <literal>internal</literal>, or the name of a user-defined
-       procedural language.  (See also <xref linkend="app-createlang"
-       endterm="app-createlang-title">.)  For backward compatibility,
+       procedural language.  For backward compatibility,
        the name may be enclosed by single quotes.
       </para>
      </listitem>
@@ -303,7 +306,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
         <term><literal>isStrict</></term>
         <listitem>
          <para>
-          Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>
+          Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>.
          </para>
         </listitem>
        </varlistentry>
@@ -394,7 +397,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
    information and examples, see <xref linkend="xfunc">.
 <programlisting>
 CREATE FUNCTION add(integer, integer) RETURNS integer
-    AS $$select $1 + $2;$$
+    AS 'select $1 + $2;'
     LANGUAGE SQL
     IMMUTABLE
     RETURNS NULL ON NULL INPUT;
@@ -406,10 +409,11 @@ CREATE FUNCTION add(integer, integer) RETURNS integer
    <application>PL/pgSQL</application>:
 
 <programlisting>
-CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS '
+CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
         BEGIN
                 RETURN i + 1;
-        END;' LANGUAGE plpgsql;
+        END;
+$$ LANGUAGE plpgsql;
 </programlisting>
   </para>
  </refsect1>
@@ -427,17 +431,17 @@ CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS '
  </refsect1>
 
 
- <refsect1 id="sql-createfunction-seealso">
+ <refsect1>
   <title>See Also</title>
 
-  <para>
-   <xref linkend="sql-alterfunction" endterm="sql-alterfunction-title">,
-   <xref linkend="sql-dropfunction" endterm="sql-dropfunction-title">,
-   <xref linkend="sql-grant" endterm="sql-grant-title">,
-   <xref linkend="sql-load" endterm="sql-load-title">,
-   <xref linkend="sql-revoke" endterm="sql-revoke-title">,
-   <xref linkend="app-createlang">
-  </para>
+  <simplelist type="inline">
+   <member><xref linkend="sql-alterfunction" endterm="sql-alterfunction-title"></member>
+   <member><xref linkend="sql-dropfunction" endterm="sql-dropfunction-title"></member>
+   <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
+   <member><xref linkend="sql-load" endterm="sql-load-title"></member>
+   <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
+   <member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
+  </simplelist>
  </refsect1>
 
 </refentry>

doc/src/sgml/ref/create_group.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_group.sgml,v 1.14 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_group.sgml,v 1.15 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -33,9 +33,13 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
   <title>Description</title>
 
   <para>
-   <command>CREATE GROUP</command> will create a new group in the
-   database cluster.  You must be a database
-   superuser to use this command.
+   <command>CREATE GROUP</command> will create a new group of users.
+   You must be a database superuser to use this command.
+  </para>
+
+  <para>
+   Note that both users and groups are defined at the database cluster
+   level, and so are valid in all databases in the cluster.
   </para>
 
   <para>
@@ -53,7 +57,7 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
       <term><replaceable class="parameter">name</replaceable></term>
       <listitem>
        <para>
-	The name of the group.
+        The name of the group.
        </para>
       </listitem>
      </varlistentry>
@@ -64,11 +68,14 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
        <para>
         The <literal>SYSID</literal> clause can be used to choose
         the <productname>PostgreSQL</productname> group ID of the new
-        group. It is not necessary to do so, however.
+        group.
+        This is normally not necessary, but may
+        be useful if you need to recreate a group referenced in the
+        permissions of some object.
        </para>
        <para>
-        If this is not specified, the highest assigned group ID plus one,
-        starting at 1, will be used as default.
+        If this is not specified, the highest assigned group ID plus one
+        (with a minimum of 100) will be used as default.
        </para>
       </listitem>
      </varlistentry>
@@ -111,6 +118,15 @@ CREATE GROUP marketing WITH USER jonathan, david;
    standard.  Roles are similar in concept to groups.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-altergroup" endterm="sql-altergroup-title"></member>
+   <member><xref linkend="sql-dropgroup" endterm="sql-dropgroup-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/create_index.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.50 2004/11/05 19:15:51 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.51 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -74,13 +74,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <re
     can improve performance by creating an index on just that portion.
     Another possible application is to use <literal>WHERE</literal> with
     <literal>UNIQUE</literal> to enforce uniqueness over a subset of a
-    table.
-  </para>
-
-  <para>
-   Indexes are not used for <literal>IS NULL</> clauses by default.
-   The best way to use indexes in such cases is to create a partial index
-   using an <literal>IS NULL</> comparison.
+    table.  See <xref linkend="indexes-partial"> for more discussion.
   </para>
 
   <para>
@@ -211,7 +205,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <re
   <para>
    See <xref linkend="indexes"> for information about when indexes can
    be used, when they are not used, and in which particular situations
-   can be useful.
+   they can be useful.
   </para>
 
   <para>
@@ -243,6 +237,12 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <re
    Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
    to remove an index.
   </para>
+
+  <para>
+   Indexes are not used for <literal>IS NULL</> clauses by default.
+   The best way to use indexes in such cases is to create a partial index
+   using an <literal>IS NULL</> predicate.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -293,6 +293,15 @@ SELECT * FROM points
    are no provisions for indexes in the SQL standard.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-alterindex" endterm="sql-alterindex-title"></member>
+   <member><xref linkend="sql-dropindex" endterm="sql-dropindex-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/create_language.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.38 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.39 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -41,7 +41,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
   <para>
    <command>CREATE LANGUAGE</command> effectively associates the
    language name with a call handler that is responsible for executing
-   functions written in the language.  Refer to <xref linkend="xfunc">
+   functions written in the language.  Refer to <xref linkend="xplang">
    for more information about language call handlers.
   </para>
 
@@ -186,11 +186,6 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
    has an option to list the installed languages.
   </para>
 
-  <para>
-   The definition of a procedural language cannot be changed once it
-   has been created, with the exception of the privileges.
-  </para>
-
   <para>
    To be able to use a procedural language, a user must be granted the
    <literal>USAGE</literal> privilege.  The
@@ -233,8 +228,8 @@ CREATE LANGUAGE plsample
    <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
    <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
    <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
-   <member><xref linkend="app-createlang"></member>
-   <member><xref linkend="app-droplang"></member>
+   <member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
+   <member><xref linkend="app-droplang" endterm="app-droplang-title"></member>
   </simplelist>
  </refsect1>
 </refentry>

doc/src/sgml/ref/create_operator.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.43 2004/09/20 00:04:19 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.44 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -97,7 +97,7 @@ CREATE OPERATOR <replaceable>name</replaceable> (
 
   <para>
    The other clauses specify optional operator optimization clauses.
-   Their meaning is detailed in <xref linkend="xoper">.
+   Their meaning is detailed in <xref linkend="xoper-optimization">.
   </para>
  </refsect1>
 
@@ -304,6 +304,16 @@ CREATE OPERATOR === (
    provisions for user-defined operators in the SQL standard.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-alteroperator" endterm="sql-alteroperator-title"></member>
+   <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member>
+   <member><xref linkend="sql-dropoperator" endterm="sql-dropoperator-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/create_rule.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.44 2004/03/09 19:30:21 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.45 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -82,10 +82,10 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS
    attempts to perform the update action, because it thinks it might
    end up trying to perform the action on the dummy table of the view
    in some cases.  If you want to handle all the useful cases in
-   conditional rules, you can; just add an unconditional <literal>DO
+   conditional rules, add an unconditional <literal>DO
    INSTEAD NOTHING</literal> rule to ensure that the system
    understands it will never be called on to update the dummy table.
-   Then make the conditional rules not <literal>INSTEAD</literal>; in
+   Then make the conditional rules non-<literal>INSTEAD</literal>; in
    the cases where they are applied, they add to the default
    <literal>INSTEAD NOTHING</literal> action.
   </para>
@@ -213,12 +213,12 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS
 CREATE RULE "_RETURN" AS
     ON SELECT TO t1
     DO INSTEAD 
-	SELECT * FROM t2;
+        SELECT * FROM t2;
 
 CREATE RULE "_RETURN" AS
     ON SELECT TO t2
     DO INSTEAD 
-	SELECT * FROM t1;
+        SELECT * FROM t1;
 
 SELECT * FROM t1;
 </programlisting>

doc/src/sgml/ref/create_schema.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.16 2004/11/05 19:15:51 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.17 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -29,7 +29,7 @@ CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable
   <title>Description</title>
 
   <para>
-   <command>CREATE SCHEMA</command> will enter a new schema
+   <command>CREATE SCHEMA</command> enters a new schema
    into the current database.
    The schema name must be distinct from the name of any existing schema
    in the current database.
@@ -41,8 +41,9 @@ CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable
    whose names may duplicate those of other objects existing in other
    schemas.  Named objects are accessed either by <quote>qualifying</>
    their names with the schema name as a prefix, or by setting a search
-   path that includes the desired schema(s).  Unqualified objects are
-   created in the current schema (the one at the front of the search path,
+   path that includes the desired schema(s).  A <literal>CREATE</> command
+   specifying an unqualified object name creates the object
+   in the current schema (the one at the front of the search path,
    which can be determined with the function <function>current_schema</function>).
   </para>
 

doc/src/sgml/ref/create_table.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.88 2004/12/13 18:05:10 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.89 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -82,12 +82,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
   </para>
 
   <para>
-   A table cannot have more than 1600 columns.  (In practice, the
-   effective limit is lower because of tuple-length constraints).
-  </para>
-
-  <para>
-   The optional constraint clauses specify constraints (or tests) that
+   The optional constraint clauses specify constraints (tests) that
    new or updated rows must satisfy for an insert or update operation
    to succeed.  A constraint is an SQL object that helps define the
    set of valid values in the table in various ways.
@@ -99,7 +94,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
    column definition.  A table constraint definition is not tied to a
    particular column, and it can encompass more than one column.
    Every column constraint can also be written as a table constraint;
-   a column constraint is only a notational convenience if the
+   a column constraint is only a notational convenience for use when the
    constraint only affects one column.
   </para>
  </refsect1>
@@ -156,7 +151,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
     <listitem>
      <para>
       The data type of the column. This may include array
-      specifiers. For more information on the data types included with
+      specifiers. For more information on the data types supported by
       <productname>PostgreSQL</productname>, refer to <xref
       linkend="datatype">.
      </para>
@@ -184,29 +179,6 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
     </listitem>
    </varlistentry>
 
-   <varlistentry>
-    <term><literal>LIKE <replaceable>parent_table</replaceable> [ { INCLUDING | EXCLUDING } DEFAULTS ]</literal></term>
-    <listitem>
-     <para>
-      The <literal>LIKE</literal> clause specifies a table from which
-      the new table automatically copies all column names, their data types,
-      and their not-null constraints.
-     </para>
-     <para>
-      Unlike <literal>INHERITS</literal>, the new table and original table
-      are completely decoupled after creation is complete.  Changes to the
-      original table will not be applied to the new table, and it is not
-      possible to include data of the new table in scans of the original
-      table.
-     </para>
-     <para>
-      Default expressions for the copied column definitions will only be
-      included if <literal>INCLUDING DEFAULTS</literal> is specified.  The
-      default is to exclude default expressions.
-     </para>
-    </listitem>
-   </varlistentry>
-
    <varlistentry>
     <term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term>
     <listitem>
@@ -258,6 +230,30 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><literal>LIKE <replaceable>parent_table</replaceable> [ { INCLUDING | EXCLUDING } DEFAULTS ]</literal></term>
+    <listitem>
+     <para>
+      The <literal>LIKE</literal> clause specifies a table from which
+      the new table automatically copies all column names, their data types,
+      and their not-null constraints.
+     </para>
+     <para>
+      Unlike <literal>INHERITS</literal>, the new table and original table
+      are completely decoupled after creation is complete.  Changes to the
+      original table will not be applied to the new table, and it is not
+      possible to include data of the new table in scans of the original
+      table.
+     </para>
+     <para>
+      Default expressions for the copied column definitions will only be
+      copied if <literal>INCLUDING DEFAULTS</literal> is specified.  The
+      default behavior is to exclude default expressions, resulting in
+      all columns of the new table having null defaults.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><literal>WITH OIDS</></term>
     <term><literal>WITHOUT OIDS</></term>
@@ -274,15 +270,15 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
      </para>
 
      <para>
-      If <literal>WITHOUT OIDS</literal> is specified or implied, this
-      means that the generation of OIDs for this table will be
-      supressed. This is generally considered worthwhile, since it
+      If <literal>WITHOUT OIDS</literal> is specified or implied, the new
+      table does not store OIDs and no OID will be assigned for a row inserted
+      into it. This is generally considered worthwhile, since it
       will reduce OID consumption and thereby postpone the wraparound
       of the 32-bit OID counter. Once the counter wraps around, OIDs
       can no longer be assumed to be unique, which makes them
       considerably less useful. In addition, excluding OIDs from a
-      table reduces the space required on disk to storage the table by
-      4 bytes per row, leading to increased performance.
+      table reduces the space required to store the table on disk by
+      4 bytes per row (on most machines), slightly improving performance.
      </para>
 
      <para>
@@ -319,7 +315,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
      </para>
 
      <para>
-      This clause is only available for compatibility with
+      This clause is only provided for compatibility with
       non-standard SQL databases.  Its use is discouraged in new
       applications.
      </para>
@@ -333,7 +329,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
     <listitem>
      <para>
       The <literal>UNIQUE</literal> constraint specifies that a
-      group of one or more distinct columns of a table may contain
+      group of one or more columns of a table may contain
       only unique values. The behavior of the unique table constraint
       is the same as that for column constraints, with the additional
       capability to span multiple columns.
@@ -450,9 +446,9 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
       clause specifies the action to perform when a referenced column
       in the referenced table is being updated to a new value. If the
       row is updated, but the referenced column is not actually
-      changed, no action is done. Referential actions apart from the
-      check of <literal>NO ACTION</literal> can not be deferred even if
-      the constraint is deferrable. There are the following possible
+      changed, no action is done. Referential actions other than the
+      <literal>NO ACTION</literal> check cannot be deferred, even if
+      the constraint is declared deferrable. There are the following possible
       actions for each clause:
 
       <variablelist>
@@ -476,7 +472,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
           Produce an error indicating that the deletion or update
           would create a foreign key constraint violation.
           This is the same as <literal>NO ACTION</literal> except that
-	  the check is not deferrable.
+          the check is not deferrable.
          </para>
         </listitem>
        </varlistentry>
@@ -633,13 +629,11 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
  <refsect1 id="SQL-CREATETABLE-notes">
   <title>Notes</title>
 
-  <itemizedlist>
-   <listitem>
     <para>
      Using OIDs in new applications is not recommended: where
      possible, using a <literal>SERIAL</literal> or other sequence
      generator as the table's primary key is preferred. However, if
-     your application does make use of OIDs to identify specific rows
+     your application does make use of OIDs to identify specific
      rows of a table, it is recommended to create a unique constraint
      on the <structfield>oid</> column of that table, to ensure that
      OIDs in the table will indeed uniquely identify rows even after
@@ -656,26 +650,26 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
       unique data key, it is difficult to identify specific rows.
      </para>
     </tip>
-   </listitem>
 
-   <listitem>
     <para>
      <productname>PostgreSQL</productname> automatically creates an
      index for each unique constraint and primary key constraint to
-     enforce the uniqueness.  Thus, it is not necessary to create an
-     explicit index for primary key columns.  (See <xref
+     enforce uniqueness.  Thus, it is not necessary to create an
+     index explicitly for primary key columns.  (See <xref
      linkend="sql-createindex" endterm="sql-createindex-title"> for more information.)
     </para>
-   </listitem>
 
-   <listitem>
     <para>
      Unique constraints and primary keys are not inherited in the
      current implementation.  This makes the combination of
      inheritance and unique constraints rather dysfunctional.
     </para>
-   </listitem>
-  </itemizedlist>
+
+  <para>
+   A table cannot have more than 1600 columns.  (In practice, the
+   effective limit is lower because of tuple-length constraints.)
+  </para>
+
  </refsect1>
 
 
@@ -778,7 +772,7 @@ CREATE TABLE films (
    Define a primary key constraint for table
    <structname>distributors</>.  The following two examples are
    equivalent, the first using the table constraint syntax, the second
-   the column constraint notation.
+   the column constraint syntax.
 
 <programlisting>
 CREATE TABLE distributors (

doc/src/sgml/ref/create_table_as.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.26 2004/12/13 18:05:10 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.27 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,8 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
+CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable>
+    [ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
     AS <replaceable>query</replaceable>
 </synopsis>
  </refsynopsisdiv>
@@ -91,9 +92,9 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
      <para>
       The name of a column in the new table.  If column names are not
       provided, they are taken from the output column names of the
-      query.  If the table is created out of an
-      <command>EXECUTE</command> command, a column name list can
-      currently not be specified.
+      query.  If the table is created from an
+      <command>EXECUTE</command> command, a column name list cannot be
+      specified.
      </para>
     </listitem>
    </varlistentry>
@@ -105,7 +106,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
       <para>
        This optional clause specifies whether the table created by
        <command>CREATE TABLE AS</command> should include OIDs. If
-       neither form of this clause if specified, the value of the
+       neither form of this clause is specified, the value of the
        <xref linkend="guc-default-with-oids"> configuration parameter is
        used.
       </para>
@@ -143,12 +144,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
   <para>
    Prior to <productname>PostgreSQL</productname> 8.0, <command>CREATE
    TABLE AS</command> always included OIDs in the table it
-   produced. Furthermore, these OIDs were newly generated: they were
-   distinct from the OIDs of any of the rows in the source tables of
-   the <command>SELECT</command> or <command>EXECUTE</command>
-   statement. Therefore, if <command>CREATE TABLE AS</command> was
-   frequently executed, the OID counter would be rapidly
-   incremented. As of <productname>PostgresSQL</productname> 8.0,
+   produced.  As of <productname>PostgresSQL</productname> 8.0,
    the <command>CREATE TABLE AS</command> command allows the user to
    explicitly specify whether OIDs should be included. If the
    presence of OIDs is not explicitly specified,

doc/src/sgml/ref/create_type.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_type.sgml,v 1.53 2004/11/27 21:27:07 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_type.sgml,v 1.54 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -45,7 +45,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
 
   <para>
    <command>CREATE TYPE</command> registers a new data type for use in
-   the current data base.  The user who defines a type becomes its
+   the current database.  The user who defines a type becomes its
    owner.
   </para>
 
@@ -68,7 +68,8 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
    This is essentially the same as the row type
    of a table, but using <command>CREATE TYPE</command> avoids the need to
    create an actual table when all that is wanted is to define a type.
-   A stand-alone composite type is useful as the return type of a function.
+   A stand-alone composite type is useful as the argument or return type of a
+   function.
   </para>
   </refsect2>
 
@@ -104,7 +105,8 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
    The first argument is the input text as a C string, the second
    argument is the element type's OID in case this is an array type
    (or the type's own OID for a composite type),
-   and the third is the <literal>typmod</> of the destination column, if known.
+   and the third is the <literal>typmod</> of the destination column, if known
+   (-1 will be passed if not).
    The input function should return a value of the data type itself.
    The output function may be
    declared as taking one argument of the new data type,  or as taking
@@ -470,6 +472,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
    a function definition:
 <programlisting>
 CREATE TYPE compfoo AS (f1 int, f2 text);
+
 CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS $$
     SELECT fooid, fooname FROM foo
 $$ LANGUAGE SQL;
@@ -525,7 +528,7 @@ CREATE TABLE big_objs (
 
   <para>
    More examples, including suitable input and output functions, are
-   in <xref linkend="extend">.
+   in <xref linkend="xtypes">.
   </para>
  </refsect1>
 

doc/src/sgml/ref/create_user.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_user.sgml,v 1.33 2004/03/09 16:57:47 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_user.sgml,v 1.34 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -25,10 +25,10 @@ CREATE USER <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replac
 where <replaceable class="PARAMETER">option</replaceable> can be:
     
       SYSID <replaceable class="PARAMETER">uid</replaceable> 
-    | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
     | CREATEDB | NOCREATEDB
     | CREATEUSER | NOCREATEUSER
     | IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
+    | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
     | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>' 
 </synopsis>
  </refsynopsisdiv>
@@ -54,7 +54,7 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
       <term><replaceable class="parameter">name</replaceable></term>
       <listitem>
        <para>
-	The name of the user.
+        The name of the new user.
        </para>
       </listitem>
      </varlistentry>
@@ -64,92 +64,92 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
       <listitem>
        <para>
         The <literal>SYSID</literal> clause can be used to choose the
-        <productname>PostgreSQL</productname> user ID of the user that
-        is being created. This is not normally not necessary, but may
+        <productname>PostgreSQL</productname> user ID of the new user.
+        This is normally not necessary, but may
         be useful if you need to recreate the owner of an orphaned
         object.
        </para>
        <para>
         If this is not specified, the highest assigned user ID plus one
-	(with a minimum of 100) will be used as default.
+        (with a minimum of 100) will be used as default.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="parameter">password</replaceable></term>
+      <term><literal>CREATEDB</></term>
+      <term><literal>NOCREATEDB</></term>
       <listitem>
        <para>
-        Sets the user's password. If you do not plan to use password
-        authentication you can omit this option, but then the user
-        won't be able to connect if you decide to switch to password
-        authentication.  The password can be set or changed later,
-        using <xref linkend="SQL-ALTERUSER"
-        endterm="SQL-ALTERUSER-title">.
+        These clauses define a user's ability to create databases.  If
+        <literal>CREATEDB</literal> is specified, the user being
+        defined will be allowed to create his own databases. Using
+        <literal>NOCREATEDB</literal> will deny a user the ability to
+        create databases. If not specified,
+        <literal>NOCREATEDB</literal> is the default.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>ENCRYPTED</></term>
-      <term><literal>UNENCRYPTED</></term>
+      <term><literal>CREATEUSER</literal></term>
+      <term><literal>NOCREATEUSER</literal></term>
       <listitem>
        <para>
-	These key words control whether the password is stored
-	encrypted in the system catalogs.  (If neither is specified,
-	the default behavior is determined by the configuration
-	parameter <xref linkend="guc-password-encryption">.)  If the
-	presented password string is already in MD5-encrypted format,
-	then it is stored encrypted as-is, regardless of whether
-	<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
-	(since the system cannot decrypt the specified encrypted
-	password string).  This allows reloading of encrypted
-	passwords during dump/restore.
-       </para>
-
-       <para>
-        Note that older clients may lack support for the MD5
-        authentication mechanism that is needed to work with passwords
-        that are stored encrypted.
+        These clauses determine whether a user will be permitted to
+        create new users himself. <literal>CREATEUSER</literal> will also make
+        the user a superuser, who can override all access restrictions.
+        If not specified,
+        <literal>NOCREATEUSER</literal> is the default.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>CREATEDB</></term>
-      <term><literal>NOCREATEDB</></term>
+      <term><replaceable class="parameter">groupname</replaceable></term>
       <listitem>
        <para>
-	These clauses define a user's ability to create databases.  If
-	<literal>CREATEDB</literal> is specified, the user being
-	defined will be allowed to create his own databases. Using
-	<literal>NOCREATEDB</literal> will deny a user the ability to
-	create databases. If this clause is omitted,
-	<literal>NOCREATEDB</literal> is used by default.
+        A name of an existing group into which to insert the user as a new
+        member. Multiple group names may be listed.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><literal>CREATEUSER</literal></term>
-      <term><literal>NOCREATEUSER</literal></term>
+      <term><replaceable class="parameter">password</replaceable></term>
       <listitem>
        <para>
-	These clauses determine whether a user will be permitted to
-	create new users himself. This option will also make the user
-	a superuser who can override all access restrictions.
-	Omitting this clause will set the user's value of this
-	attribute to be <literal>NOCREATEUSER</literal>.
+        Sets the user's password. If you do not plan to use password
+        authentication you can omit this option, but then the user
+        won't be able to connect if you decide to switch to password
+        authentication.  The password can be set or changed later,
+        using <xref linkend="SQL-ALTERUSER"
+        endterm="SQL-ALTERUSER-title">.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="parameter">groupname</replaceable></term>
+      <term><literal>ENCRYPTED</></term>
+      <term><literal>UNENCRYPTED</></term>
       <listitem>
        <para>
-	A name of a group into which to insert the user as a new member.
-	Multiple group names may be listed.
+        These key words control whether the password is stored
+        encrypted in the system catalogs.  (If neither is specified,
+        the default behavior is determined by the configuration
+        parameter <xref linkend="guc-password-encryption">.)  If the
+        presented password string is already in MD5-encrypted format,
+        then it is stored encrypted as-is, regardless of whether
+        <literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
+        (since the system cannot decrypt the specified encrypted
+        password string).  This allows reloading of encrypted
+        passwords during dump/restore.
+       </para>
+
+       <para>
+        Note that older clients may lack support for the MD5
+        authentication mechanism that is needed to work with passwords
+        that are stored encrypted.
        </para>
       </listitem>
      </varlistentry>
@@ -158,9 +158,9 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
       <term><replaceable class="parameter">abstime</replaceable></term>
       <listitem>
        <para>
-	The <literal>VALID UNTIL</literal> clause sets an absolute
-	time after which the user's password is no longer valid.  If
-	this clause is omitted the login will be valid for all time.
+        The <literal>VALID UNTIL</literal> clause sets an absolute
+        time after which the user's password is no longer valid.  If
+        this clause is omitted the password will be valid for all time.
        </para>
       </listitem>
      </varlistentry>
@@ -184,6 +184,13 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
    the same functionality as <command>CREATE USER</command> (in fact, it calls this
    command) but can be run from the command shell.
   </para>
+
+  <para>
+   The <literal>VALID UNTIL</> clause defines an expiration time for a
+   password only, not for the user account <foreignphrase>per se</>.  In
+   particular, the expiration time is not enforced when logging in using
+   a non-password-based authentication method.
+  </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/create_view.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_view.sgml,v 1.28 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_view.sgml,v 1.29 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -165,7 +165,7 @@ CREATE VIEW <replaceable class="parameter">name</replaceable> [ ( <replaceable c
       <term><literal>CHECK OPTION</literal></term>
       <listitem>
        <para>
-        This option is to do with updatable views.  All
+        This option has to do with updatable views.  All
         <command>INSERT</> and <command>UPDATE</> commands on the view
         will be checked to ensure data satisfy the view-defining
         condition (that is, the new data would be visible through the
@@ -201,6 +201,14 @@ CREATE VIEW <replaceable class="parameter">name</replaceable> [ ( <replaceable c
    <productname>PostgreSQL</productname> language extension.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-dropview" endterm="sql-dropview-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/declare.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.32 2004/11/15 06:32:15 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.33 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -287,6 +287,16 @@ DECLARE liahona CURSOR FOR SELECT * FROM films;
    extension.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-close" endterm="sql-close-title"></member>
+   <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
+   <member><xref linkend="sql-move" endterm="sql-move-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/delete.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.20 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.21 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -37,14 +37,14 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE
    <tip>
     <para>
      <xref linkend="sql-truncate" endterm="sql-truncate-title"> is a
-     <productname>PostgreSQL</productname> extension which provides a
+     <productname>PostgreSQL</productname> extension that provides a
      faster mechanism to remove all rows from a table.
     </para>
    </tip>
 
   <para>
    By default, <command>DELETE</command> will delete rows in the
-   specified table and all its subtables. If you wish to only delete
+   specified table and all its subtables. If you wish to delete only
    from the specific table mentioned, you must use the
    <literal>ONLY</literal> clause.
   </para>

doc/src/sgml/ref/drop_group.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.8 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.9 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -48,6 +48,17 @@ DROP GROUP <replaceable class="PARAMETER">name</replaceable>
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   It is unwise to drop a group that has any
+   granted permissions on objects.  Currently, this is not enforced,
+   but it is likely that future versions of
+   <productname>PostgreSQL</productname> will check for the error.
+  </para>
+ </refsect1>
+
  <refsect1>
   <title>Examples</title>
 

doc/src/sgml/ref/drop_sequence.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_sequence.sgml,v 1.21 2004/11/27 21:27:07 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_sequence.sgml,v 1.22 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -82,7 +82,9 @@ DROP SEQUENCE serial;
   <title>Compatibility</title>
 
   <para>
-    <command>DROP SEQUENCE</command> conforms with <acronym>SQL:2003</acronym>.
+   <command>DROP SEQUENCE</command> conforms with
+   <acronym>SQL:2003</acronym>, except that the standard only allows one
+   sequence to be dropped per command. 
   </para>
  </refsect1>
 

doc/src/sgml/ref/drop_table.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_table.sgml,v 1.21 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_table.sgml,v 1.22 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -36,9 +36,10 @@ DROP TABLE <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE |
   <para>
    <command>DROP TABLE</command> always removes any indexes, rules,
    triggers, and constraints that exist for the target table.
-   However, to drop a table that is referenced by a foreign-key
+   However, to drop a table that is referenced by a view or a foreign-key
    constraint of another table, <literal>CASCADE</> must be
-   specified. (<literal>CASCADE</> will remove the foreign-key
+   specified. (<literal>CASCADE</> will remove a dependent view entirely,
+   but in the foreign-key case it will only remove the foreign-key
    constraint, not the other table entirely.)
   </para>
  </refsect1>
@@ -95,7 +96,8 @@ DROP TABLE films, distributors;
   <title>Compatibility</title>
 
   <para>
-   This command conforms to the SQL standard.
+   This command conforms to the SQL standard, except that the standard only
+   allows one table to be dropped per command. 
   </para>
  </refsect1>
 

doc/src/sgml/ref/drop_user.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.19 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.20 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -63,6 +63,13 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
    To drop a user who owns a database, first drop the database or change
    its ownership.
   </para>
+
+  <para>
+   It is unwise to drop a user who either owns any database objects or has any
+   granted permissions on objects.  Currently, this is only enforced for
+   the case of owners of databases, but it is likely that future versions of
+   <productname>PostgreSQL</productname> will check other cases.
+  </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/drop_view.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_view.sgml,v 1.20 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_view.sgml,v 1.21 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -83,7 +83,8 @@ DROP VIEW kinds;
   <title>Compatibility</title>
 
   <para>
-   This command conforms to the SQL standard.
+   This command conforms to the SQL standard, except that the standard only
+   allows one view to be dropped per command. 
   </para>
  </refsect1>
 

doc/src/sgml/ref/explain.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.34 2004/09/30 04:23:27 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.35 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -41,9 +41,9 @@ EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replac
    This command displays the execution plan that the
    <productname>PostgreSQL</productname> planner generates for the
    supplied statement.  The execution plan shows how the table(s)
-   referenced by the statement will be scanned---by plain sequential scan,
-   index scan, etc.---and if multiple tables are referenced, what join
-   algorithms will be used to bring together the required row from
+   referenced by the statement will be scanned &mdash; by plain sequential scan,
+   index scan, etc. &mdash; and if multiple tables are referenced, what join
+   algorithms will be used to bring together the required rows from
    each input table.
   </para>
 
@@ -108,7 +108,7 @@ ROLLBACK;
      <para>
       Show the full internal representation of the plan tree, rather
       than just a summary.  Usually this option is only useful for
-      debugging <productname>PostgreSQL</productname>.  The
+      specialized debugging purposes.  The
       <literal>VERBOSE</literal> output is either pretty-printed or
       not, depending on the setting of the <xref
       linkend="guc-explain-pretty-print"> configuration parameter.
@@ -248,6 +248,14 @@ EXPLAIN ANALYZE EXECUTE query(100, 200);
    There is no <command>EXPLAIN</command> statement defined in the SQL standard.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-analyze" endterm="sql-analyze-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/fetch.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/fetch.sgml,v 1.37 2004/06/17 12:41:02 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/fetch.sgml,v 1.38 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -402,6 +402,16 @@ COMMIT WORK;
    name; the option to use <literal>IN</> is an extension.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-close" endterm="sql-close-title"></member>
+   <member><xref linkend="sql-declare" endterm="sql-declare-title"></member>
+   <member><xref linkend="sql-move" endterm="sql-move-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/insert.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.27 2004/06/09 19:08:13 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.28 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -29,20 +29,29 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
   <title>Description</title>
 
   <para>
-   <command>INSERT</command> allows one to insert new rows into a
-   table. One can insert
-   a single row at a time or several rows as a result of a query.
+   <command>INSERT</command> inserts new rows into a table.
+   One can insert a single row specified by value expressions,
+   or several rows as a result of a query.
   </para>
 
   <para>
-   The columns in the target list may be listed in any order.
-   Each column not present in the target list will be inserted
-   using a default value, either its declared default value
-   or null.
+   The target column names may be listed in any order.  If no list of
+   column names is given at all, the default is all the columns of the
+   table in their declared order; or the first <replaceable>N</> column
+   names, if there are only <replaceable>N</> columns supplied by the
+   <literal>VALUES</> clause or <replaceable>query</>.  The values
+   supplied by the <literal>VALUES</> clause or <replaceable>query</> are
+   associated with the explicit or implicit column list left-to-right.
   </para>
 
   <para>
-   If the expression for each column is not of the correct data type,
+   Each column not present in the explicit or implicit column list will be
+   filled with a default value, either its declared default value
+   or null if there is none.
+  </para>
+
+  <para>
+   If the expression for any column is not of the correct data type,
    automatic type conversion will be attempted.
   </para>
 
@@ -93,7 +102,7 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
     <term><replaceable class="PARAMETER">expression</replaceable></term>
     <listitem>
      <para>
-      An expression or value to assign to <replaceable
+      An expression or value to assign to the corresponding <replaceable
       class="PARAMETER">column</replaceable>.
      </para>
     </listitem>
@@ -103,7 +112,8 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
     <term><literal>DEFAULT</literal></term>
     <listitem>
      <para>
-      This column will be filled with its default value.
+      The corresponding <replaceable>column</replaceable> will be filled with
+      its default value.
      </para>
     </listitem>
    </varlistentry>
@@ -152,8 +162,8 @@ INSERT INTO films VALUES
   </para>
 
   <para>
-   In this second example, the last column <literal>len</literal> is
-   omitted and therefore it will have the default value of null:
+   In this second example, the <literal>len</literal> column is
+   omitted and therefore it will have the default value:
 
 <programlisting>
 INSERT INTO films (code, title, did, date_prod, kind)
@@ -174,7 +184,7 @@ INSERT INTO films (code, title, did, date_prod, kind)
   </para>
 
   <para>
-   This examples inserts several rows into table
+   This example inserts several rows into table
    <literal>films</literal> from table <literal>tmp</literal>:
 
 <programlisting>
@@ -200,7 +210,13 @@ INSERT INTO tictactoe (game, board)
   <title>Compatibility</title>
 
   <para>
-   <command>INSERT</command> conforms fully to the SQL standard.
+   <command>INSERT</command> conforms to the SQL standard.  The case in
+   which a column name list is omitted, but not all the columns are
+   filled from the <literal>VALUES</> clause or <replaceable>query</>,
+   is disallowed by the standard.
+  </para>
+
+  <para>
    Possible limitations of the <replaceable
    class="PARAMETER">query</replaceable> clause are documented under
    <xref linkend="sql-select" endterm="sql-select-title">.

doc/src/sgml/ref/load.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/load.sgml,v 1.20 2003/11/29 19:51:39 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/load.sgml,v 1.21 2005/01/04 00:39:53 tgl Exp $
 -->
 
 <refentry id="SQL-LOAD">
@@ -41,7 +41,7 @@ LOAD '<replaceable class="PARAMETER">filename</replaceable>'
    The file name is specified in the same way as for shared library
    names in <xref linkend="sql-createfunction" endterm="sql-createfunction-title">; in particular, one
    may rely on a search path and automatic addition of the system's standard
-   shared library file name extension.  See <xref linkend="xfunc"> for
+   shared library file name extension.  See <xref linkend="xfunc-c"> for
    more information on this topic.
   </para>
  </refsect1>

doc/src/sgml/ref/lock.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/lock.sgml,v 1.44 2004/11/15 06:32:15 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/lock.sgml,v 1.45 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -50,7 +50,7 @@ where <replaceable class="PARAMETER">lockmode</replaceable> is one of:
    restrictive lock mode possible. <command>LOCK TABLE</command>
    provides for cases when you might need more restrictive locking.
    For example, suppose an application runs a transaction at the
-   isolation level read committed and needs to ensure that data in a
+   Read Committed isolation level and needs to ensure that data in a
    table remains stable for the duration of the transaction. To
    achieve this you could obtain <literal>SHARE</> lock mode over the
    table before querying. This will prevent concurrent data changes
@@ -66,14 +66,14 @@ where <replaceable class="PARAMETER">lockmode</replaceable> is one of:
   </para>
 
   <para>
-   To achieve a similar effect when running a transaction at the
-   isolation level serializable, you have to execute the <command>LOCK
-   TABLE</> statement before executing any data modification
-   statement.  A serializable transaction's view of data will be
-   frozen when its first data modification statement begins.  A later
-   <command>LOCK TABLE</> will still prevent concurrent writes &mdash; but it
-   won't ensure that what the transaction reads corresponds to the
-   latest committed values.
+   To achieve a similar effect when running a transaction at the Serializable
+   isolation level, you have to execute the <command>LOCK TABLE</> statement
+   before executing any <command>SELECT</> or data modification statement.
+   A serializable transaction's view of data will be frozen when its first
+   <command>SELECT</> or data modification statement begins.  A <command>LOCK
+   TABLE</> later in the transaction will still prevent concurrent writes
+   &mdash; but it won't ensure that what the transaction reads corresponds to
+   the latest committed values.
   </para>
   
   <para>
@@ -140,8 +140,8 @@ where <replaceable class="PARAMETER">lockmode</replaceable> is one of:
     <listitem>
      <para>
       Specifies that <command>LOCK TABLE</command> should not wait for
-      any conflicting locks to be released: if the specified lock
-      cannot be immediately acquired without waiting, the transaction
+      any conflicting locks to be released: if the specified lock(s)
+      cannot be acquired immediately without waiting, the transaction
       is aborted.
      </para>
     </listitem>
@@ -219,7 +219,7 @@ COMMIT WORK;
 
  <refsect1>
   <title>Compatibility</title>
-	  
+
   <para>
    There is no <command>LOCK TABLE</command> in the SQL standard,
    which instead uses <command>SET TRANSACTION</command> to specify

doc/src/sgml/ref/move.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/move.sgml,v 1.28 2004/06/17 12:41:02 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/move.sgml,v 1.29 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -86,11 +86,21 @@ COMMIT WORK;
 
  <refsect1>
   <title>Compatibility</title>
-	
+
   <para>
    There is no <command>MOVE</command> statement in the SQL standard.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-close" endterm="sql-close-title"></member>
+   <member><xref linkend="sql-declare" endterm="sql-declare-title"></member>
+   <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/notify.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.26 2003/11/29 19:51:39 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/notify.sgml,v 1.27 2005/01/04 00:39:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -34,6 +34,15 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
    for the specified notification name in the current database.
   </para>
 
+  <para>
+   <command>NOTIFY</command> provides a simple form of signal or
+   interprocess communication mechanism for a collection of processes
+   accessing the same <productname>PostgreSQL</productname> database.
+   Higher-level mechanisms can be built by using tables in the database to
+   pass additional data (beyond a mere notification name) from notifier to
+   listener(s).
+  </para>
+
   <para>
    The information passed to the client for a notification event includes the notification
    name and the notifying session's server process <acronym>PID</>.  It is up to the
@@ -50,15 +59,6 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
    to signal different sorts of changes to a single table.
   </para>
 
-  <para>
-   <command>NOTIFY</command> provides a simple form of signal or
-   interprocess communication mechanism for a collection of processes
-   accessing the same <productname>PostgreSQL</productname> database.
-   Higher-level mechanisms can be built by using tables in the database to
-   pass additional data (beyond a mere notification name) from notifier to
-   listener(s).
-  </para>
-
   <para>
    When <command>NOTIFY</command> is used to signal the occurrence of changes
    to a particular table, a useful programming technique is to put the
@@ -79,7 +79,8 @@ NOTIFY <replaceable class="PARAMETER">name</replaceable>
    the notification event will not be delivered to its connected client until just
    after the transaction is completed (either committed or aborted).  Again, the
    reasoning is that if a notification were delivered within a transaction that was
-   later aborted, one would want the notification to be undone somehow---but
+   later aborted, one would want the notification to be undone somehow &mdash;
+   but
    the server cannot <quote>take back</quote> a notification once it has sent it to the client.
    So notification events are only delivered between transactions.  The upshot of this
    is that applications using <command>NOTIFY</command> for real-time signaling