Structure reference pages consistently. Document that structure.

Add information about environment variables.

17 files changed, 1535 insertions, 944 deletions

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 7df4995cfb8..10c0463844f 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.41 2002/03/22 19:20:08 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.42 2002/07/28 15:22:20 petere Exp $ -->
 
 <appendix id="docguide">
  <title>Documentation</title>
@@ -1254,6 +1254,196 @@ End:
 
  </sect1>
 
+
+ <sect1 id="doc-style">
+  <title>Style Guide</title>
+
+  <sect2>
+   <title>Reference Pages</title>
+
+   <para>
+    Reference pages should follow a standard layout.  This allows
+    users to find the desired information more quickly, and it also
+    encourages writers to document all relevant aspects of a command.
+    Consistency is not only desired among
+    <productname>PostgreSQL</productname> reference pages, but also
+    with reference pages provided by the operating system and other
+    packages.  Hence the following guidelines have been developed.
+    They are for the most part consistent with similar guidelines
+    established by various operating systems.
+   </para>
+
+   <para>
+    Reference pages that describe executable commands should contain
+    the following sections, in this order.  Sections that do not apply
+    may be omitted.  Additional top-level sections should only be used
+    in special circumstances; often that information belongs in the
+    <quote>Usage</quote> section.
+
+    <variablelist>
+     <varlistentry>
+      <term>Name</term>
+      <listitem>
+       <para>
+        This section is generated automatically.  It contains the
+        command name and a half-sentence summary of its functionality.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>Synopsis</term>
+      <listitem>
+       <para>
+        This section contains the syntax diagram of the command.  The
+        synopsis should normally not list each command-line option;
+        that is done below.  Instead, list the major components of the
+        command line, such as where input and output files go.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Description</term>
+      <listitem>
+       <para>
+        Several paragraphs explaining what the command does.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Options</term>
+      <listitem>
+       <para>
+        A list describing each command-line option.  If there are a
+        lot of options, subsections may be used.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Exit Status</term>
+      <listitem>
+       <para>
+        If the program uses 0 for success and non-zero for failure,
+        then you don't need to document it.  If there is a meaning
+        behind the different non-zero exit codes, list them here.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Usage</term>
+      <listitem>
+       <para>
+        Describe any sublanguage or run-time interface of the program.
+        If the program is not interactive, this section can usually be
+        omitted.  Otherwise, this section is a catch-all for
+        describing run-time features.  Use subsections if appropriate.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Environment</term>
+      <listitem>
+       <para>
+        List all environment variables that the program might use.
+        Try to be complete; even seemingly trivial variables like
+        <envar>SHELL</envar> might be of interest to the user.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Files</term>
+      <listitem>
+       <para>
+        List any files that the program might access implicitly.  That
+        is, do not list input and output files that were specified on
+        the command line, but list configuration files, etc.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Diagnostics</term>
+      <listitem>
+       <para>
+        Explain any unusual output that the program might create.
+        Refrain from listing every possible error message.  This is a
+        lot of work and has little use in practice.  But if, say, the
+        error messages have a standard format that the user can parse,
+        this would be the place to explain it.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Notes</term>
+      <listitem>
+       <para>
+        Anything that doesn't fit elsewhere, but in particular bugs,
+        implementation flaws, security considerations, compatibility
+        issues.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>Examples</term>
+      <listitem>
+       <para>
+        Examples
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>History</term>
+      <listitem>
+       <para>
+        If there were some major milestones in the history of the
+        program, they might be listed here.  Usually, this section can
+        be omitted.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>See Also</term>
+      <listitem>
+       <para>
+        Cross-references, listed in the following order: other
+        <productname>PostgreSQL</productname> command reference pages,
+        <productname>PostgreSQL</productname> SQL command reference
+        pages, citation of <productname>PostgreSQL</productname>
+        manuals, other reference pages (e.g., operating system, other
+        packages), other documentation.  Items in the same group are
+        listed alphabetically.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+
+   <para>
+    Reference pages describing SQL commands should contain the
+    following sections: Name, Synopsis, Description, Parameters,
+    Usage, Diagnostics, Notes, Examples, Compatibility, History, See
+    Also.  The Parameters section is like the Options section, but
+    there is more freedom about which clauses of the command can be
+    listed.  The Compatibility section should explain to what extent
+    this command conforms to the SQL standard(s), or to which other
+    database system it is compatible.  The See Also section of SQL
+    commands should list SQL commands before cross-references to
+    programs.
+   </para>
+  </sect2>
+
+ </sect1>
 </appendix>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index 8c3723ca0e9..d0849388cd5 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.27 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -22,12 +22,42 @@ PostgreSQL documentation
    <arg><replaceable>dbname</replaceable></arg>
    <arg><replaceable>description</replaceable></arg>
   </cmdsynopsis>
+ </refsynopsisdiv>
 
-  <refsect2 id="R2-APP-CREATEDB-1">
-   <title>
-    Inputs
-   </title>
-   <para>
+
+ <refsect1 id="R1-APP-CREATEDB-1">
+  <title>
+   Description
+  </title>
+  <para>
+   <application>createdb</application> creates a new <productname>PostgreSQL</productname>
+   database.
+  </para>
+
+  <para>
+   Normally, the database user who executes this command becomes the owner of
+   the new database.
+   However a different owner can be specified via the <option>-O</option>
+   option, if the executing user has appropriate privileges.
+  </para>
+
+  <para>
+   <application>createdb</application> is a shell script wrapper around the
+   <acronym>SQL</acronym> command
+   <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
+   the <productname>PostgreSQL</productname> interactive terminal
+   <xref linkend="APP-PSQL">. Thus, there is nothing
+   special about creating databases via this or other methods. This means
+   that the <application>psql</application> program must be found by the script and that
+   a database server must be running at the targeted port. Also, any default
+   settings and environment variables available to <application>psql</application>
+   and the <application>libpq</application> front-end library will apply.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Options</title>
 
     <variablelist>
      <varlistentry>
@@ -149,6 +179,7 @@ PostgreSQL documentation
 
     </variablelist>
 
+   <para>
     The options <option>-h</option>, <option>-p</option>, <option>-U</option>,
     <option>-W</option>, and <option>-e</option> are passed on literally to
     <xref linkend="app-psql">.
@@ -160,13 +191,12 @@ PostgreSQL documentation
     endterm="SQL-CREATEDATABASE-title">; see there for more information
     about them.
    </para>
-  </refsect2>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Diagnostics</title>
 
-  <refsect2 id="R2-APP-CREATEDB-2">
-   <title>
-    Outputs
-   </title>
-   <para>
     <variablelist>
      <varlistentry>
       <term><computeroutput>CREATE DATABASE</computeroutput></term>
@@ -195,45 +225,37 @@ PostgreSQL documentation
      </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">
     and <xref linkend="APP-PSQL"> for possibilities.
    </para>
-  </refsect2>
- </refsynopsisdiv>
+ </refsect1>
 
- <refsect1 id="R1-APP-CREATEDB-1">
-  <title>
-   Description
-  </title>
-  <para>
-   <application>createdb</application> creates a new <productname>PostgreSQL</productname>
-   database.
-  </para>
 
-  <para>
-   Normally, the database user who executes this command becomes the owner of
-   the new database.
-   However a different owner can be specified via the <option>-O</option>
-   option, if the executing user has appropriate privileges.
-  </para>
+ <refsect1>
+  <title>Environment</title>
 
-  <para>
-   <application>createdb</application> is a shell script wrapper around the
-   <acronym>SQL</acronym> command
-   <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
-   the <productname>PostgreSQL</productname> interactive terminal
-   <xref linkend="APP-PSQL">. Thus, there is nothing
-   special about creating databases via this or other methods. This means
-   that the <application>psql</application> program must be found by the script and that
-   a database server must be running at the targeted port. Also, any default
-   settings and environment variables available to <application>psql</application>
-   and the <application>libpq</application> front-end library will apply.
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.  <envar>PGUSER</envar> also
+      determines the name of the database to create, if it is not
+      specified in the command line.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
+
  <refsect1 id="R1-APP-CREATEDB-2">
-  <title>Usage</title>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -262,6 +284,17 @@ PostgreSQL documentation
    </para>
   </informalexample>
  </refsect1>
+
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-dropdb"></member>
+   <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml
index 279f967412f..7ad26ae82e9 100644
--- a/doc/src/sgml/ref/createlang.sgml
+++ b/doc/src/sgml/ref/createlang.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.24 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.25 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -11,7 +11,7 @@ PostgreSQL documentation
  </refmeta>
 
  <refnamediv>
-  <refname id="createlang">createlang</refname>
+  <refname>createlang</refname>
   <refpurpose>define a new <productname>PostgreSQL</productname> procedural language</refpurpose>
  </refnamediv>
 
@@ -27,11 +27,33 @@ PostgreSQL documentation
    <group choice="plain"><arg>--list</arg><arg>-l</arg></group>
    <arg choice="plain"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
+ </refsynopsisdiv>
+
+ 
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <application>createlang</application> is a utility for adding a new 
+   programming language to a <productname>PostgreSQL</productname> database.
+   <application>createlang</application> can handle all the languages
+   supplied in the default <productname>PostgreSQL</> distribution, but
+   not languages provided by other parties.
+  </para>
+  <para>
+   Although backend programming languages can be added directly using
+   several <acronym>SQL</acronym> commands, it is recommended to use
+   <application>createlang</application> because it performs a number
+   of checks and is much easier to use. See
+   <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
+   for more.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Options</title>
 
-  <refsect2 id="R2-APP-CREATELANG-1">
-   <title>
-    Inputs
-   </title>
    <para>
     <application>createlang</application> accepts the following command line arguments:
     
@@ -138,12 +160,31 @@ PostgreSQL documentation
 
     </variablelist>
    </para>
-  </refsect2>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Diagnostics</title>
 
-  <refsect2 id="R2-APP-CREATELANG-2">
-   <title>
-    Outputs
-   </title>
    <para>
     Most error messages are self-explanatory. If not, run
     <application>createlang</application> with the <option>--echo</option>
@@ -151,35 +192,12 @@ PostgreSQL documentation
     for details. Check also under <xref linkend="APP-PSQL">
     for more possibilities.
    </para>
-  </refsect2>
- </refsynopsisdiv>
- 
- <refsect1 id="R1-APP-CREATELANG-1">
-  <title>
-   Description
-  </title>
-
-  <para>
-   <application>createlang</application> is a utility for adding a new 
-   programming language to a <productname>PostgreSQL</productname> database.
-   <application>createlang</application> can handle all the languages
-   supplied in the default <productname>PostgreSQL</> distribution, but
-   not languages provided by other parties.
-  </para>
-  <para>
-   Although backend programming languages can be added directly using
-   several <acronym>SQL</acronym> commands, it is recommended to use
-   <application>createlang</application> because it performs a number
-   of checks and is much easier to use. See
-   <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
-   for more.
-  </para>
  </refsect1>
 
- <refsect1 id="R1-APP-CREATELANG-2">
-  <title>
-   Notes
-  </title>
+
+ <refsect1>
+  <title>Notes</title>
+
   <para>
    Use <xref linkend="app-droplang"> to remove a language.
   </para>
@@ -192,8 +210,9 @@ PostgreSQL documentation
   </para>
  </refsect1>
  
- <refsect1 id="R1-APP-CREATELANG-3">
-  <title>Usage</title>
+
+ <refsect1>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -205,6 +224,16 @@ PostgreSQL documentation
    </para>
   </informalexample>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-droplang"></member>
+   <member><xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index ed92bb2d86e..d4be6e7b25d 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.25 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.26 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -21,12 +21,46 @@ PostgreSQL documentation
    <arg rep="repeat"><replaceable>options</replaceable></arg>
    <arg><replaceable>username</replaceable></arg>
   </cmdsynopsis>
+ </refsynopsisdiv>
+  
 
-  <refsect2 id="R2-APP-CREATEUSER-1">
-   <title>
-    Inputs
-   </title>
-   <para>
+ <refsect1>
+  <title>Description</title>
+  <para>
+   <application>createuser</application> creates a 
+   new <productname>PostgreSQL</productname> user.  
+   Only superusers (users with <literal>usesuper</literal> set in
+   the <literal>pg_shadow</literal> table) can create 
+   new <productname>PostgreSQL</productname> users,
+   so <application>createuser</application> must be
+   invoked by someone who is a <productname>PostgreSQL</productname>
+   superuser.
+  </para>
+
+  <para>
+   Being a superuser also implies the ability to bypass access permission
+   checks within the database, so superuser-dom should not be granted lightly.
+  </para>
+
+  <para>
+   <application>createuser</application> is a shell script wrapper around the
+   <acronym>SQL</acronym> command
+   <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via
+   the <productname>PostgreSQL</productname> interactive terminal
+   <xref linkend="APP-PSQL">. Thus, there is nothing
+   special about creating users via this or other methods. This means
+   that the <application>psql</application> application must be found by the
+   script and that 
+   a database server must be running at the targeted host. Also, any default
+   settings and environment variables used by <application>psql</application>
+   and the <application>libpq</application> front-end library will apply.
+  </para>
+
+ </refsect1>
+
+
+ <refsect1>
+  <title>Options</title>
 
     <variablelist>
      <varlistentry>
@@ -162,6 +196,7 @@ PostgreSQL documentation
      </varlistentry>  
     </variablelist>
 
+   <para>
     You will be prompted for a name and other missing information if it is not
     specified on the command line.
     </para>
@@ -172,13 +207,31 @@ PostgreSQL documentation
     <application>psql</application> options <literal>-U</literal> and <literal>-W</literal>
     are available as well, but their use can be confusing in this context.
    </para>
-  </refsect2>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Diagnostics</title>
 
-  <refsect2 id="R2-APP-CREATEUSER-2">
-   <title>
-    Outputs
-   </title>
-   <para>
     <variablelist>
      <varlistentry>
       <term><computeroutput>CREATE USER</computeroutput></term>
@@ -200,52 +253,16 @@ PostgreSQL documentation
 
     </variablelist>
 
+   <para>
     If there is an error condition, the backend error message will be displayed.
     See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
     and <xref linkend="APP-PSQL"> for possibilities.
    </para>
-  </refsect2>
- </refsynopsisdiv>
-  
- <refsect1 id="R1-APP-CREATEUSER-1">
-  <title>
-   Description
-  </title>
-  <para>
-   <application>createuser</application> creates a 
-   new <productname>PostgreSQL</productname> user.  
-   Only superusers (users with <literal>usesuper</literal> set in
-   the <literal>pg_shadow</literal> table) can create 
-   new <productname>PostgreSQL</productname> users,
-   so <application>createuser</application> must be
-   invoked by someone who is a <productname>PostgreSQL</productname>
-   superuser.
-  </para>
-
-  <para>
-   Being a superuser also implies the ability to bypass access permission
-   checks within the database, so superuser-dom should not be granted lightly.
-  </para>
-
-  <para>
-   <application>createuser</application> is a shell script wrapper around the
-   <acronym>SQL</acronym> command
-   <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via
-   the <productname>PostgreSQL</productname> interactive terminal
-   <xref linkend="APP-PSQL">. Thus, there is nothing
-   special about creating users via this or other methods. This means
-   that the <application>psql</application> application must be found by the
-   script and that 
-   a database server must be running at the targeted host. Also, any default
-   settings and environment variables used by <application>psql</application>
-   and the <application>libpq</application> front-end library will apply.
-  </para>
-
  </refsect1>
 
 
- <refsect1 id="R1-APP-CREATEUSER-2">
-  <title>Usage</title>
+ <refsect1>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -274,6 +291,16 @@ PostgreSQL documentation
   </informalexample>
  </refsect1>
 
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-dropuser"></member>
+   <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml
index ecbfef2b82e..e2fd2e3eccf 100644
--- a/doc/src/sgml/ref/dropdb.sgml
+++ b/doc/src/sgml/ref/dropdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.16 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -21,12 +21,36 @@ PostgreSQL documentation
    <arg rep="repeat"><replaceable>options</replaceable></arg>
    <arg choice="plain"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
+ </refsynopsisdiv>
 
-  <refsect2 id="R2-APP-DROPDB-1">
-   <title>
-    Inputs
-   </title>
-   <para>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <application>dropdb</application> destroys an existing
+   <productname>PostgreSQL</productname> database.
+   The user who executes this command must be a database
+   superuser or the owner of the database.
+  </para>
+
+  <para>
+   <application>dropdb</application> is a shell script wrapper around the
+   <acronym>SQL</acronym> command
+   <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> via
+   the <productname>PostgreSQL</productname> interactive terminal
+   <xref linkend="APP-PSQL">. Thus, there is nothing
+   special about dropping databases via this or other methods. This means
+   that the <application>psql</application> must be found by the script and that
+   a database server is running at the targeted host. Also, any default
+   settings and environment variables available to <application>psql</application>
+   and the <application>libpq</application> front-end library do apply.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+   <title>Options</title>
 
     <variablelist>
      <varlistentry>
@@ -110,18 +134,16 @@ PostgreSQL documentation
      </varlistentry>
     </variablelist>
 
+   <para>
     The options <literal>-h</literal>, <literal>-p</literal>, <literal>-U</literal>,
     <literal>-W</literal>, and <literal>-e</literal> are passed on literally to
     <xref linkend="APP-PSQL">.
    </para>
-  </refsect2>
+ </refsect1>
 
 
-  <refsect2 id="R2-APP-DROPDB-2">
-   <title>
-    Outputs
-   </title>
-   <para>
+ <refsect1>
+   <title>Diagnostics</title>
 
     <variablelist>
      <varlistentry>
@@ -139,41 +161,35 @@ PostgreSQL documentation
      </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">
     and <xref linkend="APP-PSQL"> for possibilities.
    </para>
-  </refsect2>
- </refsynopsisdiv>
+ </refsect1>
 
 
- <refsect1 id="R1-APP-DROPDB-1">
-  <title>
-   Description
-  </title>
-  <para>
-   <application>dropdb</application> destroys an existing
-   <productname>PostgreSQL</productname> database.
-   The user who executes this command must be a database
-   superuser or the owner of the database.
-  </para>
+ <refsect1>
+  <title>Environment</title>
 
-  <para>
-   <application>dropdb</application> is a shell script wrapper around the
-   <acronym>SQL</acronym> command
-   <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> via
-   the <productname>PostgreSQL</productname> interactive terminal
-   <xref linkend="APP-PSQL">. Thus, there is nothing
-   special about dropping databases via this or other methods. This means
-   that the <application>psql</application> must be found by the script and that
-   a database server is running at the targeted host. Also, any default
-   settings and environment variables available to <application>psql</application>
-   and the <application>libpq</application> front-end library do apply.
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
+
  <refsect1 id="R1-APP-DROPDB-2">
-  <title>Usage</title>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -201,6 +217,17 @@ DROP DATABASE</computeroutput>
    </para>
   </informalexample>
  </refsect1>
+
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-createdb"></member>
+   <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml
index c6eadb401f8..186af6e2a09 100644
--- a/doc/src/sgml/ref/droplang.sgml
+++ b/doc/src/sgml/ref/droplang.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.18 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.19 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -11,7 +11,7 @@ PostgreSQL documentation
  </refmeta>
 
  <refnamediv>
-  <refname id="droplang">droplang</refname>
+  <refname>droplang</refname>
   <refpurpose>remove a <productname>PostgreSQL</productname> procedural language</refpurpose>
  </refnamediv>
 
@@ -27,11 +27,34 @@ PostgreSQL documentation
    <group choice="plain"><arg>--list</arg><arg>-l</arg></group>
    <arg choice="plain"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+ <refsect1 id="R1-APP-DROPLANG-1">
+  <title>
+   Description
+  </title>
+
+  <para>
+   <application>droplang</application> is a utility for removing an 
+   existing programming language from a
+   <productname>PostgreSQL</productname> database.
+   <application>droplang</application> can drop any procedural language,
+   even those not supplied by the <productname>PostgreSQL</> distribution.
+  </para>
+  <para>
+   Although backend programming languages can be removed directly using
+   several <acronym>SQL</acronym> commands, it is recommended to use
+   <application>droplang</application> because it performs a number
+   of checks and is much easier to use. See
+   <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">
+   for more.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Options</title>
 
-  <refsect2 id="R2-APP-DROPLANG-1">
-   <title>
-    Inputs
-   </title>
    <para>
     <application>droplang</application> accepts the following command line arguments:
     
@@ -126,12 +149,31 @@ PostgreSQL documentation
 
     </variablelist>
    </para>
-  </refsect2>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+
+ <refsect1>
+   <title>Diagnostics</title>
 
-  <refsect2 id="R2-APP-DROPLANG-2">
-   <title>
-    Outputs
-   </title>
    <para>
     Most error messages are self-explanatory. If not, run
     <application>droplang</application> with the <option>--echo</option>
@@ -139,43 +181,20 @@ PostgreSQL documentation
     for details. Check also under <xref linkend="APP-PSQL">
     for more possibilities.
    </para>
-  </refsect2>
- </refsynopsisdiv>
- 
- <refsect1 id="R1-APP-DROPLANG-1">
-  <title>
-   Description
-  </title>
-
-  <para>
-   <application>droplang</application> is a utility for removing an 
-   existing programming language from a
-   <productname>PostgreSQL</productname> database.
-   <application>droplang</application> can drop any procedural language,
-   even those not supplied by the <productname>PostgreSQL</> distribution.
-  </para>
-  <para>
-   Although backend programming languages can be removed directly using
-   several <acronym>SQL</acronym> commands, it is recommended to use
-   <application>droplang</application> because it performs a number
-   of checks and is much easier to use. See
-   <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">
-   for more.
-  </para>
  </refsect1>
 
- <refsect1 id="R1-APP-DROPLANG-2">
-  <title>
-   Notes
-  </title>
+
+ <refsect1>
+  <title>Notes</title>
 
   <para>
    Use <xref linkend="app-createlang"> to add a language.
   </para>
  </refsect1>
  
- <refsect1 id="R1-APP-DROPLANG-3">
-  <title>Usage</title>
+
+ <refsect1>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -186,6 +205,16 @@ PostgreSQL documentation
    </para>
   </informalexample>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-createlang"></member>
+   <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml
index 9741d10707a..5d45347ee1c 100644
--- a/doc/src/sgml/ref/dropuser.sgml
+++ b/doc/src/sgml/ref/dropuser.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.18 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.19 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -21,12 +21,38 @@ PostgreSQL documentation
    <arg rep="repeat"><replaceable>options</replaceable></arg>
    <arg><replaceable>username</replaceable></arg>
   </cmdsynopsis>
+ </refsynopsisdiv>
 
-  <refsect2 id="R2-APP-DROPUSER-1">
-   <title>
-    Inputs
-   </title>
-   <para>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <application>dropuser</application> removes an existing
+   <productname>PostgreSQL</productname> user
+   <emphasis>and</emphasis> the databases which that user owned.
+   Only users with <literal>usesuper</literal> set in
+   the <literal>pg_shadow</literal> table can destroy 
+   <productname>PostgreSQL</productname> users.
+  </para>
+
+  <para>
+   <application>dropuser</application> is a shell script wrapper around the
+   <acronym>SQL</acronym> command
+   <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> via
+   the <productname>PostgreSQL</productname> interactive terminal
+   <xref linkend="APP-PSQL">. Thus, there is nothing
+   special about removing users via this or other methods. This means
+   that the <application>psql</application> must be found by the script and that
+   a database server is running at the targeted host. Also, any default
+   settings and environment variables available to <application>psql</application>
+   and the <application>libpq</application> front-end library do apply.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Options</title>
 
     <variablelist>
      <varlistentry>
@@ -91,7 +117,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
     </variablelist>
-    </para>
 
     <para>
     The options <literal>-h</literal>, <literal>-p</literal>, and <literal>-e</literal>,
@@ -99,14 +124,31 @@ PostgreSQL documentation
     <application>psql</application> options <literal>-U</literal> and <literal>-W</literal>
     are available as well, but they can be confusing in this context.
    </para>
-  </refsect2>
+ </refsect1>
 
-  <refsect2 id="R2-APP-DROPUSER-2">
-   <title>
-    Outputs
-   </title>
 
-   <para>
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+
+ <refsect1>
+   <title>Diagnostics</title>
+
     <variablelist>
      <varlistentry>
       <term><computeroutput>DROP USER</computeroutput></term>
@@ -128,43 +170,16 @@ PostgreSQL documentation
 
     </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>
-  </refsect2>
- </refsynopsisdiv>
-
- <refsect1 id="R1-APP-DROPUSER-1">
-  <title>
-   Description
-  </title>
-  <para>
-   <application>dropuser</application> removes an existing
-   <productname>PostgreSQL</productname> user
-   <emphasis>and</emphasis> the databases which that user owned.
-   Only users with <literal>usesuper</literal> set in
-   the <literal>pg_shadow</literal> table can destroy 
-   <productname>PostgreSQL</productname> users.
-  </para>
-
-  <para>
-   <application>dropuser</application> is a shell script wrapper around the
-   <acronym>SQL</acronym> command
-   <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> via
-   the <productname>PostgreSQL</productname> interactive terminal
-   <xref linkend="APP-PSQL">. Thus, there is nothing
-   special about removing users via this or other methods. This means
-   that the <application>psql</application> must be found by the script and that
-   a database server is running at the targeted host. Also, any default
-   settings and environment variables available to <application>psql</application>
-   and the <application>libpq</application> front-end library do apply.
-  </para>
-
  </refsect1>
 
- <refsect1 id="R1-APP-DROPUSER-2">
-  <title>Usage</title>
+
+ <refsect1>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -193,6 +208,16 @@ DROP USER</computeroutput>
   </informalexample>
  </refsect1>
 
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-createuser"></member>
+   <member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml
index e7e5a4a8a35..44711a8d197 100644
--- a/doc/src/sgml/ref/ecpg-ref.sgml
+++ b/doc/src/sgml/ref/ecpg-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.19 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.20 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -9,6 +9,7 @@ PostgreSQL documentation
   <manvolnum>1</manvolnum>
   <refmiscinfo>Application</refmiscinfo>
  </refmeta>
+
  <refnamediv>
   <refname>
    <application>ecpg</application>
@@ -17,6 +18,7 @@ PostgreSQL documentation
    embedded SQL C preprocessor
   </refpurpose>
  </refnamediv>
+
  <refsynopsisdiv>
   <refsynopsisdivinfo>
    <date>1999-07-20</date>
@@ -29,14 +31,33 @@ PostgreSQL documentation
    <arg choice="opt">-o <replaceable>outfile</replaceable></arg>
    <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
   </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="APP-ECPG-description">
+  <title>Description</title>
+
+  <para>
+   <application>ecpg</application>
+   is an embedded SQL preprocessor for the C language and the
+   <productname>PostgreSQL</productname>. It
+   enables development of C programs with embedded SQL code.
+  </para>
+
+  <para>
+   Linus Tolke (<email>linus@epact.se</email>) was the
+   original author of <application>ecpg</application> (up to version 0.2).
+   Michael Meskes (<email>meskes@debian.org</email>)
+   is the current author and maintainer of <application>ecpg</application>.
+   Thomas Good (<email>tomg@q8.nrnet.org</email>)
+   is the author of the last revision of the <application>ecpg</application> man page, on which
+   this document is based.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Options</title>
 
-  <refsect2 id="R2-APP-ECPG-1">
-   <refsect2info>
-    <date>1999-07-20</date>
-   </refsect2info>
-   <title>
-    Inputs
-   </title>
    <para>
     <application>ecpg</application> accepts the following command
     line arguments:
@@ -104,58 +125,23 @@ PostgreSQL documentation
      </varlistentry>
     </variablelist>
    </para>
-  </refsect2>
-
-  <refsect2 id="R2-APP-ECPG-2">
-   <refsect2info>
-    <date>1998-11-05</date>
-   </refsect2info>
-   <title>
-    Outputs
-   </title>
-   <para>
-    <application>ecpg</application> will create a file or
-    write to <filename>stdout</filename>.
+ </refsect1>
 
-    <variablelist>
-     <varlistentry>
-      <term>Return value</term>
-      <listitem>
-       <para>
-	<application>ecpg</application> returns 0 to the shell on successful completion, non-zero
-	for errors.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
-   </para>
-  </refsect2>
- </refsynopsisdiv>
 
- <refsect1 id="R1-APP-ECPG-description">
-  <title>Description</title>
-  <para>
-   <application>ecpg</application>
-   is an embedded SQL preprocessor for the C language and the
-   <productname>PostgreSQL</productname>. It
-   enables development of C programs with embedded SQL code.
-  </para>
+ <refsect1>
+  <title>Exit Status</title>
 
   <para>
-   Linus Tolke (<email>linus@epact.se</email>) was the
-   original author of <application>ecpg</application> (up to version 0.2).
-   Michael Meskes (<email>meskes@debian.org</email>)
-   is the current author and maintainer of <application>ecpg</application>.
-   Thomas Good (<email>tomg@q8.nrnet.org</email>)
-   is the author of the last revision of the <application>ecpg</application> man page, on which
-   this document is based.
+   <application>ecpg</application> returns 0 to the shell on
+   successful completion, non-zero for errors.
   </para>
  </refsect1>
 
- <refsect1 id="R1-APP-ECPG-2">
+
+ <refsect1>
   <title>Usage</title>
 
-  <refsect2 id="R2-APP-ECPG-preprocessing">
+  <refsect2 id="APP-ECPG-preprocessing">
    <title>Preprocessing for Compilation</title>
 
    <para>
@@ -175,7 +161,7 @@ ecpg [ -d ] [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceabl
    </para>
   </refsect2>
 
-  <refsect2 id="R2-APP-ECPG-compiling">
+  <refsect2 id="APP-ECPG-compiling">
    <title>Compiling and Linking</title>
 
    <para>
@@ -190,10 +176,10 @@ gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <repla
   </refsect2>
  </refsect1>
 
- <refsect1 id="R1-APP-ECPG-grammar">
+ <refsect1 id="APP-ECPG-grammar">
   <title>Grammar</title>
 
-  <refsect2 id="R2-APP-ECPG-library">
+  <refsect2 id="APP-ECPG-library">
    <title>Libraries</title>
 
    <para>
@@ -206,7 +192,7 @@ gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <repla
    </para>
   </refsect2>
 
-  <refsect2 id="R2-APP-declaration">
+  <refsect2 id="APP-ecpg-declaration">
    <title>Variable Declaration</title>
 
    <para>
@@ -237,7 +223,7 @@ char  foo[16], bar[16];
    </para>
   </refsect2>
 
-  <refsect2 id="R2-APP-ECPG-errors">
+  <refsect2 id="APP-ECPG-errors">
    <title>Error Handling</title>
 
    <para>
@@ -292,7 +278,7 @@ EXEC SQL WHENEVER not found sqlprint;
     </note>
   </refsect2>
 
-  <refsect2 id="R2-APP-ECPG-connecting">
+  <refsect2 id="APP-ECPG-connecting">
    <title>Connecting to the Database Server</title>
 
    <para>
@@ -322,7 +308,7 @@ EXEC SQL CONNECT TO <replaceable>dbname</replaceable>;
    </para>
   </refsect2>
 
-  <refsect2 id="R2-APP-ECPG-queries">
+  <refsect2 id="APP-ECPG-queries">
    <title>Queries</title>
 
    <para>
@@ -393,7 +379,7 @@ EXEC SQL COMMIT;
   </refsect2>
  </refsect1>
 
- <refsect1 id="R1-APP-ECPG-notes">
+ <refsect1 id="APP-ECPG-notes">
   <title>Notes</title>
   <para>
    The complete structure definition MUST be listed
@@ -406,6 +392,17 @@ EXEC SQL COMMIT;
   </para>
 
  </refsect1>
+
+
+ <refsect1>
+  <title>See Also</title>
+
+  <para>
+   <citetitle>PostgreSQL Programmer's Guide</citetitle> for a more
+   detailed description of the embedded SQL interface.
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml
index 917deadbbeb..e37e0a40e1f 100644
--- a/doc/src/sgml/ref/initlocation.sgml
+++ b/doc/src/sgml/ref/initlocation.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.16 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -39,7 +39,7 @@ PostgreSQL documentation
  </refsect1>
 
  <refsect1 id="R1-APP-INITLOCATION-2">
-  <title>Usage</title>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -68,6 +68,15 @@ PostgreSQL documentation
    </para>
   </informalexample>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><citetitle>PostgreSQL Administrator's Guide</citetitle></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index da545ab6fe2..397098302ed 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.14 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.15 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -225,9 +225,32 @@ PostgreSQL documentation
     </variablelist>
    </para>
   </refsect2>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Environment</title>
 
-  <refsect2>
-   <title>Files</title>
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGDATA</envar></term>
+
+    <listitem>
+     <para>
+      Default data direction location
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   For others, see <xref linkend="app-postmaster">.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Files</title>
 
    <para>
     If the file <filename>postmaster.opts.default</filename> exists in
@@ -235,8 +258,17 @@ PostgreSQL documentation
     options to the <application>postmaster</application>, unless
     overridden by the <option>-o</option> option.
    </para>
-  </refsect2>
+ </refsect1>
+
 
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   Waiting for complete start is not a well-defined operation and may
+   fail if access control is set up so that a local client cannot
+   connect without manual interaction.  It should be avoided.
+  </para>
  </refsect1>
 
 
@@ -330,15 +362,6 @@ Command line was:
   </refsect2>
  </refsect1>
 
- <refsect1>
-  <title>Bugs</title>
-
-  <para>
-   Waiting for complete start is not a well-defined operation and may
-   fail if access control is set up so that a local client cannot
-   connect without manual interaction.  It should be avoided.
-  </para>
- </refsect1>
 
  <refsect1>
   <title>See Also</title>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d2ab719fe34..7969489f11c 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.45 2002/05/10 22:36:26 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.46 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -582,6 +582,34 @@ PostgreSQL documentation
 
  </refsect1>
 
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGDATABASE</envar></term>
+
+    <listitem>
+     <para>
+      Database to dump, unless overridden on the command line.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
  <refsect1 id="app-pgdump-diagnostics">
   <title>Diagnostics</title>
 
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 44e38f28bc6..9e5f4452d0d 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.28 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.29 2002/07/28 15:22:20 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -152,6 +152,26 @@ PostgreSQL documentation
   </refsect2>
  </refsect1>
 
+
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+
  <refsect1 id="app-pg-dumpall-ex">
   <title>Examples</title>
   <para>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 0d951621d16..e89d76bbc1b 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.28 2002/07/13 00:55:53 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.29 2002/07/28 15:22:20 petere Exp $ -->
 
 <refentry id="APP-PGRESTORE">
  <docinfo>
@@ -496,6 +496,25 @@
  </refsect1>
 
 
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+
  <refsect1 id="app-pgrestore-diagnostics">
   <title>Diagnostics</title>
 
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index f78c0533201..a242dcc863d 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.27 2002/07/28 15:22:21 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -350,6 +350,28 @@ PostgreSQL documentation
  </refsect1>
 
  <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGDATA</envar></term>
+
+    <listitem>
+     <para>
+      Default data direction location
+     </para>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+
+  <para>
+   For others, which have little influence during single-user mode,
+   see <xref linkend="app-postmaster">.
+  </para>
+ </refsect1>
+
+ <refsect1>
   <title>Usage</title>
 
    <para>
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 0d2a7e93dd2..f052e5af6ee 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.30 2002/06/15 19:52:56 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.31 2002/07/28 15:22:21 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -338,10 +338,82 @@ PostgreSQL documentation
    </para>
   </refsect2>
 
-  <refsect2 id="R2-APP-POSTMASTER-2">
-   <title>
-    Outputs
-   </title>
+ </refsect1>
+
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGCLIENTENCODING</envar></term>
+
+    <listitem>
+     <para>
+      Default character encoding used by clients.  (The clients may
+      override this invidiually.)  This value can also be set in the
+      configuration file.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGDATA</envar></term>
+
+    <listitem>
+     <para>
+      Default data direction location
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGDATASTYLE</envar></term>
+
+    <listitem>
+     <para>
+      Default value of the <literal>datestyle</literal> run-time
+      parameter.  (The use of this environment variable is deprecated.)
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGPORT</envar></term>
+
+    <listitem>
+     <para>
+      Default port (preferrably set in the configuration file)
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>TZ</envar></term>
+
+    <listitem>
+     <para>
+      Server time zone
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term>others</term>
+
+    <listitem>
+     <para>
+      Other environment variables may be used to designate alternative
+      data storage locations.  See the <citetitle>Administrator's
+      Guide</citetitle> for more information.
+     </para>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
+   <title>Diagnostics</title>
    <para>
 
     <variablelist>
@@ -417,7 +489,6 @@ StreamServerPort: cannot bind to port
      </varlistentry>
     </variablelist>
    </para>
-  </refsect2>
  </refsect1>
 
  <refsect1>
@@ -457,8 +528,8 @@ StreamServerPort: cannot bind to port
 
  </refsect1>
 
- <refsect1 id="app-postmaster-usage">
-  <title>Usage</title>
+ <refsect1 id="app-postmaster-examples">
+  <title>Examples</title>
   <para>
    To start <application>postmaster</application> in the background
    using default values, type:
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 923a8741112..b9f8554abfb 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,13 +1,9 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.68 2002/07/15 01:56:25 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.69 2002/07/28 15:22:21 petere Exp $
 PostgreSQL documentation
 -->
 
 <refentry id="APP-PSQL">
- <docinfo>
-  <date>2000-12-25</date>
- </docinfo>
-
   <refmeta>
     <refentrytitle id="app-psql-title"><application>psql</application></refentrytitle>
     <manvolnum>1</manvolnum>
@@ -21,19 +17,17 @@ PostgreSQL documentation
     </refpurpose>
   </refnamediv>
 
-  <refsynopsisdiv>
-    <refsynopsisdivinfo>
-      <date>1999-10-26</date>
-    </refsynopsisdivinfo>
-
-    <synopsis>psql [ <replaceable class="parameter">options</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">user</replaceable> ] ]</synopsis>
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>psql</command>
+   <arg><replaceable class="parameter">options</replaceable></arg>
+   <arg><replaceable class="parameter">dbname</replaceable>
+     <arg><replaceable class="parameter">user</replaceable></arg></arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
 
-  <refsect2 id="R2-APP-PSQL-1">
-    <refsect2info>
-      <date>1998-09-26</date>
-    </refsect2info>
-
-    <title>Summary</title>
+ <refsect1>
+  <title>Description</title>
 
     <para>
      <application>psql</application> is a terminal-based front-end to
@@ -44,23 +38,412 @@ PostgreSQL documentation
      number of meta-commands and various shell-like features to
      facilitate writing scripts and automating a wide variety of tasks.
     </para>
+ </refsect1>
 
-  </refsect2>
+ <refsect1 id="R1-APP-PSQL-3">
+  <title>Options</title>
 
-</refsynopsisdiv>
+  <para>
+   If so configured, <application>psql</application> understands both
+   standard Unix short options, and <acronym>GNU</acronym>-style long
+   options. The latter are not available on all systems.
+  </para>
 
-<refsect1 id="R1-APP-PSQL-1">
-  <refsect1info>
-    <date>1998-10-26</date>
-  </refsect1info>
+  <variablelist>
+    <varlistentry>
+      <term>-a, --echo-all</term>
+      <listitem>
+      <para>
+      Print all the lines to the screen as they are read. This is more
+      useful for script processing rather than interactive mode. This is
+      equivalent to setting the variable <envar>ECHO</envar> to
+      <literal>all</literal>.
+      </para>
+      </listitem>
+    </varlistentry>
 
-  <title>Description</title>
+    <varlistentry>
+      <term>-A, --no-align</term>
+      <listitem>
+      <para>
+      Switches to unaligned output mode. (The default output mode is
+      otherwise aligned.)
+      </para>
+      </listitem>
+    </varlistentry>
+	
+    <varlistentry>
+      <term>-c, --command <replaceable class="parameter">query</replaceable></term>
+      <listitem>
+      <para>
+      Specifies that <application>psql</application> is to execute one
+      query string, <replaceable class="parameter">query</replaceable>,
+      and then exit. This is useful in shell scripts.
+      </para>
+      <para>
+      <replaceable class="parameter">query</replaceable> must be either
+      a query string that is completely parseable by the backend (i.e.,
+      it contains no <application>psql</application> specific features),
+      or it is a single backslash command. Thus you cannot mix
+      <acronym>SQL</acronym> and <application>psql</application>
+      meta-commands. To achieve that, you could pipe the string into
+      <application>psql</application>, like this: <literal>echo "\x \\
+      select * from foo;" | psql</literal>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
+      <listitem>
+      <para>
+      Specifies the name of the database to connect to. This is
+      equivalent to specifying <replaceable
+      class="parameter">dbname</replaceable> as the first non-option
+      argument on the command line.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-e, --echo-queries</term>
+      <listitem>
+      <para>
+      Show all queries that are sent to the backend. This is equivalent
+      to setting the variable <envar>ECHO</envar> to
+      <literal>queries</literal>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-E, --echo-hidden</term>
+      <listitem>
+      <para>
+      Echoes the actual queries generated by \d and other backslash
+      commands. You can use this if you wish to include similar
+      functionality into your own programs. This is equivalent to
+      setting the variable <envar>ECHO_HIDDEN</envar> from within
+      <application>psql</application>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-f, --file <replaceable class="parameter">filename</replaceable></term>
+      <listitem>
+      <para>
+      Use the file <replaceable class="parameter">filename</replaceable>
+      as the source of queries instead of reading queries interactively.
+      After the file is processed, <application>psql</application>
+      terminates. This is in many ways equivalent to the internal
+      command <command>\i</command>.
+      </para>
+
+      <para>
+       If <replaceable>filename</replaceable> is <literal>-</literal>
+       (hyphen), then standard input is read.
+      </para>
+
+      <para>
+      Using this option is subtly different from writing <literal>psql
+      &lt; <replaceable
+      class="parameter">filename</replaceable></literal>. In general,
+      both will do what you expect, but using <literal>-f</literal>
+      enables some nice features such as error messages with line
+      numbers. There is also a slight chance that using this option will
+      reduce the start-up overhead. On the other hand, the variant using
+      the shell's input redirection is (in theory) guaranteed to yield
+      exactly the same output that you would have gotten had you entered
+      everything by hand.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
+      <listitem>
+      <para>
+      Use <replaceable class="parameter">separator</replaceable> as the
+      field separator. This is equivalent to <command>\pset
+      fieldsep</command> or <command>\f</command>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
+      <listitem>
+      <para>
+      Specifies the host name of the machine on which the
+      <application>postmaster</application> is running. If host begins
+      with a slash, it is used as the directory for the unix domain
+      socket.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-H, --html</term>
+      <listitem>
+      <para>
+      Turns on <acronym>HTML</acronym> tabular output. This is
+      equivalent to <literal>\pset format html</literal> or the
+      <command>\H</command> command.
+      </para>
+      </listitem>
+    </varlistentry>
+ 
+    <varlistentry>
+      <term>-l, --list</term>
+      <listitem>
+      <para>
+      Lists all available databases, then exits. Other non-connection
+      options are ignored. This is similar to the internal command
+      <command>\list</command>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-o, --output <replaceable class="parameter">filename</replaceable></term>
+      <listitem>
+      <para>
+      Put all query output into file <replaceable
+      class="parameter">filename</replaceable>. This is equivalent to
+      the command <command>\o</command>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-p, --port <replaceable class="parameter">port</replaceable></term>
+      <listitem>
+      <para>
+      Specifies the TCP/IP port or, by omission, the local Unix domain
+      socket file extension on which the
+      <application>postmaster</application> is listening for
+      connections. Defaults to the value of the <envar>PGPORT</envar>
+      environment variable or, if not set, to the port specified at
+      compile time, usually 5432.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
+      <listitem>
+      <para>
+      Allows you to specify printing options in the style of
+      <command>\pset</command> on the command line. Note that here you
+      have to separate name and value with an equal sign instead of a
+      space. Thus to set the output format to LaTeX, you could write
+      <literal>-P format=latex</literal>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-q</term>
+      <listitem>
+      <para>
+      Specifies that <application>psql</application> should do its work
+      quietly. By default, it prints welcome messages and various
+      informational output. If this option is used, none of this
+      happens. This is useful with the <option>-c</option> option.
+      Within <application>psql</application> you can also set the
+      <envar>QUIET</envar> variable to achieve the same effect.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
+      <listitem>
+      <para>
+      Use <replaceable class="parameter">separator</replaceable> as the
+      record separator. This is equivalent to the <command>\pset
+      recordsep</command> command.
+      </para>
+      </listitem>
+    </varlistentry>
+ 
+    <varlistentry>
+      <term>-s, --single-step</term>
+      <listitem>
+      <para>
+      Run in single-step mode. That means the user is prompted before
+      each query is sent to the backend, with the option to cancel
+      execution as well. Use this to debug scripts.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-S, --single-line</term>
+      <listitem>
+      <para>
+      Runs in single-line mode where a newline terminates a query, as a
+      semicolon does.
+      </para>
+
+      <note>
+      <para>
+      This mode is provided for those who insist on it, but you are not
+      necessarily encouraged to use it. In particular, if you mix
+      <acronym>SQL</acronym> and meta-commands on a line the order of
+      execution might not always be clear to the inexperienced user.
+      </para>
+      </note>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-t, --tuples-only</term>
+      <listitem>
+      <para>
+      Turn off printing of column names and result row count footers,
+      etc. It is completely equivalent to the <command>\t</command>
+      meta-command.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
+      <listitem>
+      <para>
+      Allows you to specify options to be placed within the
+      <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
+      <command>\pset</command> for details.
+      </para>
+      </listitem>
+    </varlistentry>
+ 
+    <varlistentry>
+      <term>-u</term>
+      <listitem>
+      <para>
+      Makes <application>psql</application> prompt for the user name and
+      password before connecting to the database.
+      </para>
+
+      <para>
+      This option is deprecated, as it is conceptually flawed.
+      (Prompting for a non-default user name and prompting for a
+      password because the backend requires it are really two different
+      things.) You are encouraged to look at the <option>-U</option> and
+      <option>-W</option> options instead.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-U, --username <replaceable class="parameter">username</replaceable></term>
+      <listitem>
+      <para>
+      Connects to the database as the user <replaceable
+      class="parameter">username</replaceable> instead of the default.
+      (You must have permission to do so, of course.)
+      </para> 
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
+      <listitem>
+      <para>
+      Performs a variable assignment, like the <command>\set</command>
+      internal command. Note that you must separate name and value, if
+      any, by an equal sign on the command line. To unset a variable,
+      leave off the equal sign. To just set a variable without a value,
+      use the equal sign but leave off the value. These assignments are
+      done during a very early stage of start-up, so variables reserved
+      for internal purposes might get overwritten later.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-V, --version</term>
+      <listitem>
+      <para>
+      Shows the <application>psql</application> version.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-W, --password</term>
+      <listitem>
+      <para>
+      Requests that <application>psql</application> should prompt for a
+      password before connecting to a database. This will remain set for
+      the entire session, even if you change the database connection
+      with the meta-command <command>\connect</command>.
+      </para>
+
+      <para>
+      In the current version, <application>psql</application>
+      automatically issues a password prompt whenever the backend
+      requests password authentication. Because this is currently based
+      on a hack, the automatic recognition might mysteriously fail,
+      hence this option to force a prompt. If no password prompt is
+      issued and the backend requires password authentication the
+      connection attempt will fail.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-x, --expanded</term>
+      <listitem>
+      <para>
+      Turns on extended row format mode. This is equivalent to the
+      command <command>\x</command>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-X, --no-psqlrc</term>
+      <listitem>
+      <para>
+      Do not read the start-up file <filename>~/.psqlrc</filename>.
+      </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>-?, --help</term>
+      <listitem>
+      <para>
+      Shows help about <application>psql</application> command line
+      arguments.
+      </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Exit Status</title>
+
+  <para>
+   <application>psql</application> returns 0 to the shell if it
+   finished normally, 1 if a fatal error of its own (out of memory,
+   file not found) occurs, 2 if the connection to the backend went bad
+   and the session is not interactive, and 3 if an error occurred in a
+   script and the variable <envar>ON_ERROR_STOP</envar> was set.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Usage</title>
 
   <refsect2 id="R2-APP-PSQL-connecting">
-    <refsect2info>
-      <date>2000-01-14</date>
-    </refsect2info>
-   
     <title>Connecting To A Database</title>
 
     <para>
@@ -96,10 +479,6 @@ PostgreSQL documentation
   </refsect2>
 
   <refsect2 id="R2-APP-PSQL-4">
-    <refsect2info>
-      <date>1998-09-26</date>
-    </refsect2info>
-
     <title>Entering Queries</title>
 
     <para>
@@ -137,14 +516,9 @@ testdb=>
     <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
     </para>
   </refsect2>
-</refsect1>
 
-<refsect1 id="R1-APP-PSQL-2">
-    <refsect1info>
-      <date>1998-09-26</date>
-    </refsect1info>
-
-    <title><application>psql</application> Meta-Commands</title>
+  <refsect2>
+    <title>Meta-Commands</title>
 
     <para>
     Anything you enter in <application>psql</application> that begins
@@ -1038,8 +1412,8 @@ lo_import 152801
 	  <para>
 	  Toggles the use of a pager for query and psql help output. If the
 	  environment variable <envar>PAGER</envar> is set, the output
-	  is piped to the specified program. Otherwise
-	  <filename>more</filename> is used.
+	  is piped to the specified program. Otherwise a platform-dependent default (such as
+	  <filename>more</filename>) is used.
 	  </para>
 
 	  <para>
@@ -1314,440 +1688,12 @@ Access permissions for database "test"
 
     </variablelist>
   </para>
-</refsect1>
-
-
-
-<refsect1 id="R1-APP-PSQL-3">
-  <refsect1info>
-    <date>1998-09-26</date>
-  </refsect1info>
-
-  <title>Command-line Options</title>
-
-  <para>
-  If so configured, <application>psql</application> understands both
-  standard Unix short options, and <acronym>GNU</acronym>-style long
-  options. The latter are not available on all systems.
-  </para>
-
-  <para>
-  <variablelist>
-    <varlistentry>
-      <term>-a, --echo-all</term>
-      <listitem>
-      <para>
-      Print all the lines to the screen as they are read. This is more
-      useful for script processing rather than interactive mode. This is
-      equivalent to setting the variable <envar>ECHO</envar> to
-      <literal>all</literal>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-A, --no-align</term>
-      <listitem>
-      <para>
-      Switches to unaligned output mode. (The default output mode is
-      otherwise aligned.)
-      </para>
-      </listitem>
-    </varlistentry>
-
-	
-    <varlistentry>
-      <term>-c, --command <replaceable class="parameter">query</replaceable></term>
-      <listitem>
-      <para>
-      Specifies that <application>psql</application> is to execute one
-      query string, <replaceable class="parameter">query</replaceable>,
-      and then exit. This is useful in shell scripts.
-      </para>
-      <para>
-      <replaceable class="parameter">query</replaceable> must be either
-      a query string that is completely parseable by the backend (i.e.,
-      it contains no <application>psql</application> specific features),
-      or it is a single backslash command. Thus you cannot mix
-      <acronym>SQL</acronym> and <application>psql</application>
-      meta-commands. To achieve that, you could pipe the string into
-      <application>psql</application>, like this: <literal>echo "\x \\
-      select * from foo;" | psql</literal>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
-      <listitem>
-      <para>
-      Specifies the name of the database to connect to. This is
-      equivalent to specifying <replaceable
-      class="parameter">dbname</replaceable> as the first non-option
-      argument on the command line.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-e, --echo-queries</term>
-      <listitem>
-      <para>
-      Show all queries that are sent to the backend. This is equivalent
-      to setting the variable <envar>ECHO</envar> to
-      <literal>queries</literal>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-E, --echo-hidden</term>
-      <listitem>
-      <para>
-      Echoes the actual queries generated by \d and other backslash
-      commands. You can use this if you wish to include similar
-      functionality into your own programs. This is equivalent to
-      setting the variable <envar>ECHO_HIDDEN</envar> from within
-      <application>psql</application>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-f, --file <replaceable class="parameter">filename</replaceable></term>
-      <listitem>
-      <para>
-      Use the file <replaceable class="parameter">filename</replaceable>
-      as the source of queries instead of reading queries interactively.
-      After the file is processed, <application>psql</application>
-      terminates. This is in many ways equivalent to the internal
-      command <command>\i</command>.
-      </para>
-
-      <para>
-       If <replaceable>filename</replaceable> is <literal>-</literal>
-       (hyphen), then standard input is read.
-      </para>
-
-      <para>
-      Using this option is subtly different from writing <literal>psql
-      &lt; <replaceable
-      class="parameter">filename</replaceable></literal>. In general,
-      both will do what you expect, but using <literal>-f</literal>
-      enables some nice features such as error messages with line
-      numbers. There is also a slight chance that using this option will
-      reduce the start-up overhead. On the other hand, the variant using
-      the shell's input redirection is (in theory) guaranteed to yield
-      exactly the same output that you would have gotten had you entered
-      everything by hand.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
-      <listitem>
-      <para>
-      Use <replaceable class="parameter">separator</replaceable> as the
-      field separator. This is equivalent to <command>\pset
-      fieldsep</command> or <command>\f</command>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
-      <listitem>
-      <para>
-      Specifies the host name of the machine on which the
-      <application>postmaster</application> is running. If host begins
-      with a slash, it is used as the directory for the unix domain
-      socket.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-H, --html</term>
-      <listitem>
-      <para>
-      Turns on <acronym>HTML</acronym> tabular output. This is
-      equivalent to <literal>\pset format html</literal> or the
-      <command>\H</command> command.
-      </para>
-      </listitem>
-    </varlistentry>
-
- 
-    <varlistentry>
-      <term>-l, --list</term>
-      <listitem>
-      <para>
-      Lists all available databases, then exits. Other non-connection
-      options are ignored. This is similar to the internal command
-      <command>\list</command>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-o, --output <replaceable class="parameter">filename</replaceable></term>
-      <listitem>
-      <para>
-      Put all query output into file <replaceable
-      class="parameter">filename</replaceable>. This is equivalent to
-      the command <command>\o</command>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-p, --port <replaceable class="parameter">port</replaceable></term>
-      <listitem>
-      <para>
-      Specifies the TCP/IP port or, by omission, the local Unix domain
-      socket file extension on which the
-      <application>postmaster</application> is listening for
-      connections. Defaults to the value of the <envar>PGPORT</envar>
-      environment variable or, if not set, to the port specified at
-      compile time, usually 5432.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
-      <listitem>
-      <para>
-      Allows you to specify printing options in the style of
-      <command>\pset</command> on the command line. Note that here you
-      have to separate name and value with an equal sign instead of a
-      space. Thus to set the output format to LaTeX, you could write
-      <literal>-P format=latex</literal>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-q</term>
-      <listitem>
-      <para>
-      Specifies that <application>psql</application> should do its work
-      quietly. By default, it prints welcome messages and various
-      informational output. If this option is used, none of this
-      happens. This is useful with the <option>-c</option> option.
-      Within <application>psql</application> you can also set the
-      <envar>QUIET</envar> variable to achieve the same effect.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
-      <listitem>
-      <para>
-      Use <replaceable class="parameter">separator</replaceable> as the
-      record separator. This is equivalent to the <command>\pset
-      recordsep</command> command.
-      </para>
-      </listitem>
-    </varlistentry>
-
- 
-    <varlistentry>
-      <term>-s, --single-step</term>
-      <listitem>
-      <para>
-      Run in single-step mode. That means the user is prompted before
-      each query is sent to the backend, with the option to cancel
-      execution as well. Use this to debug scripts.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-S, --single-line</term>
-      <listitem>
-      <para>
-      Runs in single-line mode where a newline terminates a query, as a
-      semicolon does.
-      </para>
-
-      <note>
-      <para>
-      This mode is provided for those who insist on it, but you are not
-      necessarily encouraged to use it. In particular, if you mix
-      <acronym>SQL</acronym> and meta-commands on a line the order of
-      execution might not always be clear to the inexperienced user.
-      </para>
-      </note>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-t, --tuples-only</term>
-      <listitem>
-      <para>
-      Turn off printing of column names and result row count footers,
-      etc. It is completely equivalent to the <command>\t</command>
-      meta-command.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
-      <listitem>
-      <para>
-      Allows you to specify options to be placed within the
-      <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
-      <command>\pset</command> for details.
-      </para>
-      </listitem>
-    </varlistentry>
-
- 
-    <varlistentry>
-      <term>-u</term>
-      <listitem>
-      <para>
-      Makes <application>psql</application> prompt for the user name and
-      password before connecting to the database.
-      </para>
-
-      <para>
-      This option is deprecated, as it is conceptually flawed.
-      (Prompting for a non-default user name and prompting for a
-      password because the backend requires it are really two different
-      things.) You are encouraged to look at the <option>-U</option> and
-      <option>-W</option> options instead.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-U, --username <replaceable class="parameter">username</replaceable></term>
-      <listitem>
-      <para>
-      Connects to the database as the user <replaceable
-      class="parameter">username</replaceable> instead of the default.
-      (You must have permission to do so, of course.)
-      </para> 
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
-      <listitem>
-      <para>
-      Performs a variable assignment, like the <command>\set</command>
-      internal command. Note that you must separate name and value, if
-      any, by an equal sign on the command line. To unset a variable,
-      leave off the equal sign. To just set a variable without a value,
-      use the equal sign but leave off the value. These assignments are
-      done during a very early stage of start-up, so variables reserved
-      for internal purposes might get overwritten later.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-V, --version</term>
-      <listitem>
-      <para>
-      Shows the <application>psql</application> version.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-W, --password</term>
-      <listitem>
-      <para>
-      Requests that <application>psql</application> should prompt for a
-      password before connecting to a database. This will remain set for
-      the entire session, even if you change the database connection
-      with the meta-command <command>\connect</command>.
-      </para>
-
-      <para>
-      In the current version, <application>psql</application>
-      automatically issues a password prompt whenever the backend
-      requests password authentication. Because this is currently based
-      on a hack, the automatic recognition might mysteriously fail,
-      hence this option to force a prompt. If no password prompt is
-      issued and the backend requires password authentication the
-      connection attempt will fail.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-x, --expanded</term>
-      <listitem>
-      <para>
-      Turns on extended row format mode. This is equivalent to the
-      command <command>\x</command>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-X, --no-psqlrc</term>
-      <listitem>
-      <para>
-      Do not read the start-up file <filename>~/.psqlrc</filename>.
-      </para>
-      </listitem>
-    </varlistentry>
-
-
-    <varlistentry>
-      <term>-?, --help</term>
-      <listitem>
-      <para>
-      Shows help about <application>psql</application> command line
-      arguments.
-      </para>
-      </listitem>
-    </varlistentry>
-
-  </variablelist>
-  </para>
-
-</refsect1>
-
-
-<refsect1 id="R1-APP-PSQL-4">
-    <refsect1info>
-      <date>1998-09-27</date>
-    </refsect1info>
+ </refsect2>
 
-    <title>Advanced features</title>
+ <refsect2>
+  <title>Advanced features</title>
 
-  <refsect2 id="APP-PSQL-variables">
+   <refsect3 id="APP-PSQL-variables">
     <title id="APP-PSQL-variables-title">Variables</title>
 
     <para>
@@ -2063,11 +2009,10 @@ bar
 
     </para>
 
-  </refsect2>
-
+   </refsect3>
 
-  <refsect2 id="APP-PSQL-sql-interpol">
-    <title id="APP-PSQL-sql-interpol-title"><acronym>SQL</acronym> Interpolation</title>
+   <refsect3>
+    <title><acronym>SQL</acronym> Interpolation</title>
 
     <para>
     An additional useful feature of <application>psql</application>
@@ -2131,10 +2076,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     conflict.)
     </para>
 
-  </refsect2>
-
+   </refsect3>
 
-  <refsect2 id="APP-PSQL-prompting">
+   <refsect3 id="APP-PSQL-prompting">
     <title id="APP-PSQL-prompting-title">Prompting</title>
 
     <para>
@@ -2282,31 +2226,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     </para>
     </note>
 
-   </refsect2>
+   </refsect3>
 
-  <refsect2 id="APP-PSQL-MISC">
-    <title id="APP-PSQL-MISC-title">Miscellaneous</title>
-
-    <para>
-    <application>psql</application> returns 0 to the shell if it
-    finished normally, 1 if a fatal error of its own (out of memory,
-    file not found) occurs, 2 if the connection to the backend went bad
-    and the session is not interactive, and 3 if an error occurred in a
-    script and the variable <envar>ON_ERROR_STOP</envar> was set.
-    </para>
-
-    <para>
-    Before starting up, <application>psql</application> attempts to read
-    and execute commands from the file
-    <filename>$HOME/.psqlrc</filename>. It could be used to set up the
-    client or the server to taste (using the <command>\set </command>
-    and <command>SET</command> commands).
-    </para>
-
-  </refsect2>
-
-  <refsect2>
-    <title><acronym>GNU</acronym> readline</title>
+   <refsect3>
+    <title>Readline</title>
 
     <para>
     <application>psql</application> supports the readline and history
@@ -2356,14 +2279,167 @@ $ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib  ...
     <acronym>GNU</acronym> project's <acronym>FTP</acronym> server at
     <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
     </para>
+   </refsect3>
   </refsect2>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>HOME</envar></term>
+
+    <listitem>
+     <para>
+      Directory for initialization file (<filename>.psqlrc</filename>)
+      and command history file (<filename>.psql_history</filename>).
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PAGER</envar></term>
+
+    <listitem>
+     <para>
+      If the query results do not fit on the screen, they are piped
+      through this command.  Typical values are
+      <literal>more</literal> or <literal>less</literal>.  The default
+      is platform-dependent.  The use of the pager can be disabled by
+      using the <command>\pset</command> command.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGDATABASE</envar></term>
+
+    <listitem>
+     <para>
+      Default database to connect to
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PSQL_EDITOR</envar></term>
+    <term><envar>EDITOR</envar></term>
+    <term><envar>VISUAL</envar></term>
+
+    <listitem>
+     <para>
+      Editor used by the <command>\e</command> command.  The variables
+      are examined in the order listed; the first that is set is used.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>SHELL</envar></term>
+
+    <listitem>
+     <para>
+      Command executed by the <command>\!</command> command.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>TMPDIR</envar></term>
+
+    <listitem>
+     <para>
+      Directory for storing temporary files.  The default is
+      <filename>/tmp</filename>.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
 
+ <refsect1>
+  <title>Files</title>
+
+  <itemizedlist>
+   <listitem>
+    <para>
+     Before starting up, <application>psql</application> attempts to
+     read and execute commands from the file
+     <filename>$HOME/.psqlrc</filename>. It could be used to set up
+     the client or the server to taste (using the <command>\set
+     </command> and <command>SET</command> commands).
+    </para>
+   </listitem>
+
+   <listitem>
+    <para>
+     The command-line history is stored in the file
+     <filename>$HOME/.psql_history</filename>.
+    </para>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Notes</title>
+
+    <itemizedlist>
+      <listitem>
+      <para>
+      In some earlier life <application>psql</application> allowed the
+      first argument to start directly after the (single-letter)
+      command. For compatibility this is still supported to some extent
+      but I am not going to explain the details here as this use is
+      discouraged. But if you get strange messages, keep this in mind.
+      For example
+<programlisting>
+testdb=> <userinput>\foo</userinput>
+Field separator is "oo",
+</programlisting>
+      which is perhaps not what one would expect.
+      </para>
+      </listitem>
+
+      <listitem>
+      <para>
+      <application>psql</application> only works smoothly with servers
+      of the same version. That does not mean other combinations will
+      fail outright, but subtle and not-so-subtle problems might come
+      up.
+      </para>
+      </listitem>
 
+      <listitem>
+      <para>
+      Pressing Control-C during a <quote>copy in</quote> (data sent to
+      the server) doesn't show the most ideal of behaviors. If you get a
+      message such as <quote>COPY state must be terminated
+      first</quote>, simply reset the connection by entering <literal>\c
+      - -</literal>.
+      </para>
+      </listitem>
 
-</refsect1>
+    </itemizedlist>
+ </refsect1>
 
 
-<refsect1 id="APP-PSQL-examples">
+ <refsect1 id="APP-PSQL-examples">
   <title id="APP-PSQL-examples-title">Examples</title>
 
   <note>
@@ -2478,60 +2554,7 @@ second | four
 </programlisting>
   </para>
 
-</refsect1>
-
-
-<refsect1>
-  <refsect1info>
-    <date>1999-10-27</date>
-  </refsect1info>
-
-  <title>Appendix</title>
-
-  <refsect2>
-    <title>Bugs and Issues</title>
-
-    <itemizedlist>
-      <listitem>
-      <para>
-      In some earlier life <application>psql</application> allowed the
-      first argument to start directly after the (single-letter)
-      command. For compatibility this is still supported to some extent
-      but I am not going to explain the details here as this use is
-      discouraged. But if you get strange messages, keep this in mind.
-      For example
-<programlisting>
-testdb=> <userinput>\foo</userinput>
-Field separator is "oo",
-</programlisting>
-      which is perhaps not what one would expect.
-      </para>
-      </listitem>
-
-      <listitem>
-      <para>
-      <application>psql</application> only works smoothly with servers
-      of the same version. That does not mean other combinations will
-      fail outright, but subtle and not-so-subtle problems might come
-      up.
-      </para>
-      </listitem>
-
-      <listitem>
-      <para>
-      Pressing Control-C during a <quote>copy in</quote> (data sent to
-      the server) doesn't show the most ideal of behaviors. If you get a
-      message such as <quote>COPY state must be terminated
-      first</quote>, simply reset the connection by entering <literal>\c
-      - -</literal>.
-      </para>
-      </listitem>
-
-    </itemizedlist>
-
-  </refsect2>
-
-</refsect1>
+ </refsect1>
 
 </refentry>
 
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index b1c3cab01a8..37debc1b845 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -1,13 +1,9 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.21 2002/02/18 05:48:43 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.22 2002/07/28 15:22:21 petere Exp $
 PostgreSQL documentation
 -->
 
 <refentry id="APP-VACUUMDB">
- <docinfo>
-  <date>2000-11-11</date>
- </docinfo>
-
  <refmeta>
   <refentrytitle id="APP-VACUUMDB-TITLE"><application>vacuumdb</application></refentrytitle>
   <manvolnum>1</manvolnum>
@@ -38,11 +34,37 @@ PostgreSQL documentation
    <group><arg>--verbose</arg><arg>-v</arg></group>
    <group><arg>--analyze</arg><arg>-z</arg></group>
   </cmdsynopsis>
+ </refsynopsisdiv>
+ 
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <application>vacuumdb</application> is a utility for cleaning a
+   <productname>PostgreSQL</productname> database.
+   <application>vacuumdb</application> will also generate internal statistics
+   used by the <productname>PostgreSQL</productname> query optimizer.
+  </para>
+
+  <para>
+   <application>vacuumdb</application> is a shell script wrapper around the
+   backend command
+   <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via
+   the <productname>PostgreSQL</productname> interactive terminal
+   <xref linkend="APP-PSQL">. There is no effective
+   difference between vacuuming databases via this or other methods.
+   <application>psql</application> must be found by the script and
+   a database server must be running at the targeted host. Also, any default
+   settings and environment variables available to <application>psql</application>
+   and the <application>libpq</application> front-end library do apply.
+  </para>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Options</title>
 
-  <refsect2 id="R2-APP-VACUUMDB-1">
-   <title>
-    Inputs
-   </title>
    <para>
     <application>vacuumdb</application> accepts the following command line arguments:
     
@@ -190,12 +212,12 @@ PostgreSQL documentation
      </varlistentry>
     </variablelist>
    </para>
-  </refsect2>
+ </refsect1>
+
+
+ <refsect1>
+  <title>Diagnostics</title>
 
-  <refsect2 id="R2-APP-VACUUMDB-2">
-   <title>
-    Outputs
-   </title>
    <para>
     <variablelist>
      <varlistentry>
@@ -221,42 +243,30 @@ PostgreSQL documentation
 
     </variablelist>
    </para>
+ </refsect1>
 
-   <para>
-   </para>
 
-  </refsect2>
- </refsynopsisdiv>
- 
- <refsect1 id="R1-APP-VACUUMDB-1">
-  <title>
-   Description
-  </title>
+ <refsect1>
+  <title>Environment</title>
 
-  <para>
-   <application>vacuumdb</application> is a utility for cleaning a
-   <productname>PostgreSQL</productname> database.
-   <application>vacuumdb</application> will also generate internal statistics
-   used by the <productname>PostgreSQL</productname> query optimizer.
-  </para>
-
-  <para>
-   <application>vacuumdb</application> is a shell script wrapper around the
-   backend command
-   <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via
-   the <productname>PostgreSQL</productname> interactive terminal
-   <xref linkend="APP-PSQL">. There is no effective
-   difference between vacuuming databases via this or other methods.
-   <application>psql</application> must be found by the script and
-   a database server must be running at the targeted host. Also, any default
-   settings and environment variables available to <application>psql</application>
-   and the <application>libpq</application> front-end library do apply.
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
 
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
- <refsect1 id="R1-APP-VACUUMDB-3">
-  <title>Usage</title>
+
+ <refsect1>
+  <title>Examples</title>
 
   <informalexample>
    <para>
@@ -290,6 +300,15 @@ PostgreSQL documentation
   </informalexample>
 
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file