Another big editing pass for consistent content and presentation.

doc/src/sgml/backup.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.25 2003/03/18 00:02:11 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.26 2003/03/24 14:32:50 petere Exp $
 -->
 <chapter id="backup">
  <title>Backup and Restore</title>
@@ -110,7 +110,7 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
     <application>psql</> (e.g., with <literal>createdb -T template0
     <replaceable class="parameter">dbname</></literal>).
     <application>psql</> supports similar options to <application>pg_dump</> 
-    for controlling the database server location and the user names. See
+    for controlling the database server location and the user name. See
     its reference page for more information.
    </para>
 
@@ -135,7 +135,7 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
    <para>
     The ability of <application>pg_dump</> and <application>psql</> to
     write to or read from pipes makes it possible to dump a database
-    directly from one server to another, for example
+    directly from one server to another; for example:
 <programlisting>
 pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>host2</> <replaceable>dbname</>
 </programlisting>
@@ -179,27 +179,19 @@ pg_dumpall &gt; <replaceable>outfile</>
   <sect2 id="backup-dump-large">
    <title>Large Databases</title>
 
-   <note>
-    <title>Acknowledgement</title>
-    <para>
-     Originally written by Hannu Krosing
-     (<email>hannu@trust.ee</email>) on 1999-06-19
-    </para>
-   </note>
-
    <para>
     Since <productname>PostgreSQL</productname> allows tables larger
     than the maximum file size on your system, it can be problematic
-    to dump the table to a file, since the resulting file will likely
+    to dump such a table to a file, since the resulting file will likely
     be larger than the maximum size allowed by your system. As
-    <application>pg_dump</> writes to the standard output, you can
-    just use standard *nix tools to work around this possible problem.
+    <application>pg_dump</> can write to the standard output, you can
+    just use standard Unix tools to work around this possible problem.
    </para>
 
    <formalpara>
     <title>Use compressed dumps.</title>
     <para>
-     Use your favorite compression program, for example
+     You can use your favorite compression program, for example
      <application>gzip</application>.
 
 <programlisting>
@@ -222,9 +214,10 @@ cat <replaceable class="parameter">filename</replaceable>.gz | gunzip | psql <re
    </formalpara>
 
    <formalpara>
-    <title>Use <application>split</>.</title>
+    <title>Use <command>split</>.</title>
     <para>
-     This allows you to split the output into pieces that are
+     The <command>split</command> command
+     allows you to split the output into pieces that are
      acceptable in size to the underlying file system. For example, to
      make chunks of 1 megabyte:
 
@@ -338,7 +331,7 @@ tar -cf backup.tar /usr/local/pgsql/data
 
     <listitem>
      <para>
-      If you have dug into the details of the file system layout you
+      If you have dug into the details of the file system layout of the data you
       may be tempted to try to back up or restore only certain
       individual tables or databases from their respective files or
       directories. This will <emphasis>not</> work because the
@@ -348,7 +341,7 @@ tar -cf backup.tar /usr/local/pgsql/data
       all transactions. A table file is only usable with this
       information. Of course it is also impossible to restore only a
       table and the associated <filename>pg_clog</filename> data
-      because that will render all other tables in the database
+      because that would render all other tables in the database
       cluster useless.
      </para>
     </listitem>
@@ -381,7 +374,7 @@ tar -cf backup.tar /usr/local/pgsql/data
    server, using <application>pg_dump</>. (There are checks in place
    that prevent you from doing the wrong thing, so no harm can be done
    by confusing these things.) The precise installation procedure is
-   not subject of this section, these details are in <xref linkend="installation">.
+   not subject of this section; these details are in <xref linkend="installation">.
   </para>
 
   <para>
@@ -393,7 +386,7 @@ tar -cf backup.tar /usr/local/pgsql/data
 pg_dumpall -p 5432 | psql -d template1 -p 6543
 </programlisting>
 
-   to transfer your data, or use an intermediate file if you want.
+   to transfer your data.  Or use an intermediate file if you want.
    Then you can shut down the old server and start the new server at
    the port the old one was running at. You should make sure that the
    database is not updated after you run <application>pg_dumpall</>,
@@ -413,7 +406,7 @@ pg_dumpall -p 5432 | psql -d template1 -p 6543
 pg_dumpall > backup
 pg_ctl stop
 mv /usr/local/pgsql /usr/local/pgsql.old
-cd /usr/src/postgresql-&version;
+cd ~/postgresql-&version;
 gmake install
 initdb -D /usr/local/pgsql/data
 postmaster -D /usr/local/pgsql/data

doc/src/sgml/charset.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.32 2003/03/13 01:30:26 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.33 2003/03/24 14:32:50 petere Exp $ -->
 
 <chapter id="charset">
  <title>Localization</>
 
- <abstract>
-  <para>
-   Describes the available localization features from the point of
-   view of the administrator.
-  </para>
- </abstract>
-
-  <para>
-   <productname>PostgreSQL</productname> supports localization with
-   three approaches:
+ <para>
+  This chapter describes the available localization features from the
+  point of view of the administrator.
+  <productname>PostgreSQL</productname> supports localization with
+  three approaches:
 
    <itemizedlist>
     <listitem>
@@ -25,20 +20,17 @@
 
     <listitem>
      <para>
-      Using explicit multiple-byte character sets defined in the
-      <productname>PostgreSQL</productname> server to support languages
-      that require more characters than will fit into a single byte,
-      and to provide character set recoding between client and server.
-      The number of supported character sets is fixed at the time the
-      server is compiled, and internal operations such as string
-      comparisons require expansion of each character into a 32-bit
-      word.
+      Providing a number of different character sets defined in the
+      <productname>PostgreSQL</productname> server, including
+      multiple-byte character sets, to support storing text in all
+      kinds of languages, and providing character set recoding between
+      client and server.
      </para>
     </listitem>
 
     <listitem>
      <para>
-      Single byte character recoding provides a more light-weight
+      Single-byte character recoding provides a more light-weight
       solution for users of multiple, yet single-byte character sets.
      </para>
     </listitem>
@@ -55,7 +47,7 @@
    <firstterm>Locale</> support refers to an application respecting
    cultural preferences regarding alphabets, sorting, number
    formatting, etc.  <productname>PostgreSQL</> uses the standard ISO
-   C and <acronym>POSIX</acronym>-like locale facilities provided by the server operating
+   C and <acronym>POSIX</acronym> locale facilities provided by the server operating
    system.  For additional information refer to the documentation of your
    system.
   </para>
@@ -92,7 +84,7 @@ initdb --locale=sv_SE
 
    <para>
     Occasionally it is useful to mix rules from several locales, e.g.,
-    use U.S. collation rules but Spanish messages.  To support that, a
+    use English collation rules but Spanish messages.  To support that, a
     set of locale subcategories exist that control only a certain
     aspect of the localization rules.
 
@@ -154,7 +146,7 @@ initdb --locale=sv_SE
 
    <para>
     The other locale categories can be changed as desired whenever the
-    server is started by setting the run-time configuration variables
+    server is running by setting the run-time configuration variables
     that have the same name as the locale categories (see <xref
     linkend="runtime-config"> for details).  The defaults that are
     chosen by <command>initdb</command> are actually only written into
@@ -190,16 +182,15 @@ initdb --locale=sv_SE
      variable <envar>LANGUAGE</envar> which overrides all other locale
      settings for the purpose of setting the language of messages.  If
      in doubt, please refer to the documentation of your operating
-     system, in particular the
-     <citerefentry><refentrytitle>gettext</><manvolnum>3</></> manual
-     page, for more information.
+     system, in particular the documentation about
+     <application>gettext</>, for more information.
     </para>
    </note>
 
    <para>
     To enable messages translated to the user's preferred language,
-    the <option>--enable-nls</option> option must be used.  This
-    option is independent of the other locale support.
+    <acronym>NLS</acronym> must have been enabled at build time.  This
+    choice is independent of the other locale support.
    </para>
   </sect2>
 
@@ -212,7 +203,7 @@ initdb --locale=sv_SE
     <itemizedlist>
      <listitem>
       <para>
-       Sort order in <command>ORDER BY</> queries.
+       Sort order in queries using <command>ORDER BY</>
        <indexterm><primary>ORDER BY</></>
       </para>
      </listitem>
@@ -234,7 +225,7 @@ initdb --locale=sv_SE
 
    <para>
     The only severe drawback of using the locale support in
-    <productname>PostgreSQL</> is its speed.  So use locale only if you
+    <productname>PostgreSQL</> is its speed.  So use locales only if you
     actually need it.  It should be noted in particular that selecting
     a non-C locale disables index optimizations for <literal>LIKE</> and
     <literal>~</> operators, which can make a huge difference in the
@@ -247,49 +238,28 @@ initdb --locale=sv_SE
 
    <para>
     If locale support doesn't work in spite of the explanation above,
-    check that the locale support in your operating system is correctly configured.
-    To check whether a given locale is installed and functional you
-    can use <application>Perl</>, for example.  Perl has also support
-    for locales and if a locale is broken <command>perl -v</> will
-    complain something like this:
-<screen>
-<prompt>$</> <userinput>export LC_CTYPE='not_exist'</>
-<prompt>$</> <userinput>perl -v</>
-<computeroutput>
-perl: warning: Setting locale failed.
-perl: warning: Please check that your locale settings:
-LC_ALL = (unset),
-LC_CTYPE = "not_exist",
-LANG = (unset)
-are supported and installed on your system.
-perl: warning: Falling back to the standard locale ("C").
-</computeroutput>
-</screen>
+    check that the locale support in your operating system is
+    correctly configured.  To check what locales are installed on your
+    system, you may use the command <literal>locale -a</literal> if
+    your operating system provides it.
    </para>
 
    <para>
-    Check that your locale files are in the right location.  Possible
-    locations include: <filename>/usr/lib/locale</filename> (<systemitem class="osname">Linux</>,
-    <systemitem class="osname">Solaris</>), <filename>/usr/share/locale</filename> (<systemitem class="osname">Linux</>),
-    <filename>/usr/lib/nls/loc</filename> (<systemitem class="osname">DUX 4.0</>).  Check the locale
-    man page of your system if you are not sure.
+    Check that <productname>PostgreSQL</> is actually using the locale
+    that you think it is.  <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
+    settings are determined at <command>initdb</> time and cannot be
+    changed without repeating <command>initdb</>.  Other locale
+    settings including <envar>LC_MESSAGES</> and <envar>LC_MONETARY</>
+    are initially determined by the environment the server is started
+    in.  You can check the <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
+    settings of a database with the utility program
+    <command>pg_controldata</>.
    </para>
 
    <para>
-    Check that <productname>PostgreSQL</> is actually using the locale that
-    you think it is.  <envar>LC_COLLATE</> and <envar>LC_CTYPE</> settings are
-    determined at <application>initdb</> time and cannot be changed without
-    repeating <application>initdb</>.  Other locale settings including
-    <envar>LC_MESSAGES</> and <envar>LC_MONETARY</> are determined by the 
-    environment the postmaster is started in, and can be changed with a simple
-    postmaster restart.  You can check the <envar>LC_COLLATE</> and
-    <envar>LC_CTYPE</> settings of
-    a database with the <filename>contrib/pg_controldata</> utility program.
-   </para>
-
-   <para>
-    The directory <filename>src/test/locale</> contains a test suite
-    for <productname>PostgreSQL</>'s locale support.
+    The directory <filename>src/test/locale</> in the source
+    distribution contains a test suite for
+    <productname>PostgreSQL</>'s locale support.
    </para>
 
    <para>
@@ -297,9 +267,9 @@ perl: warning: Falling back to the standard locale ("C").
     text of the error message will obviously have problems when the
     server's messages are in a different language.  If you create such
     an application you need to devise a plan to cope with this
-    situation.  The embedded SQL interface (<application>ecpg</>) is
+    situation.  The embedded SQL interface (<application>ECPG</>) is
     also affected by this problem.  It is currently recommended that
-    servers interfacing with <application>ecpg</> applications be
+    servers interfacing with <application>ECPG</> applications be
     configured to send messages in English.
    </para>
 
@@ -316,58 +286,41 @@ perl: warning: Falling back to the standard locale ("C").
  </sect1>
 
 
-  <sect1 id="multibyte">
-   <title>Multibyte Support</title>
-
-  <indexterm zone="multibyte"><primary>multibyte</></>
-
-   <note>
-    <title>Author</title>
-
-    <para>
-     Tatsuo Ishii (<email>ishii@postgresql.org</email>),
-     last updated 2002-07-24.
-     Check <ulink
-      url="http://www.sra.co.jp/people/t-ishii/PostgreSQL/">Tatsuo's
-      web site</ulink> for more information.
-    </para>
-   </note>
+ <sect1 id="multibyte">
+  <title>Character Set Support</title>
 
-   <para>
-    Multibyte (<acronym>MB</acronym>) support is intended to allow
-    <productname>PostgreSQL</productname> to handle
-    multiple-byte character sets such as <acronym>EUC</> (Extended Unix Code), Unicode, and
-    Mule internal code. With <acronym>MB</acronym> enabled you can use multibyte
-    character sets in regular expressions (regexp), LIKE, and some
-    other functions. The default
-    encoding system is selected while initializing your
-    <productname>PostgreSQL</productname> installation using
-    <application>initdb</application>. Note that this can be
-    overridden when you create a database using
-    <application>createdb</application> or by using the SQL command
-    <command>CREATE DATABASE</>. So you can have multiple databases each with
-    a different encoding system. Note that <acronym>MB</acronym> can
-    handle single byte characters sets such as ISO-8859-1.
-   </para>
+  <indexterm zone="multibyte"><primary>character set</></>
 
-    <para>
-    Multibyte support is enabled by default since
-    <productname>PostgreSQL</> version 7.3.
-    </para>
+  <para>
+   The character set support in <productname>PostgreSQL</productname>
+   allows you to store text in a variety of character sets, including
+   single-byte character sets such as the ISO 8859 series and
+   multiple-byte character sets such as <acronym>EUC</> (Extended Unix
+   Code), Unicode, and Mule internal code.  All character sets can be
+   used transparently throughout the server.  (If you use extension
+   functions from other sources, it depends on whether they wrote
+   their code correctly.)  The default character set is selected while
+   initializing your <productname>PostgreSQL</productname> database
+   cluster using <command>initdb</>.  It can be overridden when you
+   create a database using <command>createdb</command> or by using the
+   SQL command <command>CREATE DATABASE</>. So you can have multiple
+   databases each with a different character set.
+  </para>
 
    <sect2>
-    <title>Supported character set encodings</title>
+    <title>Supported Character Sets</title>
 
     <para>
-    Following encoding can be used as database encoding.
+     <xref linkend="charset-table"> shows the character sets available
+     for use in the server.
+    </para>
 
-     <table tocentry="1">
-      <title>Character Set Encodings</title>
-      <titleabbrev>Encodings</titleabbrev>
+     <table id="charset-table">
+      <title>Server Character Sets</title>
       <tgroup cols="2">
        <thead>
 	<row>
-	 <entry>Encoding</entry>
+	 <entry>Name</entry>
 	 <entry>Description</entry>
 	</row>
        </thead>
@@ -406,59 +359,59 @@ perl: warning: Falling back to the standard locale ("C").
 	</row>
 	<row>
 	 <entry><literal>LATIN1</literal></entry>
-	 <entry>ISO 8859-1 <acronym>ECMA</>-94 Latin Alphabet No.1</entry>
+	 <entry>ISO 8859-1/<acronym>ECMA</> 94 (Latin alphabet no.1)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN2</literal></entry>
-	 <entry>ISO 8859-2 <acronym>ECMA</>-94 Latin Alphabet No.2</entry>
+	 <entry>ISO 8859-2/<acronym>ECMA</> 94 (Latin alphabet no.2)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN3</literal></entry>
-	 <entry>ISO 8859-3 <acronym>ECMA</>-94 Latin Alphabet No.3</entry>
+	 <entry>ISO 8859-3/<acronym>ECMA</> 94 (Latin alphabet no.3)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN4</literal></entry>
-	 <entry>ISO 8859-4 <acronym>ECMA</>-94 Latin Alphabet No.4</entry>
+	 <entry>ISO 8859-4/<acronym>ECMA</> 94 (Latin alphabet no.4)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN5</literal></entry>
-	 <entry>ISO 8859-9 <acronym>ECMA</>-128 Latin Alphabet No.5</entry>
+	 <entry>ISO 8859-9/<acronym>ECMA</> 128 (Latin alphabet no.5)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN6</literal></entry>
-	 <entry>ISO 8859-10 <acronym>ECMA</>-144 Latin Alphabet No.6</entry>
+	 <entry>ISO 8859-10/<acronym>ECMA</> 144 (Latin alphabet no.6)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN7</literal></entry>
-	 <entry>ISO 8859-13 Latin Alphabet No.7</entry>
+	 <entry>ISO 8859-13 (Latin alphabet no.7)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN8</literal></entry>
-	 <entry>ISO 8859-14 Latin Alphabet No.8</entry>
+	 <entry>ISO 8859-14 (Latin alphabet no.8)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN9</literal></entry>
-	 <entry>ISO 8859-15 Latin Alphabet No.9</entry>
+	 <entry>ISO 8859-15 (Latin alphabet no.9)</entry>
 	</row>
 	<row>
 	 <entry><literal>LATIN10</literal></entry>
-	 <entry>ISO 8859-16 <acronym>ASRO</> SR 14111 Latin Alphabet No.10</entry>
+	 <entry>ISO 8859-16/<acronym>ASRO</> SR 14111 (Latin alphabet no.10)</entry>
 	</row>
 	<row>
 	 <entry><literal>ISO-8859-5</literal></entry>
-	 <entry><acronym>ECMA</>-113 Latin/Cyrillic</entry>
+	 <entry>ISO 8859-5/<acronym>ECMA</> 113 (Latin/Cyrillic)</entry>
 	</row>
 	<row>
 	 <entry><literal>ISO-8859-6</literal></entry>
-	 <entry><acronym>ECMA</>-114 Latin/Arabic</entry>
+	 <entry>ISO 8859-6/<acronym>ECMA</> 114 (Latin/Arabic)</entry>
 	</row>
 	<row>
 	 <entry><literal>ISO-8859-7</literal></entry>
-	 <entry><acronym>ECMA</>-118 Latin/Greek</entry>
+	 <entry>ISO 8859-7/<acronym>ECMA</> 118 (Latin/Greek)</entry>
 	</row>
 	<row>
 	 <entry><literal>ISO-8859-8</literal></entry>
-	 <entry><acronym>ECMA</>-121 Latin/Hebrew</entry>
+	 <entry>ISO 8859-8/<acronym>ECMA</> 121 (Latin/Hebrew)</entry>
 	</row>
 	<row>
 	 <entry><literal>KOI8</literal></entry>
@@ -474,78 +427,76 @@ perl: warning: Falling back to the standard locale ("C").
 	</row>
 	<row>
 	 <entry><literal>WIN1256</literal></entry>
-	 <entry>Arabic Windows CP1256</entry>
+	 <entry>Windows CP1256 (Arabic)</entry>
 	</row>
 	<row>
 	 <entry><literal>TCVN</literal></entry>
-	 <entry>Vietnamese <acronym>TCVN</>-5712 (Windows CP1258)</entry>
+	 <entry><acronym>TCVN</>-5712/Windows CP1258 (Vietnamese)</entry>
 	</row>
 	<row>
 	 <entry><literal>WIN874</literal></entry>
-	 <entry>Thai Windows CP874</entry>
+	 <entry>Windows CP874 (Thai)</entry>
 	</row>
        </tbody>
       </tgroup>
      </table>
-    </para>
 
     <important>
      <para>
-      Before <productname>PostgreSQL</>7.2, <literal>LATIN5</> mistakenly
-      meant ISO 8859-5.  From 7.2 on,
-      <literal>LATIN5</> means ISO 8859-9. If you have a <literal>LATIN5</>
-      database created on 7.1 or earlier and want to migrate to 7.2 (or
-      later), you should be very careful about this change.
+      Before <productname>PostgreSQL</> 7.2, <literal>LATIN5</>
+      mistakenly meant ISO 8859-5.  From 7.2 on, <literal>LATIN5</>
+      means ISO 8859-9. If you have a <literal>LATIN5</> database
+      created on 7.1 or earlier and want to migrate to 7.2 or later,
+      you should be very careful about this change.
      </para>
     </important>
 
-    <important>
      <para>
-      Not all <acronym>API</>s supports all the encodings listed above. For example, the
+      Not all <acronym>API</>s support all the listed character sets. For example, the
       <productname>PostgreSQL</>
       JDBC driver does not support <literal>MULE_INTERNAL</>, <literal>LATIN6</>,
       <literal>LATIN8</>, and <literal>LATIN10</>.
      </para>
-    </important>
     </sect2>
     
    <sect2>
-    <title>Setting the Encoding</title>
+    <title>Setting the Character Set</title>
 
     <para>
-     <application>initdb</application> defines the default encoding
-     for a <productname>PostgreSQL</productname> installation. For example:
+     <command>initdb</> defines the default character set
+     for a <productname>PostgreSQL</productname> cluster. For example,
 
 <screen>
 initdb -E EUC_JP
 </screen>
 
-     sets the default encoding to <literal>EUC_JP</literal> (Extended Unix Code for Japanese).
-     Note that you can use <option>--encoding</option> instead of <option>-E</option> if you prefer
-     to type longer option strings. 
+     sets the default character set (encoding) to
+     <literal>EUC_JP</literal> (Extended Unix Code for Japanese).  You
+     can use <option>--encoding</option> instead of
+     <option>-E</option> if you prefer to type longer option strings.
      If no <option>-E</> or <option>--encoding</option> option is
-     given, SQL_ASCII is used.
+     given, <literal>SQL_ASCII</> is used.
     </para>
 
     <para>
-     You can create a database with a different encoding:
+     You can create a database with a different character set:
 
 <screen>
 createdb -E EUC_KR korean
 </screen>
 
-     will create a database named <database>korean</database> with <literal>EUC_KR</literal> encoding.
-     Another way to accomplish this is to use a SQL command:
+     This will create a database named <literal>korean</literal> that
+     uses the character set <literal>EUC_KR</literal>.  Another way to
+     accomplish this is to use this SQL command:
 
 <programlisting>
-CREATE DATABASE korean WITH ENCODING = 'EUC_KR';
+CREATE DATABASE korean WITH ENCODING 'EUC_KR';
 </programlisting>
 
-     The encoding for a database is represented as an
-     <firstterm>encoding column</firstterm>  in the
-     <literal>pg_database</literal> system catalog.
-     You can see that by using the <option>-l</option> option or the
-     <command>\l</command> command of <command>psql</command>.
+     The encoding for a database is stored in the system catalog
+     <literal>pg_database</literal>.  You can see that by using the
+     <option>-l</option> option or the <command>\l</command> command
+     of <command>psql</command>.
 
 <screen>
 $ <userinput>psql -l</userinput>
@@ -567,27 +518,26 @@ $ <userinput>psql -l</userinput>
    </sect2>
 
    <sect2>
-    <title>Automatic encoding conversion between server and
-     client</title>
+    <title>Automatic Character Set Conversion Between Server and Client</title>
 
     <para>
-     <productname>PostgreSQL</productname> supports an automatic
-     encoding conversion between server and client for some
-     encodings. The conversion info is stored in <literal>pg_conversion</> system
-     catalog. You can create a new conversion by using <command>CREATE
-     CONVERSION</command>. <productname>PostgreSQL</> comes with some predefined
-     conversions. They are listed in <xref
+     <productname>PostgreSQL</productname> supports automatic
+     character set conversion between server and client for certain
+     character sets. The conversion information is stored in the
+     <literal>pg_conversion</> system catalog. You can create a new
+     conversion by using the SQL command <command>CREATE
+     CONVERSION</command>. <productname>PostgreSQL</> comes with some
+     predefined conversions. They are listed in <xref
      linkend="multibyte-translation-table">.
     </para>
 
-     <table tocentry="1" id="multibyte-translation-table">
-      <title>Client/Server Character Set Encodings</title>
-      <titleabbrev>Communication Encodings</titleabbrev>
+     <table id="multibyte-translation-table">
+      <title>Client/Server Character Set Conversions</title>
       <tgroup cols="2">
        <thead>
 	<row>
-	 <entry>Server Encoding</entry>
-	 <entry>Available Client Encodings</entry>
+	 <entry>Server Character Set</entry>
+	 <entry>Available Client Character Sets</entry>
 	</row>
        </thead>
        <tbody>
@@ -784,10 +734,10 @@ $ <userinput>psql -l</userinput>
      </table>
 
     <para>
-     To enable the automatic encoding translation, you have to tell
-     <productname>PostgreSQL</productname> the encoding you would like
-     to use in the client. There are
-     several ways to accomplish this.
+     To enable the automatic character set conversion, you have to
+     tell <productname>PostgreSQL</productname> the character set
+     (encoding) you would like to use in the client. There are several
+     ways to accomplish this:
 
      <itemizedlist>
       <listitem>
@@ -811,17 +761,17 @@ $ <userinput>psql -l</userinput>
 	<function>PQsetClientEncoding()</function> for its purpose.
 
 <synopsis>
-int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>)
+int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
 </synopsis>
 
 	where <replaceable>conn</replaceable> is a connection to the server,
-	and <replaceable>encoding</replaceable> is an encoding you
-	want to use. If it successfully sets the encoding, it returns 0,
-	otherwise -1. The current encoding for this connection can be shown by
+	and <replaceable>encoding</replaceable> is the encoding you
+	want to use. If the function successfully sets the encoding, it returns 0,
+	otherwise -1. The current encoding for this connection can be determined by
 	using:
 
 <synopsis>
-int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
+int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
 </synopsis>
 
 	Note that it returns the encoding ID, not a symbolic string
@@ -829,7 +779,7 @@ int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
 	can use:
 
 <synopsis>
-char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>)
+char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
 </synopsis>
        </para>
       </listitem>
@@ -841,13 +791,13 @@ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>)
 	Setting the client encoding can be done with this SQL command:
 
 <programlisting>
-SET CLIENT_ENCODING TO 'encoding';
+SET CLIENT_ENCODING TO '<replaceable>value</>';
 </programlisting>
 
-	Also you can use the SQL92 syntax <literal>SET NAMES</literal> for this purpose:
+	Also you can use the more standard SQL syntax <literal>SET NAMES</literal> for this purpose:
 
 <programlisting>
-SET NAMES 'encoding';
+SET NAMES '<replaceable>value</>';
 </programlisting>
 
 	To query the current client encoding:
@@ -877,7 +827,7 @@ RESET CLIENT_ENCODING;
 
       <listitem>
       <para>
-      Using client_encoding variable.
+       Using the configuration variable <varname>client_encoding</varname>.
 
       If the <varname>client_encoding</> variable in <filename>postgresql.conf</> is set, that
       client encoding is automatically selected when a connection to the
@@ -888,26 +838,19 @@ RESET CLIENT_ENCODING;
 
      </itemizedlist>
     </para>
-   </sect2>
-
-   <sect2>
-    <title>What happens if the translation is not possible?</title>
 
     <para>
-     Suppose you choose <literal>EUC_JP</literal> for the server
-     and <literal>LATIN1</literal> for the client,
-     then some Japanese characters cannot be translated into <literal>LATIN1</literal>. In
-     this case, a letter that cannot be represented in the <literal>LATIN1</literal> character set
-     would be transformed as:
-
-<synopsis>
-(HEXA DECIMAL)
-</synopsis>
+     If the conversion of a particular character is not possible --
+     suppose you chose <literal>EUC_JP</literal> for the server and
+     <literal>LATIN1</literal> for the client, then some Japanese
+     characters cannot be converted to <literal>LATIN1</literal> -- it
+     is transformed to its hexadecimal byte values in parentheses,
+     e.g., <literal>(826C)</literal>.
     </para>
    </sect2>
 
    <sect2>
-    <title>References</title>
+    <title>Further Reading</title>
 
     <para>
      These are good sources to start learning about various kinds of encoding
@@ -949,209 +892,11 @@ RESET CLIENT_ENCODING;
     </para>
    </sect2>
 
-   <sect2>
-    <title>History</title>
-
-<literallayout class="monospaced">
-Dec 7, 2000
-	* An automatic encoding translation between Unicode and other
-	  encodings are implemented
-	* Changes above will appear in 7.1
-
-May 20, 2000
-	* SJIS UDC (NEC selection IBM kanji) support contributed
-	  by Eiji Tokuya
-	* Changes above will appear in 7.0.1
-
-Mar 22, 2000
-	* Add new libpq functions PQsetClientEncoding, PQclientEncoding
-	* ./configure --with-mb=EUC_JP
-	  now deprecated. use 
-	  ./configure --enable-multibyte=EUC_JP
-	  instead
-  	* Add SQL_ASCII regression test case
-	* Add SJIS User Defined Character (UDC) support
-	* All of above will appear in 7.0
-
-July 11, 1999
-	* Add support for WIN1250 (Windows Czech) as a client encoding
-	  (contributed by Pavel Behal)
-	* fix some compiler warnings (contributed by Tomoaki Nishiyama)
-
-Mar 23, 1999
-	* Add support for KOI8(KOI8-R), WIN(CP1251), ALT(CP866)
-	  (thanks Oleg Broytmann for testing)
-	* Fix problem with MB and locale
-
-Jan 26, 1999
-	* Add support for Big5 for frontend encoding
-	  (you need to create a database with EUC_TW to use Big5)
-	* Add regression test case for EUC_TW
-	  (contributed by Jonah Kuo <email>jonahkuo@mail.ttn.com.tw</email>)
-
-Dec 15, 1998
-	* Bugs related to SQL_ASCII support fixed
-
-Nov 5, 1998
-	* 6.4 release. In this version, pg_database has "encoding"
-	  column that represents the database encoding
-
-Jul 22, 1998
-	* determine encoding at initdb/createdb rather than compile time
-	* support for PGCLIENTENCODING when issuing COPY command
-	* support for SQL92 syntax "SET NAMES"
-	* support for LATIN2-5
-	* add UNICODE regression test case
-	* new test suite for MB
-	* clean up source files
-
-Jun 5, 1998
-	* add support for the encoding translation between the backend
-	  and the frontend
-	* new command SET CLIENT_ENCODING etc. added
-	* add support for LATIN1 character set
-	* enhance 8-bit cleanliness
-
-April 21, 1998 some enhancements/fixes
-	* character_length(), position(), substring() are now aware of 
-	  multi-byte characters
-	* add octet_length()
-	* add --with-mb option to configure
-	* new regression tests for EUC_KR
-  	  (contributed by Soonmyung Hong)
-	* add some test cases to the EUC_JP regression test
-	* fix problem in regress/regress.sh in case of System V
-	* fix toupper(), tolower() to handle 8bit chars
-
-Mar 25, 1998 MB PL2 is incorporated into <productname>PostgreSQL</> 6.3.1
-
-Mar 10, 1998 PL2 released
-	* add regression test for EUC_JP, EUC_CN and MULE_INTERNAL
-	* add an English document (this file)
-	* fix problems concerning 8-bit single byte characters
-
-Mar 1, 1998 PL1 released
-</literallayout>
-   </sect2>
-
-   <sect2>
-    <title>WIN1250 on Windows/ODBC</title>
-
-    <para>
-<!--
-[Here is a good documentation explaining how to use WIN1250 on
-Windows/ODBC from Pavel Behal]
-
-Version: 0.91 for PgSQL 6.5
-Author: Pavel Behal
-Revised by: Tatsuo Ishii
-Email: behal@opf.slu.cz
-License: The Same as <productname>PostgreSQL</>
-
-Sorry for my Eglish and C code, I'm not native :-)
-
-!!!!!!!!!!!!!!!!!!!!!!!!! NO WARRANTY !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
--->
-
-     The WIN1250 character set on Windows client platforms can be used
-     with <productname>PostgreSQL</productname> with locale support
-     enabled.
-    </para>
-
-    <para>
-     The following should be kept in mind:
-
-     <itemizedlist>
-      <listitem>
-       <para>
-	Success depends on proper system locales. This has been tested
-	with <systemitem class="osname">Red Hat 6.0</> and <systemitem
-	class="osname">Slackware 3.6</>, with the
-        <literal>cs_CZ.iso8859-2</literal> locale.
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
-	Never try to set the server's database encoding to WIN1250.
-	Always use LATIN2 instead since there is no WIN1250 locale
-	in Unix.
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
-	The WIN1250 encoding is usable only for Windows ODBC clients. The
-	characters are recoded on the fly, to be displayed and stored
-	back properly.
-       </para>
-      </listitem>
-     </itemizedlist>
-    </para>
-
-    <procedure>
-     <title>WIN1250 on Windows/ODBC</title>
-     <step>
-      <para>
-       Compile <productname>PostgreSQL</productname> with locale enabled
-       and the server-side encoding set to <literal>LATIN2</literal>.
-      </para>
-     </step>
-
-     <step>
-      <para>
-       Set up your installation. Do not forget to create locale
-       variables in your environment. For example (this may
-       not be correct for <emphasis>your</emphasis> environment):
-
-<programlisting>
-LC_ALL=cs_CZ.ISO8859-2
-</programlisting>
-      </para>
-     </step>
-
-     <step>
-      <para>
-       You have to start the server with locales set!
-      </para>
-     </step>
-
-     <step>
-      <para>
-       Try it with the Czech language, and have it sort on a query.
-      </para>
-     </step>
-
-     <step>
-      <para>
-       Install ODBC driver for <productname>PostgreSQL</productname> on your Windows machine.
-      </para>
-     </step>
-
-     <step>
-      <para>
-       Set up your data source properly. Include this line in your ODBC
-       configuration dialog in the field <guilabel>Connect Settings</guilabel>:
-
-<programlisting>
-SET CLIENT_ENCODING = 'WIN1250';
-</programlisting>
-      </para>
-     </step>
-
-     <step>
-      <para>
-       Now try it again, but in Windows with ODBC.
-      </para>
-     </step>
-    </procedure>
-   </sect2>
   </sect1>
 
 
  <sect1 id="recode">
-  <title>Single-byte character set recoding</>
-<!-- formerly in README.charsets, by Josef Balatka, <balatka@email.cz> -->
+  <title>Single-Byte Character Set Recoding</>
 
   <para>
    You can set up this feature with the <option>--enable-recode</> option
@@ -1163,57 +908,57 @@ SET CLIENT_ENCODING = 'WIN1250';
 
   <para>
    This method uses a file <filename>charset.conf</> file located in
-   the database directory (<envar>PGDATA</>).  It's a typical
-   configuration text file where spaces and newlines separate items
-   and records and # specifies comments.  Three keywords with the
+   the data directory for configuration.  It's a typical
+   configuration text file where spaces and newlines separate fields
+   and records and <literal>#</> starts a comment.  Three key words with the
    following syntax are recognized here:
 <synopsis>
-BaseCharset      <replaceable>server_charset</>
-RecodeTable      <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</>
-HostCharset      <replaceable>host_spec</>    <replaceable>host_charset</>
+BaseCharset <replaceable>server_charset</>
+RecodeTable <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</>
+HostCharset <replaceable>host_spec</>    <replaceable>host_charset</>
 </synopsis>
   </para>
 
   <para>
-   <token>BaseCharset</> defines the encoding of the database server.
+   <token>BaseCharset</> defines the character set of the database server.
    All character set names are only used for mapping inside of
    <filename>charset.conf</> so you can freely use typing-friendly
    names.
   </para>
 
   <para>
-   <token>RecodeTable</> records specify translation tables between
+   <token>RecodeTable</> records specify conversion tables between
    server and client.  The file name is relative to the
-   <envar>PGDATA</> directory.  The table file format is very
-   simple. There are no keywords and characters are represented by a
-   pair of decimal or hexadecimal (0x prefixed) values on single
+   data directory.  The table file format is very
+   simple. There are no key words, and character mappings are represented by a
+   pair of decimal or hexadecimal (prefixed by <literal>0x</>) values on single
    lines:
 <synopsis>
-<replaceable>char_value</>   <replaceable>translated_char_value</>
+<replaceable>char_value</>   <replaceable>converted_char_value</>
 </synopsis>
+   In the <filename>src/data/</> directory in the source distribution you can find an
+   example <filename>charset.conf</> and a few recoding tables.
   </para>
 
   <para>
    <token>HostCharset</> records define the client character set by IP
    address. You can use a single IP address, an IP mask range starting
-   from the given address or an IP interval (e.g., 127.0.0.1,
-   192.168.1.100/24, 192.168.1.20-192.168.1.40).
+   from the given address or an IP interval (e.g., <literal>127.0.0.1</>,
+   <literal>192.168.1.100/24</>, <literal>192.168.1.20-192.168.1.40</>).
   </para>
 
   <para>
-   The <filename>charset.conf</> file is always processed up to the
-   end, so you can easily specify exceptions from the previous
-   rules. In the <filename>src/data/</> directory you will find an
-   example <filename>charset.conf</> and a few recoding tables.
+   The <filename>charset.conf</> file is always processed to the
+   end, so you can easily specify exceptions from preceding rules.
   </para>
 
   <para>
-   As this solution is based on the client's IP address and character
-   set mapping there are obviously some restrictions as well. You
-   cannot use different encodings on the same host at the same
-   time. It is also inconvenient when you boot your client hosts into
-   multiple operating systems.  Nevertheless, when these restrictions are
-   not limiting and you do not need multibyte characters then it is a
+   As this solution is based on the client's IP address there are
+   obviously some restrictions as well. You cannot use different
+   character sets on the same host at the same time. It is also
+   inconvenient when you boot your client hosts into multiple
+   operating systems.  Nevertheless, when these restrictions are not
+   limiting and you do not need multibyte characters then it is a
    simple and effective solution.
   </para>
  </sect1>

doc/src/sgml/diskusage.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.8 2002/11/15 03:11:16 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.9 2003/03/24 14:32:50 petere Exp $
 -->
 
 <chapter id="diskusage">
@@ -33,32 +33,32 @@ $Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.8 2002/11/15 03:11:16 mo
   <para>
    You can monitor disk space from three places: from
    <application>psql</> using <command>VACUUM</> information, from
-   <application>psql</> using <filename>contrib/dbsize</>, and from
-   the command line using <application>contrib/oid2name</>. Using
-   <application>psql</> on a recently vacuumed (or analyzed) database,
+   <application>psql</> using the tools in <filename>contrib/dbsize</>, and from
+   the command line using the tools in <filename>contrib/oid2name</>. Using
+   <application>psql</> on a recently vacuumed or analyzed database,
    you can issue queries to see the disk usage of any table:
 <programlisting>
-play=# SELECT relfilenode, relpages
-play-# FROM pg_class
-play-# WHERE relname = 'customer';
+SELECT relfilenode, relpages FROM pg_class WHERE relname = 'customer';
+
  relfilenode | relpages 
 -------------+----------
        16806 |       60
 (1 row)
 </programlisting>
+   Each page is typically 8 kilobytes. (Remember, <literal>relpages</>
+   is only updated by <command>VACUUM</> and <command>ANALYZE</>.)
   </para>
 
-  <para>   
-   Each page is typically 8 kilobytes. (Remember, <literal>relpages</>
-   is only updated by <command>VACUUM</> and <command>ANALYZE</>.) To
-   show the space used by <acronym>TOAST</> tables, use a query based on
-   the heap relfilenode shown above:
+  <para>
+   To show the space used by <acronym>TOAST</> tables, use a query
+   like the following, substituting the <literal>relfilenode</literal>
+   number of the heap (determined by the query above):
 <programlisting>
-play=# SELECT relname, relpages
-play-# FROM pg_class
-play-# WHERE relname = 'pg_toast_16806' OR
-play-#       relname = 'pg_toast_16806_index'
-play-# ORDER BY relname;
+SELECT relname, relpages
+    FROM pg_class
+    WHERE relname = 'pg_toast_16806' OR relname = 'pg_toast_16806_index'
+    ORDER BY relname;
+
        relname        | relpages 
 ----------------------+----------
  pg_toast_16806       |        0
@@ -67,14 +67,15 @@ play-# ORDER BY relname;
   </para>
 
   <para>
-   You can easily display index usage too:
+   You can easily display index sizes, too:
 <programlisting>
-play=# SELECT c2.relname, c2.relpages
-play-# FROM pg_class c, pg_class c2, pg_index i
-play-# WHERE c.relname = 'customer' AND
-play-#       c.oid = i.indrelid AND
-play-#       c2.oid = i.indexrelid
-play-# ORDER BY c2.relname;
+SELECT c2.relname, c2.relpages
+    FROM pg_class c, pg_class c2, pg_index i
+    WHERE c.relname = 'customer'
+        AND c.oid = i.indrelid
+        AND c2.oid = i.indexrelid
+        ORDER BY c2.relname;
+
        relname        | relpages 
 ----------------------+----------
  customer_id_indexdex |       26
@@ -82,11 +83,11 @@ play-# ORDER BY c2.relname;
   </para>
 
   <para>
-   It is easy to find your largest files using <application>psql</>:
+   It is easy to find your largest tables and indexes using this
+   information:
 <programlisting>
-play=# SELECT relname, relpages
-play-# FROM pg_class
-play-# ORDER BY relpages DESC;
+SELECT relname, relpages FROM pg_class ORDER BY relpages DESC;
+
        relname        | relpages 
 ----------------------+----------
  bigtable             |     3290
@@ -97,12 +98,12 @@ play-# ORDER BY relpages DESC;
   <para>
    <filename>contrib/dbsize</> loads functions into your database that allow
    you to find the size of a table or database from inside
-   <application>psql</> without the need for <command>VACUUM/ANALYZE.</>
+   <application>psql</> without the need for <command>VACUUM</> or <command>ANALYZE</>.
   </para>
 
   <para>
    You can also use <filename>contrib/oid2name</> to show disk usage. See
-   <filename>README.oid2name</> for examples. It includes a script that
+   <filename>README.oid2name</> in that directory for examples. It includes a script that
    shows disk usage for each database.
   </para>
  </sect1>
@@ -114,7 +115,7 @@ play-# ORDER BY relpages DESC;
    The most important disk monitoring task of a database administrator
    is to make sure the disk doesn't grow full.  A filled data disk may
    result in subsequent corruption of database indexes, but not of the
-   fundamental data tables. If the WAL files are on the same disk (as
+   tables themselves. If the WAL files are on the same disk (as
    is the case for a default configuration) then a filled disk during
    database initialization may result in corrupted or incomplete WAL
    files. This failure condition is detected and the database server
@@ -129,8 +130,8 @@ play-# ORDER BY relpages DESC;
    information of such a setup; a restore would put everything back in
    one place.  To avoid running out of disk space, you can place the
    WAL files or individual databases in other locations while creating
-   them.  See the <application>initdb</> documentation and <xref
-   linkend="manage-ag-alternate-locs"> for more information.
+   them.  See the <command>initdb</> documentation and <xref
+   linkend="manage-ag-alternate-locs"> for more information about that.
   </para>
 
   <tip>

doc/src/sgml/func.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.146 2003/03/21 21:54:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.147 2003/03/24 14:32:50 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -5900,7 +5900,7 @@ SELECT TIMESTAMP 'now';
 	<entry><literal>255.255.255.0</literal></entry>
        </row>
        <row>
-	<entry><function>hostmask</function>(<type>inet</type>)</entry>
+	<entry><literal><function>hostmask</function>(<type>inet</type>)</literal></entry>
 	<entry><type>inet</type></entry>
 	<entry>construct hostmask for network</entry>
 	<entry><literal>hostmask('192.168.23.20/30')</literal></entry>
@@ -6477,7 +6477,7 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
 
    <indexterm zone="functions-misc">
     <primary>configuration</primary>
-    <secondary>run time</secondary>
+    <secondary>server</secondary>
    </indexterm>
 
    <para>

doc/src/sgml/install-win32.sgml

@@ -54,7 +54,7 @@
     <term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term>
     <listitem>
      <para>
-      Import library to link your program to <filename>libpq.dll</filename>
+      Import library to link your programs to <filename>libpq.dll</filename>
      </para>
     </listitem>
    </varlistentry>
@@ -98,7 +98,7 @@
  </para>
 
  <para>
-  To use the libraries, you must add the
+  To use the library, you must add the
   <filename>libpqdll.lib</filename> file to your project.  (In Visual
   C++, just right-click on the project and choose to add it.)
  </para>

doc/src/sgml/maintenance.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.21 2003/03/24 14:32:50 petere Exp $
 -->
 
 <chapter id="maintenance">
  <title>Routine Database Maintenance Tasks</title>
 
- <sect1 id="maintenance-general">
-  <title>General Discussion</Title>
-
   <para>
    There are a few routine maintenance chores that must be performed on
    a regular basis to keep a <productname>PostgreSQL</productname>
-   installation running smoothly.  The tasks discussed here are repetitive
+   server running smoothly.  The tasks discussed here are repetitive
    in nature and can easily be automated using standard Unix tools such
    as <application>cron</application> scripts.  But it is the database
    administrator's responsibility to set up appropriate scripts, and to
@@ -22,7 +19,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
    One obvious maintenance task is creation of backup copies of the data on a
    regular schedule.  Without a recent backup, you have no chance of recovery
    after a catastrophe (disk failure, fire, mistakenly dropping a critical
-   table, etc).  The backup and recovery mechanisms available in
+   table, etc.).  The backup and recovery mechanisms available in
    <productname>PostgreSQL</productname> are discussed at length in
    <xref linkend="backup">.
   </para>
@@ -45,8 +42,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
    experience with the system.
   </para>
 
- </sect1>
-
  <sect1 id="routine-vacuuming">
   <title>Routine Vacuuming</title>
 
@@ -75,8 +70,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
      </listitem>
     </orderedlist>
 
-   The frequency and scope of <command>VACUUM</>s performed for each of
-   these reasons will vary depending on the needs of each installation.
+   The frequency and scope of the <command>VACUUM</> operations performed for each of
+   these reasons will vary depending on the needs of each site.
    Therefore, database administrators must understand these issues and
    develop an appropriate maintenance strategy.  This section concentrates
    on explaining the high-level issues; for details about command syntax
@@ -86,7 +81,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
   <para>
    Beginning in <productname>PostgreSQL</productname> 7.2, the standard form
    of <command>VACUUM</> can run in parallel with normal database operations
-   (selects, inserts, updates, deletes, but not changes to table schemas).
+   (selects, inserts, updates, deletes, but not changes to table definitions).
    Routine vacuuming is therefore not nearly as intrusive as it was in prior
    releases, and it's not as critical to try to schedule it at low-usage
    times of day.
@@ -131,8 +126,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
     return disk space to the operating system.  If you need to return disk
     space to the operating system you can use <command>VACUUM FULL</> ---
     but what's the point of releasing disk space that will only have to be
-    allocated again soon?  Moderately frequent standard <command>VACUUM</>s
-    are a better approach than infrequent <command>VACUUM FULL</>s for
+    allocated again soon?  Moderately frequent standard <command>VACUUM</> runs
+    are a better approach than infrequent <command>VACUUM FULL</> runs for
     maintaining heavily-updated tables.
    </para>
 
@@ -140,7 +135,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
     Recommended practice for most sites is to schedule a database-wide
     <command>VACUUM</> once a day at a low-usage time of day, supplemented
     by more frequent vacuuming of heavily-updated tables if necessary.
-    (If you have multiple databases in an installation, don't forget to
+    (If you have multiple databases in a cluster, don't forget to
     vacuum each one; the <filename>vacuumdb</> script may be helpful.)
     Use plain <command>VACUUM</>, not <command>VACUUM FULL</>, for routine
     vacuuming for space recovery.
@@ -233,11 +228,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
 
    <para>
     <productname>PostgreSQL</productname>'s MVCC transaction semantics
-    depend on being able to compare transaction ID (<firstterm>XID</>)
-    numbers: a tuple with an insertion XID newer than the current
+    depend on being able to compare transaction ID (<acronym>XID</>)
+    numbers: a tuple with an insertion XID greater than the current
     transaction's XID is <quote>in the future</> and should not be visible
     to the current transaction.  But since transaction IDs have limited size
-    (32 bits at this writing) an installation that runs for a long time (more
+    (32 bits at this writing) a cluster that runs for a long time (more
     than 4 billion transactions) will suffer <firstterm>transaction ID
     wraparound</>: the XID counter wraps around to zero, and all of a sudden
     transactions that were in the past appear to be in the future --- which
@@ -251,7 +246,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
     against XID wraparound was to re-<command>initdb</> at least every 4
     billion transactions. This of course was not very satisfactory for
     high-traffic sites, so a better solution has been devised. The new
-    approach allows an installation to remain up indefinitely, without
+    approach allows a server to remain up indefinitely, without
     <command>initdb</> or any sort of restart. The price is this
     maintenance requirement: <emphasis>every table in the database must
     be vacuumed at least once every billion transactions</emphasis>.
@@ -293,9 +288,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
     <command>VACUUM</>'s normal policy is to reassign <literal>FrozenXID</>
     to any tuple with a normal XID more than one billion transactions in the
     past.  This policy preserves the original insertion XID until it is not
-    likely to be of interest anymore (in fact, most tuples will probably
-    live and die without ever being <quote>frozen</>).  With this policy,
-    the maximum safe interval between <command>VACUUM</>s of any table
+    likely to be of interest anymore.  (In fact, most tuples will probably
+    live and die without ever being <quote>frozen</>.)  With this policy,
+    the maximum safe interval between <command>VACUUM</> runs on any table
     is exactly one billion transactions: if you wait longer, it's possible
     that a tuple that was not quite old enough to be reassigned last time
     is now more than two billion transactions old and has wrapped around
@@ -304,13 +299,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
    </para>
 
    <para>
-    Since periodic <command>VACUUM</>s are needed anyway for the reasons
+    Since periodic <command>VACUUM</> runs are needed anyway for the reasons
     described earlier, it's unlikely that any table would not be vacuumed
     for as long as a billion transactions.  But to help administrators ensure
     this constraint is met, <command>VACUUM</> stores transaction ID
-    statistics in the system table <filename>pg_database</>.  In particular,
-    the <filename>datfrozenxid</> field of a database's
-    <filename>pg_database</> row is updated at the completion of any
+    statistics in the system table <literal>pg_database</>.  In particular,
+    the <literal>datfrozenxid</> column of a database's
+    <literal>pg_database</> row is updated at the completion of any
     database-wide vacuum operation (i.e., <command>VACUUM</> that does not
     name a specific table).  The value stored in this field is the freeze
     cutoff XID that was used by that <command>VACUUM</> command.  All normal
@@ -334,11 +329,11 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
     database at least once every half-a-billion (500 million) transactions,
     so as to provide plenty of safety margin.  To help meet this rule,
     each database-wide <command>VACUUM</> automatically delivers a warning
-    if there are any <filename>pg_database</> entries showing an
+    if there are any <literal>pg_database</> entries showing an
     <literal>age</> of more than 1.5 billion transactions, for example:
 
 <programlisting>
-play=# vacuum;
+play=# VACUUM;
 WARNING:  Some databases have not been vacuumed in 1613770184 transactions.
         Better vacuum them within 533713463 transactions,
         or you may have a wraparound failure.
@@ -355,13 +350,13 @@ VACUUM
     database will be frozen. Hence, as long as the database is not
     modified in any way, it will not need subsequent vacuuming to avoid
     transaction ID wraparound problems. This technique is used by
-    <filename>initdb</> to prepare the <filename>template0</> database.
+    <command>initdb</> to prepare the <literal>template0</> database.
     It should also be used to prepare any user-created databases that
     are to be marked <literal>datallowconn</> = <literal>false</> in
-    <filename>pg_database</>, since there isn't any convenient way to
+    <literal>pg_database</>, since there isn't any convenient way to
     vacuum a database that you can't connect to. Note that
     <command>VACUUM</command>'s automatic warning message about
-    unvacuumed databases will ignore <filename>pg_database</> entries
+    unvacuumed databases will ignore <literal>pg_database</> entries
     with <literal>datallowconn</> = <literal>false</>, so as to avoid
     giving false warnings about these databases; therefore it's up to
     you to ensure that such databases are frozen correctly.
@@ -415,9 +410,9 @@ VACUUM
   </para>
 
   <para>
-   If you simply direct the postmaster's <systemitem>stderr</> into a
+   If you simply direct the <systemitem>stderr</> of the <command>postmaster</command> into a
    file, the only way to truncate the log file is to stop and restart
-   the postmaster. This may be OK for development setups but you won't
+   the <command>postmaster</command>. This may be OK for development setups but you won't
    want to run a production server that way.
   </para>
 
@@ -425,7 +420,7 @@ VACUUM
    The simplest production-grade approach to managing log output is to
    send it all to <application>syslog</> and let
    <application>syslog</> deal with file rotation. To do this, set
-   <literal>syslog</> to 2 (log to <application>syslog</> only) in
+   the configurations parameter <literal>syslog</> to 2 (to log to <application>syslog</> only) in
    <filename>postgresql.conf</>. Then you can send a
    <literal>SIGHUP</literal> signal to the <application>syslog</>
    daemon whenever you want to force it to start writing a new log
@@ -436,18 +431,18 @@ VACUUM
    On many systems, however, <application>syslog</> is not very reliable, particularly
    with large log messages; it may truncate or drop messages just when
    you need them the most. You may find it more useful to pipe the
-   <application>postmaster</>'s <systemitem>stderr</> to some type of
-   log rotation script. If you start the postmaster with
-   <application>pg_ctl</>, then the postmaster's <systemitem>stderr</>
+   <systemitem>stderr</> of the <command>postmaster</> to some type of
+   log rotation program. If you start the server with
+   <command>pg_ctl</>, then the <systemitem>stderr</> of the <command>postmaster</command>
    is already redirected to <systemitem>stdout</>, so you just need a
    pipe command:
    
-<screen>
-<userinput>pg_ctl start | logrotate</userinput>
-</screen>
+<programlisting>
+pg_ctl start | logrotate
+</programlisting>
 
    The <productname>PostgreSQL</> distribution doesn't include a suitable
-   log rotation program, but there are many available on the net;
+   log rotation program, but there are many available on the Internet;
    one is included in the Apache distribution, for example.
   </para>
  </sect1>

doc/src/sgml/monitoring.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.17 2003/03/20 18:51:16 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.18 2003/03/24 14:32:50 petere Exp $
 -->
 
 <chapter id="monitoring">
@@ -14,7 +14,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.17 2003/03/20 18:51:16
   <para>
    Several tools are available for monitoring database activity and
    analyzing performance.  Most of this chapter is devoted to describing
-   <productname>PostgreSQL</productname>'s <firstterm>statistics collector</>,
+   <productname>PostgreSQL</productname>'s statistics collector,
    but one should not neglect regular Unix monitoring programs such as
    <command>ps</> and <command>top</>.  Also, once one has identified a
    poorly-performing query, further investigation may be needed using
@@ -50,7 +50,7 @@ postgres  1016  0.1  2.4  6532 3080 pts/1    SN   13:19   0:00 postgres: tgl reg
    (The appropriate invocation of <command>ps</> varies across different
    platforms, as do the details of what is shown.  This example is from a
    recent Linux system.)  The first process listed here is the
-   <firstterm>postmaster</>, the master server process.  The command arguments
+   <application>postmaster</>, the master server process.  The command arguments
    shown for it are the same ones given when it was launched.  The next two
    processes implement the statistics collector, which will be described in
    detail in the next section.  (These will not be present if you have set
@@ -67,7 +67,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
   The activity may be <literal>idle</> (i.e., waiting for a client command),
   <literal>idle in transaction</> (waiting for client inside a <command>BEGIN</> block),
   or a command type name such as <literal>SELECT</>.  Also,
-  <literal>waiting</> is attached if the server is presently waiting
+  <literal>waiting</> is attached if the server process is presently waiting
   on a lock held by another server process.  In the above example we can infer
   that process 1003 is waiting for process 1016 to complete its transaction and
   thereby release some lock or other.
@@ -77,22 +77,19 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
   <para>
   <productname>Solaris</productname> requires special handling. You must
   use <command>/usr/ucb/ps</command>, rather than
-  <command>/bin/ps</command>. You also must use two <command>w</command>
+  <command>/bin/ps</command>. You also must use two <option>w</option>
   flags, not just one. In addition, your original invocation of the
-  <application>postmaster</application> must have a shorter
+  <command>postmaster</command> command must have a shorter
   <command>ps</command> status display than that provided by each
-  backend.   If you fail to do all three things, the <command>ps</>
-  output for each backend will be the original <application>postmaster</>
+  server process.  If you fail to do all three things, the <command>ps</>
+  output for each server process will be the original <command>postmaster</>
   command line.
   </para>
   </tip>
-
-
-
  </sect1>
 
  <sect1 id="monitoring-stats">
-  <title>Statistics Collector</Title>
+  <title>The Statistics Collector</Title>
 
   <indexterm zone="monitoring-stats">
    <primary>statistics</primary>
@@ -103,7 +100,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
    is a subsystem that supports collection and reporting of information about
    server activity.  Presently, the collector can count accesses to tables
    and indexes in both disk-block and individual-row terms.  It also supports
-   determining the exact query currently being executed by other server
+   determining the exact command currently being executed by other server
    processes.
   </para>
 
@@ -113,13 +110,13 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
   <para>
    Since collection of statistics adds some overhead to query execution,
    the system can be configured to collect or not collect information.
-   This is controlled by configuration variables that are normally set in
-   <filename>postgresql.conf</> (see <xref linkend="runtime-config"> for
-   details about setting configuration variables).
+   This is controlled by configuration parameters that are normally set in
+   <filename>postgresql.conf</>.  (See <xref linkend="runtime-config"> for
+   details about setting configuration parameters.)
   </para>
 
   <para>
-   The variable <varname>STATS_START_COLLECTOR</varname> must be set to
+   The parameter <varname>stats_start_collector</varname> must be set to
    <literal>true</> for the statistics collector to
    be launched at all.  This is the default and recommended setting,
    but it may be turned off if you have no interest in statistics and
@@ -129,32 +126,32 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
   </para>
 
   <para>
-   The variables <varname>STATS_COMMAND_STRING</varname>,
-   <varname>STATS_BLOCK_LEVEL</varname>,
-   and <varname>STATS_ROW_LEVEL</varname> control how much information is
-   actually sent to the collector, and thus determine how much run-time
+   The parameters <varname>stats_command_string</varname>,
+   <varname>stats_block_level</varname>,
+   and <varname>stats_row_level</varname> control how much information is
+   actually sent to the collector and thus determine how much run-time
    overhead occurs.  These respectively determine whether a server process
    sends its current command string, disk-block-level access statistics, and
-   row-level access statistics to the collector.  Normally these variables are
+   row-level access statistics to the collector.  Normally these parameters are
    set in <filename>postgresql.conf</> so that they apply to all server
-   processes, but it is possible to turn them on or off in individual server
-   processes using the <command>SET</> command.  (To prevent ordinary users
+   processes, but it is possible to turn them on or off in individual sessions
+   using the <command>SET</> command.  (To prevent ordinary users
    from hiding their activity from the administrator, only superusers are
-   allowed to change these variables with <command>SET</>.)
+   allowed to change these parameters with <command>SET</>.)
   </para>
 
-   <important>
+   <note>
     <para>
-     Since the variables <varname>STATS_COMMAND_STRING</varname>,
-     <varname>STATS_BLOCK_LEVEL</varname>, and
-     <varname>STATS_ROW_LEVEL</varname> default to <literal>false</>,
+     Since the parameters <varname>stats_command_string</varname>,
+     <varname>stats_block_level</varname>, and
+     <varname>stats_row_level</varname> default to <literal>false</>,
      very few statistics are collected in the default
      configuration. Enabling one or more of these configuration
      variables will significantly enhance the amount of useful data
      produced by the statistics collector, at the expense of
      additional run-time overhead.
     </para>
-   </important>
+   </note>
 
  </sect2>
 
@@ -181,7 +178,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
   <para>
    Another important point is that when a server process is asked to display
    any of these statistics, it first fetches the most recent totals emitted by
-   the collector process.  It then continues to use this snapshot for all
+   the collector process and then continues to use this snapshot for all
    statistical views and functions until the end of its current transaction.
    So the statistics will appear not to change as long as you continue the
    current transaction.
@@ -209,9 +206,9 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
       <entry>One row per server process, showing process
       <acronym>ID</>, database, user, current query, and the time at
       which the current query began execution. The columns that report
-      data on the current query are only available if the
-      <varname>STATS_COMMAND_STRING</varname> configuration option has
-      been enabled. Furthermore, these columns can only be accessed by
+      data on the current query are only available if the parameter
+      <varname>stats_command_string</varname> has been turned on.
+      Furthermore, these columns can only be accessed by
       superusers; or when the user examining the view is the same as the user
       in the row; for others it reads as null.  (Note that because of the 
       collector's reporting delay, current query will only be up-to-date for 
@@ -220,7 +217,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
 
      <row>
       <entry><structname>pg_stat_database</></entry>
-      <entry>One row per database, showing number of active backends,
+      <entry>One row per database, showing the number of active backend server processes,
       total transactions committed and total rolled back in that database,
       total disk blocks read, and total number of buffer hits (i.e., block
       read requests avoided by finding the block already in buffer cache).
@@ -232,7 +229,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
       <entry>For each table in the current database, total numbers of
       sequential and index scans, total numbers of tuples returned by
       each type of scan, and totals of tuple insertions, updates,
-      and deletes.</entry>
+      and deletions.</entry>
      </row>
 
      <row>
@@ -360,12 +357,12 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
    queries that use the same underlying statistics access functions as
    these standard views do.  These functions are listed in <xref
    linkend="monitoring-stats-funcs-table">.  The per-database access
-   functions accept a database OID to identify which database to
-   report on.  The per-table and per-index functions accept a table or
-   index OID (note that only tables and indexes in the current
-   database can be seen with these functions).  The per-backend access
-   functions accept a backend ID number, which ranges from one to the
-   number of currently active backends.
+   functions take a database OID as argument to identify which database to
+   report on.  The per-table and per-index functions take a table or
+   index OID.  (Note that only tables and indexes in the current
+   database can be seen with these functions.)  The per-backend access
+   functions take a backend ID number, which ranges from one to the
+   number of currently active backend processes.
   </para>
 
   <table id="monitoring-stats-funcs-table">
@@ -382,15 +379,15 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
 
     <tbody>
      <row>
-      <entry><function>pg_stat_get_db_numbackends</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_db_numbackends</function>(<type>oid</type>)</literal></entry>
       <entry><type>integer</type></entry>
       <entry>
-       Number of active backends in database
+       Number of active backend processes for database
       </entry>
      </row>
 
      <row>
-      <entry><function>pg_stat_get_db_xact_commit</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_db_xact_commit</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Transactions committed in database
@@ -398,7 +395,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_db_xact_rollback</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_db_xact_rollback</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Transactions rolled back in database
@@ -406,7 +403,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_db_blocks_fetched</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_db_blocks_fetched</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of disk block fetch requests for database
@@ -414,7 +411,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_db_blocks_hit</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_db_blocks_hit</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of disk block fetch requests found in cache for database
@@ -422,7 +419,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_numscans</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_numscans</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of sequential scans done when argument is a table,
@@ -431,7 +428,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_tuples_returned</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_tuples_returned</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of tuples read by sequential scans when argument is a table,
@@ -440,7 +437,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_tuples_fetched</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_tuples_fetched</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of valid (unexpired) table tuples fetched by sequential scans
@@ -450,7 +447,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_tuples_inserted</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_tuples_inserted</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of tuples inserted into table
@@ -458,7 +455,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_tuples_updated</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_tuples_updated</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of tuples updated in table
@@ -466,7 +463,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_tuples_deleted</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_tuples_deleted</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of tuples deleted from table
@@ -474,7 +471,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_blocks_fetched</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_blocks_fetched</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of disk block fetch requests for table or index
@@ -482,7 +479,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_blocks_hit</function>(<type>oid</type>)</entry>
+      <entry><literal><function>pg_stat_get_blocks_hit</function>(<type>oid</type>)</literal></entry>
       <entry><type>bigint</type></entry>
       <entry>
        Number of disk block requests found in cache for table or index
@@ -490,69 +487,71 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
      </row>
 
      <row>
-      <entry><function>pg_stat_get_backend_idset</function>()</entry>
+      <entry><literal><function>pg_stat_get_backend_idset</function>()</literal></entry>
       <entry><type>set of integer</type></entry>
       <entry>
-       Set of currently active backend IDs (from 1 to N where N is the
-       number of active backends).  See usage example below
+       Set of currently active backend process IDs (from 1 to the
+       number of active backend processes).  See usage example in the text.
       </entry>
      </row>
 
      <row>
-      <entry><function>pg_backend_pid</function>()</entry>
+      <entry><literal><function>pg_backend_pid</function>()</literal></entry>
       <entry><type>integer</type></entry>
       <entry>
-       Process ID of the attached backend
+       Process ID of the backend process attached to the current session
       </entry>
      </row>
 
      <row>
-      <entry><function>pg_stat_get_backend_pid</function>(<type>integer</type>)</entry>
+      <entry><literal><function>pg_stat_get_backend_pid</function>(<type>integer</type>)</literal></entry>
       <entry><type>integer</type></entry>
       <entry>
-       Process ID of all backend processes
+       Process ID of the given backend process
       </entry>
      </row>
 
      <row>
-      <entry><function>pg_stat_get_backend_dbid</function>(<type>integer</type>)</entry>
+      <entry><literal><function>pg_stat_get_backend_dbid</function>(<type>integer</type>)</literal></entry>
       <entry><type>oid</type></entry>
       <entry>
-       Database ID of backend process
+       Database ID of the given backend process
       </entry>
      </row>
 
      <row>
-      <entry><function>pg_stat_get_backend_userid</function>(<type>integer</type>)</entry>
+      <entry><literal><function>pg_stat_get_backend_userid</function>(<type>integer</type>)</literal></entry>
       <entry><type>oid</type></entry>
       <entry>
-       User ID of backend process
+       User ID of the given backend process
       </entry>
      </row>
 
      <row>
-      <entry><function>pg_stat_get_backend_activity</function>(<type>integer</type>)</entry>
+      <entry><literal><function>pg_stat_get_backend_activity</function>(<type>integer</type>)</literal></entry>
       <entry><type>text</type></entry>
       <entry>
-       Current query of backend process (NULL if caller is not
-       superuser, or is the same user as that of the backend being queried,
-       or <varname>STATS_COMMAND_STRING</varname> is not enabled)
+       Active command of the given backend process (null if the
+       current user is not a superuser nor the same user as that of
+       the session being queried, or
+       <varname>stats_command_string</varname> is not on)
       </entry>
      </row>
 
      <row>
-      <entry><function>pg_stat_get_backend_activity_start</function>(<type>integer</type>)</entry>
+      <entry><literal><function>pg_stat_get_backend_activity_start</function>(<type>integer</type>)</literal></entry>
       <entry><type>text</type></entry>
       <entry>
-       The time at which the specified backend's currently executing query was
-       initiated (NULL if caller is not superuser, or
-       <varname>STATS_COMMAND_STRING</varname> is not enabled)
+       The time at which the specified backend process' currently
+       executing query was started (null if the current user is not a
+       superuser, or <varname>stats_command_string</varname> is not
+       on)
       </entry>
      </row>
 
 
      <row>
-      <entry><function>pg_stat_reset</function>()</entry>
+      <entry><literal><function>pg_stat_reset</function>()</literal></entry>
       <entry><type>boolean</type></entry>
       <entry>
        Reset all currently collected statistics
@@ -564,8 +563,8 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
 
    <note>
     <para>
-     <literal>blocks_fetched</literal> minus
-     <literal>blocks_hit</literal> gives the number of kernel
+     <function>pg_stat_get_db_blocks_fetched</function> minus
+     <function>pg_stat_get_db_blocks_hit</function> gives the number of kernel
      <function>read()</> calls issued for the table, index, or
      database; but the actual number of physical reads is usually
      lower due to kernel-level buffering.
@@ -574,13 +573,13 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
 
   <para>
    The function <function>pg_stat_get_backend_idset</function> provides
-   a convenient way to generate one row for each active backend.  For
-   example, to show the <acronym>PID</>s and current queries of all backends:
+   a convenient way to generate one row for each active backend process.  For
+   example, to show the <acronym>PID</>s and current queries of all backend processes:
 
 <programlisting>
-SELECT pg_stat_get_backend_pid(S.backendid) AS procpid,
-       pg_stat_get_backend_activity(S.backendid) AS current_query
-FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
+SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
+       pg_stat_get_backend_activity(s.backendid) AS current_query
+    FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s;
 </programlisting>
   </para>
 
@@ -592,7 +591,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
 
   <para>
    Another useful tool for monitoring database activity is the
-   <literal>pg_locks</literal> system catalog. This allows the
+   <literal>pg_locks</literal> system table.  It allows the
    database administrator to view information about the outstanding
    locks in the lock manager. For example, this capability can be used
    to:
@@ -609,7 +608,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
 
     <listitem>
      <para>
-      View the relation in the current database with the most
+      Determine the relation in the current database with the most
       ungranted locks (which might be a source of contention among
       database clients).
      </para>
@@ -636,7 +635,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
     view produces a consistent set of results, while not blocking
     normal lock manager operations longer than necessary.  Nonetheless
     there could be some impact on database performance if this view is
-    examined often.
+    read often.
    </para>
   </note>
 
@@ -646,7 +645,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
    <literal>pg_locks</literal> view contains one row per lockable
    object and requested lock mode.  Thus, the same lockable object may
    appear many times, if multiple transactions are holding or waiting
-   for locks on it.  A lockable object is either a relation or a
+   for locks on it.  A lockable object is either a relation (e.g., a table) or a
    transaction ID.  (Note that this view includes only table-level
    locks, not row-level ones.  If a transaction is waiting for a
    row-level lock, it will appear in the view as waiting for the
@@ -654,13 +653,13 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
   </para>
 
   <table id="monitoring-locks-table">
-   <title>Lock Status System View</title>
+   <title><literal>pg_locks</literal> Columns</title>
 
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Column Name</entry>
-      <entry>Type</entry>
+      <entry>Data Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
@@ -671,7 +670,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
       <entry><type>oid</type></entry>
       <entry>
        The OID of the locked relation, or null if the lockable object
-       is a transaction ID. This column can be joined with the
+       is a transaction ID. This column can be joined with the column <literal>oid</> of the
        <literal>pg_class</literal> system catalog to get more
        information on the locked relation.  Note however that this
        will only work for relations in the current database (those for
@@ -687,7 +686,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
        The OID of the database in which the locked relation exists, or
        null if the lockable object is a transaction ID.  If the lock
        is on a globally-shared table, this field will be zero. This
-       column can be joined with the <literal>pg_database</literal>
+       column can be joined with the column <literal>oid</> of the <literal>pg_database</literal>
        system catalog to get more information on the locked object's
        database.
       </entry>
@@ -712,11 +711,11 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
       <entry><type>integer</type></entry>
       <entry>
        The process ID of the <productname>PostgreSQL</productname>
-       backend belonging to the session that has acquired or is
+       server process belonging to the session that has acquired or is
        attempting to acquire the lock. If you have enabled the
-       statistics collector, this column can be joined with the
+       statistics collector, this column can be joined with the column
        <literal>pg_stat_activity</literal> view to get more
-       information on the backend holding or waiting to hold the
+       information on the session holding or waiting to hold the
        lock.
       </entry>
      </row>
@@ -740,8 +739,8 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
        False indicates that this session is currently waiting to
        acquire this lock, which implies that some other session is
        holding a conflicting lock mode on the same lockable object.
-       This backend will sleep until the other lock is released (or a
-       deadlock situation is detected). A single backend can be
+       The waiting session will sleep until the other lock is released (or a
+       deadlock situation is detected). A single session can be
        waiting to acquire at most one lock at a time.
       </entry>
      </row>

doc/src/sgml/ref/clusterdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.8 2003/03/20 18:53:18 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.9 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,12 +18,12 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>clusterdb</command>
-   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg>--table | -t <replaceable>table</replaceable> </arg>
    <arg><replaceable>dbname</replaceable></arg>
    <sbr>
    <command>clusterdb</command>
-   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <group><arg>--all</arg><arg>-a</arg></group>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -114,7 +114,7 @@ PostgreSQL documentation
       <term><option>--table <replaceable class="parameter">table</replaceable></></term>
       <listitem>
        <para>
-	Clusters <replaceable class="parameter">table</replaceable> only.
+	Cluster <replaceable class="parameter">table</replaceable> only.
        </para>
       </listitem>
      </varlistentry>
@@ -134,7 +134,7 @@ PostgreSQL documentation
        <para>
 	Specifies the host name of the machine on which the 
 	server
-	is running.  If host begins with a slash, it is used 
+	is running.  If the value begins with a slash, it is used 
 	as the directory for the Unix domain socket.
        </para>
       </listitem>
@@ -145,7 +145,7 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket file 
+	Specifies the TCP port or local Unix domain socket file 
 	extension on which the server
 	is listening for connections.
        </para>
@@ -219,7 +219,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Default connection parameters.
+      Default connection parameters
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/createdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.31 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.32 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,7 +18,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>createdb</command>
-   <arg rep="repeat"><replaceable>options</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
    <arg><replaceable>dbname</replaceable></arg>
    <arg><replaceable>description</replaceable></arg>
   </cmdsynopsis>
@@ -47,7 +47,7 @@ PostgreSQL documentation
    endterm="SQL-CREATEDATABASE-title">.  Thus, there is nothing
    special about creating databases via this or other methods.  This
    means that a database server must be running at the targeted
-   port. Also, any default settings and environment variables used by
+   host. Also, any default settings and environment variables used by
    the <application>libpq</application> front-end library will apply.
   </para>
  </refsect1>
@@ -65,7 +65,7 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Specifies the name of the database to be created.  The name must be
-	unique among all <productname>PostgreSQL</productname> databases in this installation.
+	unique among all <productname>PostgreSQL</productname> databases in this cluster.
         The default is to create a database with the same name as the
         current system user.
        </para>
@@ -98,7 +98,7 @@ PostgreSQL documentation
       <term><option>--echo</></term>
       <listitem>
        <para>
-        Echo the queries that <application>createdb</application> generates
+        Echo the commands that <application>createdb</application> generates
 	and sends to the server.
        </para>
       </listitem>
@@ -166,7 +166,7 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Specifies the host name of the machine on which the 
-	server is running.  If host begins with a slash, it is used 
+	server is running.  If the value begins with a slash, it is used 
 	as the directory for the Unix domain socket.
        </para>
       </listitem>
@@ -177,7 +177,7 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or the local Unix domain socket file 
+	Specifies the TCP port or the local Unix domain socket file 
 	extension on which the server is listening for connections.
        </para>
       </listitem>
@@ -296,7 +296,7 @@ PostgreSQL documentation
     To create the database <literal>demo</literal> using the
     server on host <literal>eden</>, port 5000, using the
     <literal>LATIN1</literal> encoding scheme with a look at the
-    underlying query:
+    underlying command:
 <screen>
 <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
 <computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput>

doc/src/sgml/ref/createlang.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.30 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.31 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,12 +18,12 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>createlang</command>
-   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg choice="plain"><replaceable>langname</replaceable></arg>
    <arg><replaceable>dbname</replaceable></arg>
    <sbr>
    <command>createlang</command>
-   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <group choice="plain"><arg>--list</arg><arg>-l</arg></group>
    <arg choice="plain"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
@@ -85,7 +85,7 @@ PostgreSQL documentation
       <term><option>--echo</></term>
       <listitem>
        <para>
-        Displays SQL commands as they are executed.
+        Display SQL commands as they are executed.
        </para>
       </listitem>
      </varlistentry>
@@ -95,8 +95,7 @@ PostgreSQL documentation
       <term><option>--list</></term>
       <listitem>
        <para>
-        Shows a list of already installed languages in the target database
-        (which must be specified).
+        Show a list of already installed languages in the target database.
        </para>
       </listitem>
      </varlistentry>
@@ -127,7 +126,7 @@ PostgreSQL documentation
        <para>
 	Specifies the host name of the machine on which the 
 	server
-	is running.  If host begins with a slash, it is used 
+	is running.  If the value begins with a slash, it is used 
 	as the directory for the Unix domain socket.
        </para>
       </listitem>
@@ -138,7 +137,7 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket file 
+	Specifies the TCP port or local Unix domain socket file 
 	extension on which the server
 	is listening for connections.
        </para>
@@ -182,7 +181,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Default connection parameters.
+      Default connection parameters
      </para>
     </listitem>
    </varlistentry>
@@ -215,7 +214,7 @@ PostgreSQL documentation
   <title>Examples</title>
 
    <para>
-    To install <literal>pltcl</literal> into the database
+    To install the language <literal>pltcl</literal> into the database
     <literal>template1</literal>:
 <screen>
 <prompt>$ </prompt><userinput>createlang pltcl template1</userinput>

doc/src/sgml/ref/createuser.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.31 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.32 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,7 +18,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>createuser</command>
-   <arg rep="repeat"><replaceable>options</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
    <arg><replaceable>username</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -78,7 +78,7 @@ PostgreSQL documentation
       <listitem>
        <para>
 	The new user is allowed to create other users.
-	(Note: Actually, this makes the new user a <firstterm>superuser</>.
+	(Note: Actually, this makes the new user a <emphasis>superuser</>.
 	The option is poorly named.)
        </para>
       </listitem>
@@ -120,7 +120,7 @@ PostgreSQL documentation
       <term><option>--echo</></term>
       <listitem>
        <para>
-        Echo the queries that <application>createuser</application> generates
+        Echo the commands that <application>createuser</application> generates
 	and sends to the server.
        </para>
       </listitem>
@@ -138,8 +138,8 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-i <replaceable class="parameter">uid</replaceable></></term>
-      <term><option>--sysid <replaceable class="parameter">uid</replaceable></></term>
+      <term><option>-i <replaceable class="parameter">number</replaceable></></term>
+      <term><option>--sysid <replaceable class="parameter">number</replaceable></></term>
       <listitem>
        <para>
        Allows you to pick a non-default user ID for the new user. This is not
@@ -200,7 +200,7 @@ PostgreSQL documentation
        <para>
 	Specifies the host name of the machine on which the 
 	server
-	is running.  If host begins with a slash, it is used 
+	is running.  If the value begins with a slash, it is used 
 	as the directory for the Unix domain socket.
        </para>
       </listitem>
@@ -211,7 +211,7 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket file 
+	Specifies the TCP port or local Unix domain socket file 
 	extension on which the server
 	is listening for connections.
        </para>
@@ -311,7 +311,7 @@ PostgreSQL documentation
    <para>
     To create the same user <literal>joe</literal> using the
     server on host <literal>eden</>, port 5000, avoiding the prompts and
-    taking a look at the underlying query:
+    taking a look at the underlying command:
 <screen>
 <prompt>$ </prompt><userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
 <computeroutput>CREATE USER "joe" NOCREATEDB NOCREATEUSER</computeroutput>

doc/src/sgml/ref/current_date.sgml

-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.5 2002/04/21 19:02:39 thomas Exp $
-Postgres documentation
--->
-
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.5 2002/04/21 19:02:39 thomas Exp $
-Postgres documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-DATE">
- <REFMETA>
-  <REFENTRYTITLE>CURRENT_DATE</REFENTRYTITLE>
-  <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
-  <REFNAME>
-   CURRENT_DATE
-  </REFNAME>
-  <REFPURPOSE>
-Returns the current date
-  </REFPURPOSE>
- <REFSYNOPSISDIV>
-  <REFSYNOPSISDIVINFO>
-   <DATE>1998-04-15</DATE>
-  </REFSYNOPSISDIVINFO>
-  <SYNOPSIS>
-   CURRENT_DATE
-  </SYNOPSIS>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-DATE-1">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Inputs
-   </TITLE>
-   <PARA>
-None.
-  </REFSECT2>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-DATE-2">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Outputs
-   </TITLE>
-   <PARA>
-       <VARIABLELIST>
-	<VARLISTENTRY>
-	 <TERM>
-<replaceable>date</replaceable>
-
-	 </TERM>
-	 <LISTITEM>
-	  <PARA>
-	  Returns "<replaceable class="parameter">today</replaceable>".
-   </VARIABLELIST>
-  </REFSECT2>
- </REFSYNOPSISDIV>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-DATE-1">
-  <REFSECT1INFO>
-   <DATE>1998-04-15</DATE>
-  </REFSECT1INFO>
-  <TITLE>
-   Description
-  </TITLE>
-  <PARA>
-   The niladic CURRENT_DATE function has a data type of
-   DATE and returns the date at the time that it is run.
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-DATE-3">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Notes
-   </TITLE>
-   <PARA>
-    Refer to SET DATESTYLE for further information about date format.
-   </PARA>
-  </REFSECT2>
-  
- <REFSECT1 ID="R1-SQL-CURRENT-DATE-2">
-  <TITLE>
-   Usage
-  </TITLE>
-  <PARA>
-   Insert the date of insertion into a row:
-  </PARA>
-  <ProgramListing>
-   INSERT INTO films
-         VALUES ('TM999','Ben Hur',105,CURRENT_DATE,'Action',NULL);
-  </ProgramListing>
-  
-  <PARA>
-   Display CURRENT-DATE:
-  </PARA>
-  <ProgramListing>
-   SELECT CURRENT_DATE AS today;
-
-   today
-   ------------
-   1998-03-31
-
-  </ProgramListing>
- </REFSECT1>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-DATE-3">
-  <TITLE>
-   Compatibility
-  </TITLE>
-  <PARA>
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-DATE-4">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    SQL92
-   </TITLE>
-   <PARA>
-    Full compatibility.
-   </PARA>
-  </refsect2>
- </refsect1>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->

doc/src/sgml/ref/current_time.sgml

-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_time.sgml,v 1.6 2002/04/21 19:02:39 thomas Exp $
-PostgreSQL documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-TIME">
- <REFMETA>
-  <REFENTRYTITLE>CURRENT_TIME</REFENTRYTITLE>
-  <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
-  <REFNAME>
-   CURRENT_TIME
-  </REFNAME>
-  <REFPURPOSE>
-Returns the current local time
-  </REFPURPOSE>
- <REFSYNOPSISDIV>
-  <REFSYNOPSISDIVINFO>
-   <DATE>1998-04-15</DATE>
-  </REFSYNOPSISDIVINFO>
-  <SYNOPSIS>
-   CURRENT_TIME 
-  </SYNOPSIS>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIME-1">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Inputs
-   </TITLE>
-   <PARA>
-None.
-   
-  </REFSECT2>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIME-2">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Outputs
-   </TITLE>
-   <PARA>
-       <VARIABLELIST>
-	<VARLISTENTRY>
-	 <TERM>
-	  <replaceable>time</replaceable>
-
-	 <LISTITEM>
-	  <PARA>
-	  <ReturnValue>Returns "<replaceable class="parameter">now</replaceable>"</ReturnValue>
-
-   </VARIABLELIST>
-  </REFSECT2>
- </REFSYNOPSISDIV>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-TIME-1">
-  <REFSECT1INFO>
-   <DATE>1998-04-15</DATE>
-  </REFSECT1INFO>
-  <TITLE>
-   Description
-  </TITLE>
-  <PARA>
-   The niladic CURRENT_TIME function has a data type of
-   TIME and returns the local time when it is run.
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIME-3">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Notes
-   </TITLE>
-   <PARA> Refer to the SET TIME ZONE statement for a further description
-    of local time.
-   </PARA>
-  </REFSECT2>
-  
- <REFSECT1 ID="R1-SQL-CURRENT-TIME-2">
-  <TITLE>
-   Usage
-  </TITLE>
-  <PARA>Display CURRENT_TIME:
-  </PARA>
-  <ProgramListing>
-   SELECT CURRENT_TIME AS now;
-
-   now
-   -----------
-   17:41:31+02
-
-  </ProgramListing>
- </REFSECT1>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-TIME-3">
-  <TITLE>
-   Compatibility
-  </TITLE>
-  <PARA>
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIME-4">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    SQL92
-   </TITLE>
-   <PARA>
-    SQL92 specifies some additional capabilities for CURRENT_TIME:
-   </PARA>
-   <VARIABLELIST>
-    <VARLISTENTRY>
-     <TERM>
-     </TERM>
-     <LISTITEM>
-      <PARA>
-       <VARIABLELIST>
-	<VARLISTENTRY>
-	 <TERM>
-	  <ReturnValue>
-	   CURRENT_TIME [ (<replaceable class="parameter">scale</replaceable>) ]</ReturnValue>
-	 </TERM>
-	 <LISTITEM>
-	  <PARA>
-	   The optional scale for CURRENT_TIME, if specified, is an
-	   unsigned integer representing the number of digits in the
-	   optional seconds fraction of the time value represented
-	   by the function.
-	  </PARA>
-	 </LISTITEM>
-	</VARLISTENTRY>
-       </VARIABLELIST>
-     </LISTITEM>
-    </VARLISTENTRY>
-   </VARIABLELIST>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->

doc/src/sgml/ref/current_timestamp.sgml

-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_timestamp.sgml,v 1.6 2002/04/21 19:02:39 thomas Exp $
-PostgreSQL documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-TIMESTAMP">
- <REFMETA>
-  <REFENTRYTITLE>CURRENT_TIMESTAMP</REFENTRYTITLE>
-  <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
-  <REFNAME>
-   CURRENT_TIMESTAMP
-  </REFNAME>
-  <REFPURPOSE>
-   Returns the current date and time
-  </REFPURPOSE>
-  
-  
- <REFSYNOPSISDIV>
-  <REFSYNOPSISDIVINFO>
-   <DATE>1998-04-15</DATE>
-  </REFSYNOPSISDIVINFO>
-  <synopsis>
-  CURRENT_TIMESTAMP 
- </SYNOPSIS>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-1">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Inputs
-   </TITLE>
-   <PARA>
-None.
-
-  </REFSECT2>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-2">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Outputs
-   </TITLE>
-   <PARA>
-       <VARIABLELIST>
-	<VARLISTENTRY>
-	 <TERM>
-<replaceable>timestamp</replaceable>
-
-	 <LISTITEM>
-	  <PARA>
-	  Returns "<replaceable class="parameter">today</replaceable>" and "<replaceable class="parameter">now</replaceable>".
-
-   </VARIABLELIST>
-  </REFSECT2>
- </REFSYNOPSISDIV>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-1">
-  <REFSECT1INFO>
-   <DATE>1998-04-15</DATE>
-  </REFSECT1INFO>
-  <TITLE>
-   Description
-  </TITLE>
-  <PARA>
-   The niladic CURRENT_TIMESTAMP function has a data type of
-   TIMESTAMP and returns the date and local time at which it is run.
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-3">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Notes
-   </TITLE>
-   <PARA>
-    Refer to the SET TIME ZONE statement for a further description
-    of local time.
-   </PARA>
-   
-   
-  </REFSECT2>
-  
- <REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-2">
-  <TITLE>
-   Usage
-  </TITLE>
-  <PARA>
-   Display CURRENT_TIMESTAMP:
-  </PARA>
-  <ProgramListing>
-   SELECT CURRENT_TIMESTAMP AS date_and_time;
-
-   date_and_time
-   ----------------------
-   1998-03-31 07:41:21-08
-  </ProgramListing>
- </REFSECT1>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-3">
-  <TITLE>
-   Compatibility
-  </TITLE>
-  <PARA>
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-4">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    SQL92
-   </TITLE>
-   <PARA>
-   SQL92 specifies some additional capabilities for CURRENT_TIMESTAMP:
-   </PARA>
-   
-   <VARIABLELIST>
-    <VARLISTENTRY>
-     <TERM>
-     </TERM>
-     <LISTITEM>
-      <PARA>
-       <VARIABLELIST>
-	<VARLISTENTRY>
-	 <TERM>
-	  <ReturnValue>CURRENT_TIMESTAMP [ (<replaceable class="parameter">scale</replaceable>) ]</ReturnValue>
-	 </TERM>
-	 <LISTITEM>
-	  <PARA>
-	   The optional scale for CURRENT_TIMESTAMP, if specified, is an
-	   unsigned integer representing the number of digits in the
-	   optional seconds fraction of the time value represented
-	   by the function.
-	  </PARA>
-	 </LISTITEM>
-	</VARLISTENTRY>
-       </VARIABLELIST>
-      </para>
-     </LISTITEM>
-    </VARLISTENTRY>
-   </VARIABLELIST>
-  </refsect2>
- </refsect1>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->

doc/src/sgml/ref/current_user.sgml

-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_user.sgml,v 1.7 2002/08/13 20:40:43 momjian Exp $
-PostgreSQL documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-USER">
- <REFMETA>
-  <REFENTRYTITLE>CURRENT_USER</REFENTRYTITLE>
-  <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
-  <REFNAME>
-   CURRENT_USER
-  </REFNAME>
-  <REFPURPOSE>
-   Returns the current user name
-  </REFPURPOSE>
- <REFSYNOPSISDIV>
-  <REFSYNOPSISDIVINFO>
-   <DATE>1998-04-15</DATE>
-  </REFSYNOPSISDIVINFO>
-  <SYNOPSIS>
-   CURRENT_USER 
-  </SYNOPSIS>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-USER-1">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Inputs
-   </TITLE>
-   <PARA>
-
-None.
-  </REFSECT2>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-USER-2">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Outputs
-   </TITLE>
-   <PARA>
-
-       <VARIABLELIST>
-	<VARLISTENTRY>
-	 <TERM>
-	  <replaceable>username</replaceable>
-	 </TERM>
-	 <LISTITEM>
-	  <PARA>
-The name of the current user.
-
-   </VARIABLELIST>
-  </REFSECT2>
- </REFSYNOPSISDIV>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-USER-1">
-  <REFSECT1INFO>
-   <DATE>1998-04-15</DATE>
-  </REFSECT1INFO>
-  <TITLE>
-   Description
-  </TITLE>
-  <PARA>
-   The niladic CURRENT_USER function returns a string of type "name"
-   whose value represents a user name identification.
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-USER-3">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    Notes
-   </TITLE>
-   <PARA>
-    Data type "name" is a non-standard 63-character type for storing
-    system identifiers.
-   </PARA>
-  </REFSECT2>
-  
- <REFSECT1 ID="R1-SQL-CURRENT-USER-2">
-  <TITLE>
-   Usage
-  </TITLE>
-  <PARA>
-   Display CURRENT_USER
-  </PARA>
-  <ProgramListing>
-   SELECT CURRENT_USER AS who_am_i;
-
-   who_am_i
-   ------------
-   jose
-  </ProgramListing>
- </REFSECT1>
- 
- <REFSECT1 ID="R1-SQL-CURRENT-USER-3">
-  <TITLE>
-   Compatibility
-  </TITLE>
-  <PARA>
-  </PARA>
-  
-  <REFSECT2 ID="R2-SQL-CURRENT-USER-4">
-   <REFSECT2INFO>
-    <DATE>1998-04-15</DATE>
-   </REFSECT2INFO>
-   <TITLE>
-    SQL92
-   </TITLE>
-   <PARA>
-   SQL92 specifies some additional niladic USER functions:
-   </PARA>
-   <variablelist>
-    <varlistentry>
-     <term>CURRENT_USER / USER</term>
-     <listitem>
-      <para>  
-       USER is a synonym for CURRENT_USER. 
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>SESSION_USER</term>
-     <listitem>
-      <para>
-       The SESSION_USER function returns the SQL-session user name.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>SYSTEM_USER</term>
-     <listitem>
-      <para>
-       The SYSTEM_USER function returns the database's initial default user.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-   <para>
-    A niladic USER function returns a SQL_TEXT character string whose
-    value represents a user name.
-   </para>
-  </refsect2>
- </refsect1>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->

doc/src/sgml/ref/dropdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.20 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.21 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,7 +18,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>dropdb</command>
-   <arg rep="repeat"><replaceable>options</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
    <arg choice="plain"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -57,9 +57,7 @@ PostgreSQL documentation
       <term><replaceable class="parameter">dbname</replaceable></term>
       <listitem>
        <para>
-	Specifies the name of the database to be removed.  The database
-	must be one of the existing <productname>PostgreSQL</productname> databases
-	in this installation.
+	Specifies the name of the database to be removed.
        </para>
       </listitem>
      </varlistentry>
@@ -69,7 +67,7 @@ PostgreSQL documentation
       <term><option>--echo</></term>
       <listitem>
        <para>
-        Echo the queries that <application>dropdb</application> generates
+        Echo the commands that <application>dropdb</application> generates
 	and sends to the server.
        </para>
       </listitem>
@@ -109,7 +107,7 @@ PostgreSQL documentation
        <para>
 	Specifies the host name of the machine on which the 
 	server
-	is running.  If host begins with a slash, it is used 
+	is running.  If the value begins with a slash, it is used 
 	as the directory for the Unix domain socket.
        </para>
       </listitem>
@@ -120,7 +118,7 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket file 
+	Specifies the TCP port or local Unix domain socket file 
 	extension on which the server
 	is listening for connections.
        </para>
@@ -212,7 +210,7 @@ PostgreSQL documentation
    <para>
     To destroy the database <literal>demo</literal> using the
     server on host <literal>eden</literal>, port 5000, with verification and a peek
-    at the underlying query:
+    at the underlying command:
 <screen>
 <prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
 <computeroutput>Database "demo" will be permanently deleted.

doc/src/sgml/ref/droplang.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.22 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.23 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,12 +18,12 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>droplang</command>
-   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <arg choice="plain"><replaceable>langname</replaceable></arg>
    <arg><replaceable>dbname</replaceable></arg>
    <sbr>
    <command>droplang</command>
-   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <group choice="plain"><arg>--list</arg><arg>-l</arg></group>
    <arg choice="plain"><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
@@ -85,7 +85,7 @@ PostgreSQL documentation
       <term><option>--echo</></term>
       <listitem>
        <para>
-        Displays SQL commands as they are executed.
+        Display SQL commands as they are executed.
        </para>
       </listitem>
      </varlistentry>
@@ -95,8 +95,7 @@ PostgreSQL documentation
       <term><option>--list</></term>
       <listitem>
        <para>
-        Shows a list of already installed languages in the target database
-        (which must be specified).
+        Show a list of already installed languages in the target database.
        </para>
       </listitem>
      </varlistentry>
@@ -171,7 +170,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Default connection parameters.
+      Default connection parameters
      </para>
     </listitem>
    </varlistentry>
@@ -204,7 +203,7 @@ PostgreSQL documentation
   <title>Examples</title>
 
    <para>
-    To remove <literal>pltcl</literal>:
+    To remove the language <literal>pltcl</literal>:
 <screen>
 <prompt>$ </prompt><userinput>droplang pltcl dbname</userinput>
 </screen>

doc/src/sgml/ref/dropuser.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.23 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.24 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,7 +18,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>dropuser</command>
-   <arg rep="repeat"><replaceable>options</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
    <arg><replaceable>username</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -31,8 +31,8 @@ PostgreSQL documentation
    <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 
+   Only superusers (users with <literal>usesuper</literal> set in
+   the <literal>pg_shadow</literal> table) can destroy 
    <productname>PostgreSQL</productname> users.
   </para>
 
@@ -61,7 +61,6 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Specifies the name of the <productname>PostgreSQL</productname> user to be removed. 
-	This name must exist in the <productname>PostgreSQL</productname> installation.
 	You will be prompted for a name if none is specified on the command line.
        </para>
       </listitem>
@@ -72,7 +71,7 @@ PostgreSQL documentation
       <term><option>--echo</></term>
       <listitem>
        <para>
-        Echo the queries that <application>dropuser</application> generates
+        Echo the commands that <application>dropuser</application> generates
 	and sends to the server.
        </para>
       </listitem>
@@ -112,7 +111,7 @@ PostgreSQL documentation
        <para>
 	Specifies the host name of the machine on which the 
 	server
-	is running.  If host begins with a slash, it is used 
+	is running.  If the value begins with a slash, it is used 
 	as the directory for the Unix domain socket.
        </para>
       </listitem>
@@ -123,7 +122,7 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket file 
+	Specifies the TCP port or local Unix domain socket file 
 	extension on which the server
 	is listening for connections.
        </para>
@@ -219,9 +218,9 @@ PostgreSQL documentation
    </para>
 
    <para>
-    To remove user <literal>joe</literal> using the postmaster on host
+    To remove user <literal>joe</literal> using the server on host
     <literal>eden</literal>, port 5000, with verification and a peek at the underlying
-    query:
+    command:
 <screen>
 <prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput>
 <computeroutput>User "joe" and any owned databases will be permanently deleted.

doc/src/sgml/ref/ecpg-ref.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.25 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -66,7 +66,7 @@ PostgreSQL documentation
      <term><option>-c</option></term>
      <listitem>
       <para>
-       Automatically generate C code from SQL code.  Currently, this
+       Automatically generate certain C code from SQL code.  Currently, this
        works for <literal>EXEC SQL TYPE</literal>.
       </para>
      </listitem>
@@ -101,7 +101,7 @@ PostgreSQL documentation
      <term><option>-o <replaceable>filename</replaceable></option></term>
      <listitem>
       <para>
-       Specifies that <application>ecpg</application> should write all
+       Specifies that <command>ecpg</command> should write all
        its output to the given <replaceable>filename</replaceable>.
       </para>
      </listitem>
@@ -111,9 +111,9 @@ PostgreSQL documentation
      <term><option>-t</option></term>
      <listitem>
       <para>
-       Turn on autocommit of transactions. In this mode, each query is
+       Turn on autocommit of transactions. In this mode, each SQL command is
        automatically committed unless it is inside an explicit
-       transaction block. In the default mode, queries are committed
+       transaction block. In the default mode, commands are committed
        only when <command>EXEC SQL COMMIT</command> is issued.
       </para>
      </listitem>
@@ -130,7 +130,7 @@ PostgreSQL documentation
     </varlistentry>
 
     <varlistentry>
-     <term><option>---help</option></term>
+     <term><option>--help</option></term>
      <listitem>
       <para>
        Show a brief summary of the command usage, then exit.
@@ -165,7 +165,7 @@ PostgreSQL documentation
   <para>
    Programs using C code with embedded SQL have to be linked against
    the <filename>libecpg</filename> library, for example using the
-   flags <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
+   linker options <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
   </para>
 
   <para>

doc/src/sgml/ref/initdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.25 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,7 +18,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>initdb</command>
-   <arg rep="repeat">options</arg>
+   <arg rep="repeat"><replaceable>option</></arg>
    <group choice="plain">
     <arg>--pgdata </arg>
     <arg>-D </arg>
@@ -33,17 +33,17 @@ PostgreSQL documentation
   </title>
   <para>
    <command>initdb</command> creates a new
-   <productname>PostgreSQL</productname> database cluster (or database
-   system).  A database cluster is a collection of databases that are
-   managed by a single server instance.
+   <productname>PostgreSQL</productname> database cluster.  A database
+   cluster is a collection of databases that are managed by a single
+   server instance.
   </para>
 
   <para>
-   Creating a database system consists of creating the directories in which
+   Creating a database cluster consists of creating the directories in which
    the database data will live, generating the shared catalog tables 
    (tables that belong to the whole cluster rather than to any particular
    database), and creating the <literal>template1</literal>
-   database.  When you create a new database, everything in the
+   database.  When you later create a new database, everything in the
    <literal>template1</literal> database is copied.
    It contains catalog tables filled in for things like the
    built-in types.
@@ -99,7 +99,7 @@ PostgreSQL documentation
       <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
       <listitem>
        <para>
-        This option specifies the directory where the database system
+        This option specifies the directory where the database cluster
         should be stored. This is the only information required by
         <command>initdb</command>, but you can avoid writing it by
         setting the <envar>PGDATA</envar> environment variable, which
@@ -117,9 +117,7 @@ PostgreSQL documentation
        <para>
         Selects the encoding of the template database. This will also
         be the default encoding of any database you create later, unless you
-        override it there. To use the encoding feature, you must
-        have enabled it at build time, at which time you also select the default
-        for this option.
+        override it there.  The default is <literal>SQL_ASCII</literal>.
        </para>
       </listitem>
      </varlistentry>
@@ -205,7 +203,7 @@ PostgreSQL documentation
       <listitem>
        <para>
         Specifies where <command>initdb</command> should find
-        its input files to initialize the database system.  This is
+        its input files to initialize the database cluster.  This is
         normally not necessary.  You will be told if you need to
         specify their location explicitly.
        </para>
@@ -219,7 +217,7 @@ PostgreSQL documentation
        <para>
 	By default, when <command>initdb</command>
 	determines that an error prevented it from completely creating the database
-	system, it removes any files it may have created before discovering
+	cluster, it removes any files it may have created before discovering
 	that it can't finish the job. This option inhibits tidying-up and is
 	thus useful for debugging.
        </para>
@@ -239,7 +237,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Specifies the directory where the database system is to be
+      Specifies the directory where the database cluster is to be
       stored; may be overridden using the <option>-D</option> option.
      </para>
     </listitem>

doc/src/sgml/ref/initlocation.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.18 2003/01/19 00:13:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.19 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -47,9 +47,9 @@ PostgreSQL documentation
 <screen>
 <prompt>$ </prompt><userinput>export PGDATA2=/opt/postgres/data</userinput>
 </screen>
-    Stop and start postmaster so it sees the <envar>PGDATA2</envar>
+    Stop and start <command>postmaster</> so it sees the <envar>PGDATA2</envar>
     environment variable.  The system must be configured so the
-    postmaster sees <envar>PGDATA2</envar> every time it starts.  Finally:
+    <command>postmaster</> sees <envar>PGDATA2</envar> every time it starts.  Finally:
 <screen>
 <prompt>$</prompt> <userinput>initlocation PGDATA2</userinput>
 <prompt>$</prompt> <userinput>createdb -D PGDATA2 testdb</userinput>

doc/src/sgml/ref/ipcclean.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/ipcclean.sgml,v 1.7 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/ipcclean.sgml,v 1.8 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -36,12 +36,10 @@ PostgreSQL documentation
   <para>
    Only the database administrator should execute this program as it
    can cause bizarre behavior (i.e., crashes) if run during multiuser
-   execution.  If this command is executed while a
-   <application>postmaster</application> is running, the shared memory
-   and semaphores allocated by the
-   <application>postmaster</application> will be deleted.  This will
-   result in a general failure of the backend servers started by that
-   <application>postmaster</application>.
+   execution.  If this command is executed while a server is running,
+   the shared memory and semaphores allocated by that server will be
+   deleted, which would have rather severe consequences for that
+   server.
   </para>
  </refsect1>
 
@@ -51,14 +49,14 @@ PostgreSQL documentation
   <para>
    This script is a hack, but in the many years since it was written,
    no one has come up with an equally effective and portable solution.
-   Since the <application>postmaster</application> can now clean up by
+   Since the <command>postmaster</command> can now clean up by
    itself, it is unlikely that <command>ipcclean</command> will be
    improved upon in the future.
   </para>
 
   <para>
    The script makes assumption about the format of output of the
-   <application>ipcs</application>
+   <command>ipcs</command>
    utility which may not be true across different operating systems.
    Therefore, it may not work on your particular OS.
   </para>

doc/src/sgml/ref/pg_config-ref.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.13 2003/01/19 00:13:29 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.14 2003/03/24 14:32:51 petere Exp $ -->
 
 <refentry id="app-pgconfig">
  <refmeta>
@@ -50,7 +50,7 @@
      <listitem>
       <para>
        Print the location of user executables. Use this, for example, to find
-       the <application>psql</> program. This is normally also the location
+       the <command>psql</> program. This is normally also the location
        where the <filename>pg_config</> program resides.       
       </para>
      </listitem>
@@ -130,10 +130,10 @@
   <title>Notes</title>
 
   <para>
-   The option <option>--includedir-server</option> is new in
+   The option <option>--includedir-server</option> was new in
    <productname>PostgreSQL</> 7.2.  In prior releases, the server include files were
    installed in the same location as the client headers, which could
-   be queried with the <option>--includedir</option>.  To make your
+   be queried with the option <option>--includedir</option>.  To make your
    package handle both cases, try the newer option first and test the
    exit status to see whether it succeeded.
   </para>

doc/src/sgml/ref/pg_controldata.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_controldata.sgml,v 1.4 2002/08/17 05:07:18 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_controldata.sgml,v 1.5 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -12,7 +12,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_controldata</refname>
-  <refpurpose>display server-wide control information</refpurpose>
+  <refpurpose>display control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -25,16 +25,16 @@ PostgreSQL documentation
  <refsect1 id="R1-APP-PGCONTROLDATA-1">
   <title>Description</title>
   <para>
-   <command>pg_controldata</command> returns information initialized during
-   <application>initdb</>, such as the catalog version and server locale.
+   <command>pg_controldata</command> prints information initialized during
+   <command>initdb</>, such as the catalog version and server locale.
    It also shows information about write-ahead logging and checkpoint 
-   processing.  This information is server-wide, and not specific to any one
+   processing.  This information is cluster-wide, and not specific to any one
    database.
   </para>
 
   <para>
-   This utility may only be run by the user who installed the server because
-   it requires read access to the <literal>datadir</>.
+   This utility may only be run by the user who initialized the cluster because
+   it requires read access to the data directory.
    You can specify the data directory on the command line, or use 
    the environment variable <envar>PGDATA</>.
   </para>

doc/src/sgml/ref/pg_ctl-ref.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.20 2003/03/20 17:37:46 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.21 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -69,17 +69,17 @@ PostgreSQL documentation
   <title>Description</title>
   <para>
    <application>pg_ctl</application> is a utility for starting,
-   stopping, or restarting <xref linkend="app-postmaster">, the
-   <productname>PostgreSQL</productname> backend server, or displaying
-   the status of a running postmaster.  Although the postmaster can be
-   started manually, <application>pg_ctl</application> encapsulates
-   tasks such as redirecting log output and properly detaching from the
-   terminal and process group. It also provides convenient options for
+   stopping, or restarting the <productname>PostgreSQL</productname>
+   backend server (<xref linkend="app-postmaster">), or displaying the
+   status of a running server.  Although the server can be started
+   manually, <application>pg_ctl</application> encapsulates tasks such
+   as redirecting log output and properly detaching from the terminal
+   and process group. It also provides convenient options for
    controlled shutdown.
   </para>
 
   <para>
-   In <option>start</option> mode, a new postmaster is launched.  The
+   In <option>start</option> mode, a new server is launched.  The
    server is started in the background, and standard input is attached to
    <filename>/dev/null</filename>.  The standard output and standard
    error are either appended to a log file (if the <option>-l</option>
@@ -87,42 +87,45 @@ PostgreSQL documentation
    standard output (not standard error).  If no log file is chosen, the 
    standard output of <application>pg_ctl</application> should be redirected 
    to a file or piped to another process, for example a log rotating program,
-   otherwise the postmaster will write its output to the controlling
+   otherwise <command>postmaster</command> will write its output to the controlling
    terminal (from the background) and will not leave the shell's
    process group.
   </para>
 
   <para>
-   In <option>stop</option> mode, the postmaster that is running in
+   In <option>stop</option> mode, the server that is running in
    the specified data directory is shut down.  Three different
    shutdown methods can be selected with the <option>-m</option>
    option: <quote>Smart</quote> mode waits for all the clients to
    disconnect.  This is the default.  <quote>Fast</quote> mode does
    not wait for clients to disconnect.  All active transactions are
    rolled back and clients are forcibly disconnected, then the
-   database is shut down.  <quote>Immediate</quote> mode will abort
+   server is shut down.  <quote>Immediate</quote> mode will abort
    all server processes without a clean shutdown.  This will lead to 
    a recovery run on restart.
   </para>
 
   <para>
    <option>restart</option> mode effectively executes a stop followed
-   by a start.  This allows the changing of postmaster command line
-   options.
+   by a start.  This allows changing the <command>postmaster</command>
+   command-line options.
   </para>
 
   <para>
-   <option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
-   causing it to reread its configuration files
-   (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
-   etc.).  This allows changing of configuration-file options that do not
-   require a complete restart to take effect.
+   <option>reload</option> mode simply sends the
+   <command>postmaster</command> process a <systemitem>SIGHUP</>
+   signal, causing it to reread its configuration files
+   (<filename>postgresql.conf</filename>,
+   <filename>pg_hba.conf</filename>, etc.).  This allows changing of
+   configuration-file options that do not require a complete restart
+   to take effect.
   </para>
 
   <para>
-   <option>status</option> mode checks whether a postmaster is running. 
-   If it is, the <acronym>PID</acronym> and the command line
-   options that were used to invoke it are displayed.
+   <option>status</option> mode checks whether a server is running in
+   the specified data directory. If it is, the <acronym>PID</acronym>
+   and the command line options that were used to invoke it are
+   displayed.
   </para>
  </refsect1>
 
@@ -133,7 +136,7 @@ PostgreSQL documentation
 
     <variablelist>
      <varlistentry>
-      <term>-D <replaceable class="parameter">datadir</replaceable></term>
+      <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
       <listitem>
        <para>
 	Specifies the file system location of the database files.  If
@@ -144,7 +147,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-l <replaceable class="parameter">filename</replaceable></term>
+      <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
       <listitem>
        <para>
         Append the server log output to
@@ -156,7 +159,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-m <replaceable class="parameter">mode</replaceable></term>
+      <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
       <listitem>
        <para>
 	Specifies the shutdown mode.  <replaceable>mode</replaceable>
@@ -168,35 +171,35 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-o <replaceable class="parameter">options</replaceable></term>
+      <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
       <listitem>
        <para>
-        Specifies options to be passed directly to
-	<application>postmaster</application>.
+        Specifies options to be passed directly to the
+        <command>postmaster</command> command.
        </para>
        <para>
-	The parameters are usually surrounded by single or double
+	The options are usually surrounded by single or double
 	quotes to ensure that they are passed through as a group.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-p <replaceable class="parameter">path</replaceable></term>
+      <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
       <listitem>
        <para>
 	Specifies the location of the <filename>postmaster</filename>
-	executable.  By default the postmaster is taken from the same
+	executable.  By default the <filename>postmaster</filename> executable is taken from the same
 	directory as <command>pg_ctl</command>, or failing that, the hard-wired
 	installation directory.  It is not necessary to use this
 	option unless you are doing something unusual and get errors
-	that the postmaster was not found.
+	that the <filename>postmaster</filename> executable was not found.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-s</term>
+      <term><option>-s</option></term>
       <listitem>
        <para>
         Only print errors, no informational messages.
@@ -205,7 +208,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-w</term>
+      <term><option>-w</option></term>
       <listitem>
        <para>
 	Wait for the start or shutdown to complete.  Times out after
@@ -224,7 +227,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-W</term>
+      <term><option>-W</option></term>
       <listitem>
        <para>
         Do not wait for start or shutdown to complete.  This is the
@@ -276,9 +279,10 @@ PostgreSQL documentation
     <term><filename>postmaster.pid</filename></term>
 
     <listitem>
-     <para>The existence of this file in the data directory is used to help 
-           <application>pg_ctl</application> determine if the server is 
-           currently running or not.
+     <para>
+      The existence of this file in the data directory is used to help
+      <application>pg_ctl</application> determine if the server is
+      currently running or not.
      </para>
     </listitem>
    </varlistentry>
@@ -287,11 +291,12 @@ PostgreSQL documentation
     <term><filename>postmaster.opts.default</filename></term>
 
     <listitem>
-     <para>If this file exists in the data directory, 
-      <application>pg_ctl</application> (in <option>start</option> mode) 
-      will pass the contents of the file as options to the 
-      <application>postmaster</application>, unless overridden 
-      by the <option>-o</option> option.
+     <para>
+      If this file exists in the data directory,
+      <application>pg_ctl</application> (in <option>start</option>
+      mode) will pass the contents of the file as options to the
+      <command>postmaster</command> command, unless overridden by the
+      <option>-o</option> option.
      </para>
     </listitem>
    </varlistentry>
@@ -314,10 +319,10 @@ PostgreSQL documentation
     <term><filename>postgresql.conf</filename></term>
 
     <listitem>
-     <para>This file, located in the data directory, is parsed to 
-      find the proper port to send to the 
-      <application>psql</application> when the <option>-w</option> 
-      is given in <option>start</option> mode.      
+     <para>
+      This file, located in the data directory, is parsed to find the
+      proper port to use with <application>psql</application> when the
+      <option>-w</option> is given in <option>start</option> mode.
      </para>
     </listitem>
    </varlistentry>
@@ -332,7 +337,7 @@ PostgreSQL documentation
   <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 (e.g. password authentication).
+   connect without manual interaction (e.g., password authentication).
   </para>
  </refsect1>
 
@@ -341,25 +346,25 @@ PostgreSQL documentation
   <title>Examples</title>
 
   <refsect2 id="R2-APP-PGCTL-3">
-   <title>Starting the postmaster</title>
+   <title>Starting the Server</title>
 
    <para>
-    To start up a <application>postmaster</application>:
+    To start up a server:
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 </screen>
    </para>
 
    <para>
-    An example of starting the <application>postmaster</application>,
-    blocking until the postmaster comes up is:
+    An example of starting the server, blocking until the server has
+    come up is:
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 </screen>
    </para>
 
    <para>
-    For a <application>postmaster</application> using port 5433, and
+    For a server using port 5433, and
     running without <function>fsync</function>, use:
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
@@ -368,32 +373,32 @@ PostgreSQL documentation
   </refsect2>
 
   <refsect2 id="R2-APP-PGCTL-4">
-   <title>Stopping the postmaster</title>
+   <title>Stopping the Server</title>
    <para>
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 </screen>
-    stops the postmaster. Using the <option>-m</option> switch allows one
+    stops the server. Using the <option>-m</option> switch allows one
     to control <emphasis>how</emphasis> the backend shuts down.
    </para>
   </refsect2>
 
   <refsect2 id="R2-APP-PGCTL-5">
-   <title>Restarting the postmaster</title>
+   <title>Restarting the Server</title>
 
    <para>
-    This is almost equivalent to stopping the
-    <application>postmaster</application> and starting it again
+    Restarting the server is almost equivalent to stopping the
+    server and starting it again
     except that <command>pg_ctl</command> saves and reuses the command line options that
     were passed to the previously running instance.  To restart
-    the <application>postmaster</application> in the simplest form:
+    the server in the simplest form, use:
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 </screen>
    </para>
 
    <para>
-    To restart <application>postmaster</application>,
+    To restart server,
     waiting for it to shut down and to come up:
 <screen>
 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
@@ -409,7 +414,7 @@ PostgreSQL documentation
   </refsect2>
 
   <refsect2 id="R2-APP-PGCTL-6">
-   <title>Showing postmaster status</title>
+   <title>Showing the Server Status</title>
 
    <para>
     Here is a sample status output from

doc/src/sgml/ref/pg_dump.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.58 2003/03/18 17:05:01 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.59 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -21,7 +21,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_dump</command>
-   <arg rep="repeat"><replaceable>options</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
    <arg><replaceable>dbname</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
@@ -54,14 +54,6 @@ PostgreSQL documentation
    architectures.
   </para>
 
-  <para>
-   <application>pg_dump</application> will save the information necessary to
-   re-generate all user-defined types, functions, tables, indexes,
-   aggregates, and operators.  In addition, all the data is copied out
-   in text format so that it can be readily copied in again, as well
-   as imported into tools for editing.
-  </para>
-
   <para>
    When used with one of the archive file formats and combined with
    <application>pg_restore</application>, <application>pg_dump</application> provides a
@@ -73,14 +65,14 @@ PostgreSQL documentation
    The most flexible output file format is the <quote>custom</quote>
    format (<option>-Fc</option>). It allows for selection and
    reordering of all archived items, and is compressed by default. The
-   <filename>tar</filename> format (<option>-Ft</option>) is not
+   <application>tar</application> format (<option>-Ft</option>) is not
    compressed and it is not possible to reorder data when loading, but
    it is otherwise quite flexible; moreover, it can be manipulated with
-   other tools such as <filename>tar</filename>.
+   other tools such as <command>tar</command>.
   </para>
 
   <para>
-   While running <command>pg_dump</command>, one should examine the
+   While running <application>pg_dump</application>, one should examine the
    output for any warnings (printed on standard error), especially in
    light of the limitations listed below.
   </para>
@@ -198,7 +190,7 @@ PostgreSQL documentation
 	<replaceable>table</replaceable>
 	(<replaceable>column</replaceable>, ...) VALUES
 	...</literal>).  This will make restoration very slow,
-	but it is necessary if you desire to rearrange column ordering.
+	but it is necessary if you desire to rearrange the column ordering.
        </para>
       </listitem>
      </varlistentry>
@@ -224,7 +216,7 @@ PostgreSQL documentation
 
        <variablelist>
         <varlistentry>
-         <term>p</term>
+         <term><literal>p</></term>
          <listitem>
           <para>
            Output a plain-text <acronym>SQL</acronym> script file (default)
@@ -233,10 +225,10 @@ PostgreSQL documentation
         </varlistentry>
 
         <varlistentry>
-         <term>t</term>
+         <term><literal>t</></term>
          <listitem>
           <para>
-         Output a <filename>tar</filename> archive suitable for input into 
+         Output a <command>tar</command> archive suitable for input into 
          <application>pg_restore</application>. Using this archive format 
          allows reordering and/or exclusion of schema elements 
          at the time the database is restored. It is also possible to limit 
@@ -246,7 +238,7 @@ PostgreSQL documentation
         </varlistentry>
 
         <varlistentry>
-         <term>c</term>
+         <term><literal>c</></term>
          <listitem>
           <para>
          Output a custom archive suitable for input into 
@@ -514,8 +506,9 @@ PostgreSQL documentation
       <term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
       <listitem>
        <para>
-	Specify the compression level to use in archive formats that support 
-      compression (currently only the custom archive format supports compression).
+	Specify the compression level to use in archive formats that
+	support compression.  (Currently only the custom archive
+	format supports compression.)
        </para>
       </listitem>
      </varlistentry>
@@ -531,9 +524,11 @@ PostgreSQL documentation
       <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
       <listitem>
        <para>
-	Specifies the host name of the machine on which the server is
-	running.  If the host name begins with a slash, it is used as the
-	directory for the Unix domain socket.
+        Specifies the host name of the machine on which the server is
+        running.  If the value begins with a slash, it is used as the
+        directory for the Unix domain socket. The default is taken
+        from the <envar>PGHOST</envar> environment variable, if set,
+        else a Unix domain socket connection is attempted.
        </para>
       </listitem>
      </varlistentry>
@@ -543,11 +538,10 @@ PostgreSQL documentation
       <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket file 
-	extension on which the server
-	is listening for connections.  The port number defaults to 5432,
-	or the value of the <envar>PGPORT</envar>
-	environment variable (if set).
+	Specifies the TCP port or local Unix domain socket file
+	extension on which the server is listening for connections.
+	Defaults to the <envar>PGPORT</envar> environment variable, if
+	set, or a compiled-in default.
        </para>
       </listitem>
      </varlistentry>
@@ -596,42 +590,13 @@ PostgreSQL documentation
  <refsect1 id="app-pgdump-diagnostics">
   <title>Diagnostics</title>
 
-  <msgset>
-   <msgentry>
-    <msg>
-     <msgmain>
-      <msgtext>
-<screen>
-Connection to database 'template1' failed.
-connectDBStart() -- connect() failed: No such file or directory
-        Is the postmaster running locally
-        and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
-</screen>
-      </msgtext>
-     </msgmain> 
-    </msg>
-
-    <msgexplan>
-       <para>
-	<application>pg_dump</application> could not connect to the
-	PostgreSQL server on the specified host and port.  If you see this
-	message, ensure that the server is running on the proper host and
-	that you have specified the proper port.
-       </para>
-    </msgexplan>
-   </msgentry>
-
-  </msgset>
-
-   <note>
-    <para>
-     <application>pg_dump</application> internally executes
-     <command>SELECT</command> statements. If you have problems running
-     <application>pg_dump</application>,
-     make sure you are able to select information from the database using, for
-     example, <xref linkend="app-psql">.
-    </para>
-   </note>
+  <para>
+   <application>pg_dump</application> internally executes
+   <command>SELECT</command> statements. If you have problems running
+   <application>pg_dump</application>, make sure you are able to
+   select information from the database using, for example, <xref
+   linkend="app-psql">.
+  </para>
  </refsect1>
 
 
@@ -639,11 +604,11 @@ connectDBStart() -- connect() failed: No such file or directory
   <title>Notes</title>
 
   <para>
-   If your installation has any local additions to the template1 database,
+   If your database cluster has any local additions to the <literal>template1</> database,
    be careful to restore the output of <application>pg_dump</application> into a
    truly empty database; otherwise you are likely to get errors due to
    duplicate definitions of the added objects.  To make an empty database
-   without any local additions, copy from template0 not template1,
+   without any local additions, copy from <literal>template0</> not <literal>template1</>,
    for example:
 <programlisting>
 CREATE DATABASE foo WITH TEMPLATE template0;
@@ -657,17 +622,20 @@ CREATE DATABASE foo WITH TEMPLATE template0;
     <listitem>
      <para>
       When dumping a single table or as plain text, <application>pg_dump</application> 
-      does not handle large objects. Large objects must be dumped in their
-      entirety using one of the binary archive formats.
+      does not handle large objects. Large objects must be dumped with the
+      entire database using one of the non-text archive formats.
      </para>
     </listitem>
 
     <listitem>
      <para>
-      When doing a data-only dump, <application>pg_dump</application> emits queries
-      to disable triggers on user tables before inserting the data and queries to
-      re-enable them after the data has been inserted.  If the restore is stopped
-      in the middle, the system catalogs may be left in the wrong state.
+      When a data-only dump is chosen and the option
+      <option>--disable-triggers</> is used,
+      <application>pg_dump</application> emits commands to disable
+      triggers on user tables before inserting the data and commands
+      to re-enable them after the data has been inserted.  If the
+      restore is stopped in the middle, the system catalogs may be
+      left in the wrong state.
      </para>
     </listitem>
 
@@ -732,9 +700,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
 
   <para>
    The <application>pg_dump</application> utility first appeared in
-   <application>Postgres95</application> release <literal>0.02</literal>.  The
+   <application>Postgres95</application> release 0.02.  The
    non-plain-text output formats were introduced in
-   <application>PostgreSQL</application> release <literal>7.1</literal>.
+   <application>PostgreSQL</application> release 7.1.
   </para>
  </refsect1>
 

doc/src/sgml/ref/pg_dumpall.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.37 2003/03/18 00:02:11 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.38 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,7 +18,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_dumpall</command>
-   <arg rep="repeat"><replaceable>options</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -63,8 +63,8 @@ PostgreSQL documentation
   </para>
 
   <para>
-  <application>pg_dumpall</application> might need to connect several
-  times to the <productname>PostgreSQL</productname> server, asking for
+  <application>pg_dumpall</application> needs to connect several
+  times to the <productname>PostgreSQL</productname> server and might be asking for
   a password each time. It is convenient to have a
   <filename>$HOME/.pgpass</> file in such cases.
   </para>
@@ -96,7 +96,7 @@ PostgreSQL documentation
        <para>
 	Dump data as <command>INSERT</command> commands (rather
 	than <command>COPY</command>). This will make restoration very
-	slow, but it makes the output more portable to other RDBMS
+	slow, but it makes the output more portable to other SQL database
 	packages.
        </para>
       </listitem>
@@ -184,10 +184,10 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Specifies the host name of the machine on which the database
-	server is running.  If host begins with a slash, it is used as
-	the directory for the Unix domain socket.  The default is
-	taken from the <envar>PGHOST</envar> environment variable, if
-	set, else a Unix domain socket connection is attempted.
+	server is running.  If the value begins with a slash, it is
+	used as the directory for the Unix domain socket.  The default
+	is taken from the <envar>PGHOST</envar> environment variable,
+	if set, else a Unix domain socket connection is attempted.
        </para>
       </listitem>
      </varlistentry>
@@ -196,9 +196,10 @@ PostgreSQL documentation
       <term>-p <replaceable>port</replaceable></term>
       <listitem>
        <para>
-        The port number on which the server is listening.  Defaults to
-        the <envar>PGPORT</envar> environment variable, if set, or a
-        compiled-in default.
+	Specifies the TCP port or local Unix domain socket file
+	extension on which the server is listening for connections.
+	Defaults to the <envar>PGPORT</envar> environment variable, if
+	set, or a compiled-in default.
        </para>
       </listitem>
      </varlistentry>
@@ -237,7 +238,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Default connection parameters.
+      Default connection parameters
      </para>
     </listitem>
    </varlistentry>
@@ -254,18 +255,10 @@ PostgreSQL documentation
    messages will refer to <application>pg_dump</application>.
   </para>
 
-  <para>
-   <application>pg_dumpall</application> will need to connect several
-   times to the <productname>PostgreSQL</productname> server.  If password
-   authentication is configured, it will ask for a password each time. In
-   that case it would be convenient to set up a <filename>.pgpass</> 
-   password file.
-  </para>
-
   <para>
    Once restored, it is wise to run <command>ANALYZE</> on each
    database so the optimizer has useful statistics. You
-   can also run <command>vacuumdb -a -z</> to <command>ANALYZE</> all
+   can also run <command>vacuumdb -a -z</> to analyze all
    databases.
   </para>
 

doc/src/sgml/ref/pg_resetxlog.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.6 2002/10/02 21:30:13 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -12,7 +12,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_resetxlog</refname>
-  <refpurpose>reset write-ahead log and pg_control contents</refpurpose>
+  <refpurpose>reset the write-ahead log and other control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -30,25 +30,24 @@ PostgreSQL documentation
  <refsect1 id="R1-APP-PGRESETXLOG-1">
   <title>Description</title>
   <para>
-   <command>pg_resetxlog</command> clears the write-ahead log and
-   optionally resets some fields in the <filename>pg_control</> file.  This
-   function is sometimes 
-   needed if these files have become corrupted.
-   It should be used only as a last resort,
-   when the server will not start due to such corruption.
+   <command>pg_resetxlog</command> clears the write-ahead log (WAL) and
+   optionally resets some other control information (stored in the
+   <filename>pg_control</> file).  This function is sometimes needed
+   if these files have become corrupted.  It should be used only as a
+   last resort, when the server will not start due to such corruption.
   </para>
 
   <para>
    After running this command, it should be possible to start the server,
    but bear in mind that the database may contain inconsistent data due to
    partially-committed transactions.  You should immediately dump your data,
-   run <application>initdb</>, and reload.  After reload, check for
+   run <command>initdb</>, and reload.  After reload, check for
    inconsistencies and repair as needed.
   </para>
 
   <para>
    This utility can only be run by the user who installed the server, because
-   it requires read/write access to the <literal>datadir</>.
+   it requires read/write access to the data directory.
    For safety reasons, you must specify the data directory on the command line.
    <command>pg_resetxlog</command> does not use the environment variable
    <envar>PGDATA</>.
@@ -64,12 +63,12 @@ PostgreSQL documentation
    The first three of these can be set using the switches discussed below.
    <command>pg_resetxlog</command>'s own environment is the source for its
    guess at the locale fields; take care that <envar>LANG</> and so forth
-   match the environment that <application>initdb</> was run in.
+   match the environment that <command>initdb</> was run in.
    If you are not able to determine correct values for all these fields,
    <literal>-f</> can still be used, but
    the recovered database must be treated with even more suspicion than
-   usual --- an immediate dump and reload is imperative.  <emphasis>Do not</>
-   execute any data-modifying operations in the database before you dump,
+   usual: an immediate dump and reload is imperative.  <emphasis>Do not</>
+   execute any data-modifying operations in the database before you dump;
    as any such action is likely to make the corruption worse.
   </para>
 
@@ -79,8 +78,8 @@ PostgreSQL documentation
    be set manually.  These are only needed when
    <command>pg_resetxlog</command> is unable to determine appropriate values
    by reading <filename>pg_control</>.  A safe value for the
-   next transaction ID may be determined by looking for the largest
-   file name in <envar>$PGDATA</><filename>/pg_clog</>, adding one,
+   next transaction ID may be determined by looking for the numerically largest
+   file name in the directory <filename>pg_clog</> under the data directory, adding one,
    and then multiplying by 1048576.  Note that the file names are in
    hexadecimal.  It is usually easiest to specify the switch value in
    hexadecimal too. For example, if <filename>0011</> is the largest entry
@@ -88,7 +87,7 @@ PostgreSQL documentation
    zeroes provide the proper multiplier).
    The WAL starting address should be
    larger than any file number currently existing in
-   <envar>$PGDATA</><filename>/pg_xlog</>.  These also are in hex, and
+   the directory <filename>pg_xlog</> under the data directory.  The addresses are also in hexadecimal and
    have two parts.   For example, if <filename>000000FF0000003A</> is the
    largest entry in <filename>pg_xlog</>, <literal>-l 0xFF,0x3B</> will work.
    There is no comparably easy way to determine a next OID that's beyond
@@ -109,14 +108,14 @@ PostgreSQL documentation
   <title>Notes</title>
 
   <para>
-   This command must not be used when the <application>postmaster</> is 
+   This command must not be used when the server is 
    running.  <command>pg_resetxlog</command> will refuse to start up if
-   it finds a postmaster lock file in the <literal>datadir</>.  If the
-   <application>postmaster</> crashed then a lock file may have been left
+   it finds a server lock file in the data directory.  If the
+   server crashed then a lock file may have been left
    behind; in that case you can remove the lock file to allow
    <command>pg_resetxlog</command> to run.  But before you do
    so, make doubly certain that there
-   is no postmaster nor any backend server process still alive.
+   is no <command>postmaster</command> nor any backend server process still alive.
   </para>
  </refsect1>
 

doc/src/sgml/ref/pg_restore.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.36 2003/03/18 00:02:11 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.37 2003/03/24 14:32:51 petere Exp $ -->
 
 <refentry id="APP-PGRESTORE">
- <docinfo>
-  <date>2001-03-06</date>
- </docinfo>
-
  <refmeta>
   <refentrytitle>pg_restore</refentrytitle>
   <manvolnum>1</manvolnum>
@@ -22,7 +18,8 @@
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_restore</command>
-   <arg rep="repeat"><replaceable>options</replaceable></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
+   <arg><replaceable>filename</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -34,36 +31,31 @@
    <application>pg_restore</application> is a utility for restoring a
    <productname>PostgreSQL</productname> database from an archive
    created by <xref linkend="app-pgdump"> in one of the non-plain-text
-   formats.  It
-   will issue the commands necessary to re-generate all user-defined
-   types, functions, tables, indexes, aggregates, and operators, as
-   well as the data in the tables.
-  </para>
-
-  <para>
-   The archive files contain information for
-   <application>pg_restore</application> to rebuild the database, but also
-   allow <application>pg_restore</application> to be selective about what is
-   restored, or even to reorder the items prior to being restored. The
-   archive files are designed to be portable across architectures.
+   formats.  It will issue the commands necessary to reconstruct the
+   database to the state it was in at the time it was saved.  The
+   archive files also allow <application>pg_restore</application> to
+   be selective about what is restored, or even to reorder the items
+   prior to being restored. The archive files are designed to be
+   portable across architectures.
   </para>
 
   <para>
-   <application>pg_restore</application> can operate in two modes:  If a
-   database name is specified, the archive is restored directly into
-   the database.  Otherwise, a script containing the SQL commands
-   necessary to rebuild the database is created (and written to a file
-   or standard output), similar to the ones created by the
-   <application>pg_dump</application> plain text format.  Some of the options
-   controlling the script output are therefore analogous to
+   <application>pg_restore</application> can operate in two modes: If
+   a database name is specified, the archive is restored directly into
+   the database.  Large objects can only be restored by using a direct
+   database connection.  Otherwise, a script containing the SQL
+   commands necessary to rebuild the database is created (and written
+   to a file or standard output), similar to the ones created by the
+   <application>pg_dump</application> plain text format.  Some of the
+   options controlling the script output are therefore analogous to
    <application>pg_dump</application> options.
   </para>
 
   <para>
    Obviously, <application>pg_restore</application> cannot restore information
-   that is not present in the archive file; for instance, if the
+   that is not present in the archive file.  For instance, if the
    archive was made using the <quote>dump data as
-   <command>INSERT</command>s</quote> option,
+   <command>INSERT</command> commands</quote> option,
    <application>pg_restore</application> will not be able to load the data
    using <command>COPY</command> statements.
   </para>
@@ -73,12 +65,12 @@
   <title>Options</title>
 
    <para>
-    <command>pg_restore</command> accepts the following command
+    <application>pg_restore</application> accepts the following command
     line arguments.
 
     <variablelist>
      <varlistentry>
-      <term><replaceable class="parameter">archive-name</replaceable></term>
+      <term><replaceable class="parameter">filename</replaceable></term>
       <listitem>
        <para>
        Specifies the location of the archive file to be restored.
@@ -92,7 +84,7 @@
       <term><option>--data-only</option></term>
       <listitem>
        <para>
-	Restore only the data, no schema (definitions).
+	Restore only the data, not the schema (data definitions).
        </para>
       </listitem>
      </varlistentry>
@@ -113,7 +105,7 @@
       <listitem>
        <para>
         Create the database before restoring into it.  (When this
-        switch appears, the database named with <option>-d</option> is
+        option is used, the database named with <option>-d</option> is
         used only to issue the initial <literal>CREATE DATABASE</>
         command.  All data is restored into the database name that
         appears in the archive.)
@@ -128,8 +120,7 @@
        <para>
         Connect to database <replaceable
         class="parameter">dbname</replaceable> and restore directly
-        into the database. Large objects can only be restored by using
-        a direct database connection.
+        into the database.
        </para>
       </listitem>
      </varlistentry>
@@ -155,14 +146,13 @@
 	the format, since <application>pg_restore</application> will
 	determine the format automatically. If specified, it can be
 	one of the following:
-       </para>
 
        <variablelist>
         <varlistentry>
-         <term>t</term>
+         <term><literal>t</></term>
          <listitem>
           <para>
-           Archive is a <filename>tar</filename> archive. Using this
+           The archive is a <command>tar</command> archive. Using this
            archive format allows reordering and/or exclusion of schema
            elements at the time the database is restored. It is also
            possible to limit which data is reloaded at restore time.
@@ -171,10 +161,10 @@
         </varlistentry>
 
         <varlistentry>
-         <term>c</term>
+         <term><literal>c</></term>
          <listitem>
           <para>
-           Archive is in the custom format of
+           The archive is in the custom format of
            <application>pg_dump</application>. This is the most
            flexible format in that it allows reordering of data load
            as well as schema elements.  This format is also compressed
@@ -183,6 +173,7 @@
          </listitem>
         </varlistentry>
        </variablelist>
+       </para>
       </listitem>
      </varlistentry>
 
@@ -201,8 +192,7 @@
       <term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
       <listitem>
        <para>
-	Restore definition for named <replaceable
-	class="parameter">index</replaceable> only.
+	Restore definition of named index only.
        </para>
       </listitem>
      </varlistentry>
@@ -212,7 +202,7 @@
       <term><option>--list</option></term>
       <listitem>
        <para>
-        List the contents of the archive. The output of this command
+        List the contents of the archive. The output of this operation
         can be used with the <option>-L</option> option to restrict
         and reorder the items that are restored.
        </para>
@@ -228,7 +218,7 @@
         CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
         order they appear in the file. Lines can be moved and may also
         be commented out by placing a <literal>;</literal> at the
-        start of the line.
+        start of the line.  (See below for examples.)
        </para>
       </listitem>
      </varlistentry>
@@ -268,7 +258,8 @@
        <para>
         Prevent any attempt to restore original object
         ownership. Objects will be owned by the user name used to
-        attach to the database.
+        attach to the database. See also under <option>-R</option> and
+        <option>-X use-set-session-authorization</option>.
        </para>
       </listitem>
      </varlistentry>
@@ -278,7 +269,7 @@
       <term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
       <listitem>
        <para>
-        Specify a procedure or function to be restored.
+        Restore the named function only.
        </para>
       </listitem>
      </varlistentry>
@@ -327,7 +318,8 @@
       <term><option>--schema-only</option></term>
       <listitem>
        <para>
-	Restore the schema (definitions), no data. Sequence values will be reset.
+        Restore only the schema (data defintions), not the data.
+        Sequence values will be reset.
        </para>
       </listitem>
      </varlistentry>
@@ -348,7 +340,7 @@
       <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
       <listitem>
        <para>
-	Restore schema/data for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> only.
+        Restore definition and/or data of named table only.
        </para>
       </listitem>
      </varlistentry>
@@ -358,7 +350,7 @@
       <term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
       <listitem>
        <para>
-	  Restore definition of <REPLACEABLE CLASS="PARAMETER">trigger</REPLACEABLE> only.
+        Restore named trigger only.
        </para>
       </listitem>
      </varlistentry>
@@ -431,7 +423,7 @@
    </para>
 
    <para>
-    <command>pg_restore</command> also accepts
+    <application>pg_restore</application> also accepts
     the following command line arguments for connection parameters:
 
     <variablelist>
@@ -441,8 +433,10 @@
       <listitem>
        <para>
 	Specifies the host name of the machine on which the server is
-	running.  If host begins with a slash, it is used as the
-	directory for the Unix domain socket.
+	running.  If the value begins with a slash, it is used as the
+	directory for the Unix domain socket. The default is taken
+	from the <envar>PGHOST</envar> environment variable, if set,
+	else a Unix domain socket connection is attempted.
        </para>
       </listitem>
      </varlistentry>
@@ -452,11 +446,11 @@
       <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket
-	file extension on which the server is listening for
-	connections.  The port number defaults to 5432, or the value
-	of the <envar>PGPORT</envar> environment variable (if set).
-       </para>
+	Specifies the TCP port or local Unix domain socket file
+	extension on which the server is listening for connections.
+	Defaults to the <envar>PGPORT</envar> environment variable, if
+	set, or a compiled-in default.
+        </para>
       </listitem>
      </varlistentry>
 
@@ -494,7 +488,7 @@
 
     <listitem>
      <para>
-      Default connection parameters.
+      Default connection parameters
      </para>
     </listitem>
    </varlistentry>
@@ -505,45 +499,14 @@
  <refsect1 id="app-pgrestore-diagnostics">
   <title>Diagnostics</title>
 
-  <msgset>
-   <msgentry>
-    <msg>
-     <msgmain>
-      <msgtext>
-<screen>
-Connection to database 'template1' failed.
-connectDBStart() -- connect() failed: No such file or directory
-        Is the postmaster running locally
-        and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
-</screen>
-      </msgtext>
-     </msgmain>
-    </msg>
-
-    <msgexplan>
-       <para>
-	<application>pg_restore</application> could not attach to the
-        <productname>PostgreSQL</> server process on the specified
-        host and port.  If you see this message, ensure that the
-        server is running on the proper host and that you have
-        specified the proper port.  If your site uses an
-        authentication system, ensure that you have obtained the
-        required authentication credentials.
-       </para>
-    </msgexplan>
-   </msgentry>
-  </msgset>  
-
-   <note>
-    <para>
-     When a direct database connection is specified using the -d
-     option, <application>pg_restore</application> internally executes
-     <acronym>SQL</acronym> statements. If you have problems running
-     <application>pg_restore</application>, make sure you are able to select
-     information from the database using, for example,
-     <application>psql</application>.
-    </para>
-   </note>
+  <para>
+   When a direct database connection is specified using the
+   <option>-d</option> option, <application>pg_restore</application>
+   internally executes <acronym>SQL</acronym> statements. If you have
+   problems running <application>pg_restore</application>, make sure
+   you are able to select information from the database using, for
+   example, <application>psql</application>.
+  </para>
  </refsect1>
 
 
@@ -556,9 +519,9 @@ connectDBStart() -- connect() failed: No such file or directory
    <application>pg_restore</application> into a truly empty database;
    otherwise you are likely to get errors due to duplicate definitions
    of the added objects.  To make an empty database without any local
-   additions, copy from template0 not template1, for example:
+   additions, copy from <literal>template0</> not <literal>template1</>, for example:
 <programlisting>
-CREATE DATABASE foo WITH TEMPLATE = template0;
+CREATE DATABASE foo WITH TEMPLATE template0;
 </programlisting>
   </para>
 
@@ -568,8 +531,10 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
    <itemizedlist>
     <listitem>
      <para>
-      When restoring data to a pre-existing table, <application>pg_restore</application> emits queries
-      to disable triggers on user tables before inserting the data then emits queries to
+      When restoring data to a pre-existing table and the option
+      <option>--disable-triggers</> is used,
+      <application>pg_restore</application> emits commands
+      to disable triggers on user tables before inserting the data then emits commands to
       re-enable them after the data has been inserted.  If the restore is stopped in the
       middle, the system catalogs may be left in the wrong state.
      </para>
@@ -601,20 +566,6 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
  <refsect1 id="app-pgrestore-examples">
   <title>Examples</title>
 
-  <para>
-   To dump a database:
-<screen>
-<prompt>$</prompt> <userinput>pg_dump mydb &gt; db.out</userinput>
-</screen>
-  </para>
-
-  <para>
-   To reload this database:
-<screen>
-<prompt>$</prompt> <userinput>psql -d database -f db.out</userinput>
-</screen>
-  </para>
-
   <para>
    To dump a database called <literal>mydb</> that contains
    large objects to a <filename>tar</filename> file:
@@ -665,7 +616,7 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
 12; 145443 TABLE hs_old postgres
 13; 145443 ACL hs_old
 </programlisting>
-   Semi-colons are comment delimiters, and the numbers at the start of lines refer to the
+   Semicolons start a comment, and the numbers at the start of lines refer to the
    internal archive ID assigned to each item.
   </para>
 
@@ -678,8 +629,8 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
 6; 145402 TABLE species_records postgres
 ;8; 145416 TABLE ss_old postgres
 </programlisting>
-   could be used as input to <command>pg_restore</command> and would only restore
-   items 10 and 6, in that order.
+   could be used as input to <application>pg_restore</application> and would only restore
+   items 10 and 6, in that order:
 <screen>
 <prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
 </screen>

doc/src/sgml/ref/pgtclsh.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtclsh.sgml,v 1.6 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtclsh.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pgtclsh</command>
-   <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>arguments</replaceable></arg></arg>
+   <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 

doc/src/sgml/ref/pgtksh.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtksh.sgml,v 1.6 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtksh.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -20,7 +20,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pgtksh</command>
-   <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>arguments</replaceable></arg></arg>
+   <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 

doc/src/sgml/ref/postgres-ref.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.30 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.31 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -62,7 +62,7 @@ PostgreSQL documentation
     <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
    </group>
    <arg>-S <replaceable>sort-mem</replaceable></arg>
-   <arg>-v <replaceable>protocol-version</replaceable></arg>
+   <arg>-v <replaceable>protocol</replaceable></arg>
    <arg>-W <replaceable>seconds</replaceable></arg>
    <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   </cmdsynopsis>
@@ -72,7 +72,7 @@ PostgreSQL documentation
   <title>Description</title>
 
   <para>
-   The <filename>postgres</filename> executable is the actual
+   The <command>postgres</command> executable is the actual
    <productname>PostgreSQL</productname> server process that processes
    queries.  It is normally not called directly; instead a <xref
    linkend="app-postmaster"> multiuser server is started.
@@ -80,7 +80,7 @@ PostgreSQL documentation
 
   <para>
    The second form above is how
-   <application>postgres</application> is invoked by the <xref
+   <command>postgres</command> is invoked by the <xref
    linkend="app-postmaster"> (only
    conceptually, since both <filename>postmaster</filename> and
    <filename>postgres</filename> are in fact the same program); it
@@ -94,15 +94,15 @@ PostgreSQL documentation
    When invoked in interactive mode from the shell, the user can enter
    queries and the results will be printed to the screen, but in a
    form that is more useful for developers than end users.  But note
-   that running a single-user backend is not truly suitable for
+   that running a single-user server is not truly suitable for
    debugging the server since no realistic interprocess communication
    and locking will happen.
   </para>
 
   <para>
-   When running a stand-alone backend, the session user will be set to
+   When running a stand-alone server, the session user will be set to
    the user with ID 1.  This user does not actually have to exist, so
-   a stand-alone backend can be used to manually recover from certain
+   a stand-alone server can be used to manually recover from certain
    kinds of accidental damage to the system catalogs.  Implicit
    superuser powers are granted to the user with ID 1 in stand-alone
    mode.
@@ -113,11 +113,11 @@ PostgreSQL documentation
   <title>Options</title>
 
    <para>
-    When <application>postgres</application> is started by a <xref
+    When <command>postgres</command> is started by a <xref
     linkend="app-postmaster"> then it
     inherits all options set by the latter.  Additionally,
-    <application>postgres</application>-specific options can be passed
-    from the <application>postmaster</application> with the
+    <command>postgres</command>-specific options can be passed
+    from the <command>postmaster</command> with the
     <option>-o</option> switch.
    </para>
 
@@ -129,7 +129,7 @@ PostgreSQL documentation
     variable <envar>PGOPTIONS</envar> is set, then
     <application>libpq</>-based clients will pass that string to the
     server, which will interpret it as
-    <application>postgres</application> command-line options.
+    <command>postgres</command> command-line options.
    </para>
 
    <refsect2>
@@ -138,10 +138,10 @@ PostgreSQL documentation
     <para>
      The options <option>-A</option>, <option>-B</option>,
      <option>-c</option>, <option>-d</option>, <option>-D</option>,
-     <option>-F</option>, and <option>--name</> have the same meanings
+     <option>-F</option>, and <option>--<replaceable>name</></option> have the same meanings
      as the <xref linkend="app-postmaster"> except that
-     <option>-d</option> <literal>0</> prevents the debugging level of
-     the postmaster from being propagated to the backend.
+     <literal>-d 0</> prevents the server log level of
+     the <command>postmaster</> from being propagated to <command>postgres</>.
     </para>
 
     <variablelist>
@@ -162,12 +162,12 @@ PostgreSQL documentation
       <term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
       <listitem>
        <para>
-	Sends all debugging and error output to 
+	Send all server log output to 
 	<replaceable class="parameter">filename</replaceable>.
-	If the backend is running under the
-	<application>postmaster</application>, this option is ignored,
+	If <command>postgres</command> is running under the
+	<command>postmaster</command>, this option is ignored,
 	and the <systemitem>stderr</> inherited from the
-	<application>postmaster</application> is used.
+	<command>postmaster</command> is used.
        </para>
       </listitem>
      </varlistentry>
@@ -176,7 +176,7 @@ PostgreSQL documentation
       <term><option>-P</option></term>
       <listitem>
        <para>
-	Ignore system indexes while scanning/updating system tuples. The
+	Ignore system indexes while scanning/updating system tables. The
 	<command>REINDEX</command> command for system tables/indexes
 	requires this option to be used.
        </para>
@@ -187,7 +187,7 @@ PostgreSQL documentation
       <term><option>-s</option></term>
       <listitem>
        <para>
-	Print time information and other statistics at the end of each query.
+	Print time information and other statistics at the end of each command.
 	This is useful for benchmarking or for use in tuning the number of
 	buffers.
        </para>
@@ -200,7 +200,7 @@ PostgreSQL documentation
        <para>
 	Specifies the amount of memory to be used by internal sorts and hashes
 	before resorting to temporary disk files.  The value is specified in
-	kilobytes, and defaults to 512 kilobytes.  Note that for a complex query,
+	kilobytes, and defaults to 1024.  Note that for a complex query,
 	several sorts and/or hashes might be running in parallel, and each one
 	will be allowed to use as much as
 	<replaceable class="parameter">sort-mem</replaceable> kilobytes
@@ -230,7 +230,7 @@ PostgreSQL documentation
       <term><option>-E</option></term>
       <listitem>
        <para>
-	Echo all queries.
+	Echo all commands.
        </para>
       </listitem>
      </varlistentry>
@@ -239,7 +239,7 @@ PostgreSQL documentation
       <term><option>-N</option></term>
       <listitem>
        <para>
-	Disables use of newline as a query delimiter.
+	Disables use of newline as a statement delimiter.
        </para>
       </listitem>
      </varlistentry>
@@ -268,6 +268,7 @@ PostgreSQL documentation
 	disable sequential and index scans respectively, while
 	<literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
 	disable nested-loop, merge and hash joins respectively.
+       </para>
 	
 	<note>
 	 <para>
@@ -277,7 +278,6 @@ PostgreSQL documentation
 	  plan types if it has any other alternative.
 	 </para>
 	</note>
-       </para>
       </listitem>
      </varlistentry>
 
@@ -295,7 +295,7 @@ PostgreSQL documentation
       <listitem>
        <para>
 	Allows the structure of system tables to be modified.  This is
-	used by <application>initdb</application>.
+	used by <command>initdb</command>.
        </para>
       </listitem>
      </varlistentry>
@@ -304,9 +304,8 @@ PostgreSQL documentation
       <term><option>-p</option> <replaceable class="parameter">database</replaceable></term>
       <listitem>
        <para>
-	Indicates that this server has been started by a
-	<application>postmaster</application> and makes different
-	assumptions about buffer pool management, file descriptors,
+	Indicates that this process has been started by a
+	<command>postmaster</command> and specifies the database to use.
 	etc.
        </para>
       </listitem>
@@ -339,7 +338,7 @@ PostgreSQL documentation
        <para>
 	As soon as this option is encountered, the process sleeps for
 	the specified amount of seconds.  This gives developers time
-	to attach a debugger to the backend process.
+	to attach a debugger to the server process.
        </para>
       </listitem>
      </varlistentry>
@@ -375,10 +374,10 @@ PostgreSQL documentation
 
   <para>
    To stop a running query use the <literal>SIGINT</literal> signal. To
-   tell <application>postgres</application> to reread the config file,
+   tell <command>postgres</command> to reread the configuration file,
    use a <literal>SIGHUP</literal> signal. The
-   <application>postmaster</application> uses <literal>SIGTERM</literal>
-   to tell a postgres process to quit normally and
+   <command>postmaster</command> uses <literal>SIGTERM</literal>
+   to tell a <command>postgres</command> process to quit normally and
    <literal>SIGQUIT</literal> to terminate without the normal cleanup.
    These <emphasis>should not</emphasis> be used by users.
   </para>
@@ -389,17 +388,17 @@ PostgreSQL documentation
   <title>Usage</title>
 
    <para>
-    Start a stand-alone backend with a command like
+    Start a stand-alone server with a command like
 <screen>
-<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
+<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
 </screen>
-    Provide the correct path to the database area with <option>-D</>, or
+    Provide the correct path to the database directory with <option>-D</>, or
     make sure that the environment variable <envar>PGDATA</> is set.
     Also specify the name of the particular database you want to work in.
    </para>
 
    <para>
-    Normally, the stand-alone backend treats newline as the command
+    Normally, the stand-alone server treats newline as the command
     entry terminator; there is no intelligence about semicolons,
     as there is in <application>psql</>.  To continue a command
     across multiple lines, you must type backslash just before each
@@ -408,9 +407,9 @@ PostgreSQL documentation
 
    <para>
     But if you use the <option>-N</> command line switch, then newline does
-    not terminate command entry.  The backend will read the standard input
+    not terminate command entry.  In this case, the server will read the standard input
     until the end-of-file (<acronym>EOF</>) marker, then
-    process the input as a single query string.  Backslash-newline is not
+    process the input as a single command string.  Backslash-newline is not
     treated specially in this case.
    </para>
 
@@ -422,7 +421,7 @@ PostgreSQL documentation
    </para>
 
    <para>
-    Note that the stand-alone backend does not provide sophisticated
+    Note that the stand-alone server does not provide sophisticated
     line-editing features (no command history, for example).
    </para>
 

doc/src/sgml/ref/postmaster.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.34 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.35 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -41,33 +41,33 @@ PostgreSQL documentation
   <title>Description</title>
 
   <para>
-   <application>postmaster</application> is the
+   <command>postmaster</command> is the
    <productname>PostgreSQL</productname> multiuser database server.
    In order for a client application to access a database it connects
    (over a network or locally) to a running
-   <application>postmaster</application>.  The
-   <application>postmaster</application> then starts a separate server
+   <command>postmaster</command>.  The
+   <command>postmaster</command> then starts a separate server
    process (<quote><xref linkend="app-postgres"></quote>) to handle
-   the connection.  The <application>postmaster</application> also
+   the connection.  The <command>postmaster</command> also
    manages the communication among server processes.
   </para>
 
   <para>
-   By default the <application>postmaster</application> starts in the
-   foreground and prints log messages to the standard output.  In
-   practical applications the <application>postmaster</application>
+   By default the <command>postmaster</command> starts in the
+   foreground and prints log messages to the standard error stream.  In
+   practical applications the <command>postmaster</command>
    should be started as a background process, perhaps at boot time.
   </para>
 
   <para>
-   One <application>postmaster</application> always manages the data
+   One <command>postmaster</command> always manages the data
    from exactly one database cluster.  A database cluster is a
    collection of databases that is stored at a common file system
-   location.  When the postmaster starts it needs to know the location
+   location.  When the <command>postmaster</command> starts it needs to know the location
    of the database cluster files (<quote>data area</quote>).  This is
    done with the <option>-D</option> invocation option or the
    <envar>PGDATA</envar> environment variable; there is no default.
-   More than one postmaster process can run on a system at one time,
+   More than one <command>postmaster</command> process can run on a system at one time,
    as long as they use different data areas and different
    communication ports (see below).  A data area is created with <xref
    linkend="app-initdb">.
@@ -78,17 +78,17 @@ PostgreSQL documentation
   <title>Options</title>
 
    <para>
-    <application>postmaster</application> accepts the following
+    <command>postmaster</command> accepts the following
     command line arguments.  For a detailed discussion of the options
     consult the &cite-admin;.  You can also save typing most of these
     options by setting up a configuration file.
     
     <variablelist>
      <varlistentry>
-      <term>-A 0|1</term>
+      <term><option>-A 0|1</option></term>
       <listitem>
        <para>
-        Enables run-time assert checks, which is a debugging aid to
+        Enables run-time assertion checks, which is a debugging aid to
         detect programming mistakes.  This is only available if it was
         enabled during compilation.  If so, the default is on.
        </para>
@@ -96,7 +96,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-B <replaceable class="parameter">nbuffers</replaceable></term>
+      <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
       <listitem>
        <para>
 	Sets the number of shared buffers for use by the server
@@ -107,7 +107,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+      <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
       <listitem>
        <para>
         Sets a named run-time parameter. Consult the &cite-admin; for
@@ -120,7 +120,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-d <replaceable>debug-level</replaceable></term>
+      <term><option>-d <replaceable>debug-level</replaceable></option></term>
       <listitem>
        <para>
         Sets the debug level.  The higher this value is set, the more
@@ -131,7 +131,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-D <replaceable class="parameter">datadir</replaceable></term>
+      <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
       <listitem>
        <para>
 	Specifies the file system location of the data directory.  See
@@ -141,12 +141,12 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-F</term>
+      <term><option>-F</option></term>
       <listitem>
        <para>
         Disables <function>fsync</function> calls for performance
         improvement, at the risk of data corruption in event of a
-        system crash.  This parameter corresponds to setting
+        system crash.  This option corresponds to setting
         <literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
         documentation before using this!
        </para>
@@ -158,11 +158,11 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-h <replaceable class="parameter">hostname</replaceable></term>
+      <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
       <listitem>
        <para>
-	Specifies the TCP/IP host name or address on which the
-	<application>postmaster</application> is to listen for
+	Specifies the IP host name or address on which the
+	<command>postmaster</command> is to listen for
 	connections from client applications.  Defaults to
 	listening on all configured addresses (including
         <systemitem class="systemname">localhost</systemitem>).
@@ -171,7 +171,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-i</term>
+      <term><option>-i</option></term>
       <listitem>
        <para>
         Allows clients to connect via TCP/IP (Internet domain)
@@ -180,18 +180,18 @@ PostgreSQL documentation
         to setting <literal>tcpip_socket=true</> in <filename>postgresql.conf</>.
        </para>
        <para>
-        <option>--tcpip_socket=false</option> has the opposite
+        <option>--tcpip-socket=false</option> has the opposite
         effect of this option.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-k <replaceable class="parameter">directory</replaceable></term>
+      <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
       <listitem>
        <para>
 	Specifies the directory of the Unix-domain socket on which the
-	<application>postmaster</application> is to listen for
+	<command>postmaster</command> is to listen for
 	connections from client applications.  The default is normally
 	<filename>/tmp</filename>, but can be changed at build time.
        </para>
@@ -199,7 +199,7 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-l</term>
+      <term><option>-l</option></term>
       <listitem>
        <para>
 	Enables secure connections using SSL.  The <option>-i</option>
@@ -210,11 +210,11 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-N <replaceable class="parameter">max-connections</replaceable></term>
+      <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
       <listitem>
        <para>
 	Sets the maximum number of client connections that this
-	<application>postmaster</application> will accept.  By
+	<command>postmaster</command> will accept.  By
 	default, this value is 32, but it can be set as high as your
 	system will support.  (Note that
 	<option>-B</option> is required to be at least twice
@@ -226,13 +226,13 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-o <replaceable class="parameter">extra-options</replaceable></term>
+      <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
       <listitem>
        <para>
 	The command line-style options specified in <replaceable
 	class="parameter">extra-options</replaceable> are passed to
-	all backend server processes started by this
-	<application>postmaster</application>.  See <xref
+	all server processes started by this
+	<command>postmaster</command>.  See <xref
 	linkend="app-postgres"> for possibilities.  If the option
 	string contains any spaces, the entire string must be quoted.
        </para>
@@ -240,11 +240,11 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-p <replaceable class="parameter">port</replaceable></term>
+      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
       <listitem>
        <para>
 	Specifies the TCP/IP port or local Unix domain socket file
-	extension on which the <application>postmaster</application>
+	extension on which the <command>postmaster</command>
 	is to listen for connections from client applications.
 	Defaults to the value of the <envar>PGPORT</envar> environment
 	variable, or if <envar>PGPORT</envar> is not set, then
@@ -257,10 +257,10 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-S</term>
+      <term><option>-S</option></term>
       <listitem>
        <para>
-	Specifies that the <application>postmaster</application>
+	Specifies that the <command>postmaster</command>
 	process should start up in silent mode.  That is, it will
 	disassociate from the user's (controlling) terminal, start its
 	own process group, and redirect its standard output and
@@ -270,17 +270,17 @@ PostgreSQL documentation
         Using this switch discards all logging output, which is
 	probably not what you want, since it makes it very difficult
 	to troubleshoot problems.  See below for a better way to start
-	the <application>postmaster</application> in the background.
+	the <command>postmaster</command> in the background.
        </para>
        <para>
-        <option>--silent_mode=false</option> has the opposite effect
+        <option>--silent-mode=false</option> has the opposite effect
         of this option.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>--<replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+      <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
       <listitem>
        <para>
         Sets a named run-time parameter; a shorter form of
@@ -294,17 +294,18 @@ PostgreSQL documentation
 
    <para>
     Two additional command line options are available for debugging
-    problems that cause a backend to die abnormally.  These options
-    control the behavior of the <application>postmaster</application>
-    in this situation, and <emphasis>neither option is intended for
-    use in ordinary operation</emphasis>.
+    problems that cause a server process to die abnormally.  The
+    ordinary strategy in this situation is to notify all other server
+    processes that they must terminate and then reinitialize the
+    shared memory and semaphores.  This is because an errant server
+    process could have corrupted some shared state before terminating.
+    These options select alternative behaviors of the
+    <command>postmaster</command> in this situation.
+    <emphasis>Neither option is intended for use in ordinary
+    operation.</emphasis>
    </para>
 
    <para>
-    The ordinary strategy for this situation is to notify all other
-    backends that they must terminate and then reinitialize the shared
-    memory and semaphores.  This is because an errant backend could
-    have corrupted some shared state before terminating.
    </para>
 
    <para>
@@ -312,10 +313,10 @@ PostgreSQL documentation
 
     <variablelist>
      <varlistentry>
-      <term>-n</term>
+      <term><option>-n</option></term>
       <listitem>
        <para>
-	<application>postmaster</application>
+	<command>postmaster</command>
 	will not reinitialize shared data structures.  A knowledgeable system
 	programmer can then use a debugger
 	to examine shared memory and semaphore state.
@@ -324,14 +325,14 @@ PostgreSQL documentation
     </varlistentry>
 
     <varlistentry>
-      <term>-s</term>
+      <term><option>-s</option></term>
       <listitem>
        <para>
-	<application>postmaster</application>
-	will stop all other backend processes by sending the signal
+	<command>postmaster</command>
+	will stop all other server processes by sending the signal
 	<literal>SIGSTOP</literal>,
 	but will not cause them to terminate.  This permits system programmers
-	to collect core dumps from all backend processes by hand.
+	to collect core dumps from all server processes by hand.
        </para>
       </listitem>
      </varlistentry>
@@ -367,7 +368,7 @@ PostgreSQL documentation
    </varlistentry>
 
    <varlistentry>
-    <term><envar>PGDATASTYLE</envar></term>
+    <term><envar>PGDATESTYLE</envar></term>
 
     <listitem>
      <para>
@@ -418,22 +419,17 @@ PostgreSQL documentation
 
     <variablelist>
      <varlistentry>
-      <term><computeroutput>
-semget: No space left on device
-       </computeroutput></term>
+      <term><computeroutput>semget: No space left on device</computeroutput></term>
       <listitem>
        <para>
-	If you see this message, you should run the
-	<application>ipcclean</application>
-	command.  After doing so, try starting
-	<application>postmaster</application>
-	again.  If this still doesn't work, you probably need to configure
-	your kernel for shared memory and semaphores as described in the
-	installation notes.  If you run multiple instances of
-	<application>postmaster</application>
+	If you see this message, you probably need to configure
+	your kernel for shared memory and semaphores as described in the &cite-admin;.
+	If you run multiple instances of
+	<command>postmaster</command>
 	on a single host, or have a kernel with particularly small shared memory
 	and/or semaphore limits, you may have to reconfigure your kernel to increase
 	its shared memory or semaphore parameters.
+       </para>
 
 	<tip>
 	 <para>
@@ -444,18 +440,15 @@ semget: No space left on device
 	  consumption.
 	 </para>
 	</tip>
-       </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><computeroutput>
-StreamServerPort: cannot bind to port
-       </computeroutput></term>
+      <term><computeroutput>StreamServerPort: cannot bind to port</computeroutput></term>
       <listitem>
        <para>
 	If you see this message, you should make certain that there is no
-	other <application>postmaster</application>
+	other <command>postmaster</command>
 	process already running on the same port number.  The easiest way to
 	determine this is by using the command
 <screen>
@@ -471,18 +464,18 @@ StreamServerPort: cannot bind to port
        <para>
 	If you 
 	are sure that no other
-	<application>postmaster</application>
+	<command>postmaster</command>
 	processes are running and you still get this error, try specifying a
 	different port using the
 	<literal>-p</literal>
 	option.  You may also get this error if you terminate the
-	<application>postmaster</application>
+	<command>postmaster</command>
 	and immediately restart it using the same port; in this case, you must
 	simply wait a few seconds until the operating system closes the port
 	before trying again.  Finally, you may get this error if you specify
 	a port number that your operating system considers to be reserved.
 	For example, many versions of Unix consider port numbers under 1024 to
-	be <firstterm>trusted</firstterm>
+	be <quote>trusted</quote>
 	and only permit the Unix superuser to access them.
        </para>
       </listitem>
@@ -497,14 +490,14 @@ StreamServerPort: cannot bind to port
   <para>
    If at all possible, <emphasis>do not</emphasis> use
    <literal>SIGKILL</literal> to kill the
-   <application>postmaster</application>.  This will prevent
-   <application>postmaster</application> from freeing the system
+   <command>postmaster</command>.  This will prevent
+   <command>postmaster</command> from freeing the system
    resources (e.g., shared memory and semaphores) that it holds before
    terminating.
   </para>
 
   <para>
-   To terminate the <application>postmaster</application> normally,
+   To terminate the <command>postmaster</command> normally,
    the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>,
    or <literal>SIGQUIT</literal> can be used.  The first will wait for
    all clients to terminate before quitting, the second will
@@ -515,7 +508,7 @@ StreamServerPort: cannot bind to port
 
   <para>
    The utility command <xref linkend="app-pg-ctl"> can be used to
-   start and shut down the <application>postmaster</application>
+   start and shut down the <command>postmaster</command>
    safely and comfortably.
   </para>
 
@@ -532,7 +525,7 @@ StreamServerPort: cannot bind to port
  <refsect1 id="app-postmaster-examples">
   <title>Examples</title>
   <para>
-   To start <application>postmaster</application> in the background
+   To start <command>postmaster</command> in the background
    using default values, type:
 
 <screen>
@@ -541,14 +534,14 @@ StreamServerPort: cannot bind to port
   </para>
 
   <para>
-   To start <application>postmaster</application> with a specific
+   To start <command>postmaster</command> with a specific
    port:
 <screen>
 <prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
 </screen>
-   This command will start up <application>postmaster</application>
+   This command will start up <command>postmaster</command>
    communicating through the port 1234. In order to connect to this
-   <application>postmaster</application> using <application>psql</>, you would need to
+   <command>postmaster</command> using <application>psql</>, you would need to
    run it as
 <screen>
 <prompt>$</prompt> <userinput>psql -p 1234</userinput>

doc/src/sgml/ref/psql-ref.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.85 2003/02/13 05:37:43 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.86 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -20,9 +20,9 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>psql</command>
-   <arg><replaceable class="parameter">options</replaceable></arg>
+   <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
    <arg><replaceable class="parameter">dbname</replaceable>
-   <arg><replaceable class="parameter">user</replaceable></arg></arg>
+   <arg><replaceable class="parameter">username</replaceable></arg></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -69,17 +69,17 @@ PostgreSQL documentation
     </varlistentry>
 	
     <varlistentry>
-      <term><option>-c <replaceable class="parameter">query</replaceable></></term>
-      <term><option>--command <replaceable class="parameter">query</replaceable></></term>
+      <term><option>-c <replaceable class="parameter">command</replaceable></></term>
+      <term><option>--command <replaceable class="parameter">command</replaceable></></term>
       <listitem>
       <para>
       Specifies that <application>psql</application> is to execute one
-      query string, <replaceable class="parameter">query</replaceable>,
+      command string, <replaceable class="parameter">command</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 parsable by the backend (i.e.,
+      <replaceable class="parameter">command</replaceable> must be either
+      a command string that is completely parsable by the server (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>
@@ -108,7 +108,7 @@ PostgreSQL documentation
       <term><option>--echo-queries</></term>
       <listitem>
       <para>
-      Show all queries that are sent to the backend. This is equivalent
+      Show all commands that are sent to the server. This is equivalent
       to setting the variable <varname>ECHO</varname> to
       <literal>queries</literal>.
       </para>
@@ -120,7 +120,7 @@ PostgreSQL documentation
       <term><option>--echo-hidden</></term>
       <listitem>
       <para>
-      Echoes the actual queries generated by \d and other backslash
+      Echo the actual queries generated by <command>\d</command> 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 <varname>ECHO_HIDDEN</varname> from within
@@ -135,7 +135,7 @@ PostgreSQL documentation
       <listitem>
       <para>
       Use the file <replaceable class="parameter">filename</replaceable>
-      as the source of queries instead of reading queries interactively.
+      as the source of commands instead of reading commands interactively.
       After the file is processed, <application>psql</application>
       terminates. This is in many ways equivalent to the internal
       command <command>\i</command>.
@@ -179,7 +179,7 @@ PostgreSQL documentation
       <listitem>
       <para>
       Specifies the host name of the machine on which the
-      <application>postmaster</application> is running. If host begins
+      server is running. If the value begins
       with a slash, it is used as the directory for the Unix-domain
       socket.
       </para>
@@ -191,7 +191,7 @@ PostgreSQL documentation
       <term><option>--html</></term>
       <listitem>
       <para>
-      Turns on <acronym>HTML</acronym> tabular output. This is
+      Turn on <acronym>HTML</acronym> tabular output. This is
       equivalent to <literal>\pset format html</literal> or the
       <command>\H</command> command.
       </para>
@@ -203,7 +203,7 @@ PostgreSQL documentation
       <term><option>--list</></term>
       <listitem>
       <para>
-      Lists all available databases, then exits. Other non-connection
+      List all available databases, then exits. Other non-connection
       options are ignored. This is similar to the internal command
       <command>\list</command>.
       </para>
@@ -227,9 +227,8 @@ PostgreSQL documentation
       <term><option>--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
+      Specifies the TCP port or the local Unix domain
+      socket file extension on which the server 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.
@@ -284,7 +283,7 @@ PostgreSQL documentation
       <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
+      each command is sent to the server, with the option to cancel
       execution as well. Use this to debug scripts.
       </para>
       </listitem>
@@ -295,7 +294,7 @@ PostgreSQL documentation
       <term><option>--single-line</></term>
       <listitem>
       <para>
-      Runs in single-line mode where a newline terminates a query, as a
+      Runs in single-line mode where a newline terminates an SQL command, as a
       semicolon does.
       </para>
 
@@ -345,7 +344,7 @@ PostgreSQL documentation
       <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
+      password because the server requires it are really two different
       things.) You are encouraged to look at the <option>-U</option> and
       <option>-W</option> options instead.
       </para>
@@ -357,7 +356,7 @@ PostgreSQL documentation
       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
       <listitem>
       <para>
-      Connects to the database as the user <replaceable
+      Connect 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> 
@@ -370,7 +369,7 @@ PostgreSQL documentation
       <term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
       <listitem>
       <para>
-      Performs a variable assignment, like the <command>\set</command>
+      Perform 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,
@@ -386,7 +385,7 @@ PostgreSQL documentation
       <term><option>--version</></term>
       <listitem>
       <para>
-      Shows the <application>psql</application> version.
+      Show the <application>psql</application> version.
       </para>
       </listitem>
     </varlistentry>
@@ -404,11 +403,11 @@ PostgreSQL documentation
 
       <para>
       In the current version, <application>psql</application>
-      automatically issues a password prompt whenever the backend
+      automatically issues a password prompt whenever the server
       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
+      issued and the server requires password authentication the
       connection attempt will fail.
       </para>
       </listitem>
@@ -419,7 +418,7 @@ PostgreSQL documentation
       <term><option>--expanded</></term>
       <listitem>
       <para>
-      Turns on extended row format mode. This is equivalent to the
+      Turn on the extended table formatting mode. This is equivalent to the
       command <command>\x</command>.
       </para>
       </listitem>
@@ -440,7 +439,7 @@ PostgreSQL documentation
       <term><option>--help</></term>
       <listitem>
       <para>
-      Shows help about <application>psql</application> command line
+      Show help about <application>psql</application> command line
       arguments.
       </para>
       </listitem>
@@ -455,8 +454,8 @@ PostgreSQL documentation
   <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
+   file not found) occurs, 2 if the connection to the server went bad
+   and the session was not interactive, and 3 if an error occurred in a
    script and the variable <varname>ON_ERROR_STOP</varname> was set.
   </para>
  </refsect1>
@@ -495,13 +494,13 @@ PostgreSQL documentation
 
     <para>
     If the connection could not be made for any reason (e.g., insufficient
-    privileges, postmaster is not running on the server, etc.),
+    privileges, server is not running on the targeted host, etc.),
     <application>psql</application> will return an error and terminate.
     </para>
   </refsect2>
 
   <refsect2 id="R2-APP-PSQL-4">
-    <title>Entering Queries</title>
+    <title>Entering SQL Commands</title>
 
     <para>
     In normal operation, <application>psql</application> provides a
@@ -523,16 +522,16 @@ testdb=>
     </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
+    At the prompt, the user may type in <acronym>SQL</acronym> commands.
+    Ordinarily, input lines are sent to the server when a
+    command-terminating semicolon is reached. An end of line does not
+    terminate a command.  Thus commands can be spread over several lines for
+    clarity. If the command was sent and without error, the results of the command
     are displayed on the screen.
     </para>
 
     <para>
-    Whenever a query is executed, <application>psql</application> also polls
+    Whenever a command 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">.
@@ -586,18 +585,23 @@ testdb=>
     </para>
 
     <para>
-    Some commands take 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, while
-    whitespace within double quotes is included in the argument.
+    Some commands take an <acronym>SQL</acronym> identifier (such as a
+    table name) as argument. These arguments follow the syntax rules
+    of <acronym>SQL</acronym>: Unquoted letters are forced to
+    lowercase, while double quotes (<literal>"</>) protect letters
+    from case conversion and allow incorporation of whitespace into
+    the identifier.  Within double quotes, paired double quotes reduce
+    to a single double quote in the resulting name.  For example,
+    <literal>FOO"BAR"BAZ</> is interpreted as <literal>fooBARbaz</>,
+    and <literal>"A weird"" name"</> becomes <literal>A weird"
+    name</>.
     </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
+    arguments and continues parsing <acronym>SQL</acronym> commands, 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
@@ -612,8 +616,8 @@ testdb=>
         <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
+	If the current table output format is unaligned, it is switched to aligned.
+	If it is not unaligned, it is set to unaligned. This command is
 	kept for backwards compatibility. See <command>\pset</command> for a
 	general solution.
         </para>
@@ -624,8 +628,8 @@ testdb=>
        <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
        <listitem>
         <para>
-	 Change the current working directory to
-	 <replaceable>directory</replaceable>. Without argument, change
+	 Changes the current working directory to
+	 <replaceable>directory</replaceable>. Without argument, changes
 	 to the current user's home directory.
         </para>
 
@@ -641,7 +645,7 @@ testdb=>
         <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
+        Sets 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
@@ -701,10 +705,10 @@ testdb=>
         <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
+        endterm="SQL-COPY-title"> command, but instead of the server
         reading or writing the specified file,
         <application>psql</application> reads or writes the file and
-        routes the data between the backend and the local file system.
+        routes the data between the server and the local file system.
 	This means that file accessibility and privileges are those
 	of the local user, not the server, and no SQL superuser
 	privileges are required.
@@ -712,8 +716,8 @@ testdb=>
 
 	<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,
+	<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.
@@ -723,7 +727,7 @@ testdb=>
         <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
+	through the client/server connection. For large
 	amounts of data the other technique may be preferable.
         </para>
         </tip>
@@ -732,9 +736,9 @@ testdb=>
         <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
+        client and server copies: in a client copy these always
         refer to <application>psql</application>'s input and output
-        stream. On a backend copy <literal>stdin</literal> comes from
+        stream. On a server 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
@@ -792,7 +796,7 @@ testdb=>
         <para>
         Lists all available aggregate functions, together with the data
         type they operate on. If <replaceable
-        class="parameter">pattern</replaceable> (a regular expression)
+        class="parameter">pattern</replaceable>
         is specified, only matching aggregates are shown.
         </para>
         </listitem>
@@ -845,16 +849,8 @@ testdb=>
 
         <para>
         Descriptions for objects can be created with the
-        <command>COMMENT ON</command> <acronym>SQL</acronym> command.
+        <command>COMMENT</command> <acronym>SQL</acronym> command.
 	</para>
-
-        <note>
-        <para>
-        <productname>PostgreSQL</productname> stores the object
-        descriptions in the <structname>pg_description</> system table.
-        </para>
-        </note>
-
         </listitem>
       </varlistentry>
 
@@ -863,7 +859,7 @@ testdb=>
         <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
         <listitem>
         <para>
-        Lists all available domains (derived types). If <replaceable
+        Lists all available domains. If <replaceable
         class="parameter">pattern</replaceable>
         is specified, only matching domains are shown.
         </para>
@@ -907,12 +903,12 @@ testdb=>
 	order, to obtain a listing of all the matching objects.  The letter
 	S restricts the listing to system objects; without S, only non-system
 	objects are shown.
-	If <quote>+</quote> is appended to the command name, each object is
+	If <literal>+</literal> is appended to the command name, each object is
 	listed with its associated description, if any.
 	</para>
 
 	<para>
-	If a <replaceable class="parameter">pattern</replaceable> is
+	If <replaceable class="parameter">pattern</replaceable> is
 	specified, only objects whose name matches the pattern are listed.
 	</para>
 	</listitem>
@@ -948,7 +944,7 @@ testdb=>
         <listitem>
         <para>
         Lists available operators with their operand and return types.
-	If a <replaceable class="parameter">pattern</replaceable> is
+	If <replaceable class="parameter">pattern</replaceable> is
 	specified, only operators whose name matches the pattern are listed.
         </para>
         </listitem>
@@ -960,15 +956,15 @@ testdb=>
 	<listitem>
 	<para>
         Produces a list of all available tables with their
-        associated access permissions.
-	If a <replaceable class="parameter">pattern</replaceable> is
+        associated access privileges.
+	If <replaceable class="parameter">pattern</replaceable> is
 	specified, only tables whose name matches the pattern are listed.
 	</para>
 
 	<para>
 	The commands <xref linkend="SQL-GRANT"> and
 	<xref linkend="SQL-REVOKE">
-	are used to set access permissions.  See <xref linkend="SQL-GRANT">
+	are used to set access privileges.  See <xref linkend="SQL-GRANT">
 	for more information.
 	</para>
 	</listitem>
@@ -991,7 +987,7 @@ testdb=>
         <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
         <listitem>
         <para>
-        Lists all database users, or only those that match <replaceable
+        Lists all database users or only those that match <replaceable
         class="parameter">pattern</replaceable>.
         </para>
         </listitem>
@@ -1063,13 +1059,13 @@ Tue Oct 26 21:40:57 CEST 1999
 
         <listitem>
         <para>
-        Sets the client encoding.  Without an argument, this command
+        Sets the client character set encoding.  Without an argument, this command
         shows the current encoding.
         </para>
 	<note>
 	<para>
 	This command will not notice changes made directly by <command>SET
-        CLIENT_ENCODING</>.  If you use <literal>\encoding</literal>,
+        client_encoding</>.  If you use <command>\encoding</command>,
 	be sure to use it to set as well as examine the encoding.
 	</para>
 	</note>	
@@ -1083,7 +1079,7 @@ Tue Oct 26 21:40:57 CEST 1999
         <listitem>
         <para>
         Sets the field separator for unaligned query output. The default
-        is pipe (<literal>|</literal>). See also
+        is the vertical bar (<literal>|</literal>). See also
         <command>\pset</command> for a generic way of setting output
         options.
         </para>
@@ -1096,7 +1092,7 @@ Tue Oct 26 21:40:57 CEST 1999
 
         <listitem>
         <para>
-        Sends the current query input buffer to the backend and
+        Sends the current query input buffer to the server and
         optionally saves the output in <replaceable
         class="parameter">filename</replaceable> or pipes the output
         into a separate Unix shell to execute <replaceable
@@ -1112,12 +1108,12 @@ Tue Oct 26 21:40:57 CEST 1999
         <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>
+        Gives 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
+        asterisk (<literal>*</literal>), then syntax help on all
         <acronym>SQL</acronym> commands is shown.
         </para>
 
@@ -1169,8 +1165,8 @@ Tue Oct 26 21:40:57 CEST 1999
         <term><literal>\l</literal> (or <literal>\list</literal>)</term>
         <listitem>
         <para>
-        List the names, owners, and encodings of all the databases in
-        the server.  Append a <quote>+</quote> to the command name to
+        List the names, owners, and character set encodings of all the databases in
+        the server.  Append a <literal>+</literal> to the command name to
         see any descriptions for the databases as well.
         </para>
         </listitem>
@@ -1214,13 +1210,13 @@ Tue Oct 26 21:40:57 CEST 1999
 	<listitem>
 	<para>
 	Stores the file into a <productname>PostgreSQL</productname>
-	<quote>large object</quote>. Optionally, it associates the given
+	large object. 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
+	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
@@ -1249,7 +1245,7 @@ lo_import 152801
 	<listitem>
 	<para>
 	Shows a list of all <productname>PostgreSQL</productname>
-	<quote>large objects</quote> currently stored in the database,
+	large objects currently stored in the database,
 	along with any comments provided for them.
 	</para>
 	</listitem>
@@ -1291,8 +1287,7 @@ lo_import 152801
         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>.
+        specified, the query output will be reset to the standard output.
         </para>
 
 	<para>
@@ -1349,7 +1344,7 @@ lo_import 152801
 	  </para>
 
 	  <para>
-	  <quote>Unaligned</quote> writes all fields of a tuple on a
+	  <quote>Unaligned</quote> writes all columns of a row 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).
@@ -1385,14 +1380,14 @@ lo_import 152801
 	  <listitem>
 	  <para>
 	  Toggles between regular and expanded format. When expanded
-	  format is enabled, all output has two columns with the field
+	  format is enabled, all output has two columns with the column
 	  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.
+	  Expanded mode is supported by all four output formats.
 	  </para>
 	  </listitem>
 	  </varlistentry>
@@ -1402,7 +1397,7 @@ lo_import 152801
 	  <listitem>
 	  <para>
 	  The second argument is a string that should be printed
-	  whenever a field is null. The default is not to print
+	  whenever a column 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>.
@@ -1419,7 +1414,7 @@ lo_import 152801
 	  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).
+	  <literal>'|'</literal> (a vertical bar).
 	  </para>
 	  </listitem>
 	  </varlistentry>
@@ -1464,13 +1459,6 @@ lo_import 152801
 	  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>
 
@@ -1512,6 +1500,9 @@ lo_import 152801
 	  </listitem>
 	  </varlistentry>
 	</variablelist>
+        </para>
+
+        <para>
 	Illustrations on how these different formats look can be seen in
 	the <xref linkend="APP-PSQL-examples"
 	endterm="APP-PSQL-examples-title"> section.
@@ -1541,7 +1532,7 @@ lo_import 152801
         <term><literal>\q</literal></term>
         <listitem>
         <para>
-        Quit the <application>psql</application> program.
+        Quits the <application>psql</application> program.
         </para>
         </listitem>
       </varlistentry>
@@ -1608,8 +1599,9 @@ lo_import 152801
 
 	<para>
 	Valid variable names can contain characters, digits, and
-	underscores. See the section about
-	<application>psql</application> variables for details.
+	underscores. See the section <xref
+	linkend="APP-PSQL-variables"
+	endterm="APP-PSQL-variables-title"> below for details.
 	</para>
 
 	<para>
@@ -1644,7 +1636,7 @@ lo_import 152801
         <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
         <listitem>
         <para>
-        Allows you to specify options to be placed within the
+        Allows you to specify attributes 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
@@ -1680,7 +1672,7 @@ lo_import 152801
         <term><literal>\x</literal></term>
         <listitem>
         <para>
-        Toggles extended row format mode. As such it is equivalent to
+        Toggles extended table formatting mode. As such it is equivalent to
 	<literal>\pset expanded</literal>.
        </para>
        </listitem>
@@ -1692,7 +1684,7 @@ lo_import 152801
         <listitem>
         <para>
         Produces a list of all available tables with their
-        associated access permissions.
+        associated access privileges.
 	If a <replaceable class="parameter">pattern</replaceable> is
 	specified, only tables whose name matches the pattern are listed.
 	</para>
@@ -1700,13 +1692,13 @@ lo_import 152801
 	<para>
 	The commands <xref linkend="SQL-GRANT"> and
 	<xref linkend="SQL-REVOKE">
-	are used to set access permissions.  See <xref linkend="SQL-GRANT">
+	are used to set access privileges.  See <xref linkend="SQL-GRANT">
 	for more information.
 	</para>
 
 	<para>
 	This is an alias for <command>\dp</command> (<quote>display
-	permissions</quote>).
+	privileges</quote>).
         </para>
         </listitem>
       </varlistentry>
@@ -1729,8 +1721,7 @@ lo_import 152801
         <term><literal>\?</literal></term>
         <listitem>
         <para>
-        Get help information about the backslash (<quote>\</quote>)
-        commands.
+        Shows help information about the backslash commands.
         </para>
         </listitem>
       </varlistentry>
@@ -1741,31 +1732,20 @@ lo_import 152801
   <para>
    The various <literal>\d</> commands accept a <replaceable
    class="parameter">pattern</replaceable> parameter to specify the
-   object name(s) to be displayed.  Patterns are interpreted similarly
-   to SQL identifiers, in that unquoted letters are forced to lowercase,
-   while double quotes (<literal>"</>) protect letters from case conversion
-   and allow incorporation of whitespace into the identifier.  Within
-   double quotes, paired double quotes reduce to a single double quote in
-   the resulting name.  For example, <literal>FOO"BAR"BAZ</> is interpreted
-   as <literal>fooBARbaz</>, and <literal>"A weird"" name"</> becomes
-   <literal>A weird" name</>.
-  </para>
-
-  <para>
-   More interestingly, <literal>\d</> patterns allow the use of
-   <literal>*</> to mean <quote>any sequence of characters</>, and
-   <literal>?</> to mean <quote>any single character</>.  (This notation
-   is comparable to Unix shell filename patterns.)  Advanced users can
-   also use regular-expression notations such as character classes, for
-   example <literal>[0-9]</> to match <quote>any digit</>.  To make any of
-   these pattern-matching characters be interpreted literally, surround it
+   object name(s) to be displayed.  <literal>*</> means <quote>any
+   sequence of characters</> and <literal>?</> means <quote>any single
+   character</>.  (This notation is comparable to Unix shell file name
+   patterns.)  Advanced users can also use regular-expression
+   notations such as character classes, for example <literal>[0-9]</>
+   to match <quote>any digit</>.  To make any of these
+   pattern-matching characters be interpreted literally, surround it
    with double quotes.
   </para>
 
   <para>
    A pattern that contains an (unquoted) dot is interpreted as a schema
    name pattern followed by an object name pattern.  For example,
-   <literal> \dt foo*.bar*</> displays all tables in schemas whose name
+   <literal>\dt foo*.bar*</> displays all tables in schemas whose name
    starts with <literal>foo</> and whose table name 
    starts with <literal>bar</>.  If no dot appears, then the pattern
    matches only objects that are visible in the current schema search path.
@@ -1787,17 +1767,16 @@ lo_import 152801
 
     <para>
     <application>psql</application> provides variable substitution
-    features similar to common Unix command shells. This feature is new
-    and not very sophisticated, yet, but there are plans to expand it in
-    the future. Variables are simply name/value pairs, where the value
+    features similar to common Unix command shells.
+    Variables are simply name/value pairs, where the value
     can be any string of any length. To set variables, use the
     <application>psql</application> meta-command
     <command>\set</command>:
 <programlisting>
 testdb=> <userinput>\set foo bar</userinput>
 </programlisting>
-    sets the variable <quote>foo</quote> to the value
-    <quote>bar</quote>. To retrieve the content of the variable, precede
+    sets the variable <literal>foo</literal> to the value
+    <literal>bar</literal>. To retrieve the content of the variable, precede
     the name with a colon and use it as the argument of any slash
     command:
 <programlisting>
@@ -1840,6 +1819,8 @@ bar
     consist of all upper-case letters (and possibly numbers and
     underscores). To ensure maximum compatibility in the future, avoid
     such variables. A list of all specially treated variables follows.
+   </para>
+
     <variablelist>
       <varlistentry>
         <term><varname>DBNAME</varname></term>
@@ -1856,13 +1837,13 @@ bar
         <term><varname>ECHO</varname></term>
 	<listitem>
 	<para>
-	If set to <quote><literal>all</literal></quote>, all lines
+	If set to <literal>all</literal>, all lines
 	entered or from a script are written to the standard output
 	before they are parsed or executed. To specify this on program
 	start-up, use the switch <option>-a</option>. If set to
-	<quote><literal>queries</literal></quote>,
+	<literal>queries</literal>,
 	<application>psql</application> merely prints all queries as
-	they are sent to the backend. The option for this is
+	they are sent to the server. The option for this is
 	<option>-e</option>.
 	</para>
 	</listitem>
@@ -1877,7 +1858,7 @@ bar
 	<productname>PostgreSQL</productname> internals and provide
 	similar functionality in your own programs. If you set the
 	variable to the value <literal>noexec</literal>, the queries are
-	just shown but are not actually sent to the backend and
+	just shown but are not actually sent to the server and
 	executed.
 	</para>
 	</listitem>
@@ -1887,9 +1868,7 @@ bar
         <term><varname>ENCODING</varname></term>
 	<listitem>
 	<para>
-        The current client multibyte encoding. If you are not set up to
-        use multibyte characters, this variable will always contain
-        <quote>SQL_ASCII</quote>.
+        The current client character set encoding.
 	</para>
 	</listitem>
       </varlistentry>
@@ -1909,7 +1888,7 @@ bar
         <note>
         <para>
         This feature was shamelessly plagiarized from
-        <application>bash</application>.
+        <application>Bash</application>.
         </para>
         </note>
 	</listitem>
@@ -1925,7 +1904,7 @@ bar
         <note>
         <para>
         This feature was shamelessly plagiarized from
-        <application>bash</application>.
+        <application>Bash</application>.
         </para>
         </note>
 	</listitem>
@@ -1957,7 +1936,7 @@ bar
         <note>
         <para>
         This feature was shamelessly plagiarized from
-        <application>bash</application>.
+        <application>Bash</application>.
         </para>
         </note>
 	</listitem>
@@ -1982,7 +1961,7 @@ bar
 	<para>
 	If you use the <productname>PostgreSQL</productname> large
 	object interface to specially store data that does not fit into
-	one tuple, all the operations must be contained in a transaction
+	one row, all the operations must be contained in a transaction
 	block. (See the documentation of the large object interface for
 	more information.) Since <application>psql</application> has no
 	way to tell if you already have a transaction in progress when
@@ -1992,16 +1971,15 @@ bar
 	action. This action could either be to roll back any transaction
 	that might already be in progress, or to commit any such
 	transaction, or to do nothing at all. In the last case you must
-	provide your own <command>BEGIN
-	TRANSACTION</command>/<command>COMMIT</command> block or the
+	provide your own <command>BEGIN</command>/<command>COMMIT</command> block or the
 	results will be unpredictable (usually resulting in the desired
 	action's not being performed in any case).
 	</para>
 
 	<para>
 	To choose what you want to do you set this variable to one of
-	<quote>rollback</quote>, <quote>commit</quote>, or
-	<quote>nothing</quote>. The default is to roll back the
+	<literal>rollback</literal>, <literal>commit</literal>, or
+	<literal>nothing</literal>. The default is to roll back the
 	transaction. If you just want to load one or a few objects this
 	is fine. However, if you intend to transfer many large objects,
 	it might be advisable to provide one explicit transaction block
@@ -2015,7 +1993,7 @@ bar
 	<listitem>
 	<para>
 	By default, if non-interactive scripts encounter an error, such
-	as a malformed <acronym>SQL</acronym> query or internal
+	as a malformed <acronym>SQL</acronym> command or internal
 	meta-command, processing continues. This has been the
 	traditional behavior of <application>psql</application> but it
 	is sometimes not desirable. If this variable is set, script
@@ -2048,9 +2026,9 @@ bar
 	<listitem>
 	<para>
 	These specify what the prompt <application>psql</application>
-	issues is supposed to look like. See <quote><xref
+	issues is supposed to look like. See <xref
 	linkend="APP-PSQL-prompting"
-	endterm="APP-PSQL-prompting-title"></quote> below.
+	endterm="APP-PSQL-prompting-title"> below.
 	</para>
 	</listitem>
       </varlistentry>
@@ -2099,8 +2077,6 @@ bar
 
     </variablelist>
 
-    </para>
-
    </refsect3>
 
    <refsect3>
@@ -2127,7 +2103,7 @@ testdb=> <userinput>SELECT * FROM :foo;</userinput>
     A popular application of this facility is to refer to the last
     inserted <acronym>OID</acronym> in subsequent statements to build a
     foreign key scenario. Another possible use of this mechanism is to
-    copy the contents of a file into a field. First load the file into a
+    copy the contents of a file into a table column. First load the file into a
     variable and then proceed as above.
 <programlisting>
 testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
@@ -2135,8 +2111,8 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:content);</userinput>
 </programlisting>
     One possible problem with this approach is that <filename>my_file.txt</filename>
     might contain single quotes. These need to be escaped so that
-    they don't cause a syntax error when the third line is processed. This
-    could be done with the program <application>sed</application>:
+    they don't cause a syntax error when the second line is processed. This
+    could be done with the program <command>sed</command>:
 <programlisting>
 testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
 </programlisting>
@@ -2144,9 +2120,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     this way: After <application>psql</application> has parsed this
     line, it passes <literal>sed -e "s/'/\\\'/g" < my_file.txt</literal>
     to the shell. The shell will do its own thing inside the double
-    quotes and execute <filename>sed</filename> with the arguments
+    quotes and execute <command>sed</command> with the arguments
     <literal>-e</literal> and <literal>s/'/\\'/g</literal>. When
-    <application>sed</application> parses this it will replace the two
+    <command>sed</command> parses this it will replace the two
     backslashes with a single one and then do the substitution. Perhaps
     at one point you thought it was great that all Unix commands use the
     same escape character. And this is ignoring the fact that you might
@@ -2157,12 +2133,12 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     </para>
 
     <para>
-    Since colons may legally appear in queries, the following rule
+    Since colons may legally appear in SQL commands, the following rule
     applies: If the variable is not set, the character sequence
     <quote>colon+name</quote> is not changed. In any case you can escape
     a colon with a backslash to protect it from interpretation. (The
     colon syntax for variables is standard <acronym>SQL</acronym> for
-    embedded query languages, such as <application>ecpg</application>.
+    embedded query languages, such as <application>ECPG</application>.
     The colon syntax for array slices and type casts are
     <productname>PostgreSQL</productname> extensions, hence the
     conflict.)
@@ -2179,17 +2155,17 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     <varname>PROMPT2</varname>, and <varname>PROMPT3</varname> contain strings
     and special escape sequences that describe the appearance of the
     prompt. Prompt 1 is the normal prompt that is issued when
-    <application>psql</application> requests a new query. Prompt 2 is
-    issued when more input is expected during query input because the
-    query was not terminated with a semicolon or a quote was not closed.
+    <application>psql</application> requests a new command. Prompt 2 is
+    issued when more input is expected during command input because the
+    command was not terminated with a semicolon or a quote was not closed.
     Prompt 3 is issued when you run an <acronym>SQL</acronym>
     <command>COPY</command> command and you are expected to type in the
-    tuples on the terminal.
+    row values on the terminal.
     </para>
 
     <para>
     The value of the respective prompt variable is printed literally,
-    except where a percent sign (<quote>%</quote>) is encountered.
+    except where a percent sign (<literal>%</literal>) is encountered.
     Depending on the next character, certain other text is substituted
     instead. Defined substitutions are:
 
@@ -2212,7 +2188,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
         <term><literal>%m</literal></term>
 	<listitem>
          <para>
-          The host name of the database server, truncated after the
+          The host name of the database server, truncated at the
           first dot, or <literal>[local]</literal> if the connection is
           over a Unix domain socket.
          </para>
@@ -2237,28 +2213,28 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
 
       <varlistentry>
         <term><literal>%~</literal></term>
-	<listitem><para>Like <literal>%/</literal>, but the output is <quote>~</quote>
+	<listitem><para>Like <literal>%/</literal>, but the output is <literal>~</literal>
          (tilde) if the database is your default database.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><literal>%#</literal></term>
 	<listitem><para>If the current user is a database superuser, then a
-         <quote>#</quote>, otherwise a <quote>&gt;</quote>.</para></listitem>
+         <literal>#</literal>, otherwise a <literal>&gt;</literal>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><literal>%R</literal></term>
 	<listitem>
 	<para>
-	In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if
-	in single-line mode, and <quote>!</quote> if the session is
+	In prompt 1 normally <literal>=</literal>, but <literal>^</literal> if
+	in single-line mode, and <literal>!</literal> if the session is
 	disconnected from the database (which can happen if
 	<command>\connect</command> fails). In prompt 2 the sequence is
-	replaced by <quote>-</quote>, <quote>*</quote>, a single quote,
+	replaced by <literal>-</literal>, <literal>*</literal>, a single quote,
 	or a double quote, depending on whether
 	<application>psql</application> expects more input because the
-	query wasn't terminated yet, because you are inside a
+	command wasn't terminated yet, because you are inside a
 	<literal>/* ... */</literal> comment, or because you are inside
 	a quote. In prompt 3 the sequence doesn't resolve to anything.
 	</para>
@@ -2284,10 +2260,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
         <term><literal>%:</literal><replaceable class="parameter">name</replaceable><literal>:</literal></term>
 	<listitem>
 	<para>
-	The value of the <application>psql</application>, variable
+	The value of the <application>psql</application> variable
 	<replaceable class="parameter">name</replaceable>. See the
-	section <quote><xref linkend="APP-PSQL-variables"
-	endterm="APP-PSQL-variables-title"></quote> for details.
+	section <xref linkend="APP-PSQL-variables"
+	endterm="APP-PSQL-variables-title"> for details.
 	</para>
 	</listitem>
       </varlistentry>
@@ -2330,9 +2306,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
     in your home directory and is reloaded when
     <application>psql</application> starts up. Tab-completion is also
     supported, although the completion logic makes no claim to be an
-    <acronym>SQL</acronym> parser. When available,
-    <application>psql</application> is automatically built to use these
-    features. If for some reason you do not like the tab completion, you
+    <acronym>SQL</acronym> parser.  If for some reason you do not like the tab completion, you
     can turn if off by putting this in a file named
     <filename>.inputrc</filename> in your home directory:
 <programlisting>
@@ -2341,7 +2315,7 @@ set disable-completion on
 $endif
 </programlisting>
     (This is not a <application>psql</application> but a
-    <application>readline</application> feature. Read its documentation
+    <application>Readline</application> feature. Read its documentation
     for further details.)
     </para>
    </refsect3>
@@ -2471,12 +2445,12 @@ $endif
       first argument of a single-letter backslash command to start
       directly after the command, without intervening whitespace. For
       compatibility this is still supported to some extent,
-      but I am not going to explain the details here as this use is
+      but were are not going to explain the details here as this use is
       discouraged.  If you get strange messages, keep this in mind.
       For example
 <programlisting>
 testdb=> <userinput>\foo</userinput>
-Field separator is "oo",
+Field separator is "oo".
 </programlisting>
       which is perhaps not what one would expect.
       </para>
@@ -2494,10 +2468,11 @@ Field separator is "oo",
 
       <listitem>
       <para>
-      Pressing Control-C during a <quote>copy in</quote> (data sent to
+      Pressing <keycombo action="simul"><keycap>Control</><keycap>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
+      message such as <errorname>COPY state must be terminated
+      first</errorname>, simply reset the connection by entering <literal>\c
       - -</literal>.
       </para>
       </listitem>
@@ -2515,19 +2490,19 @@ Field separator is "oo",
   <application>psql</application>. If you want to learn
   <acronym>SQL</acronym> or get familiar with
   <productname>PostgreSQL</productname>, you might wish to read the
-  Tutorial that is included in the distribution.
+  &cite-tutorial;.
   </para>
   </note>
 
   <para>
-  The first example shows how to spread a query over several lines of
+  The first example shows how to spread a command over several lines of
   input. Notice the changing prompt:
 <programlisting>
 testdb=> <userinput>CREATE TABLE my_table (</userinput>
 testdb(> <userinput> first integer not null default 0,</userinput>
 testdb(> <userinput> second text</userinput>
 testdb-> <userinput>);</userinput>
-CREATE
+CREATE TABLE
 </programlisting>
   Now look at the table definition again:
 <programlisting>
@@ -2539,8 +2514,7 @@ testdb=> <userinput>\d my_table</userinput>
  second    | text    |
 
 </programlisting>
-  At this point you decide to change the prompt to something more
-  interesting:
+  Now we change the prompt to something more interesting:
 <programlisting>
 testdb=> <userinput>\set PROMPT1 '%n@%m %~%R%# '</userinput>
 peter@localhost testdb=>

doc/src/sgml/ref/vacuumdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.27 2002/10/11 23:03:48 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.28 2003/03/24 14:32:51 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -18,12 +18,12 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>vacuumdb</command>
-   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
    <group><arg>--full</arg><arg>-f</arg></group>
    <group><arg>--verbose</arg><arg>-v</arg></group>
    <group><arg>--analyze</arg><arg>-z</arg></group>
-   <arg>--table | -t '<replaceable>table</replaceable>
-    <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>'
+   <arg>--table | -t <replaceable>table</replaceable>
+    <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>
    </arg>
    <arg><replaceable>dbname</replaceable></arg>
    <sbr>
@@ -78,6 +78,16 @@ PostgreSQL documentation
     <application>vacuumdb</application> accepts the following command-line arguments:
     
     <variablelist>
+     <varlistentry>
+      <term><option>-a</option></term>
+      <term><option>--all</option></term>
+      <listitem>
+       <para>
+	Vacuum all databases.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term>
       <term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></option></term>
@@ -93,17 +103,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>-a</option></term>
-      <term><option>--all</option></term>
-      <listitem>
-       <para>
-	Vacuum all databases.
-       </para>
-      </listitem>
-     </varlistentry>
-
-
      <varlistentry>
       <term><option>-e</></term>
       <term><option>--echo</></term>
@@ -146,8 +145,8 @@ PostgreSQL documentation
        </para>
        <tip>
         <para>
-         If you specify columns to vacuum, you probably have to escape the parentheses
-         from the shell.
+         If you specify columns, you probably have to escape the parentheses
+         from the shell.  (See examples below.)
         </para>
        </tip>
       </listitem>
@@ -187,7 +186,7 @@ PostgreSQL documentation
        <para>
 	Specifies the host name of the machine on which the 
 	server
-	is running.  If host begins with a slash, it is used 
+	is running.  If the value begins with a slash, it is used 
 	as the directory for the Unix domain socket.
        </para>
       </listitem>
@@ -198,7 +197,7 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the Internet TCP/IP port or local Unix domain socket file 
+	Specifies the TCP port or local Unix domain socket file 
 	extension on which the server
 	is listening for connections.
        </para>
@@ -272,7 +271,7 @@ PostgreSQL documentation
 
     <listitem>
      <para>
-      Default connection parameters.
+      Default connection parameters
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/reference.sgml

 <!-- reference.sgml
-$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.42 2003/03/20 07:02:07 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.43 2003/03/24 14:32:50 petere Exp $
 
 PostgreSQL Reference Manual
 -->
@@ -135,27 +135,6 @@ PostgreSQL Reference Manual
 
  </reference>
 
-<!--
-Disable this chapter until we have more functions documented.
-- thomas 1998-10-27
-
- <reference id="sql-functions">
-  <title>SQL Functions</title>
-
-  <partintro>
-   <para>
-    This part provides reference information for the
-    <acronym>SQL</acronym> functions supported by
-    <productname>PostgreSQL</productname>.
-   </para>
-
-   &currentDate;
-   &currentTime;
-   &currentTimestamp;
-   &currentUser;
- </reference>
--->
-
  <reference id="reference-client">
   <title>PostgreSQL Client Applications</title>
 
@@ -182,9 +161,9 @@ Disable this chapter until we have more functions documented.
    &pgDump;
    &pgDumpall;
    &pgRestore;
-   &psqlRef;
    &pgTclSh;
    &pgTkSh;
+   &psqlRef;
    &vacuumdb;
 
  </reference>
@@ -205,8 +184,8 @@ Disable this chapter until we have more functions documented.
    &initdb;
    &initlocation;
    &ipcclean;
-   &pgCtl;
    &pgControldata;
+   &pgCtl;
    &pgResetxlog;
    &postgres;
    &postmaster;

doc/src/sgml/runtime.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.172 2003/03/20 04:51:44 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.173 2003/03/24 14:32:50 petere Exp $
 -->
 
 <Chapter Id="runtime">
@@ -22,7 +22,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.172 2003/03/20 04:51:44 mo
    it is advisable to run <productname>PostgreSQL</productname> under a
    separate user account. This user account should only own the data
    that is managed by the server, and should not be shared with other
-   daemons. (For example, using the user <quote>nobody</quote> is a bad
+   daemons. (For example, using the user <literal>nobody</literal> is a bad
    idea.) It is not advisable to install executables owned by
    this user because compromised systems could then modify their own 
    binaries.
@@ -83,11 +83,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.172 2003/03/20 04:51:44 mo
 
   <tip>
    <para>
-    <indexterm>
-     <primary><envar>PGDATA</envar></primary>
-    </indexterm>
     As an alternative to the <option>-D</option> option, you can set
     the environment variable <envar>PGDATA</envar>.
+    <indexterm><primary><envar>PGDATA</envar></primary></indexterm>
    </para>
   </tip>
 
@@ -128,16 +126,14 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
    password to the database superuser. After <command>initdb</command>,
    modify the <filename>pg_hba.conf</filename> file to use <literal>md5</> or
    <literal>password</> instead of <literal>trust</> authentication
-   <emphasis>before</> you start the server for the first time. (Other,
+   <emphasis>before</> you start the server for the first time. (Other
    approaches include using <literal>ident</literal> authentication or
    file system permissions to restrict connections. See <xref
    linkend="client-authentication"> for more information.)
   </para>
 
   <para>
-   <indexterm><primary>locale</></>
-   <indexterm><primary>LC_COLLATE</></>
-   <command>initdb</command> also initializes the default locale for
+   <command>initdb</command> also initializes the default locale<indexterm><primary>locale</></> for
    the database cluster.  Normally, it will just take the locale
    settings in the environment and apply them to the initialized
    database.  It is possible to specify a different locale for the
@@ -168,12 +164,10 @@ set to "C".  For more information see the Administrator's Guide.
   <title>Starting the Database Server</title>
 
   <para>
-   <indexterm>
-    <primary>postmaster</primary>
-   </indexterm>
    Before anyone can access the database, you must start the database
-   server. The database server is called
-   <firstterm>postmaster</firstterm>. The postmaster must know where to
+   server. The database server program is called
+   <command>postmaster</command>.<indexterm><primary>postmaster</></>
+   The <command>postmaster</command> must know where to
    find the data it is supposed to use. This is done with the
    <option>-D</option> option. Thus, the simplest way to start the
    server is:
@@ -188,7 +182,7 @@ $ <userinput>postmaster -D /usr/local/pgsql/data</userinput>
   </para>
 
   <para>
-   To start the <application>postmaster</application> in the
+   To start the <command>postmaster</command> in the
    background, use the usual shell syntax:
 <screen>
 $ <userinput>postmaster -D /usr/local/pgsql/data &gt; logfile 2&gt;&amp;1 &amp;</userinput>
@@ -201,29 +195,26 @@ $ <userinput>postmaster -D /usr/local/pgsql/data &gt; logfile 2&gt;&amp;1 &amp;<
   </para>
 
   <para>
-   <indexterm>
-    <primary>TCP/IP</primary>
-   </indexterm>
-   The postmaster also takes a number of other command line options. For
-   more information, see the reference page and <xref
-   linkend="runtime-config"> below. In particular, in order for the
-   server to accept TCP/IP connections (rather than just Unix domain
-   socket ones), you must specify the <option>-i</option> option.
+   The <command>postmaster</command> also takes a number of other
+   command line options. For more information, see the reference page
+   and <xref linkend="runtime-config"> below. In particular, in order
+   for the server to accept
+   TCP/IP<indexterm><primary>TCP/IP</primary></indexterm> connections
+   (rather than just Unix-domain socket ones), you must specify the
+   <option>-i</option> option.
   </para>
 
   <para>
-   <indexterm>
-    <primary>pg_ctl</primary>
-   </indexterm>
    This shell syntax can get tedious quickly.  Therefore the shell
-   script wrapper <application>pg_ctl</application> is provided to
-   simplify some tasks.  For example:
+   script wrapper
+   <command>pg_ctl</command><indexterm><primary>pg_ctl</primary></indexterm>
+   is provided to simplify some tasks.  For example:
 <programlisting>
 pg_ctl start -l logfile
 </programlisting>
    will start the server in the background and put the output into the
    named log file. The <option>-D</option> option has the same meaning
-   here as in the postmaster. <application>pg_ctl</application> is also
+   here as in the <command>postmaster</command>. <command>pg_ctl</command> is also
    capable of stopping the server.
   </para>
 
@@ -232,7 +223,7 @@ pg_ctl start -l logfile
    computer boots. Autostart scripts are operating system-specific.
    There are a few distributed with
    <productname>PostgreSQL</productname> in the
-   <filename>/contrib/start-scripts</> directory. This may require root
+   <filename>contrib/start-scripts</> directory. This may require root
    privileges.
   </para>
 
@@ -305,14 +296,14 @@ fi
     <listitem>
      <para>
       On <productname>Solaris</productname>, create a file called
-      <filename>/etc/init.d/postgresql</filename> which should contain
+      <filename>/etc/init.d/postgresql</filename> that contains
       the following line:
       <indexterm><primary>Solaris</></>
 <programlisting>
 su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data"
 </programlisting>
       Then, create a symbolic link to it in <filename>/etc/rc3.d</> as
-      <literal>S99postgresql</>.
+      <filename>S99postgresql</>.
      </para>
     </listitem>
    </itemizedlist>
@@ -320,44 +311,47 @@ su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgs
   </para>
 
    <para>
-    While the <application>postmaster</application> is running, its
-    <acronym>PID</acronym> is in the file
+    While the <command>postmaster</command> is running, its
+    <acronym>PID</acronym> is stored in the file
     <filename>postmaster.pid</filename> in the data directory. This is
-    used to prevent multiple postmasters running in the same data
-    directory, and can also be used for shutting down the postmaster.
+    used to prevent multiple <command>postmaster</command> processes
+    running in the same data directory and can also be used for
+    shutting down the <command>postmaster</command> process.
    </para>
 
    <sect2 id="postmaster-start-failures">
     <title>Server Start-up Failures</title>
 
     <para>
-     There are several common reasons the postmaster might fail to
-     start. Check the postmaster's log file, or start it by hand
-     (without redirecting standard output or standard error) and see
-     what error messages appear. Some of the error messages are
-     self-explanatory, but some are not, as shown below:
+     There are several common reasons the server might fail to
+     start. Check the server's log file, or start it by hand (without
+     redirecting standard output or standard error) and see what error
+     messages appear. Below we explain some of the most common error
+     messages in more detail.
     </para>
 
     <para>
 <screen>
 FATAL: StreamServerPort: bind() failed: Address already in use
-        Is another postmaster already running on that port?
+        Is another postmaster already running on port 5432?
+        If not, wait a few seconds an retry.
 </screen>
      This usually means just what it suggests: you tried to start
-     another postmaster on the same port where one is already running.
+     another <command>postmaster</command> on the same port where one is already running.
      However, if the kernel error message is not <computeroutput>Address
      already in use</computeroutput> or some variant of that, there may
-     be a different problem. For example, trying to start a postmaster
+     be a different problem. For example, trying to start a <command>postmaster</command>
      on a reserved port number may draw something like:
 <screen>
 $ <userinput>postmaster -i -p 666</userinput>
 FATAL: StreamServerPort: bind() failed: Permission denied
-        Is another postmaster already running on that port?
+        Is another postmaster already running on port 666?
+        If not, wait a few seconds an retry.
 </screen>
     </para>
 
     <para>
-     A message like:
+     A message like
 <screen>
 IpcMemoryCreate: shmget(key=5440001, size=83918612, 01600) failed: Invalid argument
 FATAL 1:  ShmemCreate: cannot create region
@@ -367,16 +361,16 @@ FATAL 1:  ShmemCreate: cannot create region
      is trying to create (83918612 bytes in this example). Or it could
      mean that you do not have System-V-style shared memory support
      configured into your kernel at all. As a temporary workaround, you
-     can try starting the postmaster with a smaller-than-normal number
+     can try starting the server with a smaller-than-normal number
      of buffers (<option>-B</option> switch). You will eventually want
      to reconfigure your kernel to increase the allowed shared memory
-     size. You may see this message when trying to start multiple
-     postmasters on the same machine if their total space requested
+     size. You may also see this message when trying to start multiple
+     servers on the same machine if their total space requested
      exceeds the kernel limit.
     </para>
 
     <para>
-     An error like:
+     An error like
 <screen>
 IpcSemaphoreCreate: semget(key=5440026, num=16, 01600) failed: No space left on device
 </screen>
@@ -385,7 +379,7 @@ IpcSemaphoreCreate: semget(key=5440026, num=16, 01600) failed: No space left on
      class="osname">System V</> semaphores is smaller than the number
      <productname>PostgreSQL</productname> wants to create. As above,
      you may be able to work around the problem by starting the
-     postmaster with a reduced number of allowed connections
+     server with a reduced number of allowed connections
      (<option>-N</option> switch), but you'll eventually want to
      increase the kernel limit.
     </para>
@@ -422,14 +416,13 @@ psql: could not connect to server: Connection refused
 </screen>
      This is the generic <quote>I couldn't find a server to talk
      to</quote> failure. It looks like the above when TCP/IP
-     communication is attempted. A common mistake is to forget the
-     <option>-i</option> option to allow the postmaster to accept TCP/IP
-     connections.
+     communication is attempted. A common mistake is to forget to
+     configure the server to allow TCP/IP connections.
     </para>
 
     <para>
-     Alternatively, you'll get this when attempting Unix-socket
-     communication to a local postmaster:
+     Alternatively, you'll get this when attempting Unix-domain socket
+     communication to a local server:
 <screen>
 psql: could not connect to server: Connection refused
         Is the server running locally and accepting
@@ -439,14 +432,14 @@ psql: could not connect to server: Connection refused
 
     <para>
      The last line is useful in verifying that the client is trying to
-     connect to the right place. If there is in fact no postmaster
+     connect to the right place. If there is in fact no server
      running there, the kernel error message will typically be either
      <computeroutput>Connection refused</computeroutput> or
      <computeroutput>No such file or directory</computeroutput>, as
      illustrated. (It is important to realize that
      <computeroutput>Connection refused</computeroutput> in this context
-     does <emphasis>not</emphasis> mean that the postmaster got your
-     connection request and rejected it -- that case will produce a
+     does <emphasis>not</emphasis> mean that the server got your
+     connection request and rejected it. That case will produce a
      different message, as shown in <xref
      linkend="client-authentication-problems">.) Other error messages
      such as <computeroutput>Connection timed out</computeroutput> may
@@ -493,7 +486,7 @@ search_path = '$user, public'
 </programlisting>
     As you see, options are one per line. The equal sign between name
     and value is optional. Whitespace is insignificant and blank lines
-    are ignored. Hash marks (<quote>#</quote>) introduce comments
+    are ignored. Hash marks (<literal>#</literal>) introduce comments
     anywhere.  Parameter values that are not simple identifiers or
     numbers should be single-quoted.
    </para>
@@ -502,28 +495,27 @@ search_path = '$user, public'
     <indexterm>
      <primary>SIGHUP</primary>
     </indexterm>
-    The configuration file is reread whenever the postmaster receives a
+    The configuration file is reread whenever the <command>postmaster</command> process receives a
     <systemitem>SIGHUP</> signal (which is most easily sent by means of
-    <literal>pg_ctl reload</>). The postmaster also propagates this
-    signal to all currently running backend processes so that existing
+    <literal>pg_ctl reload</>). The <command>postmaster</command> also propagates this
+    signal to all currently running server processes so that existing
     sessions also get the new value. Alternatively, you can send the
-    signal to a single backend process directly.
+    signal to a single server process directly.
    </para>
 
    <para>
     A second way to set these configuration parameters is to give them
-    as a command line option to the postmaster, such as:
+    as a command line option to the <command>postmaster</command>, such as:
 <programlisting>
 postmaster -c log_connections=yes -c syslog=2
 </programlisting>
-    which would have the same effect as the previous example.
     Command-line options override any conflicting settings in
     <filename>postgresql.conf</filename>.
    </para>
 
    <para>
     Occasionally it is also useful to give a command line option to
-    one particular backend session only. The environment variable
+    one particular session only. The environment variable
     <envar>PGOPTIONS</envar> can be used for this purpose on the
     client side:
 <programlisting>
@@ -539,7 +531,7 @@ env PGOPTIONS='-c geqo=off' psql
     Some options can be changed in individual SQL sessions with the
     <command>SET</command> command, for example:
 <screen>
-=&gt; <userinput>SET ENABLE_SEQSCAN TO OFF;</userinput>
+SET ENABLE_SEQSCAN TO OFF;
 </screen>
     See the SQL command language reference for details on the syntax.
    </para>
@@ -549,22 +541,21 @@ env PGOPTIONS='-c geqo=off' psql
     a user or a database.  Whenever a session is started, the default
     settings for the user and database involved are loaded.  The
     commands <literal>ALTER DATABASE</literal> and <literal>ALTER
-    USER</literal>, respectively, are used to configure these settings.
-    Such per-database settings override anything received from the postmaster
-    or the configuration file, and in turn are overridden by per-user
+    USER</literal>, respectively, are used to configure these
+    settings.  Such per-database settings override anything received
+    from the <command>postmaster</command> command-line or the
+    configuration file, and in turn are overridden by per-user
     settings.
    </para>
 
-   <sect2 id="catalog-pg-settings">
-    <title>pg_settings</title>
-  
-    <para>
-     The <structname>pg_settings</structname> virtual table allows display and update
-     of current session run-time parameters. There is one entry for each of the 
-     available parameters provided by <command>SHOW ALL</command>. But it is
-     in a form that allows it to be joined with other relations and have a
-     selection criteria applied.
-    </para>
+   <para>
+    The virtual table <structname>pg_settings</structname> allows
+    displaying and updating session run-time parameters. It contains one
+    row for each configuration parameter; the columns are shown in
+    <xref linkend="runtime-pgsettings-table">.  This form allows the
+    configuration data to be joined with other tables and have a
+    selection criteria applied.
+   </para>
   
     <para>
      An <command>UPDATE</command> performed on <structname>pg_settings</structname>
@@ -577,14 +568,14 @@ env PGOPTIONS='-c geqo=off' psql
      overridden by another <command>UPDATE</command> or <command>SET</command>.
     </para>
   
-    <table>
-    <title>pg_settings Columns</title>
+   <table id="runtime-pgsettings-table">
+    <title><literal>pg_settings</> Columns</title>
   
     <tgroup cols=3>
      <thead>
       <row>
        <entry>Name</entry>
-       <entry>Type</entry>
+       <entry>Data Type</entry>
        <entry>Description</entry>
       </row>
      </thead>
@@ -593,30 +584,27 @@ env PGOPTIONS='-c geqo=off' psql
       <row>
        <entry><literal>name</literal></entry>
        <entry><type>text</type></entry>
-       <entry>The name of a current session run-time parameter</entry>
+       <entry>The name of the run-time configuration parameter</entry>
       </row>
  
       <row>
        <entry><literal>setting</literal></entry>
        <entry><type>text</type></entry>
-       <entry>The value of a current session run-time parameter</entry>
+       <entry>The current value of the run-time configuration parameter</entry>
       </row>
      </tbody>
     </tgroup>
     </table>
 
-   </sect2>
-
    <sect2 id="runtime-config-optimizer">
     <title>Planner and Optimizer Tuning</title>
 
-   <para>
     <variablelist>
      <varlistentry>
       <term><varname>CPU_INDEX_TUPLE_COST</varname> (<type>floating point</type>)</term>
       <listitem>
        <para>
-        Sets the query optimizer's estimate of the cost of processing
+        Sets the query planner's estimate of the cost of processing
 	each index tuple during an index scan. This is measured as a
 	fraction of the cost of a sequential page fetch.
        </para>
@@ -627,7 +615,7 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>CPU_OPERATOR_COST</varname> (<type>floating point</type>)</term>
       <listitem>
        <para>
-        Sets the optimizer's estimate of the cost of processing each
+        Sets the planner's estimate of the cost of processing each
 	operator in a <literal>WHERE</> clause. This is measured as a fraction of
 	the cost of a sequential page fetch.
        </para>
@@ -638,7 +626,7 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>CPU_TUPLE_COST</varname> (<type>floating point</type>)</term>
       <listitem>
        <para>
-        Sets the query optimizer's estimate of the cost of processing
+        Sets the query planner's estimate of the cost of processing
 	each tuple during a query. This is measured as a fraction of
 	the cost of a sequential page fetch.
        </para>
@@ -662,7 +650,7 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>EFFECTIVE_CACHE_SIZE</varname> (<type>floating point</type>)</term>
       <listitem>
        <para>
-        Sets the optimizer's assumption about the effective size of the
+        Sets the planner's assumption about the effective size of the
         disk cache (that is, the portion of the kernel's disk cache that
         will be used for <productname>PostgreSQL</productname> data
         files). This is measured in disk pages, which are normally 8 kB
@@ -818,7 +806,7 @@ env PGOPTIONS='-c geqo=off' psql
         algorithm: The pool size is the number of individuals in one
         population. Valid values are between 128 and 1024. If it is set
         to 0 (the default) a pool size of 2^(QS+1), where QS is the
-        number of FROM items in the query, is taken. The effort is used
+        number of <literal>FROM</> items in the query, is taken. The effort is used
         to calculate a default for generations. Valid values are between
         1 and 80, 40 being the default. Generations specifies the number
         of iterations in the algorithm. The number must be a positive
@@ -868,7 +856,7 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>RANDOM_PAGE_COST</varname> (<type>floating point</type>)</term>
       <listitem>
        <para>
-        Sets the query optimizer's estimate of the cost of a
+        Sets the query planner's estimate of the cost of a
         nonsequentially fetched disk page. This is measured as a
         multiple of the cost of a sequential page fetch. A higher
         value makes it more likely a sequential scan will be used,
@@ -877,12 +865,11 @@ env PGOPTIONS='-c geqo=off' psql
       </listitem>
      </varlistentry>
     </variablelist>
-   </para>
 
    <note>
     <para>
      Unfortunately, there is no well-defined method for determining
-     ideal values for the family of <quote>COST</quote> variables that
+     ideal values for the family of <quote>cost</quote> variables that
      were just described. You are encouraged to experiment and share
      your findings.
     </para>
@@ -893,24 +880,24 @@ env PGOPTIONS='-c geqo=off' psql
    <sect2 id="logging">
     <title>Logging and Debugging</title>
 
-   <para>
     <variablelist>
      <varlistentry>
       <term><varname>CLIENT_MIN_MESSAGES</varname> (<type>string</type>)</term>
       <listitem>
        <para>
-        This controls how much message detail is written to the
+        This controls which message levels are send to the client.
         client.  Valid values are <literal>DEBUG5</>,
         <literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
         <literal>DEBUG1</>, <literal>LOG</>, <literal>NOTICE</>,
-        <literal>WARNING</>, and <literal>ERROR</>.  Later values send
-        less information to the client.  The default is
+        <literal>WARNING</>, and <literal>ERROR</>.  Each level
+        includes all the levels that follow it.  The later the level,
+        the fewer messages are sent.  The default is
         <literal>NOTICE</>.  Note that <literal>LOG</> has a different
-        precedence here than in <literal>LOG_MIN_MESSAGES</>. 
+        rank here than in <literal>LOG_MIN_MESSAGES</>.
        </para>
 
        <para>
-        Here is a summary of the various message types:
+        Here is a list of the various message types:
         <variablelist>
          <varlistentry>
           <term><literal>DEBUG[1-5]</literal></term>
@@ -936,7 +923,7 @@ env PGOPTIONS='-c geqo=off' psql
           <listitem>
            <para>
             Provides information that may be helpful to users, e.g.,
-            truncation of long identifiers and index creation as part
+            truncation of long identifiers and the creation of indexes as part
             of primary keys.
 	   </para>
           </listitem>
@@ -947,7 +934,7 @@ env PGOPTIONS='-c geqo=off' psql
           <listitem>
            <para>
             Provides warnings to the user, e.g., <command>COMMIT</>
-            outside a transaction.
+            outside a transaction block.
 	   </para>
           </listitem>
          </varlistentry>
@@ -956,7 +943,7 @@ env PGOPTIONS='-c geqo=off' psql
           <term><literal>ERROR</literal></term>
           <listitem>
            <para>
-            Reports the error that caused a transaction to abort.
+            Reports an error that caused the current transaction to abort.
 	   </para>
           </listitem>
          </varlistentry>
@@ -975,7 +962,7 @@ env PGOPTIONS='-c geqo=off' psql
           <term><literal>FATAL</literal></term>
           <listitem>
            <para>
-            Reports why a backend session terminated.
+            Reports an error that caused the current session to abort.
 	   </para>
           </listitem>
          </varlistentry>
@@ -984,7 +971,7 @@ env PGOPTIONS='-c geqo=off' psql
           <term><literal>PANIC</literal></term>
           <listitem>
            <para>
-            Reports why all backend sessions restarted.
+            Reports an error that caused all sessions to abort.
 	   </para>
           </listitem>
          </varlistentry>
@@ -1018,14 +1005,15 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>DEBUG_PRETTY_PRINT</varname> (<type>boolean</type>)</term>
       <listitem>
        <para>
-        These flags enable various debugging output to be sent to the
-        server log. For each executed query, print the resulting parse
+        These options enable various debugging output to be sent to the
+        server log. For each executed query, they print the resulting parse
         tree, the query rewriter output, or the execution plan.
         <option>DEBUG_PRETTY_PRINT</option> indents these displays to
         produce a more readable but much longer output format.
        </para>
       </listitem>
      </varlistentry>
+
      <varlistentry>
       <term><varname>EXPLAIN_PRETTY_PRINT</varname> (<type>boolean</type>)</term>
       <listitem>
@@ -1106,16 +1094,17 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>LOG_MIN_MESSAGES</varname> (<type>string</type>)</term>
       <listitem>
        <para>
-        Controls how much message detail is written to the server
-        logs.  Valid values are <literal>DEBUG5</>,
-        <literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
-        <literal>DEBUG1</>, <literal>INFO</>, <literal>NOTICE</>,
-        <literal>WARNING</>, <literal>ERROR</>, <literal>LOG</>,
-        <literal>FATAL</>, and <literal>PANIC</>. Later values send
-        less detail to the logs.  The default is <literal>NOTICE</>.
-        Note that <literal>LOG</> has a different precedence here than
-        in <literal>CLIENT_MIN_MESSAGES</>.  Also see that section for
-        an explanation of the various values.
+        This controls which message levels are written to the server
+        log.  Valid values are <literal>DEBUG5</>, <literal>DEBUG4</>,
+        <literal>DEBUG3</>, <literal>DEBUG2</>, <literal>DEBUG1</>,
+        <literal>INFO</>, <literal>NOTICE</>, <literal>WARNING</>,
+        <literal>ERROR</>, <literal>LOG</>, <literal>FATAL</>, and
+        <literal>PANIC</>.  Each level includes all the levels that
+        follow it.  The later the level, the fewer messages are sent
+        to the log.  The default is <literal>NOTICE</>.  Note that
+        <literal>LOG</> has a different rank here than in
+        <literal>CLIENT_MIN_MESSAGES</>.  Also see that section for an
+        explanation of the various values.
        </para>
 
       </listitem>
@@ -1125,8 +1114,8 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>LOG_PID</varname> (<type>boolean</type>)</term>
       <listitem>
        <para>
-        Prefixes each server message in the log file with the process ID of
-        the backend process. This is useful to sort out which messages
+        Prefixes each message in the server log file with the process ID of
+        the server process. This is useful to sort out which messages
         pertain to which connection. The default is off.  This parameter
         does not affect messages logged via <application>syslog</>, which always contain
         the process ID.
@@ -1185,8 +1174,8 @@ env PGOPTIONS='-c geqo=off' psql
       <listitem>
        <para>
         Enables the collection of statistics on the currently
-        executing command of each backend, along with the time at
-        which that query began execution. This option is off by
+        executing command of each session, along with the time at
+        which that command began execution. This option is off by
         default. Note that even when enabled, this information is only
         visible to the superuser, so it should not represent a
         security risk. This data can be accessed via the
@@ -1201,7 +1190,7 @@ env PGOPTIONS='-c geqo=off' psql
       <term><varname>STATS_ROW_LEVEL</varname> (<type>boolean</type>)</term>
       <listitem>
        <para>
-        Enables the collection of block-level and row-level statistics
+        These enable the collection of block-level and row-level statistics
         on database activity, respectively. These options are off by
         default. This data can be accessed via the
         <structname>pg_stat</structname> and
@@ -1293,13 +1282,11 @@ env PGOPTIONS='-c geqo=off' psql
       </listitem>
      </varlistentry>
     </variablelist>
-   </para>
    </sect2>
 
    <sect2 id="runtime-config-general">
     <title>General Operation</title>
 
-   <para>
     <variablelist>
      <varlistentry>
       <term><varname>AUTOCOMMIT</varname> (<type>boolean</type>)</term>
@@ -1356,10 +1343,11 @@ env PGOPTIONS='-c geqo=off' psql
       <indexterm><primary>Australian time zones</></>
       <listitem>
        <para>
-        If set to true, <literal>CST</literal>, <literal>EST</literal>,
-        and <literal>SAT</literal> are interpreted as Australian
-        time zones rather than as North American Central/Eastern
-        time zones and Saturday. The default is false.
+        If set to true, <literal>ACST</literal>,
+        <literal>CST</literal>, <literal>EST</literal>, and
+        <literal>SAT</literal> are interpreted as Australian time
+        zones rather than as North/South American time zones and
+        Saturday. The default is false.
        </para>
       </listitem>
      </varlistentry>
@@ -1384,7 +1372,7 @@ env PGOPTIONS='-c geqo=off' psql
       <indexterm><primary>character set encoding</></>
       <listitem>
        <para>
-        Sets the client-side encoding for multibyte character sets.
+        Sets the client-side encoding (character set).
 	The default is to use the database encoding.
        </para>
       </listitem>
@@ -1395,8 +1383,8 @@ env PGOPTIONS='-c geqo=off' psql
       <indexterm><primary>date style</></>
       <listitem>
        <para>
-        Sets the display format for dates, as well as the rules for
-	interpreting ambiguous input dates.
+        Sets the display format for date and time values, as well as the rules for
+	interpreting ambiguous date input values.
         The default is <literal>ISO, US</>.
        </para>
       </listitem>
@@ -1410,7 +1398,7 @@ env PGOPTIONS='-c geqo=off' psql
        </para>
 
        <para>
-        If this is on, create users as <literal> username@dbname</>.
+        If this is on, you should create users as <literal>username@dbname</>.
         When <literal>username</> is passed by a connecting client,
         <literal>@</> and the database name is appended to the user
         name and that database-specific user name is looked up by the
@@ -1454,14 +1442,14 @@ env PGOPTIONS='-c geqo=off' psql
         check for deadlock is relatively slow, so the server doesn't run
         it every time it waits for a lock. We (optimistically?) assume
         that deadlocks are not common in production applications and
-        just wait on the lock for a while before starting check for a
+        just wait on the lock for a while before starting the check for a
         deadlock. Increasing this value reduces the amount of time
         wasted in needless deadlock checks, but slows down reporting of
         real deadlock errors. The default is 1000 (i.e., one second),
         which is probably about the smallest value you would want in
         practice. On a heavily loaded server you might want to raise it.
         Ideally the setting should exceed your typical transaction time,
-        so as to improve the odds that the lock will be released before
+        so as to improve the odds that a lock will be released before
         the waiter decides to check for deadlock.
        </para>
       </listitem>
@@ -1504,7 +1492,7 @@ env PGOPTIONS='-c geqo=off' psql
        </para>
 
        <para>
-        The value for dynamic_library_path has to be a colon-separated
+        The value for <varname>DYNAMIC_LIBRARY_PATH</varname> has to be a colon-separated
         list of absolute directory names. If a directory name starts
         with the special value <literal>$libdir</literal>, the
         compiled-in <productname>PostgreSQL</productname> package
@@ -1577,10 +1565,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       <term><varname>FSYNC</varname> (<type>boolean</type>)</term>
       <listitem>
        <para>
-        If this option is on, the <productname>PostgreSQL</> backend
+        If this option is on, the <productname>PostgreSQL</> server
         will use the <function>fsync()</> system call in several places
         to make sure that updates are physically written to disk. This
-        insures that a database installation will recover to a
+        insures that a database cluster will recover to a
         consistent state after an operating system or hardware crash.
         (Crashes of the database server itself are <emphasis>not</>
         related to this.)
@@ -1599,20 +1587,22 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
        </para>
 
        <para>
-        For the above reasons, some administrators always leave it off,
-        some turn it off only for bulk loads, where there is a clear
-        restart point if something goes wrong, and some leave it on just
-        to be on the safe side. Because it is always safe, the default
-        is on. If you trust your operating system, your hardware, and
-        your utility company (or better your UPS), you might want to
-        disable <varname>fsync</varname>.
+        For the above reasons, everyone can decide for himself what to
+        do with the <varname>fsync</> option.  Some administrators
+        always leave it off, some turn it off only for bulk loads,
+        where there is a clear restart point if something goes wrong,
+        and some leave it on just to be on the safe side.  The default
+        is on so that you are on the safe side.  If you trust your
+        operating system, your hardware, and your utility company (or
+        better your battery backup), you can consider disabling
+        <varname>fsync</varname>.
        </para>
 
        <para>
-        It should be noted that the performance penalty of doing
-        <function>fsync</>s is considerably less in
+        It should be noted that the performance penalty of having
+        <varname>fsync</> on considerably less in
         <productname>PostgreSQL</> version 7.1 and later. If you
-        previously suppressed <function>fsync</>s for performance
+        previously suppressed <function>fsync</> for performance
         reasons, you may wish to reconsider your choice.
        </para>
 
@@ -1649,7 +1639,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       <listitem>
        <para>
         Sets the locale to use for formatting monetary amounts, for
-        example with the <function>to_char()</function> family of
+        example with the <function>to_char</function> family of
         functions.  Acceptable values are system-dependent; see <xref
         linkend="locale"> for more information.  If this variable is
         set to the empty string (which is the default) then the value
@@ -1708,7 +1698,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
         Sets the maximum expression nesting depth of the parser. The
         default value is high enough for any normal query, but you can
         raise it if needed. (But if you raise it too high, you run
-        the risk of backend crashes due to stack overflow.)
+        the risk of server crashes due to stack overflow.)
        </para>
       </listitem>
      </varlistentry>
@@ -1717,7 +1707,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       <term><varname>MAX_FILES_PER_PROCESS</varname> (<type>integer</type>)</term>
       <listitem>
        <para>
-        Sets the maximum number of simultaneously open files in each
+        Sets the maximum number of simultaneously open files allowed to each
         server subprocess. The default is 1000. The limit actually used
         by the code is the smaller of this setting and the result of
         <literal>sysconf(_SC_OPEN_MAX)</literal>. Therefore, on systems
@@ -1782,7 +1772,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
        <para>
         When a password is specified in <command>CREATE USER</> or
         <command>ALTER USER</> without writing either <literal>ENCRYPTED</> or
-        <literal>UNENCRYPTED</>, this flag determines whether the password is to be
+        <literal>UNENCRYPTED</>, this option determines whether the password is to be
         encrypted. The default is on (encrypt the password).
        </para>
       </listitem>
@@ -1845,7 +1835,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
      <varlistentry>
       <term><varname>SEARCH_PATH</varname> (<type>string</type>)</term>
       <indexterm><primary>search_path</></>
-      <indexterm><primary>namespaces</></>
+      <indexterm><primary>path</><secondary>for schemas</></>
       <listitem>
        <para>
         This variable specifies the order in which schemas are searched
@@ -1861,7 +1851,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
         The value for <varname>search_path</varname> has to be a comma-separated
         list of schema names.  If one of the list items is
         the special value <literal>$user</literal>, then the schema
-	having the same name as the <function>SESSION_USER</> is substituted, if there
+	having the name returned by <function>SESSION_USER</> is substituted, if there
 	is such a schema.  (If not, <literal>$user</literal> is ignored.)
        </para>
 
@@ -1895,10 +1885,6 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
        </para>
 
        <para>
-	 <indexterm>
-	  <primary>schemas</primary>
-	  <secondary>current schema</secondary>
-	 </indexterm>
         The current effective value of the search path can be examined
 	via the SQL function <function>current_schemas()</>.  This is not
 	quite the same as examining the value of
@@ -1948,12 +1934,12 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
      </varlistentry>
 
      <varlistentry>
-      <term><varname>SILENT_MODE</varname> (<type>bool</type>)</term>
+      <term><varname>SILENT_MODE</varname> (<type>boolean</type>)</term>
       <listitem>
        <para>
         Runs the server silently. If this option is set, the server
-        will automatically run in background and any controlling ttys
-        are disassociated, thus no messages are written to standard
+        will automatically run in background and any controlling terminals
+        are disassociated.  Thus, no messages are written to standard
         output or standard error (same effect as <command>postmaster</>'s <option>-S</option>
         option). Unless some logging system such as
         <application>syslog</> is enabled, using this option is
@@ -1966,24 +1952,24 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       <term><varname>SORT_MEM</varname> (<type>integer</type>)</term>
       <listitem>
        <para>
-	Specifies the amount of memory to be used by internal sorts and
+	Specifies the amount of memory to be used by internal sort operations and
 	hash tables before switching to temporary disk files. The value is
 	specified in kilobytes, and defaults to 1024 kilobytes (1 MB).
-	Note that for a complex query, several sorts or hashes might be
+	Note that for a complex query, several sort or hash operations might be
 	running in parallel; each one will be allowed to use as much memory
 	as this value specifies before it starts to put data into temporary
-	files. Also, each running backend could be doing one or more
-	sorts simultaneously, so the total memory used could be many
-	times the value of <varname>SORT_MEM</varname>. Sorts are used
+        files. Also, several running sessions could be doing
+        sort operations simultaneously.  So the total memory used could be many
+        times the value of <varname>SORT_MEM</varname>. Sort operations are used
 	by <literal>ORDER BY</>, merge joins, and <command>CREATE INDEX</>.
 	Hash tables are used in hash joins, hash-based aggregation, and
-	hash-based processing of <literal>IN</> sub-selects.
+	hash-based processing of <literal>IN</> subqueries.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><varname>SQL_INHERITANCE</varname> (<type>bool</type>)</term>
+      <term><varname>SQL_INHERITANCE</varname> (<type>boolean</type>)</term>
       <indexterm><primary>inheritance</></>
       <listitem>
        <para>
@@ -1992,7 +1978,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
         not included in versions prior to 7.1. If you need the old
         behavior you can set this variable to off, but in the long run
         you are encouraged to change your applications to use the
-        <literal>ONLY</literal> keyword to exclude subtables. See the
+        <literal>ONLY</literal> key word to exclude subtables. See the
         SQL language reference and the &cite-user; for more information about inheritance.
        </para>
       </listitem>
@@ -2024,7 +2010,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
 	ever be active simultaneously.  Whenever the number of active
 	concurrent connections is at least <varname>max_connections</> minus
         <varname>superuser_reserved_connections</varname>, new connections
-	will be accepted only from superuser accounts.
+	will be accepted only for superusers.
        </para>
 
        <para>
@@ -2052,7 +2038,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       <indexterm><primary>time zone</></>
       <listitem>
        <para>
-        Sets the time zone for displaying and interpreting timestamps.
+        Sets the time zone for displaying and interpreting time stamps.
 	The default is to use whatever the system environment
 	specifies as the time zone.
        </para>
@@ -2121,7 +2107,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
         Sets the group owner of the Unix domain socket.  (The owning
         user of the socket is always the user that starts the
         server.)  In combination with the option
-        <option>UNIX_SOCKET_PERMISSIONS</option> this can be used as
+        <varname>UNIX_SOCKET_PERMISSIONS</varname> this can be used as
         an additional access control mechanism for this socket type.
         By default this is the empty string, which uses the default
         group for the current user.  This option can only be set at
@@ -2147,7 +2133,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
         The default permissions are <literal>0777</literal>, meaning
         anyone can connect. Reasonable alternatives are
         <literal>0770</literal> (only user and group, see also under
-        <option>UNIX_SOCKET_GROUP</option>) and <literal>0700</literal>
+        <varname>UNIX_SOCKET_GROUP</varname>) and <literal>0700</literal>
         (only user). (Note that actually for a Unix domain socket, only write
         permission matters and there is no point in setting or revoking
         read or execute permissions.)
@@ -2181,17 +2167,15 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       <term><varname>VIRTUAL_HOST</varname> (<type>string</type>)</term>
       <listitem>
        <para>
-	Specifies the TCP/IP host name or address on which the
-	<application>postmaster</application> is to listen for
-	connections from client applications. Defaults to listening on
-	all configured addresses (including <systemitem
-	class="systemname">localhost</>).
+	Specifies the host name or IP address on which the server is
+	to listen for connections from client applications. The
+	default is to listening on all configured addresses (including
+	<systemitem class="systemname">localhost</>).
        </para>
       </listitem>
      </varlistentry>
 
     </variablelist>
-   </para>
    </sect2>
 
    <sect2 id="runtime-config-wal">
@@ -2248,7 +2232,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
         the given interval. But the delay is just wasted if no other
         transactions become ready to commit. Therefore, the delay is
         only performed if at least <varname>COMMIT_SIBLINGS</varname> other transactions
-        are active at the instant that a backend process has written its commit
+        are active at the instant that a server process has written its commit
         record.
        </para>
       </listitem>
@@ -2281,8 +2265,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       <term><varname>WAL_DEBUG</varname> (<type>integer</type>)</term>
       <listitem>
        <para>
-        If nonzero, turn on WAL-related debugging output on standard
-        error.
+        If nonzero, turn on WAL-related debugging output to the server log.
        </para>
       </listitem>
      </varlistentry>
@@ -2295,7 +2278,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
 	values are
 	<literal>FSYNC</> (call <function>fsync()</> at each commit),
 	<literal>FDATASYNC</> (call <function>fdatasync()</> at each commit),
-	<literal>OPEN_SYNC</> (write WAL files with <function>open()</> option <symbol>O_SYNC</>), or
+	<literal>OPEN_SYNC</> (write WAL files with <function>open()</> option <symbol>O_SYNC</>), and
 	<literal>OPEN_DATASYNC</> (write WAL files with <function>open()</> option <symbol>O_DSYNC</>).
 	Not all of these choices are available on all platforms.
         This option can only be set at server start or in the
@@ -2312,8 +2295,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
    <title>Short Options</title>
 
    <para>
-    For convenience there are also single letter option switches
-    available for many parameters. They are described in <xref
+    For convenience there are also single letter command-line option switches
+    available for some parameters. They are described in <xref
     linkend="runtime-config-short-table">.
    </para>
 
@@ -2373,8 +2356,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
           id="fn.runtime-config-short">
            <para>
             For historical reasons, these options must be passed to
-            the individual backend process via the <option>-o</option>
-            postmaster option, for example,
+            the individual server process via the <option>-o</option>
+            <command>postmaster</command> option, for example,
 <screen>
 $ <userinput>postmaster -o '-S 1024 -s'</userinput>
 </screen>
@@ -2454,14 +2437,14 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
 
    <para>
     The complete lack of these facilities is usually manifested by an
-    <errorname>Illegal system call</> error upon postmaster start. In
+    <errorname>Illegal system call</> error upon server start. In
     that case there's nothing left to do but to reconfigure your
-    kernel -- <productname>PostgreSQL</> won't work without them.
+    kernel.  <productname>PostgreSQL</> won't work without them.
    </para>
 
    <para>
     When <productname>PostgreSQL</> exceeds one of the various hard
-    <acronym>IPC</> limits, the postmaster will refuse to start and
+    <acronym>IPC</> limits, the server will refuse to start and
     should leave an instructive error message describing the problem
     encountered and what to do about it. (See also <xref
     linkend="postmaster-start-failures">.) The relevant kernel
@@ -2489,7 +2472,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
       <row>
        <entry><varname>SHMMAX</></>
        <entry>Maximum size of shared memory segment (bytes)</>
-       <entry>250kB + 8.2 kB * <varname>shared_buffers</> + 14.2 kB * <varname>max_connections</> or infinity</entry>
+       <entry>250 kB + 8.2 kB * <varname>shared_buffers</> + 14.2 kB * <varname>max_connections</> up to infinity</entry>
       </row>
 
       <row>
@@ -2519,19 +2502,19 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
        <row>
         <entry><varname>SEMMNI</></>
         <entry>Maximum number of semaphore identifiers (i.e., sets)</>
-        <entry><literal>&gt;= ceil(max_connections / 16)</literal></>
+        <entry>at least <literal>ceil(max_connections / 16)</literal></>
        </row>
 
        <row>
         <entry><varname>SEMMNS</></>
         <entry>Maximum number of semaphores system-wide</>
-        <entry><literal>ceil(max_connections / 16) * 17</literal> + room for other applications</>
+        <entry><literal>ceil(max_connections / 16) * 17</literal> plus room for other applications</>
        </row>
 
        <row>
         <entry><varname>SEMMSL</></>
         <entry>Maximum number of semaphores per set</>
-        <entry>&gt;= 17</>
+        <entry>at least 17</>
        </row>
 
        <row>
@@ -2543,7 +2526,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
        <row>
         <entry><varname>SEMVMX</></>
         <entry>Maximum value of semaphore</>
-        <entry>&gt;= 255  (The default is often 32767, don't change unless asked to.)</>
+        <entry>at least 255  (The default is often 32767, don't change unless asked to.)</>
        </row>
 
      </tbody>
@@ -2593,8 +2576,8 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
     exist on the system at one time.  Hence this parameter must be at
     least <literal>ceil(max_connections / 16)</>. Lowering the number
     of allowed connections is a temporary workaround for failures,
-    which are usually confusingly worded <quote><errorname>No space
-    left on device</></>, from the function <function>semget()</>.
+    which are usually confusingly worded <errorname>No space
+    left on device</>, from the function <function>semget</>.
    </para>
 
    <para>
@@ -2622,8 +2605,6 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
     for <productname>PostgreSQL</>.
    </para>
 
-
-   <para>
     <variablelist>
 
      <varlistentry>
@@ -2635,8 +2616,8 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
         <para>
          By default, only 4 MB of shared memory is supported. Keep in
          mind that shared memory is not pageable; it is locked in RAM.
-         To increase the number of shared buffers supported by the
-         postmaster, add the following to your kernel configuration
+         To increase the amount of shared memory supported by your
+         system, add the following to your kernel configuration
          file. A <varname>SHMALL</> value of 1024 represents 4 MB of
          shared memory. The following increases the maximum shared
          memory area to 32 MB:
@@ -2644,22 +2625,22 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
 options "SHMALL=8192"
 options "SHMMAX=\(SHMALL*PAGE_SIZE\)"
 </programlisting>
+         For those running 4.1 or later, just make the above changes,
+         recompile the kernel, and reboot.
         </para>
        </formalpara>
 
        <para>
-        For those running 4.1 or later, just make the above changes,
-        recompile the kernel, and reboot. For those running earlier
-        releases, use <command>bpatch</> to find the
-        <varname>sysptsize</> value in the current kernel. This is
-        computed dynamically at boot time.
+        For those running earlier releases, use <command>bpatch</> to
+        find the <varname>sysptsize</> value in the current
+        kernel. This is computed dynamically at boot time.
 <screen>
 $ <userinput>bpatch -r sysptsize</>
 <computeroutput>0x9 = 9</>
 </screen>
         Next, add <varname>SYSPTSIZE</> as a hard-coded value in the
         kernel configuration file. Increase the value you found using
-        <application>bpatch</>. Add 1 for every additional 4 MB of
+        <command>bpatch</>. Add 1 for every additional 4 MB of
         shared memory you desire.
 <programlisting>
 options "SYSPTSIZE=16"
@@ -2670,21 +2651,16 @@ options "SYSPTSIZE=16"
        <formalpara>
         <title>Semaphores</>
         <para>
-         You may need to increase the number of semaphores. By default,
-         <productname>PostgreSQL</> allocates 34 semaphores, which is
-         over half the default system total of 60.
-        </para>
-       </formalpara>
-
-        <para>
-        Set the values you want in your kernel configuration file, e.g.:
+         You may need to increase the number of semaphores. By
+         default, <productname>PostgreSQL</> allocates 34 semaphores,
+         which is over half the default system total of 60.  Set the
+         values you want in your kernel configuration file, e.g.:
 <programlisting>
 options "SEMMNI=40"
 options "SEMMNS=240"
-options "SEMUME=40"
-options "SEMMNU=120"
 </programlisting>
-       </para>
+        </para>
+       </formalpara>
       </listitem>
      </varlistentry>
 
@@ -2719,7 +2695,7 @@ options         SEMMAP=256
         <literal>option</literal> singular.)
        </para>
        <para>
-        You might also want to use the <application>sysctl</> setting to
+        You might also want to use the <command>sysctl</> setting to
         lock shared memory into RAM and prevent it from being paged out
         to swap, e.g. <literal>kern.ipc.shm_use_phys</>.
        </para>
@@ -2766,18 +2742,16 @@ options         SEMMAP=256
        </para>
 
        <para>
-        Alternatively, you can use
-        <citerefentry><refentrytitle>sysctl</refentrytitle>
-        <manvolnum>8</manvolnum></citerefentry>, if available, to
-        control these parameters.  Look for a file called
-        <filename>/etc/sysctl.conf</filename> and add lines like the
-        following to it:
+        Alternatively, you can use <command>sysctl</command>, if
+        available, to control these parameters.  Look for a file
+        called <filename>/etc/sysctl.conf</filename> and add lines
+        like the following to it:
 <programlisting>
 kernel.shmall = 134217728
 kernel.shmmax = 134217728
 </programlisting>
         This file is usually processed at boot time, but
-        <application>sysctl</application> can also be called
+        <command>sysctl</command> can also be called
         explicitly later.
        </para>
 
@@ -2806,8 +2780,6 @@ sysctl -w kern.sysv.shmmni
 sysctl -w kern.sysv.shmseg
 sysctl -w kern.sysv.shmall
 </programlisting>
-        These values have the same meanings on <productname>MacOS</> X
-        as those listed for previous operating systems.
        </para>
       </listitem>
      </varlistentry>
@@ -2820,18 +2792,18 @@ sysctl -w kern.sysv.shmall
        <para>
         In the default configuration, only 512 kB of shared memory per
         segment is allowed, which is about enough for <option>-B 24 -N
-        12</>. To increase the setting, first change directory to
+        12</>. To increase the setting, first change to the directory
         <filename>/etc/conf/cf.d</>. To display the current value of
-        <varname>SHMMAX</>, in bytes, run
+        <varname>SHMMAX</>, run
 <programlisting>
 ./configure -y SHMMAX
 </programlisting>
-        To set a new value for <varname>SHMMAX</>, run:
+        To set a new value for <varname>SHMMAX</>, run
 <programlisting>
 ./configure SHMMAX=<replaceable>value</>
 </programlisting>
         where <replaceable>value</> is the new value you want to use
-        (in bytes). After setting <varname>SHMMAX</>, rebuild the kernel
+        (in bytes). After setting <varname>SHMMAX</>, rebuild the kernel:
 <programlisting>
 ./link_unix
 </programlisting>
@@ -2887,14 +2859,14 @@ set semsys:seminfo_semmsl=32
 /etc/conf/bin/idtune -g SHMMAX
 </programlisting>
         which displays the current, default, minimum, and maximum
-        values, in bytes. To set a new value for <varname>SHMMAX</>,
-        run:
+        values. To set a new value for <varname>SHMMAX</>,
+        run
 <programlisting>
 /etc/conf/bin/idtune SHMMAX <replaceable>value</>
 </programlisting>
         where <replaceable>value</> is the new value you want to use
         (in bytes). After setting <varname>SHMMAX</>, rebuild the
-        kernel
+        kernel:
 <programlisting>
 /etc/conf/bin/idbuild -B
 </programlisting>
@@ -2905,7 +2877,6 @@ set semsys:seminfo_semmsl=32
 
     </variablelist>
 
-   </para>
   </sect2>
 
 
@@ -2927,9 +2898,8 @@ set semsys:seminfo_semmsl=32
     (Bourne shells) or <command>limit</command> (<application>csh</>) is
     used to control the resource limits from the command line. On
     BSD-derived systems the file <filename>/etc/login.conf</filename>
-    controls the various resource limits set during login. See
-    <citerefentry><refentrytitle>login.conf</refentrytitle>
-    <manvolnum>5</manvolnum></citerefentry> for details. The relevant
+    controls the various resource limits set during login. See the
+    operating system documentation for details. The relevant
     parameters are <varname>maxproc</varname>,
     <varname>openfiles</varname>, and <varname>datasize</varname>. For
     example:
@@ -3007,10 +2977,10 @@ default:\
      <term><systemitem>SIGTERM</systemitem></term>
      <listitem>
       <para>
-       After receiving <systemitem>SIGTERM</systemitem>, the postmaster
-       disallows new connections, but lets existing backends end their
-       work normally. It shuts down only after all of the backends
-       terminate normally. This is <firstterm>Smart
+       After receiving <systemitem>SIGTERM</systemitem>, the server
+       disallows new connections, but lets existing sessions end their
+       work normally. It shuts down only after all of the sessions
+       terminate normally. This is the <firstterm>Smart
        Shutdown</firstterm>.
       </para>
      </listitem>
@@ -3020,10 +2990,10 @@ default:\
      <term><systemitem>SIGINT</systemitem></term>
      <listitem>
       <para>
-       The postmaster disallows new connections and sends all existing
-       backends <systemitem>SIGTERM</systemitem>, which will cause them
+       The server disallows new connections and sends all existing
+       server processes <systemitem>SIGTERM</systemitem>, which will cause them
        to abort their current transactions and exit promptly. It then
-       waits for the backends to exit and finally shuts down. This is
+       waits for the server processes to exit and finally shuts down. This is the
        <firstterm>Fast Shutdown</firstterm>.
       </para>
      </listitem>
@@ -3032,10 +3002,11 @@ default:\
     <varlistentry>
      <term><systemitem>SIGQUIT</systemitem></term>
      <listitem>
-      <para> This is <firstterm>Immediate Shutdown</firstterm>, which
-      will cause the postmaster to send a
-      <systemitem>SIGQUIT</systemitem> to all backends and exit
-      immediately (without properly shutting itself down). The backends
+      <para>
+      This is the <firstterm>Immediate Shutdown</firstterm>, which
+      will cause the <command>postmaster</command> process to send a
+      <systemitem>SIGQUIT</systemitem> to all child processes and exit
+      immediately (without properly shutting itself down). The child processes
       likewise exit immediately upon receiving
       <systemitem>SIGQUIT</systemitem>. This will lead to recovery (by
       replaying the WAL log) upon next start-up. This is recommended
@@ -3044,18 +3015,20 @@ default:\
      </listitem>
     </varlistentry>
    </variablelist>
+  </para>
 
    <important>
     <para>
      It is best not to use <systemitem>SIGKILL</systemitem> to shut down
-     the postmaster. This will prevent the postmaster from releasing
+     the server. This will prevent the server from releasing
      shared memory and semaphores, which may then have to be done by
      manually.
     </para>
    </important>
 
-   The <acronym>PID</> of the postmaster process can be found using the
-   <application>ps</application> program, or from the file
+  <para>
+   The <acronym>PID</> of the <command>postmaster</command> process can be found using the
+   <command>ps</command> program, or from the file
    <filename>postmaster.pid</filename> in the data directory. So for
    example, to do a fast shutdown:
 <screen>
@@ -3063,9 +3036,9 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
 </screen>
   </para>
   <para>
-   The program <application>pg_ctl</application> is a shell script
+   The program <command>pg_ctl</command> is a shell script
    that provides a more convenient interface for shutting down the
-   postmaster.
+   server.
   </para>
  </sect1>
 
@@ -3079,21 +3052,21 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
   <para>
    <productname>PostgreSQL</> has native support for using
    <acronym>SSL</> connections to encrypt client/server communications
-   for increased security. This requires
-   <productname>OpenSSL</productname> be installed on both client and
-   server systems and support enabled at build time (see <xref
-   linkend="installation">).
+   for increased security. This requires that
+   <productname>OpenSSL</productname> is installed on both client and
+   server systems and that support in <productname>PostgreSQL</> is
+   enabled at build time (see <xref linkend="installation">).
   </para>
 
   <para>
    With <acronym>SSL</> support compiled in, the
    <productname>PostgreSQL</> server can be started with
-   <acronym>SSL</> support by setting the parameter
+   <acronym>SSL</> enabled by setting the parameter
    <varname>ssl</varname> to on in <filename>postgresql.conf</>. When
    starting in <acronym>SSL</> mode, the server will look for the
    files <filename>server.key</> and <filename>server.crt</> in the
-   data directory.  These files should contain the server private key
-   and certificate respectively. These files must be set up correctly
+   data directory, which should contain the server private key
+   and certificate, respectively. These files must be set up correctly
    before an <acronym>SSL</>-enabled server can start. If the private key is
    protected with a passphrase, the server will prompt for the
    passphrase and will not start until it has been entered.
@@ -3101,7 +3074,7 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
 
   <para>
    The server will listen for both standard and <acronym>SSL</>
-   connections on the same TCP/IP port, and will negotiate with any
+   connections on the same TCP port, and will negotiate with any
    connecting client on whether to use <acronym>SSL</>. See <xref
    linkend="client-authentication"> about how to force the server to
    require use of <acronym>SSL</> for certain connections.
@@ -3120,8 +3093,8 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
 openssl req -new -text -out server.req
 </programlisting>
    Fill out the information that <command>openssl</> asks for. Make sure
-   that you enter the local host name as Common Name; the challenge
-   password can be left blank. The script will generate a key that is
+   that you enter the local host name as <quote>Common Name</>; the challenge
+   password can be left blank. The programm will generate a key that is
    passphrase protected; it will not accept a passphrase that is less
    than four characters long. To remove the passphrase (as you must if
    you want automatic start-up of the server), run the commands
@@ -3146,15 +3119,6 @@ chmod og-rwx server.key
    <primary>ssh</primary>
   </indexterm>
 
-  <note>
-   <title>Acknowledgement</title>
-   <para>
-    Idea taken from an email by Gene Selkov, Jr.
-    (<email>selkovjr@mcs.anl.gov</>) written on 1999-09-08 in response
-    to a question from Eric Marsden.
-   </para>
-  </note>
-
   <para>
    One can use <application>SSH</application> to encrypt the network
    connection between clients and a
@@ -3164,8 +3128,8 @@ chmod og-rwx server.key
 
   <para>
    First make sure that an <application>SSH</application> server is
-   running properly on the same machine as
-   <productname>PostgreSQL</productname> and that you can log in using
+   running properly on the same machine as the
+   <productname>PostgreSQL</productname> server and that you can log in using
    <command>ssh</command> as some user. Then you can establish a secure
    tunnel with a command like this from the client machine:
 <programlisting>
@@ -3173,7 +3137,7 @@ ssh -L 3333:foo.com:5432 joe@foo.com
 </programlisting>
    The first number in the <option>-L</option> argument, 3333, is the
    port number of your end of the tunnel; it can be chosen freely. The
-   second number, 5432, is the remote end of the tunnel -- the port
+   second number, 5432, is the remote end of the tunnel: the port
    number your server is using. The name or the address in between
    the port numbers is the host with the database server you are going
    to connect to. In order to connect to the database server using
@@ -3185,7 +3149,7 @@ psql -h localhost -p 3333 template1
    user <literal>joe@foo.com</literal> and it will use whatever
    authentication procedure was set up for this user. In order for the
    tunnel setup to succeed you must be allowed to connect via
-   <command>ssh</command> as <systemitem>joe@foo.com</systemitem>, just
+   <command>ssh</command> as <literal>joe@foo.com</literal>, just
    as if you had attempted to use <command>ssh</command> to set up a
    terminal session.
   </para>

doc/src/sgml/wal.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.22 2002/11/15 02:44:54 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.23 2003/03/24 14:32:51 petere Exp $ -->
 
 <chapter id="wal">
  <title>Write-Ahead Logging (<acronym>WAL</acronym>)</title>
 
- <note>
-  <title>Author</title>
   <para>
-   Vadim Mikheev and Oliver Elphick
-  </para>
- </note>
-
- <sect1 id="wal-general">
-  <title>General Description</Title>
-
-  <para>
-   <firstterm>Write Ahead Logging</firstterm> (<acronym>WAL</acronym>)
+   <firstterm>Write-Ahead Logging</firstterm> (<acronym>WAL</acronym>)
    is a standard approach to transaction logging.  Its detailed
    description may be found in most (if not all) books about
    transaction processing. Briefly, <acronym>WAL</acronym>'s central
    concept is that changes to data files (where tables and indexes
-   reside) must be written only after those changes have been logged -
+   reside) must be written only after those changes have been logged,
    that is, when log records have been flushed to permanent
-   storage. When we follow this procedure, we do not need to flush
+   storage. If we follow this procedure, we do not need to flush
    data pages to disk on every transaction commit, because we know
    that in the event of a crash we will be able to recover the
    database using the log: any changes that have not been applied to
    the data pages will first be redone from the log records (this is
    roll-forward recovery, also known as REDO) and then changes made by
    uncommitted transactions will be removed from the data pages
-   (roll-backward recovery - UNDO).
+   (roll-backward recovery, UNDO).
   </para>
 
-  <sect2 id="wal-benefits-now">
-   <title>Immediate Benefits of <acronym>WAL</acronym></title>
+  <sect1 id="wal-benefits-now">
+   <title>Benefits of <acronym>WAL</acronym></title>
 
    <para>
     The first obvious benefit of using <acronym>WAL</acronym> is a
@@ -54,11 +44,11 @@
 
     <orderedlist>
      <listitem>
-      <simpara>index tuples pointing to nonexistent table rows</simpara>
+      <simpara>index rows pointing to nonexistent table rows</simpara>
      </listitem>
 
      <listitem>
-      <simpara>index tuples lost in split operations</simpara>
+      <simpara>index rows lost in split operations</simpara>
      </listitem>
 
      <listitem>
@@ -74,22 +64,22 @@
     page content in the log if that is required to ensure page
     consistency for after-crash recovery.
    </para>
-  </sect2>
+  </sect1>
   
-  <sect2 id="wal-benefits-later">
+  <sect1 id="wal-benefits-later">
    <title>Future Benefits</title>
 
    <para>
-    UNDO operation is not implemented. This means that changes
+    The UNDO operation is not implemented. This means that changes
     made by aborted transactions will still occupy disk space and that
-    we still need a permanent <filename>pg_clog</filename> file to hold
-    the status of transactions, since we are not able to re-use
-    transaction identifiers. Once UNDO is implemented,
+    a permanent <filename>pg_clog</filename> file to hold
+    the status of transactions is still needed, since
+    transaction identifiers cannot be reused. Once UNDO is implemented,
     <filename>pg_clog</filename> will no longer be required to be
     permanent; it will be possible to remove
     <filename>pg_clog</filename> at shutdown. (However, the urgency of
     this concern has decreased greatly with the adoption of a segmented
-    storage method for <filename>pg_clog</filename> --- it is no longer
+    storage method for <filename>pg_clog</filename>: it is no longer
     necessary to keep old <filename>pg_clog</filename> entries around
     forever.)
    </para>
@@ -122,7 +112,7 @@
    <para>
     A difficulty standing in the way of realizing these benefits is that
     they require saving <acronym>WAL</acronym> entries for considerable
-    periods of time (eg, as long as the longest possible transaction if
+    periods of time (e.g., as long as the longest possible transaction if
     transaction UNDO is wanted). The present <acronym>WAL</acronym>
     format is extremely bulky since it includes many disk page
     snapshots. This is not a serious concern at present, since the
@@ -130,93 +120,13 @@
     but to achieve these future benefits some sort of compressed
     <acronym>WAL</acronym> format will be needed.
    </para>
-  </sect2>
- </sect1>
-
- <sect1 id="wal-implementation">
-  <title>Implementation</title>
-
-  <para>
-   <acronym>WAL</acronym> is automatically enabled from release 7.1
-   onwards. No action is required from the administrator with the
-   exception of ensuring that the additional disk-space requirements
-   of the <acronym>WAL</acronym> logs are met, and that any necessary
-   tuning is done (see <xref linkend="wal-configuration">).
-  </para>
-
-  <para>
-   <acronym>WAL</acronym> logs are stored in the directory
-   <Filename><replaceable>$PGDATA</replaceable>/pg_xlog</Filename>, as
-   a set of segment files, each 16 MB in size.  Each segment is
-   divided into 8 kB pages. The log record headers are described in
-   <filename>access/xlog.h</filename>; record content is dependent on
-   the type of event that is being logged.  Segment files are given
-   ever-increasing numbers as names, starting at
-   <filename>0000000000000000</filename>.  The numbers do not wrap, at
-   present, but it should take a very long time to exhaust the
-   available stock of numbers.
-  </para>
-
-  <para>
-   The <acronym>WAL</acronym> buffers and control structure are in
-   shared memory, and are handled by the backends; they are protected
-   by lightweight locks.  The demand on shared memory is dependent on the
-   number of buffers.  The default size of the <acronym>WAL</acronym>
-   buffers is 8 buffers of 8 kB each, or 64 kB total.
-  </para>
-
-  <para>
-   It is of advantage if the log is located on another disk than the
-   main database files.  This may be achieved by moving the directory,
-   <filename>pg_xlog</filename>, to another location (while the
-   postmaster is shut down, of course) and creating a symbolic link
-   from the original location in <replaceable>$PGDATA</replaceable> to
-   the new location.
-  </para>
-
-  <para>
-   The aim of <acronym>WAL</acronym>, to ensure that the log is
-   written before database records are altered, may be subverted by
-   disk drives that falsely report a successful write to the kernel,
-   when, in fact, they have only cached the data and not yet stored it
-   on the disk.  A power failure in such a situation may still lead to
-   irrecoverable data corruption.  Administrators should try to ensure
-   that disks holding <productname>PostgreSQL</productname>'s
-   log files do not make such false reports.
-  </para>
-
-  <sect2 id="wal-recovery">
-   <title>Database Recovery with <acronym>WAL</acronym></title>
-
-   <para>
-    After a checkpoint has been made and the log flushed, the
-    checkpoint's position is saved in the file
-    <filename>pg_control</filename>. Therefore, when recovery is to be
-    done, the backend first reads <filename>pg_control</filename> and
-    then the checkpoint record; then it performs the REDO operation by
-    scanning forward from the log position indicated in the checkpoint
-    record.
-    Because the entire content of data pages is saved in the log on the
-    first page modification after a checkpoint, all pages changed since
-    the checkpoint will be restored to a consistent state.
-   </para>
-
-   <para>
-    Using <filename>pg_control</filename> to get the checkpoint
-    position speeds up the recovery process, but to handle possible
-    corruption of <filename>pg_control</filename>, we should actually
-    implement the reading of existing log segments in reverse order --
-    newest to oldest -- in order to find the last checkpoint.  This has
-    not been implemented, yet.
-   </para>
-  </sect2>
- </sect1>
+  </sect1>
 
  <sect1 id="wal-configuration">
   <title><acronym>WAL</acronym> Configuration</title>
 
   <para>
-   There are several <acronym>WAL</acronym>-related parameters that
+   There are several <acronym>WAL</acronym>-related configuration parameters that
    affect database performance. This section explains their use.
    Consult <xref linkend="runtime-config"> for details about setting
    configuration parameters.
@@ -232,25 +142,25 @@
    log (known as the redo record) it should start the REDO operation,
    since any changes made to data files before that record are already
    on disk. After a checkpoint has been made, any log segments written
-   before the undo records are no longer needed and can be recycled or
+   before the redo records are no longer needed and can be recycled or
    removed. (When <acronym>WAL</acronym>-based <acronym>BAR</acronym> is
    implemented, the log segments would be archived before being recycled
    or removed.)
   </para>
 
   <para>
-   The postmaster spawns a special backend process every so often
+   The server spawns a special process every so often
    to create the next checkpoint.  A checkpoint is created every
-   <varname>CHECKPOINT_SEGMENTS</varname> log segments, or every
-   <varname>CHECKPOINT_TIMEOUT</varname> seconds, whichever comes first.
+   <varname>checkpoint_segments</varname> log segments, or every
+   <varname>checkpoint_timeout</varname> seconds, whichever comes first.
    The default settings are 3 segments and 300 seconds respectively.
    It is also possible to force a checkpoint by using the SQL command
    <command>CHECKPOINT</command>.
   </para>
 
   <para>
-   Reducing <varname>CHECKPOINT_SEGMENTS</varname> and/or
-   <varname>CHECKPOINT_TIMEOUT</varname> causes checkpoints to be done
+   Reducing <varname>checkpoint_segments</varname> and/or
+   <varname>checkpoint_timeout</varname> causes checkpoints to be done
    more often. This allows faster after-crash recovery (since less work
    will need to be redone). However, one must balance this against the
    increased cost of flushing dirty data pages more often. In addition,
@@ -262,15 +172,15 @@
   </para>
 
   <para>
-   There will be at least one 16MB segment file, and will normally 
-   not be more than 2 * <varname>CHECKPOINT_SEGMENTS</varname>
-   + 1 files.  You can use this to estimate space requirements for 
-   WAL.  Ordinarily, when old log segment files are no longer needed, 
-   they are recycled (renamed to become the next sequential future 
-   segments). If, due to a short-term peak of log output rate, there 
-   are more than 2 * <varname>CHECKPOINT_SEGMENTS</varname> + 1 segment files, 
-   the unneeded segment files will be deleted instead of recycled until the
-   system gets back under this limit.
+   There will be at least one 16 MB segment file, and will normally
+   not be more than 2 * <varname>checkpoint_segments</varname> + 1
+   files.  You can use this to estimate space requirements for WAL.
+   Ordinarily, when old log segment files are no longer needed, they
+   are recycled (renamed to become the next segments in the numbered
+   sequence). If, due to a short-term peak of log output rate, there
+   are more than 2 * <varname>checkpoint_segments</varname> + 1
+   segment files, the unneeded segment files will be deleted instead
+   of recycled until the system gets back under this limit.
   </para>
 
   <para>
@@ -282,7 +192,7 @@
    to write (move to kernel cache) a few filled <acronym>WAL</acronym>
    buffers. This is undesirable because <function>LogInsert</function>
    is used on every database low level modification (for example,
-   tuple insertion) at a time when an exclusive lock is held on
+   row insertion) at a time when an exclusive lock is held on
    affected data pages, so the operation needs to be as fast as
    possible.  What is worse, writing <acronym>WAL</acronym> buffers may
    also force the creation of a new log segment, which takes even more
@@ -294,8 +204,8 @@
    not occur often enough to prevent <acronym>WAL</acronym> buffers
    being written by <function>LogInsert</function>. On such systems
    one should increase the number of <acronym>WAL</acronym> buffers by
-   modifying the <filename>postgresql.conf</filename> <varname>
-   WAL_BUFFERS</varname> parameter. The default number of <acronym>
+   modifying the configuration parameter <varname>wal_buffers</varname>.
+   The default number of <acronym>
    WAL</acronym> buffers is 8.  Increasing this value will 
    correspondingly increase shared memory usage.
   </para>
@@ -305,47 +215,122 @@
    buffers to disk using the operating system <literal>sync()</> call.
    Busy servers may fill checkpoint segment files too quickly,
    causing excessive checkpointing. If such forced checkpoints happen
-   more frequently than <varname>CHECKPOINT_WARNING</varname> seconds, 
+   more frequently than <varname>checkpoint_warning</varname> seconds, 
    a message, will be output to the server logs recommending increasing 
-   <varname>CHECKPOINT_SEGMENTS</varname>.
+   <varname>checkpoint_segments</varname>.
   </para>
 
   <para>
-   The <varname>COMMIT_DELAY</varname> parameter defines for how many
-   microseconds the backend will sleep after writing a commit
+   The <varname>commit_delay</varname> parameter defines for how many
+   microseconds the server process will sleep after writing a commit
    record to the log with <function>LogInsert</function> but before
    performing a <function>LogFlush</function>. This delay allows other
-   backends to add their commit records to the log so as to have all
+   server processes to add their commit records to the log so as to have all
    of them flushed with a single log sync. No sleep will occur if <varname>fsync</varname>
-   is not enabled or if fewer than <varname>COMMIT_SIBLINGS</varname>
-   other backends are not currently in active transactions; this avoids
-   sleeping when it's unlikely that any other backend will commit soon.
+   is not enabled or if fewer than <varname>commit_siblings</varname>
+   other sessons are currently in active transactions; this avoids
+   sleeping when it's unlikely that any other session will commit soon.
    Note that on most platforms, the resolution of a sleep request is
-   ten milliseconds, so that any nonzero <varname>COMMIT_DELAY</varname>
-   setting between 1 and 10000 microseconds will have the same effect.
+   ten milliseconds, so that any nonzero <varname>commit_delay</varname>
+   setting between 1 and 10000 microseconds would have the same effect.
    Good values for these parameters are not yet clear; experimentation
    is encouraged.
   </para>
 
   <para>
-   The <varname>WAL_SYNC_METHOD</varname> parameter determines how
+   The <varname>wal_sync_method</varname> parameter determines how
    <productname>PostgreSQL</productname> will ask the kernel to force
     WAL updates out to disk. 
    All the options should be the same as far as reliability goes,
    but it's quite platform-specific which one will be the fastest.
-   Note that this parameter is irrelevant if <varname>FSYNC</varname>
+   Note that this parameter is irrelevant if <varname>fsync</varname>
    has been turned off.
   </para>
 
   <para>
-   Setting the <varname>WAL_DEBUG</varname> parameter to any nonzero
+   Setting the <varname>wal_debug</varname> parameter to any nonzero
    value will result in each <function>LogInsert</function> and
    <function>LogFlush</function> <acronym>WAL</acronym> call being
-   logged to standard error.  At present, it makes no difference what
+   logged to the server log.  At present, it makes no difference what
    the nonzero value is.  This option may be replaced by a more
    general mechanism in the future.
   </para>
  </sect1>
+
+ <sect1 id="wal-internals">
+  <title>Internals</title>
+
+  <para>
+   <acronym>WAL</acronym> is automatically enabled; no action is
+   required from the administrator except ensuring that the additional
+   disk-space requirements of the <acronym>WAL</acronym> logs are met,
+   and that any necessary tuning is done (see <xref
+   linkend="wal-configuration">).
+  </para>
+
+  <para>
+   <acronym>WAL</acronym> logs are stored in the directory
+   <filename>pg_xlog</filename> under the data directory, as a set of
+   segment files, each 16 MB in size.  Each segment is divided into 8
+   kB pages. The log record headers are described in
+   <filename>access/xlog.h</filename>; the record content is dependent
+   on the type of event that is being logged.  Segment files are given
+   ever-increasing numbers as names, starting at
+   <filename>0000000000000000</filename>.  The numbers do not wrap, at
+   present, but it should take a very long time to exhaust the
+   available stock of numbers.
+  </para>
+
+  <para>
+   The <acronym>WAL</acronym> buffers and control structure are in
+   shared memory and are handled by the server child processes; they
+   are protected by lightweight locks.  The demand on shared memory is
+   dependent on the number of buffers.  The default size of the
+   <acronym>WAL</acronym> buffers is 8 buffers of 8 kB each, or 64 kB
+   total.
+  </para>
+
+  <para>
+   It is of advantage if the log is located on another disk than the
+   main database files.  This may be achieved by moving the directory
+   <filename>pg_xlog</filename> to another location (while the server
+   is shut down, of course) and creating a symbolic link from the
+   original location in the main data directory to the new location.
+  </para>
+
+  <para>
+   The aim of <acronym>WAL</acronym>, to ensure that the log is
+   written before database records are altered, may be subverted by
+   disk drives that falsely report a successful write to the kernel,
+   when, in fact, they have only cached the data and not yet stored it
+   on the disk.  A power failure in such a situation may still lead to
+   irrecoverable data corruption.  Administrators should try to ensure
+   that disks holding <productname>PostgreSQL</productname>'s
+   <acronym>WAL</acronym> log files do not make such false reports.
+  </para>
+
+  <para>
+   After a checkpoint has been made and the log flushed, the
+   checkpoint's position is saved in the file
+   <filename>pg_control</filename>. Therefore, when recovery is to be
+   done, the server first reads <filename>pg_control</filename> and
+   then the checkpoint record; then it performs the REDO operation by
+   scanning forward from the log position indicated in the checkpoint
+   record.  Because the entire content of data pages is saved in the
+   log on the first page modification after a checkpoint, all pages
+   changed since the checkpoint will be restored to a consistent
+   state.
+  </para>
+
+  <para>
+   Using <filename>pg_control</filename> to get the checkpoint
+   position speeds up the recovery process, but to handle possible
+   corruption of <filename>pg_control</filename>, we should actually
+   implement the reading of existing log segments in reverse order --
+   newest to oldest -- in order to find the last checkpoint.  This has
+   not been implemented, yet.
+  </para>
+ </sect1>
 </chapter>
 
 <!-- Keep this comment at the end of the file