This patch makes the following changes to the documentation:

- more work from the SGML police

- some grammar improvements: rewriting a paragraph or two, replacing
contractions where (IMHO) appropriate

- fix missing utility commands in lock mode docs

- improve CLUSTER, REINDEX, SET SESSION AUTHORIZATION ref pages

Neil Conway

doc/src/sgml/advanced.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.31 2002/11/11 20:14:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.32 2003/02/19 04:06:27 momjian Exp $
 -->
 
  <chapter id="tutorial-advanced">
@@ -41,7 +41,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.31 2002/11/11 20:14:02 pe
    <para>
     Refer back to the queries in <xref linkend="tutorial-join">.
     Suppose the combined listing of weather records and city location
-    is of particular interest to your application, but you don't want
+    is of particular interest to your application, but you do not want
     to type the query each time you need it.  You can create a
     <firstterm>view</firstterm> over the query, which gives a name to
     the query that you can refer to like an ordinary table.
@@ -232,7 +232,7 @@ COMMIT;
    </para>
 
    <para>
-    If, partway through the transaction, we decide we don't want to
+    If, partway through the transaction, we decide we do not want to
     commit (perhaps we just noticed that Alice's balance went negative),
     we can issue the command <command>ROLLBACK</> instead of
     <command>COMMIT</>, and all our updates so far will be canceled.
@@ -240,7 +240,7 @@ COMMIT;
 
    <para>
     <productname>PostgreSQL</> actually treats every SQL statement as being
-    executed within a transaction.  If you don't issue a <command>BEGIN</>
+    executed within a transaction.  If you do not issue a <command>BEGIN</>
     command, 
     then each individual statement has an implicit <command>BEGIN</> and
     (if successful) <command>COMMIT</> wrapped around it.  A group of

doc/src/sgml/arch-dev.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.17 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.18 2003/02/19 04:06:27 momjian Exp $
 -->
 
  <chapter id="overview">
@@ -17,15 +17,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.17 2003/01/19 00:13:28 mo
 
   <para>
    This chapter gives an overview of the internal structure of the
-   backend of <productname>PostgreSQL</productname>.
-   After having read the following sections you
-   should have an idea of how a query is processed. Don't expect a
-   detailed description here (I think such a description dealing with
-   all data structures and functions used within <productname>PostgreSQL</productname>
-   would exceed 1000
-   pages!). This chapter is intended to help understanding the general
-   control and data flow within the backend from receiving a query to
-   sending the results.
+   backend of <productname>PostgreSQL</productname>.  After having
+   read the following sections you should have an idea of how a query
+   is processed. This chapter does not aim to provide a detailed
+   description of the internal operation of
+   <productname>PostgreSQL</productname>, as such a document would be
+   very extensive. Rather, this chapter is intended to help the reader
+   understand the general sequence of operations that occur within the
+   backend from the point at which a query is received, to the point
+   when the results are returned to the client.
   </para>
 
   <sect1 id="query-path">
@@ -118,23 +118,25 @@ $Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.17 2003/01/19 00:13:28 mo
    <title>How Connections are Established</title>
 
    <para>
-    <productname>PostgreSQL</productname> is implemented using a simple "process per-user"
-    client/server model.  In this model there is one <firstterm>client process</firstterm>
-    connected to exactly one <firstterm>server process</firstterm>.
-    As we don't know <foreignphrase>per se</foreignphrase> 
-    how many connections will be made, we have to use a <firstterm>master process</firstterm>
-    that spawns a new server process every time a connection is
-    requested. This master process is called <literal>postmaster</literal> and 
-    listens at a specified TCP/IP port for incoming connections. Whenever
-    a request for a connection is detected the <literal>postmaster</literal> process
-    spawns a new server process called <literal>postgres</literal>. The server
-    tasks (<literal>postgres</literal> processes) communicate with each other using
-    <firstterm>semaphores</firstterm> and <firstterm>shared memory</firstterm>
-    to ensure data integrity
-    throughout concurrent data access. Figure
-    \ref{connection} illustrates the interaction of the master process 
-    <literal>postmaster</literal> the server process <literal>postgres</literal> and a client
-    application. 
+    <productname>PostgreSQL</productname> is implemented using a
+    simple "process per-user" client/server model.  In this model
+    there is one <firstterm>client process</firstterm> connected to
+    exactly one <firstterm>server process</firstterm>.  As we do not
+    know ahead of time how many connections will be made, we have to
+    use a <firstterm>master process</firstterm> that spawns a new
+    server process every time a connection is requested. This master
+    process is called <literal>postmaster</literal> and listens at a
+    specified TCP/IP port for incoming connections. Whenever a request
+    for a connection is detected the <literal>postmaster</literal>
+    process spawns a new server process called
+    <literal>postgres</literal>. The server tasks
+    (<literal>postgres</literal> processes) communicate with each
+    other using <firstterm>semaphores</firstterm> and
+    <firstterm>shared memory</firstterm> to ensure data integrity
+    throughout concurrent data access. Figure \ref{connection}
+    illustrates the interaction of the master process
+    <literal>postmaster</literal> the server process
+    <literal>postgres</literal> and a client application.
    </para>
 
    <para>
@@ -686,7 +688,7 @@ current context are performed.
      for the <literal>varno</literal> fields in the
      <literal>VAR</literal> nodes appearing in the <literal>mergeclauses</literal> list (and also in the
      <literal>targetlist</literal>) mean that not the tuples of the current node should be
-     considered but the tuples of the next "deeper" nodes (i.e. the top
+     considered but the tuples of the next <quote>deeper</quote> nodes (i.e. the top
      nodes of the subplans) should be used instead.
     </para>
 

doc/src/sgml/datatype.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.114 2003/02/19 03:48:10 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.115 2003/02/19 04:06:27 momjian Exp $
 -->
 
  <chapter id="datatype">
@@ -895,7 +895,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
     actual string, and in case of <type>character</type> plus the
     padding. Long strings are compressed by the system automatically, so
     the physical requirement on disk may be less. Long values are also
-    stored in background tables so they don't interfere with rapid
+    stored in background tables so they do not interfere with rapid
     access to the shorter column values. In any case, the longest
     possible character string that can be stored is about 1 GB. (The
     maximum value that will be allowed for <replaceable>n</> in the data

doc/src/sgml/ddl.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.11 2003/02/19 03:13:24 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.12 2003/02/19 04:06:27 momjian Exp $ -->
 
 <chapter id="ddl">
  <title>Data Definition</title>
@@ -115,8 +115,8 @@ CREATE TABLE products (
   </para>
 
   <para>
-   If you don't need a table anymore, you can remove it using the
-   <literal>DROP TABLE</literal> command.  For example:
+   If you no longer need a table, you can remove it using the
+   <command>DROP TABLE</command> command.  For example:
 <programlisting>
 DROP TABLE my_first_table;
 DROP TABLE products;
@@ -718,7 +718,7 @@ CREATE TABLE order_items (
 
    <para>
     We know that the foreign keys disallow creation of orders that
-    don't relate to any products.  But what if a product is removed
+    do not relate to any products.  But what if a product is removed
     after an order is created that references it?  SQL allows you to
     specify that as well.  Intuitively, we have a few options:
     <itemizedlist spacing="compact">
@@ -759,7 +759,7 @@ CREATE TABLE order_items (
    <para>
     Restricting and cascading deletes are the two most common options.
     <literal>RESTRICT</literal> can also be written as <literal>NO
-    ACTION</literal> and it's also the default if you don't specify
+    ACTION</literal> and it's also the default if you do not specify
     anything.  There are two other options for what should happen with
     the foreign key columns when a primary key is deleted:
     <literal>SET NULL</literal> and <literal>SET DEFAULT</literal>.
@@ -1602,7 +1602,7 @@ REVOKE CREATE ON public FROM PUBLIC;
    <para>
     In the SQL standard, the notion of objects in the same schema
     being owned by different users does not exist.  Moreover, some
-    implementations don't allow you to create schemas that have a
+    implementations do not allow you to create schemas that have a
     different name than their owner.  In fact, the concepts of schema
     and user are nearly equivalent in a database system that
     implements only the basic schema support specified in the
@@ -1686,7 +1686,7 @@ NOTICE:  constraint $1 on table orders depends on table products
 ERROR:  Cannot drop table products because other objects depend on it
         Use DROP ... CASCADE to drop the dependent objects too
 </screen>
-   The error message contains a useful hint: If you don't want to
+   The error message contains a useful hint: if you do not want to
    bother deleting all the dependent objects individually, you can run
 <screen>
 DROP TABLE products CASCADE;

doc/src/sgml/docguide.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.42 2002/07/28 15:22:20 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.43 2003/02/19 04:06:27 momjian Exp $ -->
 
 <appendix id="docguide">
  <title>Documentation</title>
@@ -1327,7 +1327,7 @@ End:
       <listitem>
        <para>
         If the program uses 0 for success and non-zero for failure,
-        then you don't need to document it.  If there is a meaning
+        then you do not need to document it.  If there is a meaning
         behind the different non-zero exit codes, list them here.
        </para>
       </listitem>

doc/src/sgml/mvcc.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.32 2003/01/11 00:00:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.33 2003/02/19 04:06:28 momjian Exp $
 -->
 
  <chapter id="mvcc">
@@ -38,9 +38,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.32 2003/01/11 00:00:02 petere
    </para>
 
    <para>
-    The main difference between multiversion and lock models is that
-    in <acronym>MVCC</acronym> locks acquired for querying (reading)
-    data don't conflict with locks acquired for writing data, and so
+    The main advantage to using the <acronym>MVCC</acronym> model of
+    concurrency control rather than locking is that in
+    <acronym>MVCC</acronym> locks acquired for querying (reading) data
+    do not conflict with locks acquired for writing data, and so
     reading never blocks writing and writing never blocks reading.
    </para>
 
@@ -437,10 +438,10 @@ ERROR:  Can't serialize access due to concurrent update
 	</para>
 
 	<para>
-	 The <command>SELECT</command> command acquires a
-	 lock of this mode on referenced tables.  In general, any query
-	 that only reads a table and does not modify it will acquire
-	 this lock mode.
+	 The commands <command>SELECT</command> and
+	 <command>ANALYZE</command> acquire a lock of this mode on
+	 referenced tables.  In general, any query that only reads a table
+	 and does not modify it will acquire this lock mode.
 	</para>
        </listitem>
       </varlistentry>
@@ -586,9 +587,10 @@ ERROR:  Can't serialize access due to concurrent update
 
 	<para>
 	 Acquired by the <command>ALTER TABLE</command>, <command>DROP
-	 TABLE</command>, and <command>VACUUM FULL</command> commands.
-	 This is also the default lock mode for <command>LOCK TABLE</command>
-         statements that do not specify a mode explicitly.
+	 TABLE</command>, <command>REINDEX</command>,
+	 <command>CLUSTER</command>, and <command>VACUUM FULL</command>
+	 commands.  This is also the default lock mode for <command>LOCK
+	 TABLE</command> statements that do not specify a mode explicitly.
 	</para>
        </listitem>
       </varlistentry>
@@ -612,7 +614,7 @@ ERROR:  Can't serialize access due to concurrent update
      A row-level lock on a specific row is automatically acquired when the
      row is updated (or deleted or marked for update).  The lock is held
      until the transaction commits or rolls back.
-     Row-level locks don't affect data
+     Row-level locks do not affect data
      querying; they block <emphasis>writers to the same row</emphasis>
      only.  To acquire a row-level lock on a row without actually
      modifying the row, select the row with <command>SELECT FOR
@@ -726,7 +728,7 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
 
    <para>
     Because readers in <productname>PostgreSQL</productname>
-    don't lock data, regardless of
+    do not lock data, regardless of
     transaction isolation level, data read by one transaction can be
     overwritten by another concurrent transaction. In other words,
     if a row is returned by <command>SELECT</command> it doesn't mean that

doc/src/sgml/page.sgml

@@ -196,9 +196,10 @@ data. Empty in ordinary tables.</entry>
  
  <para>
  
-  The final section is the "special section" which may contain anything the
-  access method wishes to store. Ordinary tables do not use this at all
-  (indicated by setting <structfield>pd_special</> to equal the pagesize).
+  The final section is the <quote>special section</quote> which may
+  contain anything the access method wishes to store. Ordinary tables
+  do not use this at all (indicated by setting
+  <structfield>pd_special</> to equal the pagesize).
   
  </para>
  

doc/src/sgml/plpgsql.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.14 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.15 2003/02/19 04:06:28 momjian Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -578,7 +578,7 @@ user_id   users.user_id%TYPE;
         </para>
 
         <para>
-         By using <type>%TYPE</type> you don't need to know
+         By using <type>%TYPE</type> you do not need to know
          the data type of the structure you are referencing,
          and most important, if the data type of the
          referenced item changes in the future (e.g: you
@@ -1649,7 +1649,7 @@ END LOOP;
     up a <firstterm>cursor</> that encapsulates the query, and then read
     the query result a few rows at a time. One reason for doing this is
     to avoid memory overrun when the result contains a large number of
-    rows. (However, <application>PL/pgSQL</> users don't normally need
+    rows. (However, <application>PL/pgSQL</> users do not normally need
     to worry about that, since FOR loops automatically use a cursor
     internally to avoid memory problems.) A more interesting usage is to
     return a reference to a cursor that it has created, allowing the

doc/src/sgml/ref/alter_table.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.55 2003/02/13 05:19:59 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.56 2003/02/19 04:06:28 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -367,7 +367,7 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
     default and NOT NULL clauses for the new column are not supported.
     The new column always comes into being with all values NULL.
     You can use the <literal>SET DEFAULT</literal> form
-    of <command>ALTER TABLE</command> to set the default afterwards.
+    of <command>ALTER TABLE</command> to set the default afterward.
     (You may also want to update the already existing rows to the
     new default value, using
     <xref linkend="sql-update" endterm="sql-update-title">.)
@@ -392,19 +392,21 @@ VACUUM FULL table;
    </para>
 
    <para>
-    If a table has any descendant tables, it is not permitted to ADD or
-    RENAME a column in the parent table without doing the same to the
-    descendants --- that is, ALTER TABLE ONLY will be rejected.  This
-    ensures that the descendants always have columns matching the parent.
+    If a table has any descendant tables, it is not permitted to ADD
+    or RENAME a column in the parent table without doing the same to
+    the descendants --- that is, <command>ALTER TABLE ONLY</command>
+    will be rejected.  This ensures that the descendants always have
+    columns matching the parent.
    </para>
 
    <para>
-    A recursive DROP COLUMN operation will remove a descendant table's column
-    only if the descendant does not inherit that column from any other
-    parents and never had an independent definition of the column.
-    A nonrecursive DROP COLUMN (i.e., ALTER TABLE ONLY ... DROP COLUMN)
-    never removes any descendant columns, but instead marks them as
-    independently defined rather than inherited.
+    A recursive <literal>DROP COLUMN</literal> operation will remove a
+    descendant table's column only if the descendant does not inherit
+    that column from any other parents and never had an independent
+    definition of the column.  A nonrecursive <literal>DROP
+    COLUMN</literal> (i.e., <command>ALTER TABLE ONLY ... DROP
+    COLUMN</command>) never removes any descendant columns, but
+    instead marks them as independently defined rather than inherited.
    </para>
 
    <para>

doc/src/sgml/ref/cluster.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.23 2002/12/30 18:42:12 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.24 2003/02/19 04:06:28 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -117,11 +117,19 @@ CLUSTER
    <command>CLUSTER</command> without any parameter re-clusters all the tables
    in the
    current database that the calling user owns, or all tables if called
-   by a superuser.  (Never-clustered tables are not touched.)  This
+   by a superuser.  (Never-clustered tables are not included.)  This
    form of <command>CLUSTER</command> cannot be called from inside a
    transaction or function.
   </para>
 
+  <para>
+   When a table is being clustered, an <literal>ACCESS
+   EXCLUSIVE</literal> lock is acquired on it. This prevents any other
+   database operations (both reads and writes) from preceding on the
+   table until the <command>CLUSTER</command> is finished. See the
+   &cite-user; for more information on database locking.
+  </para>
+
   <refsect2 id="R2-SQL-CLUSTER-3">
    <refsect2info>
     <date>1998-09-08</date>
@@ -159,8 +167,9 @@ CLUSTER
    </para>
 
    <para>
-    <command>CLUSTER</command> preserves GRANT, inheritance, index, foreign
-    key, and other ancillary information about the table.
+    <command>CLUSTER</command> preserves <command>GRANT</command>,
+    inheritance, index, foreign key, and other ancillary information
+    about the table.
    </para>
 
    <para>
@@ -212,13 +221,15 @@ SELECT <replaceable class="parameter">columnlist</replaceable> INTO TABLE <repla
    Usage
   </title>
   <para>
-   Cluster the employees relation on the basis of its ID attribute:
+   Cluster the <literal>employees</literal> relation on the basis of
+   its ID attribute:
   </para>
   <programlisting>
 CLUSTER emp_ind ON emp;
   </programlisting>
   <para>
-   Cluster the employees relation using the same index that was used before:
+   Cluster the <literal>employees</literal> relation using the same
+   index that was used before:
   </para>
   <programlisting>
 CLUSTER emp;
@@ -248,6 +259,14 @@ CLUSTER;
    </para>
   </refsect2>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-clusterdb" endterm="app-clusterdb-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/clusterdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.6 2003/02/13 05:37:43 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.7 2003/02/19 04:06:28 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -37,7 +37,7 @@ PostgreSQL documentation
    in a <productname>PostgreSQL</productname> database.  It finds tables
    that have previously been clustered, and clusters them again on the same
    index that was last used.  Tables that have never been clustered are not
-   touched.
+   affected.
   </para>
 
   <para>

doc/src/sgml/ref/reindex.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.14 2002/11/17 23:43:32 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.15 2003/02/19 04:06:28 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -38,8 +38,9 @@ REINDEX { DATABASE | TABLE | INDEX } <replaceable class="PARAMETER">name</replac
       <term>DATABASE</term>
       <listitem>
        <para>
-	Recreate all system indexes of a specified database.
-	(User-table indexes are not included.)
+	Recreate all system indexes of a specified database. Indexes on
+	user tables are not included. This form of <command>REINDEX</> can
+	only be used in standalone mode (see below).
        </para>
       </listitem>
      </varlistentry>
@@ -116,16 +117,35 @@ REINDEX
    Description
   </title>
   <para>
-   <command>REINDEX</command> is used to rebuild corrupted indexes.
-   Although in theory this should never be necessary, in practice
-   indexes may become corrupted due to software bugs or hardware
-   failures.  <command>REINDEX</command> provides a recovery method.
-  </para>
+   <command>REINDEX</command> rebuilds an index based on the data
+   stored in the table, replacing the old copy of the index. There are
+   two main reasons to use <command>REINDEX</command>:
 
-  <para>
-   <command>REINDEX</command> also removes certain dead index pages that
-   can't be reclaimed any other way. See the "Routine Reindexing"
-   section in the manual for more information.
+   <orderedlist>
+    <listitem>
+     <para>
+      An index has become corrupted, and no longer contains valid
+      data. Although in theory this should never be necessary, in
+      practice indexes may become corrupted due to software bugs or
+      hardware failures.  <command>REINDEX</command> provides a
+      recovery method.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      The index in question contains a lot of dead index pages that
+      are not being reclaimed. This can occur with B+-tree indexes
+      under certain access patterns. <command>REINDEX</command>
+      provides a way to reduce the space consumption of the index by
+      writing a new version of the index without the dead pages. See
+      the <quote>Routine Reindexing</quote> section in the
+      &cite-admin; for more information. The rest of this section
+      mostly discusses how to use <command>REINDEX</command> to
+      recover from index corruption.
+     </para>
+    </listitem>
+   </orderedlist>
   </para>
 
   <para>

doc/src/sgml/ref/set_session_auth.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.7 2002/09/21 18:32:54 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.8 2003/02/19 04:06:28 momjian Exp $ -->
 <refentry id="SQL-SET-SESSION-AUTHORIZATION">
  <docinfo>
   <date>2001-04-21</date>
@@ -16,7 +16,7 @@
 
  <refsynopsisdiv>
 <synopsis>
-SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <parameter>username</parameter>
+SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <replaceable class="PARAMETER">username</replaceable>
 SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
 RESET SESSION AUTHORIZATION
 </synopsis>
@@ -27,12 +27,12 @@ RESET SESSION AUTHORIZATION
 
   <para>
    This command sets the session user identifier and the current user
-   identifier of the current SQL-session context to be
-   <parameter>username</parameter>.  The user name may be written as
-   either an identifier or a string literal.
-   The session user identifier is valid for the duration of a
-   connection; for example, it is possible to temporarily become an
-   unprivileged user and later switch back to become a superuser.
+   identifier of the current SQL-session context to be <replaceable
+   class="PARAMETER">username</replaceable>.  The user name may be
+   written as either an identifier or a string literal.  The session
+   user identifier is valid for the duration of a connection; for
+   example, it is possible to temporarily become an unprivileged user
+   and later switch back to become a superuser.
   </para>
 
   <para>
@@ -68,19 +68,21 @@ RESET SESSION AUTHORIZATION
  <refsect1>
   <title>Examples</title>
 
-<screen>
-<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
- current_user | session_user
+<programlisting>
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user 
 --------------+--------------
  peter        | peter
 
-<userinput>SET SESSION AUTHORIZATION 'paul';</userinput>
+SET SESSION AUTHORIZATION 'paul';
+
+SELECT SESSION_USER, CURRENT_USER;
 
-<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
- current_user | session_user
+ session_user | current_user 
 --------------+--------------
  paul         | paul
-</screen>
+</programlisting>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/vacuum.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.28 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.29 2003/02/19 04:06:28 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -286,6 +286,14 @@ VACUUM
    </para>
   </refsect2>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-vacuumdb" endterm="app-vacuumdb-title"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/runtime.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.168 2003/02/06 20:25:31 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.169 2003/02/19 04:06:28 momjian Exp $
 -->
 
 <Chapter Id="runtime">
@@ -122,7 +122,7 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
   <para>
    However, while the directory contents are secure, the default
    client authentication setup allows any local user to connect to the
-   database and even become the database superuser. If you don't trust
+   database and even become the database superuser. If you do not trust
    other local users, we recommend you use <command>initdb</command>'s
    <option>-W</option> or <option>--pwprompt</option> option to assign a
    password to the database superuser. After <command>initdb</command>,
@@ -365,7 +365,7 @@ FATAL 1:  ShmemCreate: cannot create region
      probably means your kernel's limit on the size of shared memory is
      smaller than the buffer area <productname>PostgreSQL</productname>
      is trying to create (83918612 bytes in this example). Or it could
-     mean that you don't have System-V-style shared memory support
+     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
      of buffers (<option>-B</option> switch). You will eventually want
@@ -2937,7 +2937,7 @@ default:\
     On the other side of the coin, some systems allow individual
     processes to open large numbers of files; if more than a few
     processes do so then the system-wide limit can easily be exceeded.
-    If you find this happening, and don't want to alter the system-wide
+    If you find this happening, and you do not want to alter the system-wide
     limit, you can set <productname>PostgreSQL</productname>'s
     <varname>max_files_per_process</varname> configuration parameter to
     limit the consumption of open files.

doc/src/sgml/sql.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.29 2003/02/19 04:06:28 momjian Exp $
 -->
 
  <chapter id="sql">
@@ -24,7 +24,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian
   <para>
    <acronym>SQL</acronym> has become the most popular relational query 
    language.
-   The name "<acronym>SQL</acronym>" is an abbreviation for
+   The name <quote><acronym>SQL</acronym></quote> is an abbreviation for
    <firstterm>Structured Query Language</firstterm>. 
    In 1974 Donald Chamberlin and others defined the
    language SEQUEL (<firstterm>Structured English Query
@@ -72,10 +72,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian
    (<acronym>ISO</acronym>).
    This original standard version of <acronym>SQL</acronym> is often
    referred to,
-   informally, as "<abbrev>SQL/86</abbrev>". In 1989 the original
+   informally, as <quote><abbrev>SQL/86</abbrev></quote>. In 1989 the original
    standard was extended
    and this new standard is often, again informally, referred to as
-   "<abbrev>SQL/89</abbrev>". Also in 1989, a related standard called
+   <quote><abbrev>SQL/89</abbrev></quote>. Also in 1989, a related standard called
    <firstterm>Database Language Embedded <acronym>SQL</acronym></firstterm>
    (<acronym>ESQL</acronym>) was developed.
   </para>
@@ -86,11 +86,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian
    definition of a greatly expanded version of the original standard,
    referred to informally as <firstterm><acronym>SQL2</acronym></firstterm>
    or <firstterm><acronym>SQL/92</acronym></firstterm>. This version became a
-   ratified standard - "International Standard ISO/IEC 9075:1992,
-   Database Language <acronym>SQL</acronym>" - in late 1992.
+   ratified standard - <quote>International Standard ISO/IEC 9075:1992,
+   Database Language <acronym>SQL</acronym></quote> - in late 1992.
    <acronym>SQL/92</acronym> is the version
-   normally meant when people refer to "the <acronym>SQL</acronym>
-   standard". A detailed
+   normally meant when people refer to <quote>the <acronym>SQL</acronym>
+   standard</quote>. A detailed
    description of <acronym>SQL/92</acronym> is given in 
    <xref linkend="DATE97" endterm="DATE97">. At the time of
    writing this document a new standard informally referred to
@@ -768,8 +768,8 @@ x(A) &mid; F(x)
      can be formulated using relational algebra can also be formulated 
      using the relational calculus and vice versa.
      This was first proved by E. F. Codd in
-     1972. This proof is based on an algorithm ("Codd's reduction
-     algorithm") by which an arbitrary expression of the relational
+     1972. This proof is based on an algorithm (<quote>Codd's reduction
+     algorithm</quote>) by which an arbitrary expression of the relational
      calculus can be reduced to a semantically equivalent expression of
      relational algebra. For a more detailed discussion on that refer to
      <xref linkend="DATE94" endterm="DATE94">
@@ -778,11 +778,12 @@ x(A) &mid; F(x)
     </para>
 
     <para>
-     It is sometimes said that languages based on the relational calculus
-     are "higher level" or "more declarative" than languages based on
-     relational algebra because the algebra (partially) specifies the order
-     of operations while the calculus leaves it to a compiler or
-     interpreter to determine the most efficient order of evaluation.
+     It is sometimes said that languages based on the relational
+     calculus are <quote>higher level</quote> or <quote>more
+     declarative</quote> than languages based on relational algebra
+     because the algebra (partially) specifies the order of operations
+     while the calculus leaves it to a compiler or interpreter to
+     determine the most efficient order of evaluation.
     </para>
    </sect2>
   </sect1>
@@ -870,9 +871,10 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
     </para>
 
     <para>
-     Now we will illustrate the complex syntax of the SELECT statement
-     with various examples. The tables used for the examples are defined in
-     <xref linkend="supplier-fig" endterm="supplier-fig">.
+     Now we will illustrate the complex syntax of the
+     <command>SELECT</command> statement with various examples. The
+     tables used for the examples are defined in <xref
+     linkend="supplier-fig" endterm="supplier-fig">.
     </para>
 
     <sect3>
@@ -903,7 +905,7 @@ SELECT * FROM PART
        </para>
 
        <para>
-	Using "*" in the SELECT statement will deliver all attributes from
+	Using <quote>*</quote> in the SELECT statement will deliver all attributes from
 	the table. If we want to retrieve only the attributes PNAME and PRICE
 	from table PART we use the statement:
 
@@ -922,9 +924,10 @@ SELECT PNAME, PRICE
                       Cam    |   25
 	</programlisting>
 
-	Note that the <acronym>SQL</acronym> SELECT corresponds to the 
-	"projection" in relational algebra not to the "selection"
-	(see <xref linkend="rel-alg" endterm="rel-alg"> for more details).
+	Note that the <acronym>SQL</acronym> SELECT corresponds to the
+	<quote>projection</quote> in relational algebra not to the
+	<quote>selection</quote> (see <xref linkend="rel-alg"
+	endterm="rel-alg"> for more details).
        </para>
 
        <para>

doc/src/sgml/start.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.27 2002/11/11 20:14:04 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.28 2003/02/19 04:06:28 momjian Exp $
 -->
 
  <chapter id="tutorial-start">
@@ -242,7 +242,7 @@ createdb: database creation failed
    </para>
 
    <para>
-    If you don't want to use your database anymore you can remove it.
+    If you do not want to use your database anymore you can remove it.
     For example, if you are the owner (creator) of the database
     <literal>mydb</literal>, you can destroy it using the following
     command:

doc/src/sgml/typeconv.sgml

@@ -305,7 +305,7 @@ If only one candidate remains, use it; else continue to the next step.
 <para>
 If any input arguments are <quote>unknown</quote>, check the type
 categories accepted at those argument positions by the remaining
-candidates.  At each position, select the "string" category if any
+candidates.  At each position, select the <quote>string</quote> category if any
 candidate accepts that category (this bias towards string is appropriate
 since an unknown-type literal does look like a string). Otherwise, if
 all the remaining candidates accept the same type category, select that

doc/src/sgml/xfunc.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.64 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.65 2003/02/19 04:06:28 momjian Exp $
 -->
 
  <chapter id="xfunc">
@@ -606,7 +606,7 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
     The newer <quote>version 1</quote> calling convention is indicated by writing
     a <literal>PG_FUNCTION_INFO_V1()</literal> macro call for the function,
     as illustrated below.  Lack of such a macro indicates an old-style
-    ("version 0") function.  The language name specified in <command>CREATE FUNCTION</command>
+    (<quote>version 0</quote>) function.  The language name specified in <command>CREATE FUNCTION</command>
     is <literal>C</literal> in either case.  Old-style functions are now deprecated
     because of portability problems and lack of functionality, but they
     are still supported for compatibility reasons.
@@ -1380,7 +1380,7 @@ concat_text(PG_FUNCTION_ARGS)
     zero, and a negative length requests that the remainder of the
     value be returned. These routines provide more efficient access to
     parts of large values in the case where they have storage type
-    "external". (The storage type of a column can be specified using
+    <quote>external</quote>. (The storage type of a column can be specified using
     <literal>ALTER TABLE <replaceable>tablename</replaceable> ALTER
     COLUMN <replaceable>colname</replaceable> SET STORAGE
     <replaceable>storagetype</replaceable></literal>. Storage type is one of
@@ -1583,7 +1583,7 @@ TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc)
 HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
 </programlisting>
      can be used to build a <structname>HeapTuple</> given user data
-     in C string form.  "values" is an array of C strings, one for
+     in C string form.  <quote>values</quote> is an array of C strings, one for
      each attribute of the return tuple. Each C string should be in
      the form expected by the input function of the attribute data
      type. In order to return a null value for one of the attributes,

src/backend/catalog/index.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $Header: /cvsroot/pgsql/src/backend/catalog/index.c,v 1.208 2002/12/15 16:17:38 tgl Exp $
+ *	  $Header: /cvsroot/pgsql/src/backend/catalog/index.c,v 1.209 2003/02/19 04:06:28 momjian Exp $
  *
  *
  * INTERFACE ROUTINES
@@ -1894,8 +1894,8 @@ reindex_relation(Oid relid, bool force)
 
 	/*
 	 * Ensure to hold an exclusive lock throughout the transaction. The
-	 * lock could be less intensive (in the non-overwrite path) but now
-	 * it's AccessExclusiveLock for simplicity.
+	 * lock could be less intensive (in the non-overwrite path) but for
+	 * now it's AccessExclusiveLock for simplicity.
 	 */
 	rel = heap_open(relid, AccessExclusiveLock);