Make a copy-editing pass over the 8.4 release notes.

doc/src/sgml/release.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/release.sgml,v 1.627 2009/04/11 02:06:16 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/release.sgml,v 1.628 2009/04/13 06:05:12 tgl Exp $ -->
 <!--
 
 Typical markup:
@@ -69,7 +69,7 @@ do it for earlier branch release files.
 
   <note>
    <title>Release date</title>
-   <simpara>2009-XX-XX, ITEMS CURRENT AS OF 2009-04-08</simpara>
+   <simpara>2009-??-??, ITEMS CURRENT AS OF 2009-04-08</simpara>
   </note>
 
   <sect2>
@@ -78,9 +78,9 @@ do it for earlier branch release files.
    <para>
     After many years of development, <productname>PostgreSQL</> has
     become feature-complete in many areas.   This release shows a
-    targeted approach to adding features (e.g. authentication,
+    targeted approach to adding features (e.g., authentication,
     monitoring, space reuse), and adds capabilities defined in the
-    later SQL standards;  the major areas of enhancement are:
+    later SQL standards.  The major areas of enhancement are:
    </para>
 
    <itemizedlist>
@@ -131,7 +131,7 @@ do it for earlier branch release files.
 
     <listitem>
      <para>
-      Improved join performance for EXISTS and NOT EXISTS queries
+      Improved join performance for <literal>EXISTS</> and <literal>NOT EXISTS</> queries
      </para>
     </listitem>
 
@@ -214,8 +214,9 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       This was available previously via a configure
-       --enable-integer-datetimes option.
+       Previously this was selected by <application>configure</>'s
+       <option>--enable-integer-datetimes</> option.  To retain
+       the old behavior, build with <option>--disable-integer-datetimes</>.
       </para>
      </listitem>
 
@@ -225,7 +226,7 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       The utility only worked on a few platforms;  users should use
+       The utility only worked on a few platforms.  Users should use
        their operating system tools instead.
       </para>
      </listitem>
@@ -240,15 +241,15 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Change <filename>postgresql.conf</> default for
+       Change default setting for
        <literal>log_min_messages</> to <literal>warning</> (previously
-       <literal>notice</>) to reduce log file volume (Tom)
+       it was <literal>notice</>) to reduce log file volume (Tom)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Have <literal>debug_print_parse</>, <literal>debug_print_rewritten</>,
+       Make <literal>debug_print_parse</>, <literal>debug_print_rewritten</>,
        and <literal>debug_print_plan</>
        output appear at <literal>LOG</> message level, not
        <literal>DEBUG1</> as formerly (Tom)
@@ -263,33 +264,33 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Make <varname>log_temp_files</> super-user set only, like other
-       logging options (Simon)
+       Remove <varname>explain_pretty_print</> parameter (no longer needed) (Tom)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Disable appending of the epoch date/time when no <literal>%</>
-       escapes are present in <literal>log_filename</> (Robert Haas)
+       Make <varname>log_temp_files</> settable by superusers only, like other
+       logging options (Simon Riggs)
       </para>
+     </listitem>
 
+     <listitem>
       <para>
-       This change was made because some users wanted a fixed filename,
-       for use with an external log rotation tool.
+       Disable appending of the epoch date/time when no <literal>%</>
+       escapes are present in <literal>log_filename</> (Robert Haas)
       </para>
-     </listitem>
 
-     <listitem>
       <para>
-       Remove <varname>explain_pretty_print</> parameter (no longer needed) (Tom)
+       This change was made because some users wanted a fixed log filename,
+       for use with an external log rotation tool.
       </para>
      </listitem>
 
      <listitem>
       <para>
        Remove <varname>log_restartpoints</> from <filename>recovery.conf</>;
-       instead use <varname>log_checkpoints</> (Simon Riggs)
+       instead use <varname>log_checkpoints</> (Simon)
       </para>
      </listitem>
 
@@ -300,22 +301,24 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       This breaks compatibility with pre-<productname>PostgreSQL</> 7.2 versions.
+       This breaks compatibility with pre-<productname>PostgreSQL</> 7.2
+       clients, as there is no longer any non-plaintext password method
+       that they can use.
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Remove <varname>krb_realm</> and <varname>krb_server_hostname</>, now
-       <filename>pg_hba.conf</>-only settings (Magnus)
+       Remove <varname>krb_realm</> and <varname>krb_server_hostname</>;
+       these are now set in <filename>pg_hba.conf</> instead (Magnus)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       The <link
-       linkend="release-8-4-pg-hba-conf"><filename>pg_hba.conf</></link>
-       section below also has extensive changes related to migration.
+       There are also significant changes in <link
+       linkend="release-8-4-pg-hba-conf"><filename>pg_hba.conf</></link>,
+       as described below.
       </para>
      </listitem>
 
@@ -331,11 +334,11 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Force child tables to inherit <literal>CHECK</> constraints from parents
-       (Alex Hunsaker, Nikhil Sontakke, Tom Lane)
+       (Alex Hunsaker, Nikhil Sontakke, Tom)
       </para>
 
       <para>
-       Formerly it was possible to delete such a constraint from a child
+       Formerly it was possible to drop such a constraint from a child
        table, allowing rows that violate the constraint to be visible
        when scanning the parent table.  This was deemed inconsistent,
        as well as contrary to SQL standard.
@@ -344,13 +347,14 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Change <command>TRUNCATE</> and <command>LOCK</> behavior to
-       apply to all child tables (Peter)
+       Change <command>TRUNCATE</> and <command>LOCK</> to
+       apply to child tables of the specified table(s) (Peter)
       </para>
 
       <para>
-       There is a new <literal>ONLY</> clause which disables this
-       behavior.
+       These commands now accept an <literal>ONLY</> option that prevents
+       processing child tables; this option must be used if the old
+       behavior is needed.
       </para>
      </listitem>
 
@@ -368,8 +372,19 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       Such an operation is useless because the lock would be immediately
-       released.
+       Such an operation is useless because the lock would be released
+       immediately.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Sequences now contain an additional <structfield>start_value</> column
+       (Zoltan Boszormenyi)
+      </para>
+
+      <para>
+       This supports <command>ALTER SEQUENCE ... RESTART</>.
       </para>
      </listitem>
 
@@ -385,20 +400,20 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Have <literal>NUMERIC 0 ^ 4.3</> return <literal>1</>, rather
-       than an error, and have <literal>0 ^ 0.0</> return <literal>1</>,
+       Make <type>numeric</> zero raised to a fractional power return
+       <literal>0</>, rather than throwing an error, and make
+       <type>numeric</> zero raised to the zero power return <literal>1</>,
        rather than error (Bruce)
       </para>
 
       <para>
-       This was already the <type>float8</> behavior.
+       This matches the longstanding <type>float8</> behavior.
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Remove code that prevented unary minus of floating-point values
-       from producing <literal>-0</> (Tom)
+       Allow unary minus of floating-point values to produce minus zero (Tom)
       </para>
 
       <para>
@@ -410,7 +425,12 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Throw an error if an escape character is the last character in
-       a <literal>LIKE</> pattern (there is nothing to escape) (Tom)
+       a <literal>LIKE</> pattern (i.e., it has nothing to escape) (Tom)
+      </para>
+
+      <para>
+       Previously, such an escape character was silently ignored,
+       thus possibly masking application logic errors.
       </para>
      </listitem>
 
@@ -460,24 +480,37 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <function>to_char()</>'s localized month/day names depend
-        on <varname>LC_TIME</>, not <varname>LC_MESSAGES</> (Euler
-        Taveira de Oliveira)
+        <varname>DateStyle</> no longer controls <type>interval</> output
+        formatting; instead there is a new variable <varname>IntervalStyle</>
+        (Ron Mayer)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Cause <function>to_date()</> and <function>to_timestamp()</>
-        to more consistently report errors on invalid input (Brendan
-        Jurd)
+        Improve consistency of handling of fractional seconds in
+        <type>timestamp</> and <type>interval</> output (Ron Mayer)
+       </para>
+
+       <para>
+        This may result in displaying a different number of fractional
+        digits than before, or rounding instead of truncating.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Provide consistent rounding for fractional seconds (Ron Mayer)
-        bjm:  combine with another item?
+        Make <function>to_char()</>'s localized month/day names depend
+        on <varname>LC_TIME</>, not <varname>LC_MESSAGES</> (Euler
+        Taveira de Oliveira)
+       </para>
+      </listitem>
+
+      <listitem>
+       <para>
+        Cause <function>to_date()</> and <function>to_timestamp()</>
+        to more consistently report errors for invalid input (Brendan
+        Jurd)
        </para>
       </listitem>
 
@@ -497,9 +530,10 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Require the existence of periods in <function>to_timestamp()</>
+        Require <function>to_timestamp()</> input to match
         meridian (<literal>AM</>/<literal>PM</>) and era
-        (<literal>BC</>/<literal>AD</>) format designations to match
+        (<literal>BC</>/<literal>AD</>) format designations with
+        respect to presence of periods
         (Brendan Jurd)
        </para>
 
@@ -509,13 +543,6 @@ do it for earlier branch release files.
        </para>
       </listitem>
 
-      <listitem>
-       <para>
-        <varname>DateStyle</> no longer controls <type>INTERVAL</>
-        output (use new variable <varname>IntervalStyle</>)
-       </para>
-      </listitem>
-
      </itemizedlist>
 
     </sect4>
@@ -539,11 +566,12 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Improve optimizer statistics calculations (Tom, Jan Urbanski)
+       Improve optimizer statistics calculations (Jan Urbanski, Tom)
       </para>
 
       <para>
-       This includes improved statistics for full text columns.
+       In particular, estimates for full-text-search operators are
+       greatly improved.
       </para>
      </listitem>
 
@@ -561,31 +589,23 @@ do it for earlier branch release files.
        the previous behavior can be restored by
        disabling <literal>enable_hashagg</>, but that is a very
        performance-expensive fix. <literal>SELECT DISTINCT ON</> never
-       uses hashing.
-      </para>
-     </listitem>
-
-     <listitem>
-      <para>
-       New semi- and anti-joins (Tom)
-      </para>
-
-      <para>
-       While semi-joins merely replace existing <literal>IN</> joins,
-       anti-joins are a new capability for <literal>NOT EXISTS</>
-       clauses.  This improves optimization possibilities.
+       uses hashing, however, so its behavior is unchanged.
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Improve <literal>IN</>/<literal>ANY</>/<literal>EXISTS</>
-       processing (Tom)
+       Create explicit concepts of semi-joins and anti-joins (Tom)
       </para>
 
       <para>
-       <literal>IN</> and <literal>EXISTS</> now provide similar
-       performance for equivalent clauses.
+       This work formalizes our previous ad-hoc treatment of <literal>IN
+       (SELECT ...)</> clauses, and extends it to <literal>EXISTS</> and
+       <literal>NOT EXISTS</> clauses.  It should result in significantly
+       better planning of <literal>EXISTS</> and <literal>NOT EXISTS</>
+       queries.  In general, logically equivalent <literal>IN</> and
+       <literal>EXISTS</> clauses should now have similar performance,
+       whereas previously <literal>IN</> often won.
       </para>
      </listitem>
 
@@ -603,13 +623,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Improve handling of subqueries by the optimizer (Tom)
-      </para>
-     </listitem>
-
-     <listitem>
-      <para>
-       Reduce I/O frequency of writing the  backend statistics file
+       Reduce I/O load of writing the statistics collection file
        by writing the file only when requested (Martin Pihlak)
       </para>
      </listitem>
@@ -635,14 +649,13 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Modify <varname>constraint_exclusion</> to check for partitioned
-       tables by default when inheritance or <literal>UNION ALL</> is
-       used (Tom)
+       Perform <varname>constraint_exclusion</> checking by default
+       in queries involving inheritance or <literal>UNION ALL</> (Tom)
       </para>
 
       <para>
        A new <varname>constraint_exclusion</> setting,
-       <literal>partition</>, was added to match this behavior.
+       <literal>partition</>, was added to specify this behavior.
       </para>
      </listitem>
 
@@ -653,8 +666,8 @@ do it for earlier branch release files.
 
       <para>
        The amount of read-ahead is controlled by
-       <varname>effective_io_concurrency</>.  This requires
-       <function>posix_fadvise()</> support in the kernel.
+       <varname>effective_io_concurrency</>.  This feature is available only
+       if the kernel has <function>posix_fadvise()</> support.
       </para>
      </listitem>
 
@@ -703,7 +716,7 @@ do it for earlier branch release files.
       <listitem>
        <para>
         Convert many <filename>postgresql.conf</> settings to enumerated
-        values so <literal>pg_settings</> can easily display valid
+        values so <literal>pg_settings</> can display valid
         values (Magnus)
        </para>
       </listitem>
@@ -711,15 +724,15 @@ do it for earlier branch release files.
       <listitem>
        <para>
         Add <varname>cursor_tuple_fraction</> parameter to control the
-        fraction of a cursor's rows expected to be requested by the
-        user (Robert Hell)
+        fraction of a cursor's rows that the planner assumes will be
+        fetched (Robert Hell)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Allow underscores in <filename>postgresql.conf</> custom variable
-        classes (Tom)
+        Allow underscores in the names of custom variable
+        classes in <filename>postgresql.conf</> (Tom)
        </para>
       </listitem>
 
@@ -762,47 +775,49 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Parse <filename>pg_hba.conf</> in the postmaster so errors are
-        reported on reload (Magnus)
+        Parse <filename>pg_hba.conf</> fully when it is loaded,
+        so that errors are reported immediately (Magnus)
        </para>
 
        <para>
-        Previously errors in the file wouldn't be detected until clients
-        tried to connect, which could leave the system with a broken
-        file loaded.
+        Previously, most errors in the file wouldn't be detected until clients
+        tried to connect, so an erroneous file could render the system
+        unusable.  With the new behavior, if an error is detected during
+        reload then the bad file is rejected and the postmaster continues
+        to use its old copy.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Remove the <literal>sameuser</> option, making it the default
-        if no usermap is specified (Magnus)
+        Show all parsing errors in <filename>pg_hba.conf</> instead of
+        aborting after the first one (Selena Deckelmann)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Change all authentication options to be <literal>name=value</>
-        settings (Magnus)
+        Remove the <literal>ident sameuser</> option, instead making that
+        behavior the default if no usermap is specified (Magnus)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Allow usermap parameter for all external authentication methods
-        (Magnus)
+        Change all authentication options to use <literal>name=value</>
+        syntax (Magnus)
        </para>
+      </listitem>
 
+      <listitem>
        <para>
-        Previously this was only supported for <literal>ident</>
-        authentication.
+        Allow a usermap parameter for all external authentication methods
+        (Magnus)
        </para>
-      </listitem>
 
-      <listitem>
        <para>
-        Allow <literal>ident</> authentication over Unix-domain sockets
-        on <productname>Solaris</> (Garick Hamlin)
+        Previously a usermap was only supported for <literal>ident</>
+        authentication.
        </para>
       </listitem>
 
@@ -846,8 +861,8 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Add <literal>krb5</>, <literal>gssapi</>, and <literal>sspi</>
-        <varname>include_realm</> parameter (Magnus)
+        Add <varname>include_realm</> parameter for <literal>krb5</>,
+        <literal>gssapi</>, and <literal>sspi</> methods (Magnus)
        </para>
 
        <para>
@@ -858,8 +873,8 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Show all parsing errors instead of aborting after the first
-        one (Selena Deckelmann)
+        Support <literal>ident</> authentication over Unix-domain sockets
+        on <productname>Solaris</> (Garick Hamlin)
        </para>
       </listitem>
 
@@ -885,7 +900,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <function>pg_stop_backup()</> wait for modified <acronym>WAL</>
+        Make <function>pg_stop_backup()</> wait for modified <acronym>WAL</>
         files to be archived (Simon)
        </para>
 
@@ -897,14 +912,14 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Prevent normal shutdown if a continuous archiving base backup
+        Delay <quote>smart</> shutdown while a continuous archiving base backup
         is in progress (Laurenz Albe)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Cancel a continuous archiving base backup if a fast shutdown
+        Cancel a continuous archiving base backup if <quote>fast</> shutdown
         is requested (Laurenz Albe)
        </para>
       </listitem>
@@ -913,6 +928,7 @@ do it for earlier branch release files.
        <para>
         Allow <filename>recovery.conf</> boolean variables to take the
         same range of string values as <filename>postgresql.conf</>
+        boolean variables
         (Bruce)
        </para>
       </listitem>
@@ -938,47 +954,53 @@ do it for earlier branch release files.
         Add <function>pg_terminate_backend()</> to safely terminate a
         backend (the <literal>SIGTERM</> signal works also) (Tom, Bruce)
        </para>
+
+       <para>
+        While it's always been possible to <literal>SIGTERM</> a single
+        backend, this was previously considered unsupported; and testing
+        of the case found some bugs that are now fixed.
+       </para>
       </listitem>
 
       <listitem>
        <para>
-        Add ability to track user-defined functions call counts and
-        runtimes via parameter <varname>track_functions</> (Martin
-        Pihlak)
+        Add ability to track user-defined functions' call counts and
+        runtimes (Martin Pihlak)
        </para>
 
        <para>
-        Function statistics appear in a new system table,
-        <literal>pg_stat_user_functions</>.  However, inlined
-        <acronym>SQL</> functions are not tracked.
+        Function statistics appear in a new system view,
+        <literal>pg_stat_user_functions</>.  Tracking is controlled
+        by the new parameter <varname>track_functions</>.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Allow specification of the maximum <literal>pg_stat_activity</>
-        query string size via <varname>track_activity_query_size</>
-        parameter (Thomas Lee)
+        Allow specification of the maximum query string size in
+        <literal>pg_stat_activity</> via new
+        <varname>track_activity_query_size</> parameter (Thomas Lee)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Improve syslog performance by increasing the maximum line length
-        (Tom)
+        Increase the maximum line length sent to <application>syslog</>, in
+        hopes of improving performance (Tom)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Add read-only <filename>postgresql.conf</> variables <varname>segment_size</>,
-        <varname>wal_block_size</>, and <varname>wal_segment_size</> (Bernd Helmle)
+        Add read-only configuration variables <varname>segment_size</>,
+        <varname>wal_block_size</>, and <varname>wal_segment_size</>
+        (Bernd Helmle)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        When reporting a deadlock, report all session queries involved
+        When reporting a deadlock, report the text of all queries involved
         in the deadlock to the server log  (Itagaki Takahiro)
        </para>
       </listitem>
@@ -1001,8 +1023,7 @@ do it for earlier branch release files.
         This allows the statistics file to be placed in a
         <acronym>RAM</>-resident directory to reduce I/O requirements.
         On startup/shutdown, the file is copied to the top-level
-        <literal>$PGDATA</> directory so it is preserved between
-        restarts.
+        <literal>$PGDATA</> directory so it is preserved across restarts.
        </para>
       </listitem>
 
@@ -1024,7 +1045,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add <literal>WITH</> clauses support, including <literal>WITH
+       Add support for <literal>WITH</> clauses (CTEs), including <literal>WITH
        RECURSIVE</> (Yoshiyuki Asaba, Tatsuo Ishii, Tom)
       </para>
      </listitem>
@@ -1035,8 +1056,8 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       <command>TABLE tablename</> is a short-hand for <command>SELECT
-       * FROM tablename</>.
+       <literal>TABLE tablename</> is a SQL standard short-hand for
+       <literal>SELECT * FROM tablename</>.
       </para>
      </listitem>
 
@@ -1044,8 +1065,25 @@ do it for earlier branch release files.
       <para>
        Allow <literal>AS</> to be optional when specifying a
        <command>SELECT</> (or <literal>RETURNING</>) column output
-       label (assuming the label is not an <acronym>SQL</> keyword)
-       (Hiroshi Saito)
+       label (Hiroshi Saito)
+      </para>
+
+      <para>
+       This works so long as the column label is not any
+       <productname>PostgreSQL</> keyword; otherwise <literal>AS</> is still
+       needed.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Support set-returning functions in <command>SELECT</> result lists
+       even for functions that return their result via a tuplestore (Tom)
+      </para>
+
+      <para>
+       In particular, this means that functions written in PL/PgSQL
+       and other PL languages can now be called this way.
       </para>
      </listitem>
 
@@ -1073,7 +1111,7 @@ do it for earlier branch release files.
        There are no remote or external <acronym>SQL/MED</> capabilities
        yet, but this change provides a standardized and future-proof
        system for managing connection information for modules like
-       dblink and plproxy.
+       <filename>dblink</> and <filename>plproxy</>.
       </para>
      </listitem>
 
@@ -1095,9 +1133,9 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       Specifically this allows <literal>array[row(1,2), row(3,4)]</>
-       and <literal>row(1,1.1) = any (array[row(7,7.7), row(1,1.0)])</>.
-       This is particularly useful for recursive queries.
+       This allows constructs such as
+       <literal>row(1, 1.1) = any (array[row(7, 7.7), row(1, 1.0)])</>.
+       This is particularly useful in recursive queries.
       </para>
      </listitem>
 
@@ -1113,6 +1151,11 @@ do it for earlier branch release files.
       <para>
        Improve the parser's ability to report error locations (Tom)
       </para>
+
+      <para>
+       An error location is now reported for many semantic errors,
+       such as mismatched datatypes, that previously could not be localized.
+      </para>
      </listitem>
 
     </itemizedlist>
@@ -1162,8 +1205,8 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <command>EXPLAIN VERBOSE</> show the output columns of a
-        query (Tom)
+        Make <command>EXPLAIN VERBOSE</> show the output columns of each
+        plan node (Tom)
        </para>
 
        <para>
@@ -1182,7 +1225,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <command>EXPLAIN</> honor <varname>debug_print_plan</> (Tom)
+        Make <command>EXPLAIN</> honor <varname>debug_print_plan</> (Tom)
        </para>
       </listitem>
 
@@ -1202,15 +1245,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Allow <literal>LIMIT</> and <literal>OFFSET</> to use subselects
-        as arguments (Tom)
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
-        Document that <literal>LIMIT NULL</> and <literal>OFFSET NULL</>
-        have no effect (Tom)
+        Allow sub-selects in <literal>LIMIT</> and <literal>OFFSET</> (Tom)
        </para>
       </listitem>
 
@@ -1261,7 +1296,7 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Add <literal>WITH [NO] DATA</> clause to <command>CREATE TABLE
-       AS</>, per the <acronym>SQL</> standard (Tom, Peter)
+       AS</>, per the <acronym>SQL</> standard (Peter, Tom)
       </para>
      </listitem>
 
@@ -1274,7 +1309,7 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Allow <command>CREATE AGGREGATE</> to use an <type>internal</>
-       transition datatype (for super-users only)  (Tom)
+       transition datatype (Tom)
       </para>
      </listitem>
 
@@ -1292,7 +1327,7 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Allow <command>CREATE OR REPLACE VIEW</> to add columns to the
-       <emphasis>end</> of a view (Robert Haas)
+       end of a view (Robert Haas)
       </para>
      </listitem>
 
@@ -1310,9 +1345,8 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Add <command>ALTER SEQUENCE ... RESTART</> (no parameter) to
+        Add <command>ALTER SEQUENCE ... RESTART</> (with no parameter) to
         reset a sequence to its initial value (Zoltan Boszormenyi)
-        bjm: compatibility problem?
        </para>
       </listitem>
 
@@ -1321,15 +1355,10 @@ do it for earlier branch release files.
         Modify the <command>ALTER TABLE</> syntax to allow all reasonable
         combinations for tables, indexes, sequences, and views (Tom)
        </para>
-      </listitem>
 
-      <listitem>
        <para>
-        New syntax supported (these formerly required <command>ALTER
-        TABLE</>)
-       </para>
+        This change allows the following new syntaxes:
 
-       <para>
         <itemizedlist>
          <listitem>
           <para>
@@ -1352,8 +1381,11 @@ do it for earlier branch release files.
           </para>
          </listitem>
         </itemizedlist>
-       </para>
 
+        There is no actual new functionality here, but formerly
+        you had to say <command>ALTER TABLE</> to do these things,
+        which was confusing.
+       </para>
       </listitem>
 
       <listitem>
@@ -1370,8 +1402,8 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <command>ALTER TABLE SET WITHOUT OIDS</> rewrite the table
-        to remove <type>OID</> values (Tom)
+        Make <command>ALTER TABLE SET WITHOUT OIDS</> rewrite the table
+        to physically remove <type>OID</> values (Tom)
        </para>
 
        <para>
@@ -1399,8 +1431,8 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Make <varname>LC_COLLATE</> and <varname>LC_CTYPE</> database-level
-        settings (Radek Strnad, Heikki)
+        Make <varname>LC_COLLATE</> and <varname>LC_CTYPE</> into
+        per-database settings (Radek Strnad, Heikki)
        </para>
 
        <para>
@@ -1437,7 +1469,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add verbose option to the <command>CLUSTER</> command and
+       Add a verbose option to the <command>CLUSTER</> command and
        <application>clusterdb</> (Jim Cox)
       </para>
      </listitem>
@@ -1469,13 +1501,13 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have hash indexes store only the hashed value, not the full
+        Make hash indexes store only the hashed value, not the full
         indexed columns (Xiao Meng)
        </para>
 
        <para>
         This greatly reduces the size of hash indexes for long indexed
-        values, and improves performance.
+        values, improving performance.
        </para>
       </listitem>
 
@@ -1493,7 +1525,7 @@ do it for earlier branch release files.
       <listitem>
        <para>
         <literal>xxx_pattern_ops</> indexes can now be used for simple
-        equality comparisons, not only <literal>LIKE</> (Tom)
+        equality comparisons, not only for <literal>LIKE</> (Tom)
        </para>
       </listitem>
 
@@ -1540,13 +1572,13 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Improve support for Nepali language and Devanagari alphabet (Teodor)
+        Support multi-column <acronym>GIN</> indexes (Teodor Sigaev)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Support multi-column <acronym>GIN</> indexes (Teodor Sigaev)
+        Improve support for Nepali language and Devanagari alphabet (Teodor)
        </para>
       </listitem>
 
@@ -1560,53 +1592,55 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Allow relation forks to track free space (Heikki)
+        Track free space in separate per-relation <quote>fork</> files (Heikki)
        </para>
 
        <para>
-        This allows the recording of all free space discovered by vacuum
-        in <filename>*.fsm</> files, rather than having to limit
-        recording to a fixed-sized shared memory area;
-        <varname>max_fsm_pages</> and <varname>max_fsm_relations</>
-        settings have been removed.
+        Free space discovered by <command>VACUUM</> is now recorded in
+        <filename>*_fsm</> files, rather than in a fixed-sized shared memory
+        area.  The <varname>max_fsm_pages</> and <varname>max_fsm_relations</>
+        settings have been removed, greatly simplifying administration of
+        free space management.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        New visibility map file to track pages that do not require
-        vacuum (Heikki)
+        Add a visibility map to track pages that do not require
+        vacuuming (Heikki)
        </para>
 
        <para>
-        This allows <command>VACUUM</> to avoid sequentially scanning
+        This allows <command>VACUUM</> to avoid scanning all of
         a table when only a portion of the table needs vacuuming.
+        The visibility map is stored in per-relation <quote>fork</> files.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Track explicit transaction snapshots (Alvaro)
+        Add <varname>vacuum_freeze_table_age</> parameter to control
+        when <command>VACUUM</> should ignore the visibility map and
+        do a full table scan to set frozen xids (Heikki)
        </para>
+      </listitem>
 
+      <listitem>
        <para>
-        This improves space reuse by vacuum in the presence of long-running
-        transactions.
+        Track transaction snapshots more carefully (Alvaro)
        </para>
-      </listitem>
 
-      <listitem>
        <para>
-        Add <varname>vacuum_freeze_table_age</> parameter to control
-        when <command>VACUUM</> should ignore the visibility map and
-        do a full table scan to set frozen xids (Heikki)
+        This can improve space reuse by <command>VACUUM</> in the presence of
+        long-running transactions.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Add ability to specify autovacuum and <acronym>TOAST</> parameters
-        in <command>CREATE TABLE</> (Alvaro, Euler Taveira de Oliveira)
+        Add ability to specify per-relation autovacuum and <acronym>TOAST</>
+        parameters in <command>CREATE TABLE</> (Alvaro, Euler Taveira de
+        Oliveira)
        </para>
 
        <para>
@@ -1646,26 +1680,26 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add <type>int2</> with <type>int8</> basic arithmetic operators
+       Add basic arithmetic operators for <type>int2</> with <type>int8</>
        (Tom)
       </para>
 
       <para>
-       This simplifies casting requirements.
+       This eliminates the need for explicit casting in some situations.
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Allow <type>UUID</> input to accept optional hyphens after
-       every four digits (Robert Haas)
+       Allow <type>UUID</> input to accept an optional hyphen after
+       every fourth digit (Robert Haas)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Accept <literal>on</>/<literal>off</> as boolean data type
-       values (Itagaki Takahiro)
+       Allow <literal>on</>/<literal>off</> as input for the boolean data type
+       (Itagaki Takahiro)
       </para>
      </listitem>
 
@@ -1689,9 +1723,9 @@ do it for earlier branch release files.
        </para>
 
        <para>
-        Previously these were interpreted as <literal>1 BC</>;  years
-        <literal>0</> and <literal>00</> are assumed to be the year
-        2000.
+        Previously these were interpreted as <literal>1 BC</>.
+        (Note: years <literal>0</> and <literal>00</> are still assumed to be
+        the year 2000.)
        </para>
       </listitem>
 
@@ -1704,8 +1738,8 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Support the <acronym>IS0 8601</> <type>interval</> syntax (Tom,
-        Kevin Grittner)
+        Support the <acronym>IS0 8601</> <type>interval</> syntax (Kevin
+        Grittner)
        </para>
 
        <para>
@@ -1716,41 +1750,42 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Allow <type>INTERVAL</> precision to be specified after the
+        Allow <type>interval</> precision to be specified after the
         last field, for <acronym>SQL</>-standards compliance (Tom)
        </para>
 
        <para>
         Formerly the precision had to be specified after the keyword
-        <type>INTERVAL</> (this syntax is still supported).  Data type
+        <type>interval</> (this syntax is still supported).  Data type
         definitions will now be output using the new format.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Support <literal>infinite</> dates (Tom)
+        Support <literal>infinity</> and <literal>-infinity</> as
+        values of type <type>date</> (Tom)
        </para>
       </listitem>
 
       <listitem>
        <para>
         Add <varname>IntervalStyle</> parameter
-        which controls how <type>INTERVAL</> values are output (Ron Mayer)
+        which controls how <type>interval</> values are output (Ron Mayer)
        </para>
 
        <para>
-        Valid value are:  <literal>postgres</>, <literal>postgres_verbose</>,
-        <literal>sql_standard</>, <literal>iso_8601</>.  This also
-        controls the handling of negative <type>INTERVAL</> input when only
+        Valid values are:  <literal>postgres</>, <literal>postgres_verbose</>,
+        <literal>sql_standard</>, <literal>iso_8601</>.  This setting also
+        controls the handling of negative <type>interval</> input when only
         some fields have positive/negative designations.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Make <type>INTERVAL</> seconds rounding more consistent across
-        output formats (Ron Mayer)
+        Improve consistency of handling of fractional seconds in
+        <type>timestamp</> and <type>interval</> output (Ron Mayer)
        </para>
       </listitem>
 
@@ -1764,13 +1799,18 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have cast on <type>ARRAY</> apply to all elements, not just
-        the array result (Brendan Jurd)
+        Improve the handling of casts applied to <literal>ARRAY[]</>
+        constructs, such as <literal>ARRAY[...]::integer[]</>
+        (Brendan Jurd)
        </para>
 
        <para>
-        This allows <literal>NULL</> <type>ARRAY</> entries as long as
-        they are properly cast.
+        Formerly <productname>PostgreSQL</> attempted to determine a data type
+        for the <literal>ARRAY[]</> construct without reference to the ensuing
+        cast.  This could fail unnecessarily in many cases, in particular when
+        the <literal>ARRAY[]</> construct was empty or contained only
+        ambiguous entries such as <literal>NULL</>.  Now the cast is consulted
+        to determine the type that the array elements must be.
        </para>
       </listitem>
 
@@ -1791,7 +1831,7 @@ do it for earlier branch release files.
       <listitem>
        <para>
         Add <function>array_length()</> to return the length
-        of an array for the specified dimensions (Jim Nasby, Robert
+        of an array for a specified dimension (Jim Nasby, Robert
         Haas, Peter Eisentraut)
        </para>
       </listitem>
@@ -1847,21 +1887,24 @@ do it for earlier branch release files.
       <listitem>
        <para>
         Consider <acronym>TOAST</> compression on values as short as
-        32 bytes (previously 256 bytes) (Tom)
+        32 bytes (previously 256 bytes) (Greg Stark)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Require 25% of space savings before using <acronym>TOAST</>
-        compression (previously 20%) (Tom)
+        Require 25% minimum space savings before using <acronym>TOAST</>
+        compression (previously 20% for small values and any-savings-at-all
+        for large values) (Greg)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Be more aggressive in storing <literal>EXTERNAL</> and
-        <literal>EXTENDED</> column values in <acronym>TOAST</>(Tom)
+        Improve toast heuristics for rows including a mix of large and
+        small toastable fields, so that we prefer to push large values
+        out of line and don't compress small values unnecessarily
+        (Greg, Tom)
        </para>
       </listitem>
 
@@ -1885,7 +1928,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add server side function <function>lo_import(filename, oid)</>
+       Add server-side function <function>lo_import(filename, oid)</>
        (Tatsuo)
       </para>
      </listitem>
@@ -1893,14 +1936,14 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Add <function>quote_nullable()</>, which behaves like
-       <function>quote_literal()</> but returns <literal>NULL</> for
+       <function>quote_literal()</> but returns the string <literal>NULL</> for
        a null argument (Brendan Jurd)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Improve full text search <function>headline()</> generation to
+       Improve full text search <function>headline()</> function to
        allow several fragments (Sushant Sinha)
       </para>
      </listitem>
@@ -1908,14 +1951,14 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Add <function>suppress_redundant_updates_trigger()</> trigger
-       function to avoid non-data-changing updates (Andrew)
+       function to prevent non-data-changing updates (Andrew)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Add <function>div(NUMERIC, NUMERIC)</> for <type>NUMERIC</>
-       division, without rounding (Tom)
+       Add <function>div(numeric, numeric)</> to perform <type>numeric</>
+       division without rounding (Tom)
       </para>
      </listitem>
 
@@ -1941,25 +1984,18 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Add <function>pg_get_keywords()</> to return predefined
+        Add <function>pg_get_keywords()</> to return a list of the
         parser keywords (Dave Page)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Add <function>pg_get_functiondef()</> to see a functions
+        Add <function>pg_get_functiondef()</> to see a function's
         definition (Abhijit Menon-Sen)
        </para>
       </listitem>
 
-      <listitem>
-       <para>
-        Modify <function>pg_relation_size()</> to handle free space
-        map (<filename>*.fsm</>) files (Heikki)
-       </para>
-      </listitem>
-
       <listitem>
        <para>
         Modify <function>pg_relation_size()</> to use <literal>regclass</>
@@ -1999,7 +2035,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <function>version()</> return information about whether
+        Make <function>version()</> return information about whether
         the server is a 32 or 64-bit binary (Bruce)
        </para>
       </listitem>
@@ -2028,7 +2064,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <function>pg_*_is_visible()</> and
+        Make <function>pg_*_is_visible()</> and
         <function>has_*_privilege()</> functions return <literal>NULL</>
         for invalid oids, rather than generate an error (Tom)
        </para>
@@ -2064,7 +2100,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Allow <literal>DEFAULT</> values for function arguments (Pavel
+        Support <literal>DEFAULT</> values for function arguments (Pavel
         Stehule)
        </para>
       </listitem>
@@ -2082,10 +2118,6 @@ do it for earlier branch release files.
         of an <command>INSERT</>/<command>UPDATE</>/<command>DELETE</>
         <literal>RETURNING</> clause (Tom)
        </para>
-
-       <para>
-        Formerly only <command>SELECT</> was supported.
-       </para>
       </listitem>
 
      </itemizedlist>
@@ -2104,7 +2136,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Allow looping over an open cursor using a <literal>FOR</>
+        Allow looping over the results of a cursor using a <literal>FOR</>
         loop (Pavel Stehule)
        </para>
       </listitem>
@@ -2118,7 +2150,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Improve the <literal>RAISE</> command: (Pavel Stehule)
+        Improve the <literal>RAISE</> command (Pavel Stehule)
 
         <itemizedlist>
          <listitem>
@@ -2139,7 +2171,7 @@ do it for earlier branch release files.
          <listitem>
           <para>
            Allow <literal>RAISE</> without parameters in an exception
-           block to rethrow the current error
+           block to re-throw the current error
           </para>
          </listitem>
         </itemizedlist>
@@ -2148,7 +2180,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Allow specification of <varname>SQLSTATE</> numeric codes
+        Allow specification of numeric <varname>SQLSTATE</> codes
         in <literal>EXCEPTION</> lists (Pavel Stehule)
        </para>
 
@@ -2219,7 +2251,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Remove <literal>-q</> (quiet) option for create* and drop*
+       Remove <literal>-q</> (quiet) option of create* and drop*
        utility commands (Peter)
       </para>
 
@@ -2232,19 +2264,19 @@ do it for earlier branch release files.
     </itemizedlist>
 
     <sect4>
-     <title><link linkend="APP-PSQL"><application>psql</></link></title>
+     <title><application>psql</></title>
      <itemizedlist>
 
       <listitem>
        <para>
-        Remove startup banner;  now just suggest <literal>help</>
+        Remove verbose startup banner; now just suggest <literal>help</>
         (Joshua Drake)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Have <literal>help</> show common backslash commands (Greg
+        Make <literal>help</> show common backslash commands (Greg
         Sabino Mullane)
        </para>
       </listitem>
@@ -2268,6 +2300,10 @@ do it for earlier branch release files.
         Require a space between a backslash command and the first
         argument (Bernd Helmle)
        </para>
+
+       <para>
+        This removes a historical source of ambiguity.
+       </para>
       </listitem>
 
       <listitem>
@@ -2279,14 +2315,14 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Improve tab completion support for schema qualified and
+        Improve tab completion support for schema-qualified and
         quoted identifiers (Greg Sabino Mullane)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Allow the normal range of boolean values in <command>\pset</>,
+        Allow all supported spellings of boolean values in <command>\pset</>,
         rather than just <literal>on</> and <literal>off</> (Bruce)
        </para>
       </listitem>
@@ -2300,13 +2336,13 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <command>\l</> show access privileges (Andrew Gilligan)
+        Make <command>\l</> show access privileges (Andrew Gilligan)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Have <command>\l+</> show database sizes, if permissions
+        Make <command>\l+</> show database sizes, if permissions
         allow (Andrew Gilligan)
        </para>
       </listitem>
@@ -2316,11 +2352,6 @@ do it for earlier branch release files.
         Add the <command>\ef</> command to edit function definitions
         (Abhijit Menon-Sen)
        </para>
-
-       <para>
-        <command>\ef</> without a function name creates an empty
-        function template for editing.
-       </para>
       </listitem>
 
      </itemizedlist>
@@ -2328,19 +2359,19 @@ do it for earlier branch release files.
     </sect4>
 
     <sect4>
-     <title><link linkend="APP-PSQL"><application>psql</></link> \d*</title>
+     <title><application>psql</> \d* commands</title>
      <itemizedlist>
 
       <listitem>
        <para>
-        Have <command>\d</> show cases where this table is referenced
-        as a foreign-key constraint (Kenneth D'Souza)
+        Make <command>\d</> show cases where the current table is referenced
+        by a foreign-key constraint (Kenneth D'Souza)
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Have <command>\d</> show the value of sequence columns
+        Make <command>\d</> on a sequence show its column values
         (Euler Taveira de Oliveira)
        </para>
       </listitem>
@@ -2355,7 +2386,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Show relation size in <command>\d+</> output (Dickson S.
+        Show relation size in <command>\dt+</> output (Dickson S.
         Guedes)
        </para>
       </listitem>
@@ -2369,25 +2400,15 @@ do it for earlier branch release files.
 
        <para>
         The former behavior was inconsistent across different variants
-        of <command>\d</>, and provided no easy way to see just user objects.
+        of <command>\d</>, and in most cases it provided no easy way to see
+        just user objects.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Make <command>\d</> and <command>\dt</> consistent in
-        their display of system tables (Bruce)
-       </para>
-
-       <para>
-        Previously, <literal>\d pg_class</> would show <literal>pg_class</>
-        while <literal>\dt pg_class</> would not.
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
-        Show enumerated values in <command>\dT+</> (David Fetter)
+        Show the values of <literal>enum</> types in <command>\dT+</> (David
+        Fetter)
        </para>
       </listitem>
 
@@ -2423,14 +2444,14 @@ do it for earlier branch release files.
     </sect4>
 
     <sect4>
-     <title><link linkend="APP-PGDUMP"><application>pg_dump</></link></title>
+     <title><application>pg_dump</></title>
      <itemizedlist>
 
       <listitem>
        <para>
         Add a <literal>--no-tablespaces</> option to
         <application>pg_dump</>/<application>pg_dumpall</>/<application>pg_restore</>
-        so dumps can be restored to clusters that have non-matching
+        so that dumps can be restored to clusters that have non-matching
         tablespace layouts (Gavin Roy)
        </para>
       </listitem>
@@ -2459,7 +2480,7 @@ do it for earlier branch release files.
        <para>
         Use of this option does not throw an error, but it has no
         effect.  This option was removed because the version checks
-        are considered necessary.
+        are necessary for safety.
        </para>
       </listitem>
 
@@ -2485,14 +2506,14 @@ do it for earlier branch release files.
       <listitem>
        <para>
         Reorder <application>pg_dump</> <literal>--data-only</> output
-        to dump primary-key tables referenced by foreign keys before
-        the foreign-key referencing tables (Tom)
+        to dump tables referenced by foreign keys before
+        the referencing tables (Tom)
        </para>
 
        <para>
         This allows data loads when foreign keys are already present.
-        If circular references make this impossible, a <literal>NOTICE</>
-        is issued.
+        If circular references make a safe ordering impossible, a
+        <literal>NOTICE</> is issued.
        </para>
       </listitem>
 
@@ -2506,20 +2527,20 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Allow <application>pg_restore</> of a custom format archive to
-        use multiple concurrent connections to do the restore (Andrew)
+        Allow <application>pg_restore</> to use multiple concurrent
+        connections to do the restore (Andrew)
        </para>
 
        <para>
         The number of concurrent connections is controlled by the option
-        <literal>--jobs</>.
+        <literal>--jobs</>.  This is supported only for custom-format archives.
        </para>
       </listitem>
 
       <listitem>
        <para>
-        Add new <application>pg_dump</> <literal>--binary-upgrade</>
-        option for use by binary upgrade utilities (Bruce)
+        Add new <application>pg_dump</> option <option>--binary-upgrade</>
+        for use by binary upgrade utilities (Bruce)
        </para>
       </listitem>
 
@@ -2533,13 +2554,13 @@ do it for earlier branch release files.
     <title>Programming Tools</title>
 
     <sect4>
-     <title><link linkend="libpq"><application>libpq</></link></title>
+     <title><application>libpq</></title>
      <itemizedlist>
 
       <listitem>
        <para>
-        Allow the <type>OID</> to be specified when importing large
-        objects using <function>lo_import_with_oid()</> (Tatsuo)
+        Allow the <type>OID</> to be specified when importing a large
+        object, via new function <function>lo_import_with_oid()</> (Tatsuo)
        </para>
       </listitem>
 
@@ -2563,7 +2584,7 @@ do it for earlier branch release files.
 
       <listitem>
        <para>
-        Have <function>PQexecParams()</> return
+        Make <function>PQexecParams()</> return
         <varname>PGRES_EMPTY_QUERY</> for an empty query (Tom)
        </para>
 
@@ -2584,8 +2605,8 @@ do it for earlier branch release files.
     </sect4>
 
     <sect4>
-     <title><link linkend="libpq"><application>libpq</></link>
-     <acronym>SSL</> (Secure Sockets Layer)</title>
+     <title><application>libpq</> <acronym>SSL</> (Secure Sockets Layer)
+      support</title>
      <itemizedlist>
 
       <listitem>
@@ -2604,13 +2625,6 @@ do it for earlier branch release files.
        </para>
       </listitem>
 
-      <listitem>
-       <para>
-        Allow the file locations for client certificates to be specified
-        (Mark Woodward, Alvaro, Magnus)
-       </para>
-      </listitem>
-
       <listitem>
        <para>
         Add connection parameter <literal>sslverify</> to control
@@ -2623,6 +2637,13 @@ do it for earlier branch release files.
        </para>
       </listitem>
 
+      <listitem>
+       <para>
+        Allow the file locations for client certificates to be specified
+        (Mark Woodward, Alvaro, Magnus)
+       </para>
+      </listitem>
+
       <listitem>
        <para>
         Add a <function>PQinitOpenSSL</> function to allow greater control
@@ -2633,7 +2654,7 @@ do it for earlier branch release files.
       <listitem>
        <para>
         Properly unregister <application>OpenSSL</> callbacks when
-        libpq is done with all connections (Bruce, Magnus, Russell Smith)
+        libpq is finished with all connections (Bruce, Magnus, Russell Smith)
        </para>
 
        <para>
@@ -2647,7 +2668,7 @@ do it for earlier branch release files.
     </sect4>
 
     <sect4>
-     <title><link linkend="ecpg"><application>ecpg</></link></title>
+     <title><application>ecpg</></title>
      <itemizedlist>
 
       <listitem>
@@ -2664,7 +2685,7 @@ do it for earlier branch release files.
        </para>
 
        <para>
-        Previously a separate ecpg parser was maintained.
+        Previously the ecpg parser was hand-maintained.
        </para>
       </listitem>
 
@@ -2705,24 +2726,6 @@ do it for earlier branch release files.
     <title>Build Options</title>
     <itemizedlist>
 
-     <listitem>
-      <para>
-       Support 64-bit time zone data files (Heikki)
-      </para>
-
-      <para>
-       This adds support for daylight saving time (<acronym>DST</>)
-       calculations beyond year 2038.
-      </para>
-     </listitem>
-
-     <listitem>
-      <para>
-       Fix bug in handling of the time zone database when cross-compiling
-       (Richard Evans)
-      </para>
-     </listitem>
-
      <listitem>
       <para>
        Update build system to use <productname>Autoconf</> 2.61 (Peter)
@@ -2735,8 +2738,8 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       This has been a requirement for several years but this removes
-       the infrastructure for supporting other parser tools.
+       This has effectively been required for several years, but now there
+       is no infrastructure claiming to support other parser tools.
       </para>
      </listitem>
 
@@ -2779,9 +2782,9 @@ do it for earlier branch release files.
       </para>
 
       <para>
-       This allows compile-time control over several constants that
-       affect how tables and <acronym>WAL</> files are segmented and
-       their internal block sizes.
+       This simplifies build-time control over several constants that
+       previously could only be changed by editing
+       <filename>pg_config_manual.h</>.
       </para>
      </listitem>
 
@@ -2812,13 +2815,13 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Append the major version number to the <application>gettext</>
+       Append the major version number to the backend <application>gettext</>
        domain, and the <literal>soname</> major version number to
-       libraries (Peter)
+       libraries' <application>gettext</> domain (Peter)
       </para>
 
       <para>
-       This simplifies parallel installations.
+       This simplifies parallel installations of multiple versions.
       </para>
      </listitem>
 
@@ -2836,14 +2839,6 @@ do it for earlier branch release files.
       </para>
      </listitem>
 
-     <listitem>
-      <para>
-       Fix problem when setting <varname>LC_MESSAGES</> on
-       <application>MSVC</>-built systems (Hiroshi Inoue, Hiroshi
-       Saito, Magnus)  bjm: details?
-      </para>
-     </listitem>
-
     </itemizedlist>
 
    </sect3>
@@ -2852,6 +2847,24 @@ do it for earlier branch release files.
     <title>Source Code</title>
     <itemizedlist>
 
+     <listitem>
+      <para>
+       Support 64-bit time zone data files (Heikki)
+      </para>
+
+      <para>
+       This adds support for daylight saving time (<acronym>DST</>)
+       calculations beyond the year 2038.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Fix bug in handling of the time zone database when cross-compiling
+       (Richard Evans)
+      </para>
+     </listitem>
+
      <listitem>
       <para>
        Link backend object files in one step, rather than in stages
@@ -2907,7 +2920,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add function hook to let plug-ins control the executor (Itagaki
+       Add function hook to let plug-ins monitor the executor (Itagaki
        Takahiro)
       </para>
      </listitem>
@@ -2976,6 +2989,14 @@ do it for earlier branch release files.
       </para>
      </listitem>
 
+     <listitem>
+      <para>
+       Fix problem when setting <varname>LC_MESSAGES</> on
+       <application>MSVC</>-built systems (Hiroshi Inoue, Hiroshi
+       Saito, Magnus)
+      </para>
+     </listitem>
+
     </itemizedlist>
 
    </sect3>
@@ -2986,21 +3007,14 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add query mode option to <filename>/contrib/pgbench</>
+       Add duration and query mode options to <filename>contrib/pgbench</>
        (Itagaki Takahiro)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Add duration option to <filename>/contrib/pgbench</> (Itagaki
-       Takahiro)
-      </para>
-     </listitem>
-
-     <listitem>
-      <para>
-       Fix <filename>/contrib/pgstattuple</> to handle tables and
+       Fix <filename>contrib/pgstattuple</> to handle tables and
        indexes with over 2 billion pages (Tatsuhito Kasahara)
       </para>
      </listitem>
@@ -3008,7 +3022,7 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Add Levenshtein string-distance function to
-       <filename>/contrib/fuzzystrmatch</> that allows the user to
+       <filename>contrib/fuzzystrmatch</> that allows the user to
        specify the cost of insertion, deletion, and substitution
        (Volkan Yazici)
       </para>
@@ -3017,37 +3031,37 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Remove <function>dblink_current_query()</> from
-       <filename>/contrib/dblink</>;  it should now use
+       <filename>contrib/dblink</>; one should now use
        <function>current_query()</> (Tomas Doran)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Have <filename>/contrib/ltree</> support multibyte encodings
+       Make <filename>contrib/ltree</> support multibyte encodings
        (laser)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Add <filename>/contrib/btree_gin</> to allow GIN indexes to
+       Add <filename>contrib/btree_gin</> to allow GIN indexes to
        handle more datatypes (Oleg, Teodor)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Add <filename>/contrib/citext</> as a case-insensitive,
+       Add <filename>contrib/citext</> to provide a case-insensitive,
        multibyte-aware text data type (David Wheeler)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Make sure <filename>/contrib/dblink</> uses a password supplied
-       by the user, and not accidentally from the server's .pgpass file
-       (Joe Conway)
+       Make sure <filename>contrib/dblink</> uses a password supplied
+       by the user, and not accidentally taken from the server's
+       <filename>.pgpass</> file (Joe Conway)
       </para>
 
       <para>
@@ -3058,26 +3072,28 @@ do it for earlier branch release files.
      <listitem>
       <para>
        Add <function>fsm_page_contents()</>
-       to<filename>/contrib/pageinspect</> (Heikki)
+       to <filename>contrib/pageinspect</> (Heikki)
       </para>
+     </listitem>
 
+     <listitem>
       <para>
        Modify <function>get_raw_page()</> to support free space map
-       (<filename>*.fsm</>) files.  Also update
-       <filename>/contrib/pg_freespacemap</>.
+       (<filename>*_fsm</>) files.  Also update
+       <filename>contrib/pg_freespacemap</>.
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Add support for multibyte encodings to <filename>/contrib/pg_trgm</>
+       Add support for multibyte encodings to <filename>contrib/pg_trgm</>
        (Teodor)
       </para>
      </listitem>
 
      <listitem>
       <para>
-       Rewrite <filename>/contrib/intagg</> to user new server-side
+       Rewrite <filename>contrib/intagg</> to use new
        functions <function>array_agg()</> and <function>unnest()</>
        (Tom)
       </para>
@@ -3085,13 +3101,13 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Remove <filename>/contrib/intarray</>'s definitions of the
+       Remove <filename>contrib/intarray</>'s definitions of the
        <literal>&lt;@</> and <literal>@&gt;</> operators (Tom)
       </para>
 
       <para>
        This avoids confusion with the equivalent built-in operators.
-       If necessary, the <filename>/contrib/intarray</> implementations
+       If needed, the <filename>contrib/intarray</> implementations
        are still available under their historical names <literal>@</>
        and <literal>~</>.
       </para>
@@ -3099,7 +3115,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add <filename>/contrib/auto_explain</> to automatically run
+       Add <filename>contrib/auto_explain</> to automatically run
        <command>EXPLAIN</> on queries exceeding a specified duration
        (Itagaki Takahiro, Tom)
       </para>
@@ -3107,7 +3123,7 @@ do it for earlier branch release files.
 
      <listitem>
       <para>
-       Add <filename>/contrib/pg_stat_statements</> for server-wide
+       Add <filename>contrib/pg_stat_statements</> for server-wide
        tracking of statement execution statistics (Itagaki Takahiro)
       </para>
      </listitem>