From 06ad580f75dd54db254d9b1a9665975b9a47570c Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Sun, 28 Jul 2002 15:22:21 +0000
Subject: [PATCH] Structure reference pages consistently.  Document that
 structure. Add information about environment variables.

---
 doc/src/sgml/docguide.sgml         |  192 +-
 doc/src/sgml/ref/createdb.sgml     |  115 +-
 doc/src/sgml/ref/createlang.sgml   |  109 +-
 doc/src/sgml/ref/createuser.sgml   |  129 +-
 doc/src/sgml/ref/dropdb.sgml       |  101 +-
 doc/src/sgml/ref/droplang.sgml     |  109 +-
 doc/src/sgml/ref/dropuser.sgml     |  113 +-
 doc/src/sgml/ref/ecpg-ref.sgml     |  115 +-
 doc/src/sgml/ref/initlocation.sgml |   13 +-
 doc/src/sgml/ref/pg_ctl-ref.sgml   |   49 +-
 doc/src/sgml/ref/pg_dump.sgml      |   30 +-
 doc/src/sgml/ref/pg_dumpall.sgml   |   22 +-
 doc/src/sgml/ref/pg_restore.sgml   |   21 +-
 doc/src/sgml/ref/postgres-ref.sgml |   24 +-
 doc/src/sgml/ref/postmaster.sgml   |   87 +-
 doc/src/sgml/ref/psql-ref.sgml     | 2971 ++++++++++++++--------------
 doc/src/sgml/ref/vacuumdb.sgml     |  107 +-
 17 files changed, 2449 insertions(+), 1858 deletions(-)

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 7df4995cfb..10c0463844 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 8c3723ca0e..d0849388cd 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 279f967412..7ad26ae82e 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 ed92bb2d86..d4be6e7b25 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 ecbfef2b82..e2fd2e3ecc 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 c6eadb401f..186af6e2a0 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 9741d10707..5d45347ee1 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 e7e5a4a8a3..44711a8d19 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 917deadbbe..e37e0a40e1 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 da545ab6fe..397098302e 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 d2ab719fe3..7969489f11 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 44e38f28bc..9e5f4452d0 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 0d951621d1..e89d76bbc1 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 f78c053320..a242dcc863 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
 -->
 
@@ -349,6 +349,28 @@ PostgreSQL documentation
   </refsect2>
  </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>
 
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 0d2a7e93dd..f052e5af6e 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 923a874111..b9f8554abf 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,1127 +38,1161 @@ 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>
 
-  <refsect2 id="R2-APP-PSQL-connecting">
-    <refsect2info>
-      <date>2000-01-14</date>
-    </refsect2info>
-   
-    <title>Connecting To A Database</title>
+    <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>
 
-    <para>
-    <application>psql</application> is a regular
-    <productname>PostgreSQL</productname> client application. In order
-    to connect to a database you need to know the name of your target
-    database, the host name and port number of the server and what user
-    name you want to connect as. <application>psql</application> can be
-    told about those parameters via command line options, namely
-    <option>-d</option>, <option>-h</option>, <option>-p</option>, and
-    <option>-U</option> respectively. If an argument is found that does
-    not belong to any option it will be interpreted as the database name
-    (or the user name, if the database name is also given). Not all
-    these options are required, defaults do apply. If you omit the host
-    name psql will connect via a Unix domain socket to a server on the
-    local host. The default port number is compile-time determined.
-    Since the database server uses the same default, you will not have
-    to specify the port in most cases. The default user name is your
-    Unix user name, as is the default database name. Note that you can't
-    just connect to any database under any user name. Your database
-    administrator should have informed you about your access rights. To
-    save you some typing you can also set the environment variables
-    <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
-    <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate
-    values.
-    </para>
+    <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>
 
-    <para>
-    If the connection could not be made for any reason (e.g., insufficient
-    privileges, postmaster is not running on the server, etc.),
-    <application>psql</application> will return an error and terminate.
-    </para>
-  </refsect2>
+    <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>
 
-  <refsect2 id="R2-APP-PSQL-4">
-    <refsect2info>
-      <date>1998-09-26</date>
-    </refsect2info>
+    <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>
 
-    <title>Entering Queries</title>
+      <para>
+       If <replaceable>filename</replaceable> is <literal>-</literal>
+       (hyphen), then standard input is read.
+      </para>
 
-    <para>
-    In normal operation, <application>psql</application> provides a
-    prompt with the name of the database to which
-    <application>psql</application> is currently connected, followed by
-    the string <literal>=&gt;</literal>. For example,
-<programlisting>
-$ <userinput>psql testdb</userinput>
-Welcome to psql, the PostgreSQL interactive terminal.
+      <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>
 
-Type:  \copyright for distribution terms
-       \h for help with SQL commands
-       \? for help on internal slash commands
-       \g or terminate with semicolon to execute query
-       \q to quit
+    <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>
 
-testdb=>
-</programlisting>
-    </para>
+    <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>
 
-    <para>
-    At the prompt, the user may type in <acronym>SQL</acronym> queries.
-    Ordinarily, input lines are sent to the backend when a
-    query-terminating semicolon is reached. An end of line does not
-    terminate a query! Thus queries can be spread over several lines for
-    clarity. If the query was sent and without error, the query results
-    are displayed on the screen.
-    </para>
+    <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>
 
-    <para>
-    Whenever a query is executed, <application>psql</application> also polls
-    for asynchronous notification events generated by
-    <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
-    <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
-    </para>
-  </refsect2>
-</refsect1>
+    <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>
 
-<refsect1 id="R1-APP-PSQL-2">
-    <refsect1info>
-      <date>1998-09-26</date>
-    </refsect1info>
+    <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>
 
-    <title><application>psql</application> Meta-Commands</title>
+    <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>
 
-    <para>
-    Anything you enter in <application>psql</application> that begins
-    with an unquoted backslash is a <application>psql</application>
-    meta-command that is processed by <application>psql</application>
-    itself. These commands are what makes
-    <application>psql</application> interesting for administration or
-    scripting. Meta-commands are more commonly called slash or backslash
-    commands.
-    </para>
-
-    <para>
-    The format of a <application>psql</application> command is the backslash, 
-    followed immediately by a command verb, then any arguments. The arguments
-    are separated from the command verb and each other by any number of 
-    whitespace characters.
-    </para>
-
-    <para>
-    To include whitespace into an argument you must quote it with a
-    single quote. To include a single quote into such an argument,
-    precede it by a backslash. Anything contained in single quotes is
-    furthermore subject to C-like substitutions for
-    <literal>\n</literal> (new line), <literal>\t</literal> (tab),
-    <literal>\</literal><replaceable>digits</replaceable>,
-    <literal>\0</literal><replaceable>digits</replaceable>, and
-    <literal>\0x</literal><replaceable>digits</replaceable> (the
-    character with the given decimal, octal, or hexadecimal code).
-    </para>
-
-    <para>
-    If an unquoted argument begins with a colon (<literal>:</literal>),
-    it is taken as a variable and the value of the variable is taken as
-    the argument instead.
-    </para>
-
-    <para>
-    Arguments that are quoted in <quote>backticks</quote>
-    (<literal>`</literal>) are taken as a command line that is passed to
-    the shell. The output of the command (with a trailing newline
-    removed) is taken as the argument value. The above escape sequences
-    also apply in backticks.
-    </para>
-
-    <para>
-    Some commands take the name of an <acronym>SQL</acronym> identifier
-    (such as a table name) as argument. These arguments follow the
-    syntax rules of <acronym>SQL</acronym> regarding double quotes: an
-    identifier without double quotes is coerced to lower-case. For all
-    other commands double quotes are not special and will become part of
-    the argument.
-    </para>
-
-    <para>
-    Parsing for arguments stops when another unquoted backslash occurs.
-    This is taken as the beginning of a new meta-command. The special
-    sequence <literal>\\</literal> (two backslashes) marks the end of
-    arguments and continues parsing <acronym>SQL</acronym> queries, if
-    any. That way <acronym>SQL</acronym> and
-    <application>psql</application> commands can be freely mixed on a
-    line. But in any case, the arguments of a meta-command cannot
-    continue beyond the end of the line.
-    </para>
-
-    <para>
-    The following meta-commands are defined:
+    <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>
 
-    <variablelist>
-      <varlistentry>
-        <term><literal>\a</literal></term>
-        <listitem>
-        <para>
-	If the current table output format is unaligned, switch to aligned.
-	If it is not unaligned, set it to unaligned. This command is
-	kept for backwards compatibility. See <command>\pset</command> for a
-	general solution.
-        </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><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
-       <listitem>
-        <para>
-	 Change the current working directory to
-	 <replaceable>directory</replaceable>. Without argument, change
-	 to the current user's home directory.
-        </para>
+    <varlistentry>
+      <term>-S, --single-line</term>
+      <listitem>
+      <para>
+      Runs in single-line mode where a newline terminates a query, as a
+      semicolon does.
+      </para>
 
-	<tip>
-	 <para>
-	  To print your current working directory, use <literal>\!pwd</literal>.
-	 </para>
-	</tip>
-       </listitem>
-      </varlistentry>
+      <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><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
-        <listitem>
-        <para>
-        Set the title of any tables being printed as the result of a
-        query or unset any such title. This command is equivalent to
-        <literal>\pset title <replaceable
-        class="parameter">title</replaceable></literal>. (The name of
-        this command derives from <quote>caption</quote>, as it was
-        previously only used to set the caption in an
-        <acronym>HTML</acronym> table.)
-        </para>
-        </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><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term>
-        <listitem>
-        <para>
-	Establishes a connection to a new database and/or under a user
-	name. The previous connection is closed. If <replaceable
-	class="parameter">dbname</replaceable> is <literal>-</literal>
-	the current database name is assumed.
-	</para>
+    <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>
-	If <replaceable class="parameter">username</replaceable> is
-	omitted the current user name is assumed. </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>
 
-	<para>
-	As a special rule, <command>\connect</command> without any
-	arguments will connect to the default database as the default
-	user (as you would have gotten by starting
-	<application>psql</application> without any arguments).
-	</para>
+    <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>
 
-	<para>
-	If the connection attempt failed (wrong user name, access
-	denied, etc.), the previous connection will be kept if and only
-	if <application>psql</application> is in interactive mode. When
-	executing a non-interactive script, processing will immediately
-	stop with an error. This distinction was chosen as a user
-	convenience against typos on the one hand, and a safety
-	mechanism that scripts are not accidentally acting on the wrong
-	database on the other hand.
-	</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><literal>\copy</literal> <replaceable class="parameter">table</replaceable>
-        { <literal>from</literal> | <literal>to</literal> }
-	<replaceable class="parameter">filename</replaceable> | stdin | stdout
-        [ <literal>with</literal> ] 
-            [ <literal>oids</literal> ] 
-            [ <literal>delimiter [as] </literal> '<replaceable class="parameter">character</replaceable>' ]
-            [ <literal>null [as] </literal> '<replaceable class="parameter">string</replaceable>' ]
-        </term>
+    <varlistentry>
+      <term>-V, --version</term>
+      <listitem>
+      <para>
+      Shows the <application>psql</application> version.
+      </para>
+      </listitem>
+    </varlistentry>
 
-        <listitem>
-        <para>
-        Performs a frontend (client) copy. This is an operation that
-        runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY"
-        endterm="SQL-COPY-title"> command, but instead of the backend's
-        reading or writing the specified file, and consequently
-        requiring backend access and special user privilege, as well as
-        being bound to the file system accessible by the backend,
-        <application>psql</application> reads or writes the file and
-        routes the data between the backend and the local file system.
-	</para>
+    <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>
-	The syntax of the command is similar to that of the
-	<acronym>SQL</acronym> <command>COPY</command> command (see its
-	description for the details). Note that, because of this,
-	special parsing rules apply to the <command>\copy</command>
-	command. In particular, the variable substitution rules and
-	backslash escapes do not apply.
-	</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>
 
-        <tip>
-        <para>
-	This operation is not as efficient as the <acronym>SQL</acronym>
-	<command>COPY</command> command because all data must pass
-	through the client/server IP or socket connection. For large
-	amounts of data the other technique may be preferable.
-        </para>
-        </tip>
+    <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>
 
-        <note>
-        <para>
-        Note the difference in interpretation of
-        <literal>stdin</literal> and <literal>stdout</literal> between
-        frontend and backend copies: in a frontend copy these always
-        refer to <application>psql</application>'s input and output
-        stream. On a backend copy <literal>stdin</literal> comes from
-        wherever the <command>COPY</command> itself came from (for
-        example, a script run with the <option>-f</option> option), and
-        <literal>stdout</literal> refers to the query output stream (see
-        <command>\o</command> meta-command below).
-        </para>
-        </note>
-        </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><literal>\copyright</literal></term>
-        <listitem>
-        <para>
-        Shows the copyright and distribution terms of
-        <application>PostgreSQL</application>.
-        </para>
-        </listitem>
-      </varlistentry>
+    <varlistentry>
+      <term>-?, --help</term>
+      <listitem>
+      <para>
+      Shows help about <application>psql</application> command line
+      arguments.
+      </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+ </refsect1>
 
-      <varlistentry>
-        <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term>
 
-        <listitem>
-        <para>
-	Shows all columns of <replaceable
-	class="parameter">relation</replaceable> (which could be a
-	table, view, index, or sequence), their types, and any special
-	attributes such as <literal>NOT NULL</literal> or defaults, if
-	any. If the relation is, in fact, a table, any defined indices,
-	primary keys, unique constraints and check constraints are also
-	listed. If the relation is a view, the view definition is also
-	shown.
-	</para>
+ <refsect1>
+  <title>Exit Status</title>
 
-	<para>
-	The command form <literal>\d+</literal> is identical, but any
-	comments associated with the table columns are shown as well.
-	</para>
+  <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>
 
-	<note>
-	<para>
-	If <command>\d</command> is called without any arguments, it is
-	equivalent to <command>\dtvs</command> which will show a list of
-	all tables, views, and sequences. This is purely a convenience
-	measure.
-	</para>
-	</note>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+ <refsect1>
+  <title>Usage</title>
 
-        <listitem>
-        <para>
-        Lists all available aggregate functions, together with the data
-        type they operate on. If <replaceable
-        class="parameter">pattern</replaceable> (a regular expression)
-        is specified, only matching aggregates are shown.
-        </para>
-        </listitem>
-      </varlistentry>
+  <refsect2 id="R2-APP-PSQL-connecting">
+    <title>Connecting To A Database</title>
 
-      <varlistentry>
-        <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term>
-        <listitem>
-        <para>
-        Shows the descriptions of <replaceable
-        class="parameter">object</replaceable> (which can be a regular
-        expression), or of all objects if no argument is given.
-        (<quote>Object</quote> covers aggregates, functions, operators,
-        types, relations (tables, views, indexes, sequences, large
-        objects), rules, and triggers.) For example:
-<programlisting>
-=> <userinput>\dd version</userinput>
-              Object descriptions
-  Name   |   What   |        Description
----------+----------+---------------------------
- version | function | PostgreSQL version string
-(1 row)
-</programlisting>
-        </para>
+    <para>
+    <application>psql</application> is a regular
+    <productname>PostgreSQL</productname> client application. In order
+    to connect to a database you need to know the name of your target
+    database, the host name and port number of the server and what user
+    name you want to connect as. <application>psql</application> can be
+    told about those parameters via command line options, namely
+    <option>-d</option>, <option>-h</option>, <option>-p</option>, and
+    <option>-U</option> respectively. If an argument is found that does
+    not belong to any option it will be interpreted as the database name
+    (or the user name, if the database name is also given). Not all
+    these options are required, defaults do apply. If you omit the host
+    name psql will connect via a Unix domain socket to a server on the
+    local host. The default port number is compile-time determined.
+    Since the database server uses the same default, you will not have
+    to specify the port in most cases. The default user name is your
+    Unix user name, as is the default database name. Note that you can't
+    just connect to any database under any user name. Your database
+    administrator should have informed you about your access rights. To
+    save you some typing you can also set the environment variables
+    <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
+    <envar>PGPORT</envar> and <envar>PGUSER</envar> to appropriate
+    values.
+    </para>
 
-        <para>
-        Descriptions for objects can be generated with the
-        <command>COMMENT ON</command> <acronym>SQL</acronym> command.
-	</para>
+    <para>
+    If the connection could not be made for any reason (e.g., insufficient
+    privileges, postmaster is not running on the server, etc.),
+    <application>psql</application> will return an error and terminate.
+    </para>
+  </refsect2>
 
-        <note>
-        <para>
-        <productname>PostgreSQL</productname> stores the object
-        descriptions in the pg_description system table.
-        </para>
-        </note>
+  <refsect2 id="R2-APP-PSQL-4">
+    <title>Entering Queries</title>
 
-        </listitem>
-      </varlistentry>
+    <para>
+    In normal operation, <application>psql</application> provides a
+    prompt with the name of the database to which
+    <application>psql</application> is currently connected, followed by
+    the string <literal>=&gt;</literal>. For example,
+<programlisting>
+$ <userinput>psql testdb</userinput>
+Welcome to psql, the PostgreSQL interactive terminal.
 
+Type:  \copyright for distribution terms
+       \h for help with SQL commands
+       \? for help on internal slash commands
+       \g or terminate with semicolon to execute query
+       \q to quit
 
-      <varlistentry>
-        <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
-        <listitem>
-        <para>
-        Lists all available domains (derived types). If <replaceable
-        class="parameter">pattern</replaceable> (a regular expression)
-        is specified, only matching domains are shown.
-        </para>
-        </listitem>
-      </varlistentry>
+testdb=>
+</programlisting>
+    </para>
 
+    <para>
+    At the prompt, the user may type in <acronym>SQL</acronym> queries.
+    Ordinarily, input lines are sent to the backend when a
+    query-terminating semicolon is reached. An end of line does not
+    terminate a query! Thus queries can be spread over several lines for
+    clarity. If the query was sent and without error, the query results
+    are displayed on the screen.
+    </para>
 
-      <varlistentry>
-        <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+    <para>
+    Whenever a query is executed, <application>psql</application> also polls
+    for asynchronous notification events generated by
+    <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
+    <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
+    </para>
+  </refsect2>
 
-        <listitem>
-        <para>
-        Lists available functions, together with their argument and
-        return types. If <replaceable
-        class="parameter">pattern</replaceable> (a regular expression)
-        is specified, only matching functions are shown. If the form
-        <literal>\df+</literal> is used, additional information about
-        each function, including language and description, is shown.
-        </para>
-        </listitem>
-      </varlistentry>
+  <refsect2>
+    <title>Meta-Commands</title>
 
+    <para>
+    Anything you enter in <application>psql</application> that begins
+    with an unquoted backslash is a <application>psql</application>
+    meta-command that is processed by <application>psql</application>
+    itself. These commands are what makes
+    <application>psql</application> interesting for administration or
+    scripting. Meta-commands are more commonly called slash or backslash
+    commands.
+    </para>
 
-      <varlistentry>
-        <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+    <para>
+    The format of a <application>psql</application> command is the backslash, 
+    followed immediately by a command verb, then any arguments. The arguments
+    are separated from the command verb and each other by any number of 
+    whitespace characters.
+    </para>
 
-	<listitem>
-	<para>
-	This is not the actual command name: The letters i, s, t, v, S
-	stand for index, sequence, table, view, and system table,
-	respectively. You can specify any or all of them in any order to
-	obtain a listing of them, together with who the owner is.
-	</para>
+    <para>
+    To include whitespace into an argument you must quote it with a
+    single quote. To include a single quote into such an argument,
+    precede it by a backslash. Anything contained in single quotes is
+    furthermore subject to C-like substitutions for
+    <literal>\n</literal> (new line), <literal>\t</literal> (tab),
+    <literal>\</literal><replaceable>digits</replaceable>,
+    <literal>\0</literal><replaceable>digits</replaceable>, and
+    <literal>\0x</literal><replaceable>digits</replaceable> (the
+    character with the given decimal, octal, or hexadecimal code).
+    </para>
 
-	<para>
-	If <replaceable class="parameter">pattern</replaceable> is
-	specified, it is a regular expression that restricts the listing
-	to those objects whose name matches. If one appends a
-	<quote>+</quote> to the command name, each object is listed with
-	its associated description, if any.
-	</para>
-	</listitem>
-      </varlistentry>
+    <para>
+    If an unquoted argument begins with a colon (<literal>:</literal>),
+    it is taken as a variable and the value of the variable is taken as
+    the argument instead.
+    </para>
+
+    <para>
+    Arguments that are quoted in <quote>backticks</quote>
+    (<literal>`</literal>) are taken as a command line that is passed to
+    the shell. The output of the command (with a trailing newline
+    removed) is taken as the argument value. The above escape sequences
+    also apply in backticks.
+    </para>
 
+    <para>
+    Some commands take the name of an <acronym>SQL</acronym> identifier
+    (such as a table name) as argument. These arguments follow the
+    syntax rules of <acronym>SQL</acronym> regarding double quotes: an
+    identifier without double quotes is coerced to lower-case. For all
+    other commands double quotes are not special and will become part of
+    the argument.
+    </para>
 
-      <varlistentry>
-        <term><literal>\dl</literal></term>
-	<listitem>
-	<para>
-	This is an alias for <command>\lo_list</command>, which shows a
-	list of large objects.
-	</para>
-	</listitem>
-      </varlistentry>
+    <para>
+    Parsing for arguments stops when another unquoted backslash occurs.
+    This is taken as the beginning of a new meta-command. The special
+    sequence <literal>\\</literal> (two backslashes) marks the end of
+    arguments and continues parsing <acronym>SQL</acronym> queries, if
+    any. That way <acronym>SQL</acronym> and
+    <application>psql</application> commands can be freely mixed on a
+    line. But in any case, the arguments of a meta-command cannot
+    continue beyond the end of the line.
+    </para>
 
+    <para>
+    The following meta-commands are defined:
 
+    <variablelist>
       <varlistentry>
-        <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term>
+        <term><literal>\a</literal></term>
         <listitem>
         <para>
-        Lists available operators with their operand and return types.
-        If <replaceable class="parameter">name</replaceable> is
-        specified, only operators with that name will be shown.
+	If the current table output format is unaligned, switch to aligned.
+	If it is not unaligned, set it to unaligned. This command is
+	kept for backwards compatibility. See <command>\pset</command> for a
+	general solution.
         </para>
         </listitem>
       </varlistentry>
 
-
-      <varlistentry>
-        <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
-	<listitem>
-	<para>
-	This is an alias for <command>\z</command> which was included
-	for its greater mnemonic value (<quote>display
-	permissions</quote>).
-	</para>
-	</listitem>
-      </varlistentry>
-
-
       <varlistentry>
-        <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
-        <listitem>
+       <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
+       <listitem>
         <para>
-        Lists all data types or only those that match <replaceable
-        class="parameter">pattern</replaceable>. The command form
-        <literal>\dT+</literal> shows extra information.
+	 Change the current working directory to
+	 <replaceable>directory</replaceable>. Without argument, change
+	 to the current user's home directory.
         </para>
-        </listitem>
-      </varlistentry>
 
+	<tip>
+	 <para>
+	  To print your current working directory, use <literal>\!pwd</literal>.
+	 </para>
+	</tip>
+       </listitem>
+      </varlistentry>
 
       <varlistentry>
-        <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
         <listitem>
         <para>
-        Lists all configured users or only those that match <replaceable
-        class="parameter">pattern</replaceable>.
+        Set the title of any tables being printed as the result of a
+        query or unset any such title. This command is equivalent to
+        <literal>\pset title <replaceable
+        class="parameter">title</replaceable></literal>. (The name of
+        this command derives from <quote>caption</quote>, as it was
+        previously only used to set the caption in an
+        <acronym>HTML</acronym> table.)
         </para>
         </listitem>
       </varlistentry>
 
-
       <varlistentry>
-        <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term>
-
+        <term><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term>
         <listitem>
         <para>
-        If <replaceable class="parameter">filename</replaceable> is
-        specified, the file is edited; after the editor exits, its
-        content is copied back to the query buffer. If no argument is
-        given, the current query buffer is copied to a temporary file
-        which is then edited in the same fashion.
-        </para>
-
-        <para>
-        The new query buffer is then re-parsed according to the normal
-        rules of <application>psql</application>, where the whole buffer
-        is treated as a single line. (Thus you cannot make scripts this
-        way. Use <command>\i</command> for that.) This means also that
-        if the query ends with (or rather contains) a semicolon, it is
-        immediately executed. In other cases it will merely wait in the
-        query buffer.
-        </para>
-
-        <tip>
-        <para>
-        <application>psql</application> searches the environment
-        variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and
-        <envar>VISUAL</envar> (in that order) for an editor to use. If
-        all of them are unset, <filename>/bin/vi</filename> is run.
-        </para>
-        </tip>
-        </listitem>
-      </varlistentry>
+	Establishes a connection to a new database and/or under a user
+	name. The previous connection is closed. If <replaceable
+	class="parameter">dbname</replaceable> is <literal>-</literal>
+	the current database name is assumed.
+	</para>
 
+	<para>
+	If <replaceable class="parameter">username</replaceable> is
+	omitted the current user name is assumed. </para>
 
-      <varlistentry>
-        <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term>
-        <listitem>
 	<para>
-        Prints the arguments to the standard output, separated by one
-        space and followed by a newline. This can be useful to
-        intersperse information in the output of scripts. For example:
-<programlisting>
-=> <userinput>\echo `date`</userinput>
-Tue Oct 26 21:40:57 CEST 1999
-</programlisting>
-        If the first argument is an unquoted <literal>-n</literal> the the trailing
-        newline is not written.
+	As a special rule, <command>\connect</command> without any
+	arguments will connect to the default database as the default
+	user (as you would have gotten by starting
+	<application>psql</application> without any arguments).
 	</para>
 
-	<tip>
 	<para>
-	If you use the <command>\o</command> command to redirect your
-	query output you may wish to use <command>\qecho</command>
-	instead of this command.
+	If the connection attempt failed (wrong user name, access
+	denied, etc.), the previous connection will be kept if and only
+	if <application>psql</application> is in interactive mode. When
+	executing a non-interactive script, processing will immediately
+	stop with an error. This distinction was chosen as a user
+	convenience against typos on the one hand, and a safety
+	mechanism that scripts are not accidentally acting on the wrong
+	database on the other hand.
 	</para>
-	</tip>
-	</listitem>
+        </listitem>
       </varlistentry>
 
-
       <varlistentry>
-        <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term>
+        <term><literal>\copy</literal> <replaceable class="parameter">table</replaceable>
+        { <literal>from</literal> | <literal>to</literal> }
+	<replaceable class="parameter">filename</replaceable> | stdin | stdout
+        [ <literal>with</literal> ] 
+            [ <literal>oids</literal> ] 
+            [ <literal>delimiter [as] </literal> '<replaceable class="parameter">character</replaceable>' ]
+            [ <literal>null [as] </literal> '<replaceable class="parameter">string</replaceable>' ]
+        </term>
 
         <listitem>
         <para>
-        Sets the client encoding, if you are using multibyte encodings.
-        Without an argument, this command shows the current encoding.
-        </para>
-        </listitem>
-      </varlistentry>
+        Performs a frontend (client) copy. This is an operation that
+        runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY"
+        endterm="SQL-COPY-title"> command, but instead of the backend's
+        reading or writing the specified file, and consequently
+        requiring backend access and special user privilege, as well as
+        being bound to the file system accessible by the backend,
+        <application>psql</application> reads or writes the file and
+        routes the data between the backend and the local file system.
+	</para>
 
+	<para>
+	The syntax of the command is similar to that of the
+	<acronym>SQL</acronym> <command>COPY</command> command (see its
+	description for the details). Note that, because of this,
+	special parsing rules apply to the <command>\copy</command>
+	command. In particular, the variable substitution rules and
+	backslash escapes do not apply.
+	</para>
 
-      <varlistentry>
-        <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term>
+        <tip>
+        <para>
+	This operation is not as efficient as the <acronym>SQL</acronym>
+	<command>COPY</command> command because all data must pass
+	through the client/server IP or socket connection. For large
+	amounts of data the other technique may be preferable.
+        </para>
+        </tip>
 
-        <listitem>
+        <note>
         <para>
-        Sets the field separator for unaligned query output. The default
-        is pipe (<literal>|</literal>). See also
-        <command>\pset</command> for a generic way of setting output
-        options.
+        Note the difference in interpretation of
+        <literal>stdin</literal> and <literal>stdout</literal> between
+        frontend and backend copies: in a frontend copy these always
+        refer to <application>psql</application>'s input and output
+        stream. On a backend copy <literal>stdin</literal> comes from
+        wherever the <command>COPY</command> itself came from (for
+        example, a script run with the <option>-f</option> option), and
+        <literal>stdout</literal> refers to the query output stream (see
+        <command>\o</command> meta-command below).
         </para>
+        </note>
         </listitem>
       </varlistentry>
 
-
       <varlistentry>
-        <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>
-
+        <term><literal>\copyright</literal></term>
         <listitem>
         <para>
-        Sends the current query input buffer to the backend and
-        optionally saves the output in <replaceable
-        class="parameter">filename</replaceable> or pipes the output
-        into a separate Unix shell to execute <replaceable
-        class="parameter">command</replaceable>. A bare
-        <literal>\g</literal> is virtually equivalent to a semicolon. A
-        <literal>\g</literal> with argument is a <quote>one-shot</quote>
-        alternative to the <command>\o</command> command.
+        Shows the copyright and distribution terms of
+        <application>PostgreSQL</application>.
         </para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
-        <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
+        <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term>
+
         <listitem>
         <para>
-        Give syntax help on the specified <acronym>SQL</acronym>
-        command. If <replaceable class="parameter">command</replaceable>
-        is not specified, then <application>psql</application> will list
-        all the commands for which syntax help is available. If
-        <replaceable class="parameter">command</replaceable> is an
-        asterisk (<quote>*</quote>), then syntax help on all
-        <acronym>SQL</acronym> commands is shown.
-        </para>
+	Shows all columns of <replaceable
+	class="parameter">relation</replaceable> (which could be a
+	table, view, index, or sequence), their types, and any special
+	attributes such as <literal>NOT NULL</literal> or defaults, if
+	any. If the relation is, in fact, a table, any defined indices,
+	primary keys, unique constraints and check constraints are also
+	listed. If the relation is a view, the view definition is also
+	shown.
+	</para>
+
+	<para>
+	The command form <literal>\d+</literal> is identical, but any
+	comments associated with the table columns are shown as well.
+	</para>
 
 	<note>
 	<para>
-	To simplify typing, commands that consists of several words do
-	not have to be quoted. Thus it is fine to type <userinput>\help
-	alter table</userinput>.
+	If <command>\d</command> is called without any arguments, it is
+	equivalent to <command>\dtvs</command> which will show a list of
+	all tables, views, and sequences. This is purely a convenience
+	measure.
 	</para>
-	</note>	
-        </listitem>
+	</note>
+	</listitem>
       </varlistentry>
 
-
       <varlistentry>
-        <term><literal>\H</literal></term>
+        <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+
         <listitem>
         <para>
-	Turns on <acronym>HTML</acronym> query output format. If the
-	<acronym>HTML</acronym> format is already on, it is switched
-	back to the default aligned text format. This command is for
-	compatibility and convenience, but see <command>\pset</command>
-	about setting other output options.
+        Lists all available aggregate functions, together with the data
+        type they operate on. If <replaceable
+        class="parameter">pattern</replaceable> (a regular expression)
+        is specified, only matching aggregates are shown.
         </para>
         </listitem>
       </varlistentry>
 
-
       <varlistentry>
-        <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
+        <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term>
         <listitem>
         <para>
-        Reads input from the file <replaceable
-        class="parameter">filename</replaceable> and executes it as
-        though it had been typed on the keyboard.
+        Shows the descriptions of <replaceable
+        class="parameter">object</replaceable> (which can be a regular
+        expression), or of all objects if no argument is given.
+        (<quote>Object</quote> covers aggregates, functions, operators,
+        types, relations (tables, views, indexes, sequences, large
+        objects), rules, and triggers.) For example:
+<programlisting>
+=> <userinput>\dd version</userinput>
+              Object descriptions
+  Name   |   What   |        Description
+---------+----------+---------------------------
+ version | function | PostgreSQL version string
+(1 row)
+</programlisting>
         </para>
-	<note>
-	<para>
-	If you want to see the lines on the screen as they are read you
-	must set the variable <envar>ECHO</envar> to
-	<literal>all</literal>.
+
+        <para>
+        Descriptions for objects can be generated with the
+        <command>COMMENT ON</command> <acronym>SQL</acronym> command.
 	</para>
-	</note>
+
+        <note>
+        <para>
+        <productname>PostgreSQL</productname> stores the object
+        descriptions in the pg_description system table.
+        </para>
+        </note>
+
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\l</literal> (or <literal>\list</literal>)</term>
+        <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
         <listitem>
         <para>
-        List all the databases in the server as well as their owners.
-        Append a <quote>+</quote> to the command name to see any
-        descriptions for the databases as well. If your
-        <productname>PostgreSQL</productname> installation was compiled
-        with multibyte encoding support, the encoding scheme of each
-        database is shown as well.
+        Lists all available domains (derived types). If <replaceable
+        class="parameter">pattern</replaceable> (a regular expression)
+        is specified, only matching domains are shown.
         </para>
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term>
+        <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
 
-	<listitem>
-	<para>
-	Reads the large object with <acronym>OID</acronym> <replaceable
-	class="parameter">loid</replaceable> from the database and
-	writes it to <replaceable
-	class="parameter">filename</replaceable>. Note that this is
-	subtly different from the server function
-	<function>lo_export</function>, which acts with the permissions
-	of the user that the database server runs as and on the server's
-	file system.
-	</para>
-	<tip>
-	<para>
-	Use <command>\lo_list</command> to find out the large object's
-	<acronym>OID</acronym>.
-	</para>
-	</tip>
-	<note>
-	<para>
-	See the description of the <envar>LO_TRANSACTION</envar>
-	variable for important information concerning all large object
-	operations.
-	</para>
-	</note>
-	</listitem>
+        <listitem>
+        <para>
+        Lists available functions, together with their argument and
+        return types. If <replaceable
+        class="parameter">pattern</replaceable> (a regular expression)
+        is specified, only matching functions are shown. If the form
+        <literal>\df+</literal> is used, additional information about
+        each function, including language and description, is shown.
+        </para>
+        </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term>
-
-	<listitem>
-	<para>
-	Stores the file into a <productname>PostgreSQL</productname>
-	<quote>large object</quote>. Optionally, it associates the given
-	comment with the object. Example:
-<programlisting>
-foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
-lo_import 152801
-</programlisting>
-	The response indicates that the large object received object id
-	152801 which one ought to remember if one wants to access the
-	object ever again. For that reason it is recommended to always
-	associate a human-readable comment with every object. Those can
-	then be seen with the <command>\lo_list</command> command.
-	</para>
+        <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
 
+	<listitem>
 	<para>
-	Note that this command is subtly different from the server-side
-	<function>lo_import</function> because it acts as the local user
-	on the local file system, rather than the server's user and file
-	system.
+	This is not the actual command name: The letters i, s, t, v, S
+	stand for index, sequence, table, view, and system table,
+	respectively. You can specify any or all of them in any order to
+	obtain a listing of them, together with who the owner is.
 	</para>
 
-	<note>
 	<para>
-	See the description of the <envar>LO_TRANSACTION</envar>
-	variable for important information concerning all large object
-	operations.
+	If <replaceable class="parameter">pattern</replaceable> is
+	specified, it is a regular expression that restricts the listing
+	to those objects whose name matches. If one appends a
+	<quote>+</quote> to the command name, each object is listed with
+	its associated description, if any.
 	</para>
-	</note>
 	</listitem>
       </varlistentry>
 
+
       <varlistentry>
-        <term><literal>\lo_list</literal></term>
+        <term><literal>\dl</literal></term>
 	<listitem>
 	<para>
-	Shows a list of all <productname>PostgreSQL</productname>
-	<quote>large objects</quote> currently stored in the database,
-	along with any comments provided for them.
+	This is an alias for <command>\lo_list</command>, which shows a
+	list of large objects.
 	</para>
 	</listitem>
       </varlistentry>
 
+
       <varlistentry>
-        <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term>
+        <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term>
+        <listitem>
+        <para>
+        Lists available operators with their operand and return types.
+        If <replaceable class="parameter">name</replaceable> is
+        specified, only operators with that name will be shown.
+        </para>
+        </listitem>
+      </varlistentry>
 
-	<listitem>
-	<para>
-	Deletes the large object with <acronym>OID</acronym>
-	<replaceable class="parameter">loid</replaceable> from the
-	database.
-	</para>
 
-	<tip>
-	<para>
-	Use <command>\lo_list</command> to find out the large object's
-	<acronym>OID</acronym>.
-	</para>
-	</tip>
-	<note>
+      <varlistentry>
+        <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+	<listitem>
 	<para>
-	See the description of the <envar>LO_TRANSACTION</envar>
-	variable for important information concerning all large object
-	operations.
+	This is an alias for <command>\z</command> which was included
+	for its greater mnemonic value (<quote>display
+	permissions</quote>).
 	</para>
-	</note>
 	</listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term>
-
+        <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
         <listitem>
         <para>
-        Saves future query results to the file <replaceable
-        class="parameter">filename</replaceable> or pipes future results
-        into a separate Unix shell to execute <replaceable
-        class="parameter">command</replaceable>. If no arguments are
-        specified, the query output will be reset to
-        <filename>stdout</filename>.
+        Lists all data types or only those that match <replaceable
+        class="parameter">pattern</replaceable>. The command form
+        <literal>\dT+</literal> shows extra information.
         </para>
-
-	<para>
-	<quote>Query results</quote> includes all tables, command
-	responses, and notices obtained from the database server, as
-	well as output of various backslash commands that query the
-	database (such as <command>\d</command>), but not error
-	messages.
-	</para>
-
-	<tip>
-	<para>
-	To intersperse text output in between query results, use
-	<command>\qecho</command>.
-	</para>
-	</tip>
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\p</literal></term>
+        <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
         <listitem>
         <para>
-        Print the current query buffer to the standard output.
+        Lists all configured users or only those that match <replaceable
+        class="parameter">pattern</replaceable>.
         </para>
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term>
-
-	<listitem>
-	<para>
-	This command sets options affecting the output of query result
-	tables. <replaceable class="parameter">parameter</replaceable>
-	describes which option is to be set. The semantics of
-	<replaceable class="parameter">value</replaceable> depend
-	thereon.
-	</para>
-
-	<para>
-	Adjustable printing options are:
-	<variablelist>
-	  <varlistentry>
-	  <term><literal>format</literal></term>
-	  <listitem>
-	  <para>
-	  Sets the output format to one of <literal>unaligned</literal>,
-	  <literal>aligned</literal>, <literal>html</literal>, or
-	  <literal>latex</literal>. Unique abbreviations are allowed.
-	  (That would mean one letter is enough.)
-	  </para>
-
-	  <para>
-	  <quote>Unaligned</quote> writes all fields of a tuple on a
-	  line, separated by the currently active field separator. This
-	  is intended to create output that might be intended to be read
-	  in by other programs (tab-separated, comma-separated).
-	  <quote>Aligned</quote> mode is the standard, human-readable,
-	  nicely formatted text output that is default. The
-	  <quote><acronym>HTML</acronym></quote> and
-	  <quote>LaTeX</quote> modes put out tables that are intended to
-	  be included in documents using the respective mark-up
-	  language. They are not complete documents! (This might not be
-	  so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
-	  have a complete document wrapper.)
-	  </para>
-	  </listitem>
-          </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>border</literal></term>
-	  <listitem>
-	  <para>
-	  The second argument must be a number. In general, the higher
-	  the number the more borders and lines the tables will have,
-	  but this depends on the particular format. In
-	  <acronym>HTML</acronym> mode, this will translate directly
-	  into the <literal>border=...</literal> attribute, in the
-	  others only values 0 (no border), 1 (internal dividing lines),
-	  and 2 (table frame) make sense.
-	  </para>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>expanded</literal> (or <literal>x</literal>)</term>
-	  <listitem>
-	  <para>
-	  Toggles between regular and expanded format. When expanded
-	  format is enabled, all output has two columns with the field
-	  name on the left and the data on the right. This mode is
-	  useful if the data wouldn't fit on the screen in the normal
-	  <quote>horizontal</quote> mode.
-	  </para>
-
-	  <para>
-	  Expanded mode is supported by all four output modes.
-	  </para>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>null</literal></term>
-	  <listitem>
-	  <para>
-	  The second argument is a string that should be printed
-	  whenever a field is null. The default is not to print
-	  anything, which can easily be mistaken for, say, an empty
-	  string. Thus, one might choose to write <literal>\pset null
-	  '(null)'</literal>.
-	  </para>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>fieldsep</literal></term>
-	  <listitem>
-	  <para>
-	  Specifies the field separator to be used in unaligned output
-	  mode. That way one can create, for example, tab- or
-	  comma-separated output, which other programs might prefer. To
-	  set a tab as field separator, type <literal>\pset fieldsep
-	  '\t'</literal>. The default field separator is
-	  <literal>'|'</literal> (a <quote>pipe</quote> symbol).
-	  </para>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>footer</literal></term>
-	  <listitem>
-	  <para>
-	  Toggles the display of the default footer <literal>(x
-	  rows)</literal>.
-	  </para>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>recordsep</literal></term>
-	  <listitem>
-	  <para>
-          Specifies the record (line) separator to use in unaligned
-          output mode. The default is a newline character.
-	  </para>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
-	  <listitem>
-	  <para>
-	  Toggles between tuples only and full display. Full display may
-	  show extra information such as column headers, titles, and
-	  various footers. In tuples only mode, only actual table data
-	  is shown.
-	  </para>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term>
-	  <listitem>
-	  <para>
-	  Sets the table title for any subsequently printed tables. This
-	  can be used to give your output descriptive tags. If no
-	  argument is given, the title is unset.
-	  </para>
-
-	  <note>
-	  <para>
-	  This formerly only affected <acronym>HTML</acronym> mode. You
-	  can now set titles in any output format.
-	  </para>
-	  </note>
-	  </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	  <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term>
-	  <listitem>
-	  <para>
-	  Allows you to specify any attributes to be placed inside the
-	  <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This
-	  could for example be <literal>cellpadding</literal> or
-	  <literal>bgcolor</literal>. Note that you probably don't want
-	  to specify <literal>border</literal> here, as that is already
-	  taken care of by <literal>\pset border</literal>.
-	  </para>
-	  </listitem>
-	  </varlistentry>
+        <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term>
 
+        <listitem>
+        <para>
+        If <replaceable class="parameter">filename</replaceable> is
+        specified, the file is edited; after the editor exits, its
+        content is copied back to the query buffer. If no argument is
+        given, the current query buffer is copied to a temporary file
+        which is then edited in the same fashion.
+        </para>
 
-	  <varlistentry>
-	  <term><literal>pager</literal></term>
-	  <listitem>
-	  <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.
-	  </para>
+        <para>
+        The new query buffer is then re-parsed according to the normal
+        rules of <application>psql</application>, where the whole buffer
+        is treated as a single line. (Thus you cannot make scripts this
+        way. Use <command>\i</command> for that.) This means also that
+        if the query ends with (or rather contains) a semicolon, it is
+        immediately executed. In other cases it will merely wait in the
+        query buffer.
+        </para>
 
-	  <para>
-	  In any case, <application>psql</application> only uses the
-	  pager if it seems appropriate. That means among other things
-	  that the output is to a terminal and that the table would
-	  normally not fit on the screen. Because of the modular nature
-	  of the printing routines it is not always possible to predict
-	  the number of lines that will actually be printed. For that
-	  reason <application>psql</application> might not appear very
-	  discriminating about when to use the pager.
-	  </para>
-	  </listitem>
-	  </varlistentry>
-	</variablelist>
-	Illustrations on how these different formats look can be seen in
-	the <xref linkend="APP-PSQL-examples"
-	endterm="APP-PSQL-examples-title"> section.
+        <tip>
+        <para>
+        <application>psql</application> searches the environment
+        variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and
+        <envar>VISUAL</envar> (in that order) for an editor to use. If
+        all of them are unset, <filename>/bin/vi</filename> is run.
+        </para>
+        </tip>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term>
+        <listitem>
+	<para>
+        Prints the arguments to the standard output, separated by one
+        space and followed by a newline. This can be useful to
+        intersperse information in the output of scripts. For example:
+<programlisting>
+=> <userinput>\echo `date`</userinput>
+Tue Oct 26 21:40:57 CEST 1999
+</programlisting>
+        If the first argument is an unquoted <literal>-n</literal> the the trailing
+        newline is not written.
 	</para>
 
 	<tip>
 	<para>
-	There are various shortcut commands for <command>\pset</command>. See
-	<command>\a</command>, <command>\C</command>, <command>\H</command>,
-	<command>\t</command>, <command>\T</command>, and <command>\x</command>.
+	If you use the <command>\o</command> command to redirect your
+	query output you may wish to use <command>\qecho</command>
+	instead of this command.
 	</para>
 	</tip>
+	</listitem>
+      </varlistentry>
 
-	<note>
-	<para>
-	It is an error to call <command>\pset</command> without
-	arguments. In the future this call might show the current status
-	of all printing options.
-	</para>
-	</note>
 
-	</listitem>
+      <varlistentry>
+        <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term>
+
+        <listitem>
+        <para>
+        Sets the client encoding, if you are using multibyte encodings.
+        Without an argument, this command shows the current encoding.
+        </para>
+        </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\q</literal></term>
+        <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term>
+
         <listitem>
         <para>
-        Quit the <application>psql</application> program.
+        Sets the field separator for unaligned query output. The default
+        is pipe (<literal>|</literal>). See also
+        <command>\pset</command> for a generic way of setting output
+        options.
         </para>
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term>
+        <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>
+
         <listitem>
         <para>
-	This command is identical to <command>\echo</command> except
-	that all output will be written to the query output channel, as
-	set by <command>\o</command>.
+        Sends the current query input buffer to the backend and
+        optionally saves the output in <replaceable
+        class="parameter">filename</replaceable> or pipes the output
+        into a separate Unix shell to execute <replaceable
+        class="parameter">command</replaceable>. A bare
+        <literal>\g</literal> is virtually equivalent to a semicolon. A
+        <literal>\g</literal> with argument is a <quote>one-shot</quote>
+        alternative to the <command>\o</command> command.
+        </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
+        <listitem>
+        <para>
+        Give syntax help on the specified <acronym>SQL</acronym>
+        command. If <replaceable class="parameter">command</replaceable>
+        is not specified, then <application>psql</application> will list
+        all the commands for which syntax help is available. If
+        <replaceable class="parameter">command</replaceable> is an
+        asterisk (<quote>*</quote>), then syntax help on all
+        <acronym>SQL</acronym> commands is shown.
         </para>
+
+	<note>
+	<para>
+	To simplify typing, commands that consists of several words do
+	not have to be quoted. Thus it is fine to type <userinput>\help
+	alter table</userinput>.
+	</para>
+	</note>	
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\r</literal></term>
+        <term><literal>\H</literal></term>
         <listitem>
         <para>
-        Resets (clears) the query buffer.
+	Turns on <acronym>HTML</acronym> query output format. If the
+	<acronym>HTML</acronym> format is already on, it is switched
+	back to the default aligned text format. This command is for
+	compatibility and convenience, but see <command>\pset</command>
+	about setting other output options.
         </para>
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
+        <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
         <listitem>
         <para>
-        Print or save the command line history to <replaceable
-        class="parameter">filename</replaceable>. If <replaceable
-        class="parameter">filename</replaceable> is omitted, the history
-        is written to the standard output. This option is only available
-        if <application>psql</application> is configured to use the
-        <acronym>GNU</acronym> history library.
+        Reads input from the file <replaceable
+        class="parameter">filename</replaceable> and executes it as
+        though it had been typed on the keyboard.
+        </para>
+	<note>
+	<para>
+	If you want to see the lines on the screen as they are read you
+	must set the variable <envar>ECHO</envar> to
+	<literal>all</literal>.
+	</para>
+	</note>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><literal>\l</literal> (or <literal>\list</literal>)</term>
+        <listitem>
+        <para>
+        List all the databases in the server as well as their owners.
+        Append a <quote>+</quote> to the command name to see any
+        descriptions for the databases as well. If your
+        <productname>PostgreSQL</productname> installation was compiled
+        with multibyte encoding support, the encoding scheme of each
+        database is shown as well.
         </para>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term>
+
+	<listitem>
+	<para>
+	Reads the large object with <acronym>OID</acronym> <replaceable
+	class="parameter">loid</replaceable> from the database and
+	writes it to <replaceable
+	class="parameter">filename</replaceable>. Note that this is
+	subtly different from the server function
+	<function>lo_export</function>, which acts with the permissions
+	of the user that the database server runs as and on the server's
+	file system.
+	</para>
+	<tip>
+	<para>
+	Use <command>\lo_list</command> to find out the large object's
+	<acronym>OID</acronym>.
+	</para>
+	</tip>
+	<note>
+	<para>
+	See the description of the <envar>LO_TRANSACTION</envar>
+	variable for important information concerning all large object
+	operations.
+	</para>
+	</note>
+	</listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term>
+
+	<listitem>
+	<para>
+	Stores the file into a <productname>PostgreSQL</productname>
+	<quote>large object</quote>. Optionally, it associates the given
+	comment with the object. Example:
+<programlisting>
+foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
+lo_import 152801
+</programlisting>
+	The response indicates that the large object received object id
+	152801 which one ought to remember if one wants to access the
+	object ever again. For that reason it is recommended to always
+	associate a human-readable comment with every object. Those can
+	then be seen with the <command>\lo_list</command> command.
+	</para>
+
+	<para>
+	Note that this command is subtly different from the server-side
+	<function>lo_import</function> because it acts as the local user
+	on the local file system, rather than the server's user and file
+	system.
+	</para>
 
 	<note>
 	<para>
-	In the current version, it is no longer necessary to save the
-	command history, since that will be done automatically on
-	program termination. The history is also loaded automatically
-	every time <application>psql</application> starts up.
+	See the description of the <envar>LO_TRANSACTION</envar>
+	variable for important information concerning all large object
+	operations.
+	</para>
+	</note>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>\lo_list</literal></term>
+	<listitem>
+	<para>
+	Shows a list of all <productname>PostgreSQL</productname>
+	<quote>large objects</quote> currently stored in the database,
+	along with any comments provided for them.
 	</para>
-	</note>
-        </listitem>
+	</listitem>
       </varlistentry>
 
-
       <varlistentry>
-        <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term>
+        <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term>
 
 	<listitem>
 	<para>
-	Sets the internal variable <replaceable
-	class="parameter">name</replaceable> to <replaceable
-	class="parameter">value</replaceable> or, if more than one value
-	is given, to the concatenation of all of them. If no second
-	argument is given, the variable is just set with no value. To
-	unset a variable, use the <command>\unset</command> command.
-	</para>
-
-	<para>
-	Valid variable names can contain characters, digits, and
-	underscores. See the section about
-	<application>psql</application> variables for details.
+	Deletes the large object with <acronym>OID</acronym>
+	<replaceable class="parameter">loid</replaceable> from the
+	database.
 	</para>
 
+	<tip>
 	<para>
-	Although you are welcome to set any variable to anything you
-	want, <application>psql</application> treats several variables
-	as special. They are documented in the section about variables.
+	Use <command>\lo_list</command> to find out the large object's
+	<acronym>OID</acronym>.
 	</para>
-
+	</tip>
 	<note>
 	<para>
-	This command is totally separate from the <acronym>SQL</acronym>
-	command <xref linkend="SQL-SET" endterm="SQL-SET-title">.
+	See the description of the <envar>LO_TRANSACTION</envar>
+	variable for important information concerning all large object
+	operations.
 	</para>
 	</note>
 	</listitem>
@@ -1172,582 +1200,500 @@ lo_import 152801
 
 
       <varlistentry>
-        <term><literal>\t</literal></term>
-        <listitem>
-        <para>
-        Toggles the display of output column name headings and row count
-        footer. This command is equivalent to <literal>\pset
-        tuples_only</literal> and is provided for convenience.
-        </para>
-        </listitem>
-      </varlistentry>
-
+        <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term>
 
-      <varlistentry>
-        <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
         <listitem>
         <para>
-        Allows you to specify options to be placed within the
-        <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
-        output mode. This command is equivalent to <literal>\pset
-        tableattr <replaceable
-        class="parameter">table_options</replaceable></literal>.
+        Saves future query results to the file <replaceable
+        class="parameter">filename</replaceable> or pipes future results
+        into a separate Unix shell to execute <replaceable
+        class="parameter">command</replaceable>. If no arguments are
+        specified, the query output will be reset to
+        <filename>stdout</filename>.
         </para>
-        </listitem>
-      </varlistentry>
 
+	<para>
+	<quote>Query results</quote> includes all tables, command
+	responses, and notices obtained from the database server, as
+	well as output of various backslash commands that query the
+	database (such as <command>\d</command>), but not error
+	messages.
+	</para>
 
-      <varlistentry>
-       <term><literal>\timing</literal></term>
-        <listitem>
-        <para>
-         Toggles a display of how long each query takes in seconds.
-        </para>
-       </listitem>
+	<tip>
+	<para>
+	To intersperse text output in between query results, use
+	<command>\qecho</command>.
+	</para>
+	</tip>
+        </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
+        <term><literal>\p</literal></term>
         <listitem>
         <para>
-        Outputs the current query buffer to the file <replaceable
-        class="parameter">filename</replaceable> or pipes it to the Unix
-        command <replaceable class="parameter">command</replaceable>.
+        Print the current query buffer to the standard output.
         </para>
         </listitem>
       </varlistentry>
 
 
       <varlistentry>
-        <term><literal>\x</literal></term>
-        <listitem>
-        <para>
-        Toggles extended row format mode. As such it is equivalent to
-	<literal>\pset expanded</literal>.
-       </para>
-       </listitem>
-      </varlistentry>
-
-
-      <varlistentry>
-        <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
-        <listitem>
-        <para>
-        Produces a list of all tables in the database with their
-        appropriate access permissions listed. If an argument is given
-        it is taken as a regular expression which limits the listing to
-        those tables which match it.
-        </para>
+        <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term>
 
+	<listitem>
 	<para>
-<programlisting>
-test=&gt; <userinput>\z</userinput>
-Access permissions for database "test"
- Relation |           Access permissions
-----------+-------------------------------------
- my_table | {"=r","joe=arwR", "group staff=ar"}
-(1 row )
-</programlisting>
-        Read this as follows:
-
-	<itemizedlist>
-          <listitem>
-          <para>
-          <literal>"=r"</literal>: <literal>PUBLIC</literal> has read
-          (<command>SELECT</command>) permission on the table.
-	  </para>
-	  </listitem>
+	This command sets options affecting the output of query result
+	tables. <replaceable class="parameter">parameter</replaceable>
+	describes which option is to be set. The semantics of
+	<replaceable class="parameter">value</replaceable> depend
+	thereon.
+	</para>
 
+	<para>
+	Adjustable printing options are:
+	<variablelist>
+	  <varlistentry>
+	  <term><literal>format</literal></term>
 	  <listitem>
 	  <para>
-	  <literal>"joe=arwR"</literal>: User <literal>joe</literal> has
-	  read, write (<command>UPDATE</command>,
-	  <command>DELETE</command>), <quote>append</quote>
-	  (<command>INSERT</command>) permissions, and permission to
-	  create rules on the table.
+	  Sets the output format to one of <literal>unaligned</literal>,
+	  <literal>aligned</literal>, <literal>html</literal>, or
+	  <literal>latex</literal>. Unique abbreviations are allowed.
+	  (That would mean one letter is enough.)
 	  </para>
-	  </listitem>
 
-	  <listitem>
 	  <para>
-	  <literal>"group staff=ar"</literal>: Group
-	  <literal>staff</literal> has <command>SELECT</command> and
-	  <command>INSERT</command> permission.
+	  <quote>Unaligned</quote> writes all fields of a tuple on a
+	  line, separated by the currently active field separator. This
+	  is intended to create output that might be intended to be read
+	  in by other programs (tab-separated, comma-separated).
+	  <quote>Aligned</quote> mode is the standard, human-readable,
+	  nicely formatted text output that is default. The
+	  <quote><acronym>HTML</acronym></quote> and
+	  <quote>LaTeX</quote> modes put out tables that are intended to
+	  be included in documents using the respective mark-up
+	  language. They are not complete documents! (This might not be
+	  so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
+	  have a complete document wrapper.)
 	  </para>
-	  </listitem>
-	</itemizedlist>
-	</para>
-
-	<para>
-	The commands <xref linkend="SQL-GRANT"> and
-	<xref linkend="SQL-REVOKE">
-	are used to set access permissions.
-	</para>
-
-        </listitem>
-      </varlistentry>
-
-
-      <varlistentry>
-        <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
-        <listitem>
-        <para>
-        Escapes to a separate Unix shell or executes the Unix command
-        <replaceable class="parameter">command</replaceable>. The
-        arguments are not further interpreted, the shell will see them
-        as is.
-        </para>
-        </listitem>
-      </varlistentry>
-
-
-      <varlistentry>
-        <term><literal>\?</literal></term>
-        <listitem>
-        <para>
-        Get help information about the backslash (<quote>\</quote>)
-        commands.
-        </para>
-        </listitem>
-      </varlistentry>
-
-    </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>
-
+	  </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><literal>border</literal></term>
+	  <listitem>
+	  <para>
+	  The second argument must be a number. In general, the higher
+	  the number the more borders and lines the tables will have,
+	  but this depends on the particular format. In
+	  <acronym>HTML</acronym> mode, this will translate directly
+	  into the <literal>border=...</literal> attribute, in the
+	  others only values 0 (no border), 1 (internal dividing lines),
+	  and 2 (table frame) make sense.
+	  </para>
+	  </listitem>
+	  </varlistentry>
 
+	  <varlistentry>
+	  <term><literal>expanded</literal> (or <literal>x</literal>)</term>
+	  <listitem>
+	  <para>
+	  Toggles between regular and expanded format. When expanded
+	  format is enabled, all output has two columns with the field
+	  name on the left and the data on the right. This mode is
+	  useful if the data wouldn't fit on the screen in the normal
+	  <quote>horizontal</quote> mode.
+	  </para>
 
-    <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>
+	  <para>
+	  Expanded mode is supported by all four output modes.
+	  </para>
+	  </listitem>
+	  </varlistentry>
 
+	  <varlistentry>
+	  <term><literal>null</literal></term>
+	  <listitem>
+	  <para>
+	  The second argument is a string that should be printed
+	  whenever a field is null. The default is not to print
+	  anything, which can easily be mistaken for, say, an empty
+	  string. Thus, one might choose to write <literal>\pset null
+	  '(null)'</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><literal>fieldsep</literal></term>
+	  <listitem>
+	  <para>
+	  Specifies the field separator to be used in unaligned output
+	  mode. That way one can create, for example, tab- or
+	  comma-separated output, which other programs might prefer. To
+	  set a tab as field separator, type <literal>\pset fieldsep
+	  '\t'</literal>. The default field separator is
+	  <literal>'|'</literal> (a <quote>pipe</quote> symbol).
+	  </para>
+	  </listitem>
+	  </varlistentry>
 
+	  <varlistentry>
+	  <term><literal>footer</literal></term>
+	  <listitem>
+	  <para>
+	  Toggles the display of the default footer <literal>(x
+	  rows)</literal>.
+	  </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>
+	  <varlistentry>
+	  <term><literal>recordsep</literal></term>
+	  <listitem>
+	  <para>
+          Specifies the record (line) separator to use in unaligned
+          output mode. The default is a newline character.
+	  </para>
+	  </listitem>
+	  </varlistentry>
 
-      <para>
-       If <replaceable>filename</replaceable> is <literal>-</literal>
-       (hyphen), then standard input is read.
-      </para>
+	  <varlistentry>
+	  <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
+	  <listitem>
+	  <para>
+	  Toggles between tuples only and full display. Full display may
+	  show extra information such as column headers, titles, and
+	  various footers. In tuples only mode, only actual table data
+	  is shown.
+	  </para>
+	  </listitem>
+	  </varlistentry>
 
-      <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><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term>
+	  <listitem>
+	  <para>
+	  Sets the table title for any subsequently printed tables. This
+	  can be used to give your output descriptive tags. If no
+	  argument is given, the title is unset.
+	  </para>
 
+	  <note>
+	  <para>
+	  This formerly only affected <acronym>HTML</acronym> mode. You
+	  can now set titles in any output format.
+	  </para>
+	  </note>
+	  </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><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term>
+	  <listitem>
+	  <para>
+	  Allows you to specify any attributes to be placed inside the
+	  <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. This
+	  could for example be <literal>cellpadding</literal> or
+	  <literal>bgcolor</literal>. Note that you probably don't want
+	  to specify <literal>border</literal> here, as that is already
+	  taken care of by <literal>\pset border</literal>.
+	  </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><literal>pager</literal></term>
+	  <listitem>
+	  <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 a platform-dependent default (such as
+	  <filename>more</filename>) is used.
+	  </para>
 
+	  <para>
+	  In any case, <application>psql</application> only uses the
+	  pager if it seems appropriate. That means among other things
+	  that the output is to a terminal and that the table would
+	  normally not fit on the screen. Because of the modular nature
+	  of the printing routines it is not always possible to predict
+	  the number of lines that will actually be printed. For that
+	  reason <application>psql</application> might not appear very
+	  discriminating about when to use the pager.
+	  </para>
+	  </listitem>
+	  </varlistentry>
+	</variablelist>
+	Illustrations on how these different formats look can be seen in
+	the <xref linkend="APP-PSQL-examples"
+	endterm="APP-PSQL-examples-title"> section.
+	</para>
 
-    <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>
+	<tip>
+	<para>
+	There are various shortcut commands for <command>\pset</command>. See
+	<command>\a</command>, <command>\C</command>, <command>\H</command>,
+	<command>\t</command>, <command>\T</command>, and <command>\x</command>.
+	</para>
+	</tip>
 
- 
-    <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>
+	<note>
+	<para>
+	It is an error to call <command>\pset</command> without
+	arguments. In the future this call might show the current status
+	of all printing options.
+	</para>
+	</note>
 
+	</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><literal>\q</literal></term>
+        <listitem>
+        <para>
+        Quit the <application>psql</application> program.
+        </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><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term>
+        <listitem>
+        <para>
+	This command is identical to <command>\echo</command> except
+	that all output will be written to the query output channel, as
+	set by <command>\o</command>.
+        </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><literal>\r</literal></term>
+        <listitem>
+        <para>
+        Resets (clears) the query buffer.
+        </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><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
+        <listitem>
+        <para>
+        Print or save the command line history to <replaceable
+        class="parameter">filename</replaceable>. If <replaceable
+        class="parameter">filename</replaceable> is omitted, the history
+        is written to the standard output. This option is only available
+        if <application>psql</application> is configured to use the
+        <acronym>GNU</acronym> history library.
+        </para>
 
-    <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>
+	<note>
+	<para>
+	In the current version, it is no longer necessary to save the
+	command history, since that will be done automatically on
+	program termination. The history is also loaded automatically
+	every time <application>psql</application> starts up.
+	</para>
+	</note>
+        </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><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term>
 
-    <varlistentry>
-      <term>-S, --single-line</term>
-      <listitem>
-      <para>
-      Runs in single-line mode where a newline terminates a query, as a
-      semicolon does.
-      </para>
+	<listitem>
+	<para>
+	Sets the internal variable <replaceable
+	class="parameter">name</replaceable> to <replaceable
+	class="parameter">value</replaceable> or, if more than one value
+	is given, to the concatenation of all of them. If no second
+	argument is given, the variable is just set with no value. To
+	unset a variable, use the <command>\unset</command> command.
+	</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>
+	<para>
+	Valid variable names can contain characters, digits, and
+	underscores. See the section about
+	<application>psql</application> variables for details.
+	</para>
 
+	<para>
+	Although you are welcome to set any variable to anything you
+	want, <application>psql</application> treats several variables
+	as special. They are documented in the section about variables.
+	</para>
 
-    <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>
+	<note>
+	<para>
+	This command is totally separate from the <acronym>SQL</acronym>
+	command <xref linkend="SQL-SET" endterm="SQL-SET-title">.
+	</para>
+	</note>
+	</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><literal>\t</literal></term>
+        <listitem>
+        <para>
+        Toggles the display of output column name headings and row count
+        footer. This command is equivalent to <literal>\pset
+        tuples_only</literal> and is provided for convenience.
+        </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><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
+        <listitem>
+        <para>
+        Allows you to specify options to be placed within the
+        <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
+        output mode. This command is equivalent to <literal>\pset
+        tableattr <replaceable
+        class="parameter">table_options</replaceable></literal>.
+        </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><literal>\timing</literal></term>
+        <listitem>
+        <para>
+         Toggles a display of how long each query takes in seconds.
+        </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><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
+        <listitem>
+        <para>
+        Outputs the current query buffer to the file <replaceable
+        class="parameter">filename</replaceable> or pipes it to the Unix
+        command <replaceable class="parameter">command</replaceable>.
+        </para>
+        </listitem>
+      </varlistentry>
 
 
-    <varlistentry>
-      <term>-V, --version</term>
-      <listitem>
-      <para>
-      Shows the <application>psql</application> version.
-      </para>
-      </listitem>
-    </varlistentry>
+      <varlistentry>
+        <term><literal>\x</literal></term>
+        <listitem>
+        <para>
+        Toggles extended row format mode. As such it is equivalent to
+	<literal>\pset expanded</literal>.
+       </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>
+      <varlistentry>
+        <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
+        <listitem>
+        <para>
+        Produces a list of all tables in the database with their
+        appropriate access permissions listed. If an argument is given
+        it is taken as a regular expression which limits the listing to
+        those tables which match it.
+        </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>
+	<para>
+<programlisting>
+test=&gt; <userinput>\z</userinput>
+Access permissions for database "test"
+ Relation |           Access permissions
+----------+-------------------------------------
+ my_table | {"=r","joe=arwR", "group staff=ar"}
+(1 row )
+</programlisting>
+        Read this as follows:
 
+	<itemizedlist>
+          <listitem>
+          <para>
+          <literal>"=r"</literal>: <literal>PUBLIC</literal> has read
+          (<command>SELECT</command>) permission on the table.
+	  </para>
+	  </listitem>
 
-    <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>
+	  <listitem>
+	  <para>
+	  <literal>"joe=arwR"</literal>: User <literal>joe</literal> has
+	  read, write (<command>UPDATE</command>,
+	  <command>DELETE</command>), <quote>append</quote>
+	  (<command>INSERT</command>) permissions, and permission to
+	  create rules on the table.
+	  </para>
+	  </listitem>
 
+	  <listitem>
+	  <para>
+	  <literal>"group staff=ar"</literal>: Group
+	  <literal>staff</literal> has <command>SELECT</command> and
+	  <command>INSERT</command> permission.
+	  </para>
+	  </listitem>
+	</itemizedlist>
+	</para>
 
-    <varlistentry>
-      <term>-X, --no-psqlrc</term>
-      <listitem>
-      <para>
-      Do not read the start-up file <filename>~/.psqlrc</filename>.
-      </para>
-      </listitem>
-    </varlistentry>
+	<para>
+	The commands <xref linkend="SQL-GRANT"> and
+	<xref linkend="SQL-REVOKE">
+	are used to set access permissions.
+	</para>
 
+        </listitem>
+      </varlistentry>
 
-    <varlistentry>
-      <term>-?, --help</term>
-      <listitem>
-      <para>
-      Shows help about <application>psql</application> command line
-      arguments.
-      </para>
-      </listitem>
-    </varlistentry>
 
-  </variablelist>
-  </para>
+      <varlistentry>
+        <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
+        <listitem>
+        <para>
+        Escapes to a separate Unix shell or executes the Unix command
+        <replaceable class="parameter">command</replaceable>. The
+        arguments are not further interpreted, the shell will see them
+        as is.
+        </para>
+        </listitem>
+      </varlistentry>
 
-</refsect1>
 
+      <varlistentry>
+        <term><literal>\?</literal></term>
+        <listitem>
+        <para>
+        Get help information about the backslash (<quote>\</quote>)
+        commands.
+        </para>
+        </listitem>
+      </varlistentry>
 
-<refsect1 id="R1-APP-PSQL-4">
-    <refsect1info>
-      <date>1998-09-27</date>
-    </refsect1info>
+    </variablelist>
+  </para>
+ </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>
-
-  <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>
+   </refsect3>
 
-  <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 b1c3cab01a..37debc1b84 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
-- 
2.24.1