This patch makes some improvements and adds some additional detail

to the documentation on routine database maintainence activities.
I also corrected a bunch of SGML markup.

doc/src/sgml/maintenance.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.29 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.30 2003/12/14 00:10:32 neilc Exp $
 -->
 
 <chapter id="maintenance">
@@ -87,7 +87,7 @@ $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.29 2003/11/29 19:51:37 pgsq
    of <command>VACUUM</> can run in parallel with normal database operations
    (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
+   releases, and it is not as critical to try to schedule it at low-usage
    times of day.
   </para>
 
@@ -115,7 +115,7 @@ $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.29 2003/11/29 19:51:37 pgsq
     Clearly, a table that receives frequent updates or deletes will need
     to be vacuumed more often than tables that are seldom updated. It
     may be useful to set up periodic <application>cron</> tasks that
-    vacuum only selected tables, skipping tables that are known not to
+    <command>VACUUM</command> only selected tables, skipping tables that are known not to
     change often. This is only likely to be helpful if you have both
     large heavily-updated tables and large seldom-updated tables --- the
     extra cost of vacuuming a small table isn't enough to be worth
@@ -123,39 +123,69 @@ $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.29 2003/11/29 19:51:37 pgsq
    </para>
 
    <para>
-    The standard form of <command>VACUUM</> is best used with the goal of
+    There are two variants of the <command>VACUUM</command>
-    maintaining a fairly level steady-state usage of disk space.  The standard
+    command. The first form, known as <quote>lazy vacuum</quote> or
-    form finds old row versions and makes their space available for re-use within
+    just <command>VACUUM</command>, marks expired data in tables and
-    the table, but it does not try very hard to shorten the table file and
+    indexes for future reuse; it does <emphasis>not</emphasis> attempt
-    return disk space to the operating system.  If you need to return disk
+    to reclaim the space used by this expired data
-    space to the operating system you can use <command>VACUUM FULL</> ---
+    immediately. Therefore, the table file is not shortened, and any
-    but what's the point of releasing disk space that will only have to be
+    unused space in the file is not returned to the operating
-    allocated again soon?  Moderately frequent standard <command>VACUUM</> runs
+    system. This variant of <command>VACUUM</command> can be run
-    are a better approach than infrequent <command>VACUUM FULL</> runs for
+    concurrently with normal database operations.
-    maintaining heavily-updated tables.
+   </para>
+
+   <para>
+    The second form is the <command>VACUUM FULL</command>
+    command. This uses a more aggressive algorithm for reclaiming the
+    space consumed by expired row versions. Any space that is freed by
+    <command>VACUUM FULL</command> is immediately returned to the
+    operating system. Unfortunately, this variant of the
+    <command>VACUUM</command> command acquires an exclusive lock on
+    each table while <command>VACUUM FULL</command> is processing
+    it. Therefore, frequently using <command>VACUUM FULL</command> can
+    have an extremely negative effect on the performance of concurrent
+    database queries.
+   </para>
+
+   <para>
+    The standard form of <command>VACUUM</> is best used with the goal
+    of maintaining a fairly level steady-state usage of disk space. 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</> runs are a better approach
+    than infrequent <command>VACUUM FULL</> runs for maintaining
+    heavily-updated tables.
    </para>
 
    <para>
     Recommended practice for most sites is to schedule a database-wide
-    <command>VACUUM</> once a day at a low-usage time of day, supplemented
+    <command>VACUUM</> once a day at a low-usage time of day,
-    by more frequent vacuuming of heavily-updated tables if necessary.
+    supplemented by more frequent vacuuming of heavily-updated tables
-    (If you have multiple databases in a cluster, don't forget to
+    if necessary. In fact, some installations with an extremely high
-    vacuum each one; the program <filename>vacuumdb</> may be helpful.)
+    rate of data modification <command>VACUUM</command> some tables as
-    Use plain <command>VACUUM</>, not <command>VACUUM FULL</>, for routine
+    often as once very five minutes.  (If you have multiple databases
+    in a cluster, don't forget to <command>VACUUM</command> each one;
+    the program <filename>vacuumdb</> may be helpful.)
+   </para>
+
+   <para>
+    <command>VACUUM FULL</> is recommended for cases where you know
+    you have deleted the majority of rows in a table, so that the
+    steady-state size of the table can be shrunk substantially with
+    <command>VACUUM FULL</>'s more aggressive approach.  Use plain
+    <command>VACUUM</>, not <command>VACUUM FULL</>, for routine
     vacuuming for space recovery.
    </para>
 
    <para>
-    <command>VACUUM FULL</> is recommended for cases where you know you have
+    If you have a table whose contents are deleted on a periodic
-    deleted the majority of rows in a table, so that the steady-state size
+    basis, consider doing it with <command>TRUNCATE</command> rather
-    of the table can be shrunk substantially with <command>VACUUM FULL</>'s
+    than using <command>DELETE</command> followed by
-    more aggressive approach.
+    <command>VACUUM</command>. <command>TRUNCATE</command> removes the
-   </para>
+    entire content of the table immediately, without recquiring a
-
+    subsequent <command>VACUUM</command> or <command>VACUUM
-   <para>
+    FULL</command> to reclaim the now-unused disk space.
-    If you have a table whose contents are deleted completely every so often,
-    consider doing it with <command>TRUNCATE</> rather than using
-    <command>DELETE</> followed by <command>VACUUM</>.
    </para>
   </sect2>
 
@@ -319,7 +349,7 @@ $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.29 2003/11/29 19:51:37 pgsq
     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
+    database-wide <command>VACUUM</command> 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
     XIDs older than this cutoff XID are guaranteed to have been replaced by
@@ -338,7 +368,7 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
     With the standard freezing policy, the <literal>age</> column will start
     at one billion for a freshly-vacuumed database.  When the <literal>age</>
     approaches two billion, the database must be vacuumed again to avoid
-    risk of wraparound failures.  Recommended practice is to vacuum each
+    risk of wraparound failures.  Recommended practice is to <command>VACUUM</command> each
     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
@@ -366,7 +396,7 @@ VACUUM
     It should also be used to prepare any user-created databases that
     are to be marked <literal>datallowconn</> = <literal>false</> in
     <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> a database that you can't connect to. Note that
     <command>VACUUM</command>'s automatic warning message about
     unvacuumed databases will ignore <literal>pg_database</> entries
     with <literal>datallowconn</> = <literal>false</>, so as to avoid
@@ -404,20 +434,22 @@ VACUUM
   </indexterm>
 
   <para>
-   It's a good idea to save the database server's log output somewhere,
+   It is a good idea to save the database server's log output
-   rather than just routing it to <filename>/dev/null</>.  The log output
+   somewhere, rather than just routing it to <filename>/dev/null</>.
-   is invaluable when it comes time to diagnose problems.  However, the
+   The log output is invaluable when it comes time to diagnose
-   log output tends to be voluminous (especially at higher debug levels)
+   problems.  However, the log output tends to be voluminous
-   and you won't want to save it indefinitely.  You need to <quote>rotate</>
+   (especially at higher debug levels) and you won't want to save it
-   the log files so that new log files are started and old ones thrown
+   indefinitely.  You need to <quote>rotate</> the log files so that
-   away every so often.
+   new log files are started and old ones removed after a reasonable
+   period of time.
   </para>
 
   <para>
    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 <command>postmaster</command>. This may be OK for development setups but you won't
+   the <command>postmaster</command>. This may be OK if you are using
-   want to run a production server that way.
+   <productname>PostgreSQL</productname> in a development environment,
+   but few production servers would find this behavior acceptable.
   </para>
 
   <para>
@@ -444,14 +476,16 @@ VACUUM
    <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:
-   
+
 <programlisting>
 pg_ctl start | logrotate
 </programlisting>
 
-   The <productname>PostgreSQL</> distribution doesn't include a suitable
+   The <productname>PostgreSQL</> distribution doesn't include a
-   log rotation program, but there are many available on the Internet;
+   suitable log rotation program, but there are many available on the
-   one is included in the Apache distribution, for example.
+   Internet. For example, the <application>logrotate</application>
+   tool included in the <productname>Apache</productname> distribution
+   can be used with <productname>PostgreSQL</productname>.
   </para>
  </sect1>
 </chapter>

doc/src/sgml/page.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/page.sgml,v 1.16 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/page.sgml,v 1.17 2003/12/14 00:10:32 neilc Exp $
 -->
 
 <chapter id="page">
@@ -151,7 +151,8 @@ data. Empty in ordinary tables.</entry>
  </table>
 
  <para>
-  All the details may be found in src/include/storage/bufpage.h.
+  All the details may be found in
+  <filename>src/include/storage/bufpage.h</filename>.
  </para>
 
  <para>  
@@ -305,7 +306,8 @@ data. Empty in ordinary tables.</entry>
  </table>
 
  <para>
-   All the details may be found in src/include/access/htup.h.
+   All the details may be found in
+   <filename>src/include/access/htup.h</filename>.
  </para>
 
  <para>

doc/src/sgml/perform.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.38 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.39 2003/12/14 00:10:32 neilc Exp $
 -->
 
  <chapter id="performance-tips">
@@ -100,7 +100,7 @@ $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.38 2003/11/29 19:51:37 pgsql Ex
 
    <para>
     Here are some examples (using the regression test database after a
-    <literal>VACUUM ANALYZE</>, and 7.3 development sources):
+    <command>VACUUM ANALYZE</>, and 7.3 development sources):
 
 <programlisting>
 EXPLAIN SELECT * FROM tenk1;

doc/src/sgml/plperl.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.21 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.22 2003/12/14 00:10:32 neilc Exp $
 -->
 
  <chapter id="plperl">
@@ -152,7 +152,7 @@ SELECT name, empcomp(employee) FROM employee;
   <para>
    The argument values supplied to a PL/Perl function's code are
    simply the input arguments converted to text form (just as if they
-   had been displayed by a <literal>SELECT</literal> statement).
+   had been displayed by a <command>SELECT</command> statement).
    Conversely, the <literal>return</> command will accept any string
    that is acceptable input format for the function's declared return
    type.  So, the PL/Perl programmer can manipulate data values as if

doc/src/sgml/protocol.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.48 2003/11/29 19:51:37 pgsql Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.49 2003/12/14 00:10:32 neilc Exp $ -->
 
 <chapter id="protocol">
  <title>Frontend/Backend Protocol</title>
@@ -200,13 +200,13 @@
   <para>
    This section describes the message flow and the semantics of each
    message type.  (Details of the exact representation of each message
-   appear in <xref linkend="protocol-message-formats">.)
+   appear in <xref linkend="protocol-message-formats">.)  There are
-   There are several different sub-protocols
+   several different sub-protocols depending on the state of the
-   depending on the state of the connection: start-up,
+   connection: start-up, query, function call,
-   query, function call, COPY, and termination.  There are also special
+   <command>COPY</command>, and termination.  There are also special
-   provisions for asynchronous operations (including
+   provisions for asynchronous operations (including notification
-   notification responses and command cancellation),
+   responses and command cancellation), which can occur at any time
-   which can occur at any time after the start-up phase.
+   after the start-up phase.
   </para>
 
   <sect2>
@@ -989,15 +989,17 @@
    </para>
 
    <para>
-    ParameterStatus messages will be generated whenever the active value
+    ParameterStatus messages will be generated whenever the active
-    changes for any of the parameters the backend believes the frontend
+    value changes for any of the parameters the backend believes the
-    should know about.  Most commonly this occurs in response to a
+    frontend should know about.  Most commonly this occurs in response
-    <command>SET</> SQL command executed by the frontend, and this case
+    to a <command>SET</> SQL command executed by the frontend, and
-    is effectively synchronous --- but it is also possible for parameter
+    this case is effectively synchronous --- but it is also possible
-    status changes to occur because the administrator changed a configuration
+    for parameter status changes to occur because the administrator
-    file and then sent the <systemitem>SIGHUP</systemitem> signal to the postmaster.  Also, if a SET command is
+    changed a configuration file and then sent the
-    rolled back, an appropriate ParameterStatus message will be generated
+    <systemitem>SIGHUP</systemitem> signal to the postmaster.  Also,
-    to report the current effective value.
+    if a <command>SET</command> command is rolled back, an appropriate
+    ParameterStatus message will be generated to report the current
+    effective value.
    </para>
 
    <para>
@@ -1129,46 +1131,53 @@
    <para>
     For either normal or abnormal termination, any open transaction is
     rolled back, not committed.  One should note however that if a
-    frontend disconnects while a non-SELECT query is being processed,
+    frontend disconnects while a non-<command>SELECT</command> query
-    the backend will probably finish the query before noticing the
+    is being processed, the backend will probably finish the query
-    disconnection.
+    before noticing the disconnection.  If the query is outside any
-    If the query is outside any transaction block (<command>BEGIN</>
+    transaction block (<command>BEGIN</> ... <command>COMMIT</>
-    ... <command>COMMIT</> sequence) then its results may be committed
+    sequence) then its results may be committed before the
-    before the disconnection is recognized.
+    disconnection is recognized.
    </para>
   </sect2>
 
   <Sect2>
-   <Title>SSL Session Encryption</Title>
+   <Title><acronym>SSL</acronym> Session Encryption</Title>
 
    <Para>
-    If <productname>PostgreSQL</> was built with SSL support, frontend/backend
+    If <productname>PostgreSQL</> was built with
-    communications can be encrypted using SSL.  This provides communication
+    <acronym>SSL</acronym> support, frontend/backend communications
-    security in environments where attackers might be able to capture the
+    can be encrypted using <acronym>SSL</acronym>.  This provides
-    session traffic.
+    communication security in environments where attackers might be
+    able to capture the session traffic. For more information on
+    encrypting <productname>PostgreSQL</productname> sessions with
+    <acronym>SSL</acronym>, see <xref linkend="ssl-tcp">.
    </para>
 
    <para>
-    To initiate an SSL-encrypted connection, the frontend initially sends
+    To initiate an <acronym>SSL</acronym>-encrypted connection, the
-    an SSLRequest message rather than a StartupMessage.  The server then
+    frontend initially sends an SSLRequest message rather than a
-    responds with a single byte containing <literal>S</> or <literal>N</>,
+    StartupMessage.  The server then responds with a single byte
-    indicating that it is willing or unwilling to perform SSL, respectively.
+    containing <literal>S</> or <literal>N</>, indicating that it is
-    The frontend may close the connection at this point if it is dissatisfied
+    willing or unwilling to perform <acronym>SSL</acronym>,
-    with the response.  To continue after <literal>S</>, perform an SSL
+    respectively.  The frontend may close the connection at this point
-    startup handshake (not described here, part of the SSL specification)
+    if it is dissatisfied with the response.  To continue after
-    with the server.  If this is successful, continue with
+    <literal>S</>, perform an <acronym>SSL</acronym> startup handshake
-    sending the usual StartupMessage.  In this case the StartupMessage and
+    (not described here, part of the <acronym>SSL</acronym>
-    all subsequent data will be SSL-encrypted.  To continue after
+    specification) with the server.  If this is successful, continue
+    with sending the usual StartupMessage.  In this case the
+    StartupMessage and all subsequent data will be
+    <acronym>SSL</acronym>-encrypted.  To continue after
     <literal>N</>, send the usual StartupMessage and proceed without
     encryption.
    </para>
 
    <para>
-    The frontend should also be prepared to handle an ErrorMessage response
+    The frontend should also be prepared to handle an ErrorMessage
-    to SSLRequest from the server.  This would only occur if the server
+    response to SSLRequest from the server.  This would only occur if
-    predates the addition of SSL support to <productname>PostgreSQL</>.
+    the server predates the addition of <acronym>SSL</acronym> support
-    In this case the connection must be closed, but the frontend may choose
+    to <productname>PostgreSQL</>.  In this case the connection must
-    to open a fresh connection and proceed without requesting SSL.
+    be closed, but the frontend may choose to open a fresh connection
+    and proceed without requesting <acronym>SSL</acronym>.
    </para>
 
    <para>
@@ -1178,8 +1187,9 @@
 
    <para>
     While the protocol itself does not provide a way for the server to
-    force SSL encryption, the administrator may configure the server to
+    force <acronym>SSL</acronym> encryption, the administrator may
-    reject unencrypted sessions as a byproduct of authentication checking.
+    configure the server to reject unencrypted sessions as a byproduct
+    of authentication checking.
    </para>
   </sect2>
  </sect1>
@@ -2106,7 +2116,7 @@ CopyData (F &amp; B)
 </Term>
 <ListItem>
 <Para>
-                Identifies the message as COPY data.
+                Identifies the message as <command>COPY</command> data.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -2153,7 +2163,7 @@ CopyDone (F &amp; B)
 </Term>
 <ListItem>
 <Para>
-                Identifies the message as a COPY-complete indicator.
+                Identifies the message as a <command>COPY</command>-complete indicator.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -2188,7 +2198,7 @@ CopyFail (F)
 </Term>
 <ListItem>
 <Para>
-                Identifies the message as a COPY-failure indicator.
+                Identifies the message as a <command>COPY</command>-failure indicator.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -2255,7 +2265,7 @@ CopyInResponse (B)
 </Term>
 <ListItem>
 <Para>
-                0 indicates the overall copy format is textual (rows
+                0 indicates the overall <command>COPY</command> format is textual (rows
 		separated by newlines, columns separated by separator
 		characters, etc).
 		1 indicates the overall copy format is binary (similar
@@ -2330,13 +2340,12 @@ CopyOutResponse (B)
 </Term>
 <ListItem>
 <Para>
-                0 indicates the overall copy format is textual (rows
+                0 indicates the overall <command>COPY</command> format
-		separated by newlines, columns separated by separator
+                is textual (rows separated by newlines, columns
-		characters, etc).
+                separated by separator characters, etc). 1 indicates
-		1 indicates the overall copy format is binary (similar
+                the overall copy format is binary (similar to DataRow
-		to DataRow format).
+                format). See <xref linkend="sql-copy"
-		See <xref linkend="sql-copy" endterm="sql-copy-title">
+                endterm="sql-copy-title"> for more information. 
-		for more information.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -3602,7 +3611,7 @@ SSLRequest (F)
 </Term>
 <ListItem>
 <Para>
-                The SSL request code.  The value is chosen to contain
+                The <acronym>SSL</acronym> request code.  The value is chosen to contain
                 <literal>1234</> in the most significant 16 bits, and <literal>5679</> in the
                 least 16 significant bits.  (To avoid confusion, this code
                 must not be the same as any protocol version number.)
@@ -3899,8 +3908,9 @@ message.
 <ListItem>
 <Para>
         Where: an indication of the context in which the error occurred.
-	Presently this includes a call stack traceback of active PL functions.
+	Presently this includes a call stack traceback of active
-	The trace is one entry per line, most recent first.
+	procedural language functions.  The trace is one entry per line,
+	most recent first.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -4006,12 +4016,12 @@ may allow improvements in performance or functionality.
 </para>
 
 <para>
-COPY data is now encapsulated into CopyData and CopyDone messages.  There
+<command>COPY</command> data is now encapsulated into CopyData and CopyDone messages.  There
-is a well-defined way to recover from errors during COPY.  The special
+is a well-defined way to recover from errors during <command>COPY</command>.  The special
 <quote><literal>\.</></quote> last line is not needed anymore, and is not sent
-during COPY OUT.
+during <command>COPY OUT</command>.
-(It is still recognized as a terminator during COPY IN, but its use is
+(It is still recognized as a terminator during <command>COPY IN</command>, but its use is
-deprecated and will eventually be removed.)  Binary COPY is supported.
+deprecated and will eventually be removed.)  Binary <command>COPY</command> is supported.
 The CopyInResponse and CopyOutResponse messages include fields indicating
 the number of columns and the format of each column.
 </para>
@@ -4046,7 +4056,7 @@ the backend.
 <para>
 The NotificationResponse ('<literal>A</>') message has an additional string
 field, which is presently empty but may someday carry additional data passed
-from the NOTIFY event sender.
+from the <command>NOTIFY</command> event sender.
 </para>
 
 <para>

doc/src/sgml/typeconv.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.41 2003/12/02 00:26:59 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.42 2003/12/14 00:10:32 neilc Exp $
 -->
 
 <chapter Id="typeconv">
@@ -122,9 +122,9 @@ with, and perhaps converted to, the types of the target columns.
 </term>
 <listitem>
 <para>
-Since all query results from a unionized <literal>SELECT</literal> statement
+Since all query results from a unionized <command>SELECT</command> statement
 must appear in a single set of columns, the types of the results of each
-<literal>SELECT</> clause must be matched up and converted to a uniform set.
+<command>SELECT</> clause must be matched up and converted to a uniform set.
 Similarly, the branch expressions of a <literal>CASE</> construct must be
 converted to a common type so that the <literal>CASE</> expression as a whole
 has a known output type.  The same holds for <literal>ARRAY</> constructs.