More cleanup of Diagnostics sections.

doc/src/sgml/ref/alter_group.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.12 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.13 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -45,7 +45,7 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
  </refsect1>
 
  <refsect1>
-  <title>Parameter</title>
+  <title>Parameters</title>
 
   <variablelist>
    <varlistentry>

doc/src/sgml/ref/alter_language.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_language.sgml,v 1.3 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_language.sgml,v 1.4 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -35,7 +35,7 @@ ALTER LANGUAGE <replaceable>name</replaceable> RENAME TO <replaceable>newname</r
  </refsect1>
 
  <refsect1>
-  <title>Parameter</title>
+  <title>Parameters</title>
 
   <variablelist>
    <varlistentry>

doc/src/sgml/ref/alter_schema.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_schema.sgml,v 1.3 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_schema.sgml,v 1.4 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -36,7 +36,7 @@ ALTER SCHEMA <replaceable>name</replaceable> RENAME TO <replaceable>newname</rep
  </refsect1>
 
  <refsect1>
-  <title>Parameter</title>
+  <title>Parameters</title>
 
   <variablelist>
    <varlistentry>

doc/src/sgml/ref/cluster.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.28 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.29 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -74,7 +74,7 @@ CLUSTER
  </refsect1>
 
  <refsect1>
-  <title>Parameter</title>
+  <title>Parameters</title>
 
   <variablelist>
    <varlistentry>

doc/src/sgml/ref/clusterdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.13 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.14 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -48,16 +48,17 @@ PostgreSQL documentation
    <application>clusterdb</application> is a wrapper around the SQL
    command <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">.
    There is no effective difference between clustering databases via
-   this or other methods.  The database server must be running at the
-   targeted host.  Also, any default settings and environment
-   variables used by the <application>libpq</application> front-end
-   library will apply.
+   this utility and via other methods for accessing the server.
   </para>
 
   <para>
    In case of difficulty, see <xref linkend="SQL-CLUSTER"
    endterm="sql-cluster-title"> and <xref linkend="APP-PSQL"> for
    discussions of potential problems and error messages.
+   The database server must be running at the
+   targeted host.  Also, any default connection settings and environment
+   variables used by the <application>libpq</application> front-end
+   library will apply.
   </para>
 
  </refsect1>

doc/src/sgml/ref/commit.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.17 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -12,8 +12,8 @@ PostgreSQL documentation
  <refnamediv>
   <refname>COMMIT</refname>
   <refpurpose>commit the current transaction</refpurpose>
- </refnamediv>  
-  
+ </refnamediv>
+
  <indexterm zone="sql-commit">
   <primary>COMMIT</primary>
  </indexterm>
@@ -74,7 +74,7 @@ COMMIT;
 </programlisting>
   </para>
  </refsect1>
- 
+
  <refsect1>
   <title>Compatibility</title>
   

doc/src/sgml/ref/create_database.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.35 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.36 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -36,6 +36,12 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
    <productname>PostgreSQL</productname> database.
   </para>
 
+  <para>
+   To create a database, you must be a superuser or have the special
+   <literal>CREATEDB</> privilege.
+   See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
+  </para>
+
   <para>
    Normally, the creator becomes the owner of the new database.
    Superusers can create databases owned by other users using the
@@ -63,6 +69,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
    a leading slash
    (e.g., <filename>/usr/local/pgsql/data</filename>),
    are allowed as well.
+   In either case, the final path name must be absolute and must not
+   contain any single quotes.
   </para>
 
   <para>
@@ -86,7 +94,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
  </refsect1>
 
  <refsect1>
-  <title>Parameter</title>
+  <title>Parameters</title>
 
     <variablelist>
      <varlistentry>
@@ -147,78 +155,20 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
  </refsect1>
 
  <refsect1>
-  <title>Diagnostics</title>
-
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>CREATE DATABASE</computeroutput></term>
-      <listitem>
-       <para>
-	Message returned if the database was successfully created.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>ERROR:  user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term>
-      <listitem>
-       <para>
-        You must have the special <literal>CREATEDB</> privilege to create databases.
-        See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
-       </para>
-      </listitem>
-     </varlistentry>
-
-
-     <varlistentry>
-      <term><computeroutput>ERROR:  createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
-      <listitem>
-       <para>
-	This occurs if a database with the specified name already
-	exists.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>ERROR:  database path may not contain single quotes</computeroutput></term>
-      <listitem>
-       <para>
-	The database location
-        <replaceable class="parameter">dbpath</replaceable> cannot contain
-        single quotes. This is required so that the shell commands that
-        create the database directory can execute safely.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>ERROR:  CREATE DATABASE: may not be called in a transaction block</computeroutput></term>
-      <listitem>
-       <para>
-        If you have an explicit transaction block in progress you cannot call
-        <command>CREATE DATABASE</command>. You must finish the transaction first.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>ERROR:  Unable to create database directory '<replaceable>path</replaceable>'.</computeroutput></term>
-      <term><computeroutput>ERROR:  Could not initialize database directory.</computeroutput></term>
-      <listitem>
-       <para>
-        These are most likely related to insufficient permissions on the data
-        directory, a full disk, or other file system problems. The user under
-        which the database server is running must have access to the location.
-       </para>
-      </listitem>
-     </varlistentry>
+  <title>Notes</title>
 
-    </variablelist>
- </refsect1>
+   <para>
+    <command>CREATE DATABASE</> cannot be executed inside a transaction
+    block.
+   </para>
 
- <refsect1>
-  <title>Notes</title>
+   <para>
+    Errors along the line of <quote>could not initialize database directory</>
+    are most likely related to insufficient permissions on the data
+    directory, a full disk, or other file system problems.  When using an
+    alternate location, the user under
+    which the database server is running must have access to the location.
+   </para>
 
    <para>
     Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
@@ -231,7 +181,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
 
   <para>
    There are security issues involved with using alternate database
-   locations specified with absolute path names.  See <xref
+   locations specified with absolute path names; this is why the feature
+   is not enabled by default.  See <xref
    linkend="manage-ag-alternate-locs"> for more information.
   </para>
 

doc/src/sgml/ref/create_sequence.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.34 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.35 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -196,49 +196,6 @@ SELECT * FROM <replaceable>seqname</replaceable>;
   </variablelist>
  </refsect1>
 
- <refsect1>
-  <title>Diagnostics</title>
-
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>CREATE SEQUENCE</computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if the sequence was successfully created.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>ERROR:  Relation '<replaceable class="parameter">seqname</replaceable>' already exists</computeroutput></term>
-    <listitem>
-     <para>
-      A sequence, table, view, or index of the specified name already exists.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
-    <term><computeroutput>ERROR:  DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)</computeroutput></term>
-    <listitem>
-     <para>
-      The specified starting value is out of range.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
-    <listitem>
-     <para>
-      The minimum and maximum values are inconsistent.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsect1>
-
  <refsect1>
   <title>Notes</title>
 

doc/src/sgml/ref/create_view.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.23 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -90,39 +90,6 @@ class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="P
   </variablelist>
  </refsect1>
 
- <refsect1>
-  <title>Diagnostics</title>
-
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>CREATE VIEW</computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if the view was successfully created.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>WARNING:  Attribute '<replaceable class="parameter">column</replaceable>' has an unknown type</computeroutput></term>
-    <listitem>
-     <para>
-      The view will be created having a column with an unknown type if
-      you do not specify it. For example, the following command gives
-      this warning:
-<programlisting>
-CREATE VIEW vista AS SELECT 'Hello World'
-</programlisting>
-      whereas this command does not:
-<programlisting>
-CREATE VIEW vista AS SELECT text 'Hello World'
-</programlisting>
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsect1>
-
  <refsect1>
   <title>Notes</title>
 
@@ -137,6 +104,20 @@ CREATE VIEW vista AS SELECT text 'Hello World'
    <para>
     Use the <command>DROP VIEW</command> statement to drop views.
    </para>
+
+   <para>
+    Be careful that the names and types of the view's columns will be
+    assigned the way you want.  For example,
+<programlisting>
+CREATE VIEW vista AS SELECT 'Hello World';
+</programlisting>
+    is bad form in two ways: the column name defaults to <literal>?column?</>,
+    and the column datatype defaults to <type>unknown</>.  If you want a
+    string literal in a view's result, use something like
+<programlisting>
+CREATE VIEW vista AS SELECT text 'Hello World' AS hello;
+</programlisting>
+   </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/createdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.34 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.35 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -48,12 +48,21 @@ PostgreSQL documentation
   <para>
    <application>createdb</application> is a wrapper around the
    <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE"
-   endterm="SQL-CREATEDATABASE-title">.  The database server must be 
-   running on the targeted host. There is nothing special about creating 
-   databases via this or other methods.  Also, any default settings and 
-   environment variables used by the <application>libpq</application> 
-   front-end library will apply.
+   endterm="SQL-CREATEDATABASE-title">.
+   There is no effective difference between creating databases via
+   this utility and via other methods for accessing the server.
   </para>
+
+  <para>
+   In case of difficulty, see <xref linkend="SQL-CREATEDATABASE"
+   endterm="sql-createdatabase-title"> and <xref linkend="APP-PSQL"> for
+   discussions of potential problems and error messages.
+   The database server must be running at the
+   targeted host.  Also, any default connection settings and environment
+   variables used by the <application>libpq</application> front-end
+   library will apply.
+  </para>
+
  </refsect1>
 
 
@@ -212,45 +221,6 @@ PostgreSQL documentation
  </refsect1>
 
 
- <refsect1>
-  <title>Diagnostics</title>
-
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>CREATE DATABASE</computeroutput></term>
-      <listitem>
-       <para>The database was successfully created.</para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>createdb: Database creation failed.</computeroutput></term>
-      <listitem>
-       <para>(Says it all.)</para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>createdb: Comment creation failed. (Database was created.)</computeroutput></term>
-      <listitem>
-       <para>
-       The comment/description for the database could not be created.
-       The database itself will have been created already. You can use the
-       <acronym>SQL</acronym> command <command>COMMENT ON DATABASE</command> to
-       create the comment later on.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
-
-   <para>
-    If there is an error condition, the backend error message will be displayed.
-    See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE">
-    for possibilities.
-   </para>
- </refsect1>
-
-
  <refsect1>
   <title>Environment</title>
 

doc/src/sgml/ref/createuser.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.36 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.37 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -49,17 +49,19 @@ PostgreSQL documentation
   <para>
    <application>createuser</application> is a wrapper around the
    <acronym>SQL</acronym> command <xref linkend="SQL-CREATEUSER"
-   endterm="SQL-CREATEUSER-title">.  The database server must be 
-   running on the targeted host. There is nothing special
-   about creating users via this or other methods. Also, any
-   default settings and environment variables used by the
-   <application>libpq</application> front-end library will apply.
+   endterm="SQL-CREATEUSER-title">.
+   There is no effective difference between creating users via
+   this utility and via other methods for accessing the server.
   </para>
 
   <para>
-   Passwords can only be added later or changed using the
-   <acronym>SQL</acronym> command <xref linkend="SQL-ALTERUSER" 
-   endterm="SQL-ALTERUSER-title">.
+   In case of difficulty, see <xref linkend="SQL-CREATEUSER"
+   endterm="sql-createuser-title"> and <xref linkend="APP-PSQL"> for
+   discussions of potential problems and error messages.
+   The database server must be running at the
+   targeted host.  Also, any default connection settings and environment
+   variables used by the <application>libpq</application> front-end
+   library will apply.
   </para>
 
  </refsect1>
@@ -101,6 +103,7 @@ PostgreSQL documentation
        <para>
 	The new user is not allowed to create other users (i.e.,
 	the new user is a regular user, not a superuser).
+	This is the default.
        </para>
       </listitem>
      </varlistentry>
@@ -121,6 +124,7 @@ PostgreSQL documentation
       <listitem>
        <para>
 	The new user is not allowed to create databases.
+	This is the default.
        </para>
       </listitem>
      </varlistentry>
@@ -142,7 +146,7 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Encrypts the user's password stored in the database. If not
-	specified, the default is used.
+	specified, the default password behavior is used.
        </para>
       </listitem>
      </varlistentry>
@@ -164,7 +168,7 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Does not encrypt the user's password stored in the database. If
-	not specified, the default is used.
+	not specified, the default password behavior is used.
        </para>
       </listitem>
      </varlistentry>
@@ -272,38 +276,6 @@ PostgreSQL documentation
  </refsect1>
 
 
- <refsect1>
-  <title>Diagnostics</title>
-
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>CREATE USER</computeroutput></term>
-      <listitem>
-       <para>
-        The user was successfully created.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>createuser: creation of user "<replaceable class="parameter">username</replaceable>" failed</computeroutput></term>
-      <listitem>
-       <para>
-        Something went wrong. The user was not created.
-       </para>
-      </listitem>
-     </varlistentry>
-
-    </variablelist>
-
-   <para>
-    If there is an error condition, the backend error message will be displayed.
-    See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
-    for possibilities.
-   </para>
- </refsect1>
-
-
  <refsect1>
   <title>Examples</title>
 

doc/src/sgml/ref/declare.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.27 2003/09/11 21:42:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.28 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -44,9 +44,10 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
    format.  Once the information comes back in text form, the client
    application may need to convert it to a binary format to manipulate
    it.  In addition, data in the text format is often larger in size
-   than in the binary format.  Binary cursors return the data in the
-   native binary representation.  Nevertheless, if you intend to
-   display the data as text anyway, retrieving it in text form will
+   than in the binary format.  Binary cursors return the data in a
+   binary representation that may be more easily manipulated.
+   Nevertheless, if you intend to display the data as text anyway,
+   retrieving it in text form will
    save you some effort on the client side.
   </para>
 
@@ -54,7 +55,8 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
    As an example, if a query returns a value of one from an integer column,
    you would get a string of <literal>1</> with a default cursor
    whereas with a binary cursor you would get
-   a 4-byte value containing the internal representation of the value.
+   a 4-byte field containing the internal representation of the value
+   (in big-endian byte order).
   </para>
 
   <para>
@@ -64,16 +66,16 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
    format.
   </para>
 
-  <para>
-   The string representation is architecture-neutral whereas binary
-   representation can differ between different machine architectures.
-   <emphasis><productname>PostgreSQL</productname> does not resolve
-   byte ordering or representation issues for binary
-   cursors.</emphasis>  Therefore, if your client machine and server
-   machine use different representations (e.g.,
-   <quote>big-endian</quote> versus <quote>little-endian</quote>), you
-   will probably not want your data returned in binary format.
-  </para>
+  <note>
+   <para>
+    When the client application uses the <quote>extended query</> protocol
+    to issue a <command>FETCH</> command, the Bind protocol message
+    specifies whether data is to be retrieved in text or binary format.
+    This choice overrides the way that the cursor is defined.  The concept
+    of a binary cursor as such is thus obsolete when using extended query
+    protocol --- any cursor can be treated as either text or binary.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1>
@@ -84,8 +86,7 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
     <term><replaceable class="parameter">cursorname</replaceable></term>
     <listitem>
      <para>
-      The name of the cursor to be used in subsequent
-      <command>FETCH</command> operations.
+      The name of the cursor to be created.
      </para>
     </listitem>
    </varlistentry>
@@ -192,48 +193,18 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
   </para>
  </refsect1>
 
- <refsect1>
-  <title>Diagnostics</title>
-
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>DECLARE CURSOR</computeroutput></term>
-    <listitem>
-     <para>
-      The message returned if the cursor was successfully defined.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>ERROR:  cursor "<replaceable class="parameter">cursorname</replaceable>" already exists</computeroutput></term>
-    <listitem>
-     <para>
-      This error occurs if a cursor with the same name already exists.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>ERROR:  DECLARE CURSOR may only be used in begin/end transaction blocks</computeroutput></term>
-    <listitem>
-     <para>
-      This error occurs if the cursor is not declared within a
-      transaction block, and <literal>WITH HOLD</literal> is not
-      specified.
-     </para>
-    </listitem>
-   </varlistentry>     
-  </variablelist>
- </refsect1>
-
  <refsect1>
   <title>Notes</title>
 
    <para>
-    If <literal>WITH HOLD</literal> is not specified, the cursor
+    Unless <literal>WITH HOLD</literal> is specified, the cursor
     created by this command can only be used within the current
-    transaction. Use
+    transaction.  Thus, <command>DECLARE</> without <literal>WITH
+    HOLD</literal> is useless outside a transaction block: the cursor would
+    survive only to the completion of the statement.  Therefore
+    <productname>PostgreSQL</productname> reports an error if this
+    command is used outside a transaction block.
+    Use
     <xref linkend="sql-begin" endterm="sql-begin-title">,
     <xref linkend="sql-commit" endterm="sql-commit-title">
     and

doc/src/sgml/ref/delete.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.18 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.19 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -52,7 +52,7 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE
   <para>
    You must have the <literal>DELETE</literal> privilege on the table
    to delete from it, as well as the <literal>SELECT</literal>
-   privilege to any table whose values are read in the <replaceable
+   privilege for any table whose values are read in the <replaceable
    class="parameter">condition</replaceable>.
   </para>
  </refsect1>
@@ -84,22 +84,20 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE
  </refsect1>
 
  <refsect1>
-  <title>Diagnostics</title>
+  <title>Outputs</title>
 
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>DELETE <replaceable class="parameter">count</replaceable></computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if rows are successfully deleted. The
-      <replaceable class="parameter">count</replaceable> is the number
-      of rows deleted.  If <replaceable
-      class="parameter">count</replaceable> is 0, no rows were
-      deleted.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
+  <para>
+   On successful completion, a <command>DELETE</> command returns a command
+   tag of the form
+<screen>
+DELETE <replaceable class="parameter">count</replaceable>
+</screen>
+   The <replaceable class="parameter">count</replaceable> is the number
+   of rows deleted.  If <replaceable class="parameter">count</replaceable> is
+   0, no rows matched the <replaceable
+   class="parameter">condition</replaceable> (this is not considered
+   an error).
+  </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/drop_database.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.17 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -31,6 +31,9 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
    <command>DROP DATABASE</command> drops a database. It removes the
    catalog entries for the database and deletes the directory
    containing the data.  It can only be executed by the database owner.
+   Also, it cannot be executed while you or anyone else are connected
+   to the target database.  (Connect to <literal>template1</literal> or any
+   other database to issue this command.) 
   </para>
 
   <para>
@@ -53,44 +56,14 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
   </variablelist>
  </refsect1>
 
- <refsect1>
-  <title>Diagnostics</title>
-
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>DROP DATABASE</computeroutput></term>
-      <listitem>
-       <para>
-        This message is returned if the command was successful.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>DROP DATABASE: cannot be executed on the currently open database</computeroutput></term>
-      <listitem>
-       <para>
-        You cannot be connected to the database you are about to remove.
-        Instead, connect to <literal>template1</literal> or any other
-        database and run this command again.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>DROP DATABASE: may not be called in a transaction block</computeroutput></term>
-      <listitem>
-       <para>
-        You must finish the transaction in progress before you can call this command.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
- </refsect1>
-
  <refsect1>
   <title>Notes</title>
 
+   <para>
+    <command>DROP DATABASE</> cannot be executed inside a transaction
+    block.
+   </para>
+
   <para>
    This command cannot be executed while connected to the target
    database. Thus, it might be more convenient to use the program

doc/src/sgml/ref/drop_user.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.17 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -49,39 +49,6 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
   </variablelist>
  </refsect1>
 
- <refsect1>
-  <title>Diagnostics</title>
-
-   <variablelist>
-    <varlistentry>
-     <term><computeroutput>DROP USER</computeroutput></term>
-     <listitem>
-      <para>
-       Message returned if the user was successfully deleted.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term><computeroutput>ERROR:  DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
-     <listitem>
-      <para>
-       Message returned if the specified user does not exist.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term><computeroutput>DROP USER: user "<replaceable class="parameter">name</replaceable>" owns database "<replaceable class="parameter">name</replaceable>", cannot be removed</computeroutput></term>
-     <listitem>
-      <para>
-       You must drop the database first or change its ownership.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
- </refsect1>
-
  <refsect1>
   <title>Notes</title>
 
@@ -91,6 +58,11 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
    same functionality as this command (in fact, it calls this command)
    but can be run from the command shell.
   </para>
+
+  <para>
+   To drop a user who owns a database, first drop the database or change
+   its ownership.
+  </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/dropdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.23 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -41,12 +41,21 @@ PostgreSQL documentation
   <para>
    <application>dropdb</application> is a wrapper around the
    <acronym>SQL</acronym> command <xref linkend="SQL-DROPDATABASE"
-   endterm="SQL-DROPDATABASE-title">.  The database server must be 
-   running on the targeted host. There is nothing special
-   about dropping databases via this or other methods. Also, any
-   default settings and environment variables used by the
-   <application>libpq</application> front-end library will apply.
+   endterm="SQL-DROPDATABASE-title">.
+   There is no effective difference between dropping databases via
+   this utility and via other methods for accessing the server.
   </para>
+
+  <para>
+   In case of difficulty, see <xref linkend="SQL-DROPDATABASE"
+   endterm="sql-dropdatabase-title"> and <xref linkend="APP-PSQL"> for
+   discussions of potential problems and error messages.
+   The database server must be running at the
+   targeted host.  Also, any default connection settings and environment
+   variables used by the <application>libpq</application> front-end
+   library will apply.
+  </para>
+
  </refsect1>
 
 
@@ -100,7 +109,7 @@ PostgreSQL documentation
   </para>
 
   <para>
-   <application>createdb</application> also accepts the following
+   <application>dropdb</application> also accepts the following
    command-line arguments for connection parameters:
 
    <variablelist>
@@ -153,33 +162,6 @@ PostgreSQL documentation
  </refsect1>
 
 
- <refsect1>
-   <title>Diagnostics</title>
-
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>DROP DATABASE</computeroutput></term>
-      <listitem>
-       <para>The database was successfully removed.</para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>dropdb: Database removal failed.</computeroutput></term>
-      <listitem>
-       <para>Something didn't work out.</para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
-
-   <para>
-    If there is an error condition, the backend error message will be displayed.
-    See <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title">
-    for possibilities.
-   </para>
- </refsect1>
-
-
  <refsect1>
   <title>Environment</title>
 

doc/src/sgml/ref/dropuser.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.28 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.29 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -43,12 +43,21 @@ PostgreSQL documentation
   <para>
    <application>dropuser</application> is a wrapper around the
    <acronym>SQL</acronym> command <xref linkend="SQL-DROPUSER"
-   endterm="SQL-DROPUSER-title">.  The database server must be running
-   on the targeted host.  There is nothing special about removing
-   users via this or other methods.  Also, any default settings and
-   environment variables used by the <application>libpq</application>
-   front-end library will apply.
+   endterm="SQL-DROPUSER-title">.
+   There is no effective difference between dropping users via
+   this utility and via other methods for accessing the server.
   </para>
+
+  <para>
+   In case of difficulty, see <xref linkend="SQL-DROPUSER"
+   endterm="sql-dropuser-title"> and <xref linkend="APP-PSQL"> for
+   discussions of potential problems and error messages.
+   The database server must be running at the
+   targeted host.  Also, any default connection settings and environment
+   variables used by the <application>libpq</application> front-end
+   library will apply.
+  </para>
+
  </refsect1>
 
 
@@ -103,7 +112,7 @@ PostgreSQL documentation
   </para>
 
   <para>
-   <application>createuser</application> also accepts the following
+   <application>dropuser</application> also accepts the following
    command-line arguments for connection parameters:
     
    <variablelist>
@@ -176,38 +185,6 @@ PostgreSQL documentation
  </refsect1>
 
 
- <refsect1>
-   <title>Diagnostics</title>
-
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>DROP USER</computeroutput></term>
-      <listitem>
-       <para>
-        The user was successfully removed.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>dropuser: deletion of user "<replaceable class="parameter">username</replaceable>" failed</computeroutput></term>
-      <listitem>
-       <para>
-        Something went wrong. The user was not removed.
-       </para>
-      </listitem>
-     </varlistentry>
-
-    </variablelist>
-
-   <para>
-    If there is an error condition, the backend error message will be displayed.
-    See <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title">
-    and <xref linkend="APP-PSQL"> for possibilities.
-   </para>
- </refsect1>
-
-
  <refsect1>
   <title>Examples</title>
 

doc/src/sgml/ref/end.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.11 2003/09/11 21:42:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.12 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -30,9 +30,10 @@ END [ WORK | TRANSACTION ]
   <para>
    <command>END</command> commits the current transaction. All changes
    made by the transaction become visible to others and are guaranteed
-   to be durable if a crash occurs.  It is a
-   <productname>PostgreSQL</productname> extension that is equivalent
-   to <xref linkend="sql-commit" endterm="sql-commit-title">.
+   to be durable if a crash occurs.  This command is a
+   <productname>PostgreSQL</productname> extension
+   that is equivalent to <xref linkend="sql-commit"
+   endterm="sql-commit-title">.
   </para>
  </refsect1>
   
@@ -51,31 +52,7 @@ END [ WORK | TRANSACTION ]
    </varlistentry>
   </variablelist>
  </refsect1>
-   
- <refsect1>
-  <title>Diagnostics</title>
 
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>COMMIT</computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if the transaction was successfully committed.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>WARNING:  COMMIT: no transaction in progress</computeroutput></term>
-    <listitem>
-     <para>
-      Message if there is no transaction in progress.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsect1>
-  
  <refsect1>
   <title>Notes</title>
 
@@ -83,6 +60,11 @@ END [ WORK | TRANSACTION ]
    Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to
    abort a transaction.
   </para>
+
+  <para>
+   Issuing <command>END</> when not inside a transaction does
+   no harm, but it will provoke a warning message.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -106,6 +88,16 @@ END;
    specified in the SQL standard.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-begin" endterm="sql-begin-title"></member>
+   <member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
+   <member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/explain.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.29 2003/09/09 18:28:53 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.30 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -80,7 +80,7 @@ ROLLBACK;
  </refsect1>
 
  <refsect1>
-  <title>Parameter</title>
+  <title>Parameters</title>
 
   <variablelist>
    <varlistentry>

doc/src/sgml/ref/fetch.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.32 2003/09/09 18:28:53 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.33 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -45,7 +45,7 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
   <title>Description</title>
 
   <para>
-   <command>FETCH</command> retrieves rows using a cursor.
+   <command>FETCH</command> retrieves rows using a previously-created cursor.
   </para>
 
   <para>
@@ -280,6 +280,23 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Outputs</title>
+
+  <para>
+   On successful completion, a <command>FETCH</> command returns a command
+   tag of the form
+<screen>
+FETCH <replaceable class="parameter">count</replaceable>
+</screen>
+   The <replaceable class="parameter">count</replaceable> is the number
+   of rows fetched (possibly zero).  Note that in
+   <application>psql</application>, the command tag will not actually be
+   displayed, since <application>psql</application> displays the fetched
+   rows instead.
+  </para>
+ </refsect1>
+
  <refsect1>
   <title>Notes</title>
 

doc/src/sgml/ref/insert.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.24 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.25 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -119,30 +119,21 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
  </refsect1>
 
  <refsect1>
-  <title>Diagnostics</title>
+  <title>Outputs</title>
 
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>INSERT <replaceable>oid</replaceable> 1</computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if only one row was inserted.
-      <returnvalue><replaceable>oid</replaceable></returnvalue> is the
-      <acronym>OID</acronym> of the inserted row.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>INSERT 0 <replaceable>count</replaceable></computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if more than one rows were inserted.
-      <replaceable>count</replaceable> is the number of rows inserted.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
+  <para>
+   On successful completion, an <command>INSERT</> command returns a command
+   tag of the form
+<screen>
+INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable>
+</screen>
+   The <replaceable class="parameter">count</replaceable> is the number
+   of rows inserted.  If <replaceable class="parameter">count</replaceable>
+   is exactly one, and the target table has OIDs, then
+   <replaceable class="parameter">oid</replaceable> is the
+   <acronym>OID</acronym> assigned to the inserted row.  Otherwise
+   <replaceable class="parameter">oid</replaceable> is zero.
+  </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/listen.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.17 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -31,6 +31,9 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
    <command>LISTEN</command> registers the current session as a
    listener on the notification condition <replaceable
    class="PARAMETER">name</replaceable>.
+   If the current session is already registered as a listener for
+   this notification condition, a warning message appears and nothing
+   is done.
   </para>
 
   <para>
@@ -85,30 +88,6 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
   </variablelist>
  </refsect1>
 
- <refsect1>
-  <title>Diagnostics</title>
-
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>LISTEN</computeroutput></term>
-    <listitem>
-     <para>
-      Message returned upon successful completion of registration.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>WARNING:  Async_Listen: We are already listening on <replaceable class="PARAMETER">name</replaceable></computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if this session is already registered for that notification condition.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </refsect1>
-
  <refsect1>
   <title>Examples</title>
 
@@ -117,7 +96,7 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
 <programlisting>
 LISTEN virtual;
 NOTIFY virtual;
-Asynchronous NOTIFY 'virtual' from backend with pid '8448' received.
+Asynchronous notification "virtual" received from server process with PID 8448.
 </programlisting>
   </para>
  </refsect1>

doc/src/sgml/ref/move.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.23 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -41,12 +41,16 @@ MOVE [ <replaceable class="PARAMETER">direction</replaceable> { FROM | IN } ] <r
  </refsect1>
 
  <refsect1>
-  <title>Diagnostics</title>
+  <title>Outputs</title>
 
   <para>
-   The count returned in <command>MOVE</command>'s status string is
-   the count of the number of rows that would have been returned by
-   the equivalent <command>FETCH</command> command.
+   On successful completion, a <command>MOVE</> command returns a command
+   tag of the form
+<screen>
+MOVE <replaceable class="parameter">count</replaceable>
+</screen>
+   The <replaceable class="parameter">count</replaceable> is the number
+   of rows moved over (possibly zero).
   </para>
  </refsect1>
 

doc/src/sgml/ref/postmaster.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.38 2003/09/11 17:31:45 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.39 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -419,73 +419,52 @@ PostgreSQL documentation
 
  <refsect1>
    <title>Diagnostics</title>
-   <para>
 
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>semget: No space left on device</computeroutput></term>
-      <listitem>
-       <para>
-	If you see this message, you probably need to configure
-	your kernel for shared memory and semaphores as described in <xref linkend="kernel-resources">.
-	If you run multiple instances of
-	<command>postmaster</command>
-	on a single host, or have a kernel with particularly small shared memory
-	and/or semaphore limits, you may have to reconfigure your kernel to increase
-	its shared memory or semaphore parameters.
-       </para>
+   <para>
+    A failure message mentioning <literal>semget</> or <literal>shmget</>
+    probably indicates you need to configure your kernel to provide adequate
+    shared memory and semaphores.  For more discussion see <xref
+    linkend="kernel-resources">.
+   </para>
 
-	<tip>
-	 <para>
-	  You may be able to postpone
-	  reconfiguring your kernel by decreasing <option>-B</option> to reduce
-	  the shared memory consumption of <productname>PostgreSQL</>,
-	  and/or by reducing <option>-N</option> to reduce the semaphore
-	  consumption.
-	 </para>
-	</tip>
-      </listitem>
-     </varlistentry>
+   <tip>
+    <para>
+     You may be able to postpone reconfiguring your kernel by decreasing
+     <varname>shared_buffers</varname> to reduce the shared memory consumption
+     of <productname>PostgreSQL</>, and/or by reducing
+     <varname>max_connections</varname> to reduce the semaphore consumption.
+    </para>
+   </tip>
 
-     <varlistentry>
-      <term><computeroutput>StreamServerPort: cannot bind to port</computeroutput></term>
-      <listitem>
-       <para>
-	If you see this message, you should make certain that there is no
-	other <command>postmaster</command>
-	process already running on the same port number.  The easiest way to
-	determine this is by using the command
+   <para>
+    A failure message suggesting that another postmaster is already running
+    should be checked carefully, for example by using the command
 <screen>
 <prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput>
 </screen>
         or
 <screen>
-<prompt>$</prompt> <userinput>ps -e | grep postmaster</userinput>
+<prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput>
 </screen>
-	depending on your system.
-       </para>
+    depending on your system.  If you are certain that no conflicting
+    postmaster is running, you may remove the lock file mentioned in the
+    message and try again.
+   </para>
 
-       <para>
-	If you 
-	are sure that no other
-	<command>postmaster</command>
-	processes are running and you still get this error, try specifying a
-	different port using the
-	<literal>-p</literal>
-	option.  You may also get this error if you terminate the
-	<command>postmaster</command>
-	and immediately restart it using the same port; in this case, you must
-	simply wait a few seconds until the operating system closes the port
-	before trying again.  Finally, you may get this error if you specify
-	a port number that your operating system considers to be reserved.
-	For example, many versions of Unix consider port numbers under 1024 to
-	be <quote>trusted</quote>
-	and only permit the Unix superuser to access them.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
+   <para>
+    A failure message indicating inability to bind to a port may indicate
+    that that port is already in use by some non-PostgreSQL process.
+    You may also get this error if you terminate the
+    <command>postmaster</command>
+    and immediately restart it using the same port; in this case, you must
+    simply wait a few seconds until the operating system closes the port
+    before trying again.  Finally, you may get this error if you specify
+    a port number that your operating system considers to be reserved.
+    For example, many versions of Unix consider port numbers under 1024 to
+    be <quote>trusted</quote>
+    and only permit the Unix superuser to access them.
    </para>
+
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/set.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.81 2003/08/31 17:32:24 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.82 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -224,48 +224,6 @@ SELECT setseed(<replaceable>value</replaceable>);
   </para>
  </refsect1>
 
- <refsect1>
-  <title>Diagnostics</title>
-
-   <variablelist>
-    <varlistentry>
-     <term><computeroutput>SET</computeroutput></term>
-     <listitem>
-      <para>
-       Message returned if successful.
-      </para>
-     </listitem>
-    </varlistentry>
-     
-    <varlistentry>
-     <term><computeroutput>ERROR:  '<replaceable>name</replaceable>' is not a valid option name</computeroutput></term>
-     <listitem>
-      <para>
-       The parameter you tried to set does not exist.
-      </para>
-     </listitem>
-    </varlistentry>
-     
-    <varlistentry>
-     <term><computeroutput>ERROR:  '<replaceable>name</replaceable>': permission denied</computeroutput></term>
-     <listitem>
-      <para>
-       You must be a superuser to alter certain settings.
-      </para>
-     </listitem>
-    </varlistentry>
-     
-    <varlistentry>
-     <term><computeroutput>ERROR:  '<replaceable>name</replaceable>' cannot be changed after server start</computeroutput></term>
-     <listitem>
-      <para>
-       Some parameters are fixed once the server is started.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
- </refsect1>
-
  <refsect1>
   <title>Notes</title>
 

doc/src/sgml/ref/truncate.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.12 2003/09/09 18:28:53 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.13 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -36,7 +36,7 @@ TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable>
  </refsect1>
   
  <refsect1>
-  <title>Parameter</title>
+  <title>Parameters</title>
 
   <variablelist>
    <varlistentry>

doc/src/sgml/ref/update.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.25 2003/09/11 21:42:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.26 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -118,21 +118,20 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replacea
  </refsect1>
 
  <refsect1>
-  <title>Diagnostics</title>
+  <title>Outputs</title>
 
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>UPDATE <replaceable class="parameter">count</replaceable></computeroutput></term>
-    <listitem>
-     <para>
-      Message returned if successful.  The value <replaceable
-      class="parameter">count</replaceable> is the number of rows
-      updated.  If <replaceable class="parameter">count</replaceable>
-      is 0, no rows were updated.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
+  <para>
+   On successful completion, an <command>UPDATE</> command returns a command
+   tag of the form
+<screen>
+UPDATE <replaceable class="parameter">count</replaceable>
+</screen>
+   The <replaceable class="parameter">count</replaceable> is the number
+   of rows updated.  If <replaceable class="parameter">count</replaceable> is
+   0, no rows matched the <replaceable
+   class="parameter">condition</replaceable> (this is not considered
+   an error).
+  </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/vacuum.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.32 2003/08/31 17:32:24 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.33 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -143,49 +143,13 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
  </refsect1>
 
  <refsect1>
-  <title>Diagnostics</title>
+  <title>Outputs</title>
 
-  <variablelist>
-   <varlistentry>
-    <term><computeroutput>VACUUM</computeroutput></term>
-    <listitem>
-     <para>
-      The command is complete.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>INFO:  --Relation <replaceable class="PARAMETER">table</replaceable>--</computeroutput></term>
-    <listitem>
-     <para>
-      The report header for <replaceable class="PARAMETER">table</replaceable>.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>INFO:  Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
-         Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
-         Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
-         Elapsed 0/0 sec.</computeroutput></term>
-    <listitem>
-     <para>
-      The analysis for <replaceable class="PARAMETER">table</replaceable> itself.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
-    <term><computeroutput>INFO:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
-         Tuples 1000: Deleted 3000. Elapsed 0/0 sec.</computeroutput></term>
-    <listitem>
-     <para>
-      The analysis for an index on the target table.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
+   <para>
+    When <literal>VERBOSE</> is specified, <command>VACUUM</> emits
+    progress messages to indicate which table is currently being
+    processed.  Various statistics about the tables are printed as well.
+   </para>
  </refsect1>
 
  <refsect1>
@@ -216,25 +180,37 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
   <title>Examples</title>
 
   <para>
-   The following is an example from running <command>VACUUM</command> on a table
-   in the regression database:
+   The following is an example from running <command>VACUUM</command> on a
+   table in the regression database:
 
 <programlisting>
-=> VACUUM VERBOSE ANALYZE onek;
-INFO:  --Relation onek--
-INFO:  Index onek_unique1: Pages 14; Tuples 1000: Deleted 3000.
-        CPU 0.00s/0.11u sec elapsed 0.12 sec.
-INFO:  Index onek_unique2: Pages 16; Tuples 1000: Deleted 3000.
-        CPU 0.00s/0.10u sec elapsed 0.10 sec.
-INFO:  Index onek_hundred: Pages 13; Tuples 1000: Deleted 3000.
-        CPU 0.00s/0.10u sec elapsed 0.10 sec.
-INFO:  Index onek_stringu1: Pages 31; Tuples 1000: Deleted 3000.
-        CPU 0.01s/0.09u sec elapsed 0.10 sec.
-INFO:  Removed 3000 tuples in 70 pages.
-        CPU 0.02s/0.04u sec elapsed 0.07 sec.
-INFO:  Pages 94: Changed 0, Empty 0; Tup 1000: Vac 3000, Keep 0, UnUsed 0.
-        Total CPU 0.05s/0.45u sec elapsed 0.59 sec.
-INFO:  Analyzing onek
+regression=# VACUUM VERBOSE ANALYZE onek;
+INFO:  vacuuming "public.onek"
+INFO:  index "onek_unique1" now contains 1000 tuples in 14 pages
+DETAIL:  3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.01s/0.08u sec elapsed 0.18 sec.
+INFO:  index "onek_unique2" now contains 1000 tuples in 16 pages
+DETAIL:  3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.00s/0.07u sec elapsed 0.23 sec.
+INFO:  index "onek_hundred" now contains 1000 tuples in 13 pages
+DETAIL:  3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.01s/0.08u sec elapsed 0.17 sec.
+INFO:  index "onek_stringu1" now contains 1000 tuples in 48 pages
+DETAIL:  3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.01s/0.09u sec elapsed 0.59 sec.
+INFO:  "onek": removed 3000 tuples in 108 pages
+DETAIL:  CPU 0.01s/0.06u sec elapsed 0.07 sec.
+INFO:  "onek": found 3000 removable, 1000 nonremovable tuples in 143 pages
+DETAIL:  0 dead tuples cannot be removed yet.
+There were 0 unused item pointers.
+0 pages are entirely empty.
+CPU 0.07s/0.39u sec elapsed 1.56 sec.
+INFO:  analyzing "public.onek"
+INFO:  "onek": 36 pages, 1000 rows sampled, 1000 estimated total rows
 VACUUM
 </programlisting>
   </para>

doc/src/sgml/ref/vacuumdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.31 2003/08/31 17:32:24 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.32 2003/09/12 00:12:47 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -55,13 +55,19 @@ PostgreSQL documentation
    <application>vacuumdb</application> is a wrapper around the SQL
    command <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">.
    There is no effective difference between vacuuming databases via
-   this or other methods.  The database server must be running at the
-   targeted host.  Also, any default settings and environment
+   this utility and via other methods for accessing the server.
+  </para>
+
+  <para>
+   In case of difficulty, see <xref linkend="SQL-VACUUM"
+   endterm="sql-vacuum-title"> and <xref linkend="APP-PSQL"> for
+   discussions of potential problems and error messages.
+   The database server must be running at the
+   targeted host.  Also, any default connection settings and environment
    variables used by the <application>libpq</application> front-end
    library will apply.
   </para>
 
-
   <para>
    <application>vacuumdb</application> might need to connect several
    times to the <productname>PostgreSQL</productname> server, asking
@@ -230,37 +236,6 @@ PostgreSQL documentation
  </refsect1>
 
 
- <refsect1>
-  <title>Diagnostics</title>
-
-   <para>
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>VACUUM</computeroutput></term>
-      <listitem>
-       <para>
-        The database was successfully vacuumed.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>vacuumdb: Vacuum failed.</computeroutput></term>
-      <listitem>
-       <para>
-        Something went wrong. <application>vacuumdb</application> is only a wrapper
-        script. See <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">
-        and <xref linkend="APP-PSQL"> for a detailed
-        discussion of error messages and potential problems.
-       </para>
-      </listitem>
-     </varlistentry>
-
-    </variablelist>
-   </para>
- </refsect1>
-
-
  <refsect1>
   <title>Environment</title>