Subject: [PATCH v3 01/12] review docs for pg12dev

From: Justin Pryzby <[email-masked]>
Date: Thu, 28 Mar 2019 18:50:03 -0500

---
 doc/src/sgml/bloom.sgml            |  2 +-
 doc/src/sgml/catalogs.sgml         |  4 ++--
 doc/src/sgml/config.sgml           | 15 +++++++------
 doc/src/sgml/ddl.sgml              |  8 +++----
 doc/src/sgml/ecpg.sgml             | 16 ++++++--------
 doc/src/sgml/libpq.sgml            |  2 +-
 doc/src/sgml/monitoring.sgml       | 44 +++++++++++++++++++-------------------
 doc/src/sgml/perform.sgml          |  8 +++----
 doc/src/sgml/protocol.sgml         |  6 +++---
 doc/src/sgml/ref/alter_table.sgml  |  4 ++--
 doc/src/sgml/ref/create_index.sgml |  4 ++--
 doc/src/sgml/ref/pg_rewind.sgml    | 17 +++++++--------
 doc/src/sgml/ref/pgbench.sgml      |  6 ++----
 doc/src/sgml/ref/reindex.sgml      |  2 +-
 doc/src/sgml/runtime.sgml          |  7 +++---
 doc/src/sgml/sources.sgml          | 36 +++++++++++++++----------------
 doc/src/sgml/xfunc.sgml            | 12 +++++------
 src/bin/pg_upgrade/check.c         |  6 +++---
 18 files changed, 98 insertions(+), 101 deletions(-)

diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml
index 6eeadde..c341b65 100644
--- a/doc/src/sgml/bloom.sgml
+++ b/doc/src/sgml/bloom.sgml
@@ -65,7 +65,7 @@
      <para>
       Number of bits generated for each index column. Each parameter's name
       refers to the number of the index column that it controls.  The default
-      is <literal>2</literal> bits and maximum is <literal>4095</literal>.  Parameters for
+      is <literal>2</literal> bits and the maximum is <literal>4095</literal>.  Parameters for
       index columns not actually used are ignored.
      </para>
     </listitem>
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 4c7e938..d544e60 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -3052,7 +3052,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        simplifies <command>ATTACH/DETACH PARTITION</command> operations:
        the partition dependencies need only be added or removed.
        Example: a child partitioned index is made partition-dependent
-       on both the partition table it is on and the parent partitioned
+       on both the table partition and the parent partitioned
        index, so that it goes away if either of those is dropped, but
        not otherwise.  The dependency on the parent index is primary,
        so that if the user tries to drop the child partitioned index,
@@ -3115,7 +3115,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
    Note that it's quite possible for two objects to be linked by more than
    one <structname>pg_depend</structname> entry.  For example, a child
    partitioned index would have both a partition-type dependency on its
-   associated partition table, and an auto dependency on each column of
+   associated table partition, and an auto dependency on each column of
    that table that it indexes.  This sort of situation expresses the union
    of multiple dependency semantics.  A dependent object can be dropped
    without <literal>CASCADE</literal> if any of its dependencies satisfies
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 36062c3..73eb768 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -112,7 +112,7 @@
        For example, <literal>30.1 GB</literal> will be converted
        to <literal>30822 MB</literal> not <literal>32319628902 B</literal>.
        If the parameter is of integer type, a final rounding to integer
-       occurs after any units conversion.
+       occurs after any unit conversion.
       </para>
      </listitem>
 
@@ -3433,7 +3433,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         current when the base backup was taken.  The
         value <literal>latest</literal> recovers
         to the latest timeline found in the archive, which is useful in
-        a standby server.  <literal>latest</literal> is the default.
+        a standby server.  The default is <literal>latest</literal>.
        </para>
 
        <para>
@@ -3540,7 +3540,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         servers or streaming base backup clients (i.e., the maximum number of
         simultaneously running WAL sender processes). The default is
         <literal>10</literal>.  The value <literal>0</literal> means
-        replication is disabled.  Abrupt streaming client disconnection might
+        replication is disabled.  Abrupt disconnection of a streaming client might
         leave an orphaned connection slot behind until a timeout is reached,
         so this parameter should be set slightly higher than the maximum
         number of expected clients so disconnected clients can immediately
@@ -4195,8 +4195,9 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
         This parameter is intended for use with streaming replication deployments;
         however, if the parameter is specified it will be honored in all cases.
 
-        <varname>hot_standby_feedback</varname> will be delayed by use of this feature
-        which could lead to bloat on the master; use both together with care.
+        <varname>hot_standby_feedback</varname> will be delayed by use of this feature.
+        Combinining these settings could lead to bloat on the master, so should
+        be done only with care.
 
         <warning>
          <para>
@@ -6947,8 +6948,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
        <para>
         Causes each action executed by autovacuum to be logged if it ran for at
         least the specified number of milliseconds.  Setting this to zero logs
-        all autovacuum actions. <literal>-1</literal> (the default) disables
-        logging autovacuum actions.  For example, if you set this to
+        all autovacuum actions. <literal>-1</literal> (the default) disables logging
+        autovacuum actions.  For example, if you set this to
         <literal>250ms</literal> then all automatic vacuums and analyzes that run
         250ms or longer will be logged.  In addition, when this parameter is
         set to any value other than <literal>-1</literal>, a message will be
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index a0a7435..cfe83a8 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3867,12 +3867,12 @@ CREATE INDEX ON measurement (logdate);
 
     <para>
       Normally the set of partitions established when initially defining the
-      table are not intended to remain static.  It is common to want to
-      remove old partitions of data and periodically add new partitions for
+      table are not intended to remain static.  It's common to
+      remove partitions of old data and add partitions for
       new data. One of the most important advantages of partitioning is
-      precisely that it allows this otherwise painful task to be executed
+      allowing this otherwise painful task to be executed
       nearly instantaneously by manipulating the partition structure, rather
-      than physically moving large amounts of data around.
+      than physically moving around large amounts of data.
     </para>
 
     <para>
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 6641eee..d2dd96c 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -979,7 +979,7 @@ EXEC SQL END DECLARE SECTION;
 
     <para>
      The other way is using the <type>VARCHAR</type> type, which is a
-     special type provided by ECPG.  The definition on an array of
+     special type provided by ECPG.  The definition of an array of
      type <type>VARCHAR</type> is converted into a
      named <type>struct</type> for every variable. A declaration like:
 <programlisting>
@@ -989,7 +989,7 @@ VARCHAR var[180];
 <programlisting>
 struct varchar_var { int len; char arr[180]; } var;
 </programlisting>
-     The member <structfield>arr</structfield> hosts the string
+     The member <structfield>arr</structfield> stores the string
      including a terminating zero byte.  Thus, to store a string in
      a <type>VARCHAR</type> host variable, the host variable has to be
      declared with the length including the zero byte terminator.  The
@@ -1209,8 +1209,8 @@ EXEC SQL END DECLARE SECTION;
      <title id="ecpg-type-bytea">bytea</title>
 
      <para>
-      The handling of the <type>bytea</type> type is also similar to
-      the <type>VARCHAR</type>. The definition on an array of type
+      The handling of the <type>bytea</type> type is similar to
+      the <type>VARCHAR</type>. The definition of an array of type
       <type>bytea</type> is converted into a named struct for every
       variable. A declaration like:
 <programlisting>
@@ -1220,9 +1220,8 @@ bytea var[180];
 <programlisting>
 struct bytea_var { int len; char arr[180]; } var;
 </programlisting>
-      The member <structfield>arr</structfield> hosts binary format
-      data. It also can handle even <literal>'\0'</literal> as part of
-      data unlike <type>VARCHAR</type>.
+      The member <structfield>arr</structfield> stores binary format
+      data, which can include zero bytes, unlike <type>VARCHAR</type>.
       The data is converted from/to hex format and sent/received by
       ecpglib.
      </para>
@@ -7571,8 +7570,7 @@ PREPARE <replaceable class="parameter">name</replaceable> FROM <replaceable clas
       <listitem>
        <para>
         A literal C string or a host variable containing a preparable
-        statement, one of the SELECT, INSERT, UPDATE, or
-        DELETE.
+        statement (SELECT, INSERT, UPDATE, or DELETE).
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7f01fcc..8a8427f 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1122,7 +1122,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>connect_timeout</literal></term>
       <listitem>
       <para>
-       Maximum wait for connection, in seconds (write as a decimal integer,
+       Maximum time to wait while connecting, in seconds (write as a decimal integer,
        e.g. <literal>10</literal>).  Zero, negative, or not specified means
        wait indefinitely.  The minimum allowed timeout is 2 seconds, therefore
        a value of <literal>1</literal> is interpreted as <literal>2</literal>.
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index a179d61..6c98596 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -271,13 +271,13 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
   <para>
    Some of the information in the dynamic statistics views shown in <xref
    linkend="monitoring-stats-dynamic-views-table"/> is security restricted.
-   Ordinary users can only see all the information about their own sessions
-   (sessions belonging to a role that they are a member of).  In rows about
+   Ordinary users can only see all information about their own sessions
+   (sessions belonging to a role of which they are a member).  In rows for
    other sessions, many columns will be null.  Note, however, that the
    existence of a session and its general properties such as its sessions user
    and database are visible to all users.  Superusers and members of the
    built-in role <literal>pg_read_all_stats</literal> (see also <xref
-   linkend="default-roles"/>) can see all the information about all sessions.
+   linkend="default-roles"/>) can see all information about all sessions.
   </para>
 
   <table id="monitoring-stats-dynamic-views-table">
@@ -2504,14 +2504,14 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
     <row>
      <entry><structfield>datname</structfield></entry>
      <entry><type>name</type></entry>
-     <entry>Name of this database, or <literal>NULL</literal> for the shared
+     <entry>Name of this database, or <literal>NULL</literal> for shared
      objects.</entry>
     </row>
     <row>
      <entry><structfield>numbackends</structfield></entry>
      <entry><type>integer</type></entry>
      <entry>Number of backends currently connected to this database, or
-     <literal>NULL</literal> for the shared objects.  This is the only column
+     <literal>NULL</literal> for shared objects.  This is the only column
      in this view that returns a value reflecting current state; all other
      columns return the accumulated values since the last reset.</entry>
     </row>
@@ -2633,7 +2633,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
 
   <para>
    The <structname>pg_stat_database</structname> view will contain one row
-   for each database in the cluster, plus one for the shared objects, showing
+   for each database in the cluster, plus one for shared objects, showing
    database-wide statistics.
   </para>
 
@@ -3594,16 +3594,16 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
       <entry><structfield>partitions_total</structfield></entry>
       <entry><type>bigint</type></entry>
       <entry>
-       When creating an index on a partitioned table, this column is set to
-       the total number of partitions on which the index is to be created.
+       When creating an index on a partitioned table, this is
+       the total number of partitions to be processed.
       </entry>
      </row>
      <row>
       <entry><structfield>partitions_done</structfield></entry>
       <entry><type>bigint</type></entry>
       <entry>
-       When creating an index on a partitioned table, this column is set to
-       the number of partitions on which the index has been completed.
+       When creating an index on a partitioned table, this is
+       the number of partitions for which the process is complete.
       </entry>
      </row>
     </tbody>
@@ -3643,9 +3643,9 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
       <entry>
        The index is being built by the access method-specific code.  In this phase,
        access methods that support progress reporting fill in their own progress data,
-       and the subphase is indicated in this column.  Typically,
+       and the subphase is indicated in this column.
        <structname>blocks_total</structname> and <structname>blocks_done</structname>
-       will contain progress data, as well as potentially
+       will contain progress data, as may
        <structname>tuples_total</structname> and <structname>tuples_done</structname>.
       </entry>
      </row>
@@ -3730,15 +3730,15 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
   <title>VACUUM Progress Reporting</title>
 
   <para>
-   Whenever <command>VACUUM</command> is running, the
-   <structname>pg_stat_progress_vacuum</structname> view will contain
-   one row for each backend (including autovacuum worker processes) that is
-   currently vacuuming.  The tables below describe the information
+   The <structname>pg_stat_progress_vacuum</structname> view will contain one
+   row for each backend that is running <command>VACUUM</command>, including
+   autovacuum worker processes.
+   The tables below describe the information
    that will be reported and provide information about how to interpret it.
    Progress for <command>VACUUM FULL</command> commands is reported via
-   <structname>pg_stat_progress_cluster</structname>
-   because both <command>VACUUM FULL</command> and <command>CLUSTER</command>
-   rewrite the table, while regular <command>VACUUM</command> only modifies it
+   <structname>pg_stat_progress_cluster</structname>,
+   because <command>VACUUM FULL</command> rewrites the table, like <command>CLUSTER</command>,
+   while regular <command>VACUUM</command> only modifies it
    in place. See <xref linkend='cluster-progress-reporting'/>.
   </para>
 
@@ -3922,9 +3922,9 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
   <title>CLUSTER Progress Reporting</title>
 
   <para>
-   Whenever <command>CLUSTER</command> or <command>VACUUM FULL</command> is
-   running, the <structname>pg_stat_progress_cluster</structname> view will
-   contain a row for each backend that is currently running either command.
+   The <structname>pg_stat_progress_cluster</structname> view will contain a
+   row for each backend that is running either
+   <command>CLUSTER</command> or <command>VACUUM FULL</command>.
    The tables below describe the information that will be reported and
    provide information about how to interpret it.
   </para>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index a84be85..65c161b 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -899,10 +899,10 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND unique2 &gt; 9000
     Generally, the <command>EXPLAIN</command> output will display details for
     every plan node which was generated by the query planner.  However, there
     are cases where the executor is able to determine that certain nodes are
-    not required; currently, the only node types to support this are the
-    <literal>Append</literal> and <literal>MergeAppend</literal> nodes.  These
-    node types have the ability to discard subnodes which they are able to
-    determine won't contain any records required by the query.  It is possible
+    not required; currently, the only node types to support this are
+    <literal>Append</literal> and <literal>MergeAppend</literal>, which
+    are able to discard subnodes when it's deduced that
+    they will not contain any records required by the query.  It is possible
     to determine that nodes have been removed in this way by the presence of a
     "Subplans Removed" property in the <command>EXPLAIN</command> output.
    </para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index b20f169..70f7286 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1515,7 +1515,7 @@ SELECT 1/0;
     the server will only accept encrypted packets from the client which are less
     than 16kB; <function>gss_wrap_size_limit()</function> should be used by the
     client to determine the size of the unencrypted message which will fit
-    within this limit and larger messages should be broken up into multiple
+    within this limit; larger messages should be broken up into multiple
     <function>gss_wrap()</function> calls.  Typical segments are 8kB of
     unencrypted data, resulting in encrypted packets of slightly larger than 8kB
     but well within the 16kB maximum.  The server can be expected to not send
@@ -1531,8 +1531,8 @@ SELECT 1/0;
     support to <productname>PostgreSQL</productname>.  In this case the
     connection must be closed, but the frontend might choose to open a fresh
     connection and proceed without requesting <acronym>GSSAPI</acronym>
-    encryption.  Given the length limits specified above, the ErrorMessage can
-    not be confused with a proper response from the server with an appropriate
+    encryption.  Given the length limits specified above, the ErrorMessage
+    cannot be confused with a proper response from the server with an appropriate
     length.
    </para>
 
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 49b081a..dd80bd0 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -219,7 +219,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
 
      <para>
       <literal>SET NOT NULL</literal> may only be applied to a column
-      providing none of the records in the table contain a
+      provided none of the records in the table contain a
       <literal>NULL</literal> value for the column.  Ordinarily this is
       checked during the <literal>ALTER TABLE</literal> by scanning the
       entire table; however, if a valid <literal>CHECK</literal> constraint is
@@ -642,7 +642,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       When applied to a partitioned table, nothing is moved, but any
       partitions created afterwards with
       <command>CREATE TABLE PARTITION OF</command> will use that tablespace,
-      unless the <literal>TABLESPACE</literal> clause is used to override it.
+      unless overridden by its <literal>TABLESPACE</literal> clause.
      </para>
 
      <para>
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 30bb38b..bf4f550 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -181,8 +181,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
        </para>
 
        <para>
-        Currently, the B-tree and the GiST index access methods support this
-        feature.  In B-tree and the GiST indexes, the values of columns listed
+        Currently, only the B-tree and GiST index access methods support this
+        feature.  In B-tree and GiST indexes, the values of columns listed
         in the <literal>INCLUDE</literal> clause are included in leaf tuples
         which correspond to heap tuples, but are not included in upper-level
         index entries used for tree navigation.
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 4d91eeb..6f6d220 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -106,15 +106,14 @@ PostgreSQL documentation
    </para>
 
    <para>
-    <application>pg_rewind</application> will fail immediately if it finds
-    files it cannot write directly to.  This can happen for example when
-    the source and the target server use the same file mapping for read-only
-    SSL keys and certificates.  If such files are present on the target server
+    <application>pg_rewind</application> will fail immediately if it experiences
+    a write error.  This can happen for example when
+    the source and target server use the same file mapping for read-only
+    SSL keys and certificates.  If such files are present on the target server,
     it is recommended to remove them before running
-    <application>pg_rewind</application>.  After doing the rewind, some of
+    <application>pg_rewind</application>.  After performing the rewind, some of
     those files may have been copied from the source, in which case it may
-    be necessary to remove the data copied and restore back the set of links
-    used before the rewind.
+    be necessary to remove them and restore the files removed beforehand.
    </para>
   </warning>
  </refsect1>
@@ -185,7 +184,7 @@ PostgreSQL documentation
         <command>pg_rewind</command> to return without waiting, which is
         faster, but means that a subsequent operating system crash can leave
         the synchronized data folder corrupt.  Generally, this option is
-        useful for testing but should not be used when creating a production
+        useful for testing but should not be used on a production
         installation.
        </para>
       </listitem>
@@ -266,7 +265,7 @@ GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, b
   <para>
    When executing <application>pg_rewind</application> using an online
    cluster as source which has been recently promoted, it is necessary
-   to execute a <command>CHECKPOINT</command> after promotion so as its
+   to execute a <command>CHECKPOINT</command> after promotion such that its
    control file reflects up-to-date timeline information, which is used by
    <application>pg_rewind</application> to check if the target cluster
    can be rewound using the designated source cluster.
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index ef22a48..7e8fc19 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -474,10 +474,8 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
            </listitem>
           </itemizedlist>
 
-        Because in "prepared" mode <application>pgbench</application> reuses
-        the parse analysis result for the second and subsequent query
-        iteration, <application>pgbench</application> runs faster in the
-        prepared mode than in other modes.
+        <application>pgbench</application> runs faster in prepared mode because the
+        parse analysis happens only during the first query.
        </para>
        <para>
         The default is simple query protocol.  (See <xref linkend="protocol"/>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index 303436c..5a1f634 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -240,7 +240,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURR
   <para>
    Reindexing a single index or table requires being the owner of that
    index or table.  Reindexing a schema or database requires being the
-   owner of that schema or database.  Note that is therefore sometimes
+   owner of that schema or database.  Note specifically that it's
    possible for non-superusers to rebuild indexes of tables owned by
    other users.  However, as a special exception, when
    <command>REINDEX DATABASE</command>, <command>REINDEX SCHEMA</command>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index e053e2e..798da30 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2634,8 +2634,9 @@ openssl x509 -req -in server.csr -text -days 365 \
    using <acronym>GSSAPI</acronym> to encrypt client/server communications for
    increased security.  Support requires that a <acronym>GSSAPI</acronym>
    implementation (such as MIT krb5) is installed on both client and server
-   systems, and that support in <productname>PostgreSQL</productname> is
-   enabled at build time (see <xref linkend="installation"/>).
+   systems, and must be enabled at the time
+   <productname>PostgreSQL</productname> is built (see <xref
+   linkend="installation"/>).
   </para>
 
   <sect2 id="gssapi-setup">
@@ -2644,7 +2645,7 @@ openssl x509 -req -in server.csr -text -days 365 \
    <para>
     The <productname>PostgreSQL</productname> server will listen for both
     normal and <acronym>GSSAPI</acronym>-encrypted connections on the same TCP
-    port, and will negotiate with any connecting client on whether to
+    port, and will negotiate with any connecting client whether to
     use <acronym>GSSAPI</acronym> for encryption (and for authentication).  By
     default, this decision is up to the client (which means it can be
     downgraded by an attacker); see <xref linkend="auth-pg-hba-conf"/> about
diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index a339ebb..2b9f59d 100644
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -103,7 +103,7 @@ less -x4
     message text.  In addition there are optional elements, the most
     common of which is an error identifier code that follows the SQL spec's
     SQLSTATE conventions.
-    <function>ereport</function> itself is just a shell function, that exists
+    <function>ereport</function> itself is just a shell function that exists
     mainly for the syntactic convenience of making message generation
     look like a function call in the C source code.  The only parameter
     accepted directly by <function>ereport</function> is the severity level.
@@ -359,7 +359,7 @@ ereport(ERROR,
      specify suppression of the <literal>CONTEXT:</literal> portion of a message in
      the postmaster log.  This should only be used for verbose debugging
      messages where the repeated inclusion of context would bloat the log
-     volume too much.
+     too much.
     </para>
    </listitem>
   </itemizedlist>
@@ -452,8 +452,8 @@ Hint:       the addendum
     enough for error messages.  Detail and hint messages can be relegated to a
     verbose mode, or perhaps a pop-up error-details window.  Also, details and
     hints would normally be suppressed from the server log to save
-    space. Reference to implementation details is best avoided since users
-    aren't expected to know the details.
+    space. References to implementation details are best avoided since users
+    aren't expected to know them.
    </para>
 
   </simplesect>
@@ -504,14 +504,14 @@ Hint:       the addendum
    <title>Use of Quotes</title>
 
    <para>
-    Use quotes always to delimit file names, user-supplied identifiers, and
+    Always use quotes to delimit file names, user-supplied identifiers, and
     other variables that might contain words.  Do not use them to mark up
     variables that will not contain words (for example, operator names).
    </para>
 
    <para>
     There are functions in the backend that will double-quote their own output
-    at need (for example, <function>format_type_be()</function>).  Do not put
+    as needed (for example, <function>format_type_be()</function>).  Do not put
     additional quotes around the output of such functions.
    </para>
 
@@ -880,16 +880,16 @@ BETTER: unrecognized node type: 42
      practices.
     </para>
     <para>
-     Features from later revision of the C standard or compiler specific
+     Features from later revisions of the C standard or compiler specific
      features can be used, if a fallback is provided.
     </para>
     <para>
-     For example <literal>_StaticAssert()</literal> and
+     For example, <literal>_StaticAssert()</literal> and
      <literal>__builtin_constant_p</literal> are currently used, even though
-     they are from newer revisions of the C standard and a
-     <productname>GCC</productname> extension respectively. If not available
-     we respectively fall back to using a C99 compatible replacement that
-     performs the same checks, but emits rather cryptic messages and do not
+     they are from a newer revision of the C standard and a
+     <productname>GCC</productname> extension, respectively. If not available, in the first case, 
+     we fall back to using a C99 compatible replacement that
+     performs the same checks, but emits rather cryptic messages; in the second case, we do not
      use <literal>__builtin_constant_p</literal>.
     </para>
    </simplesect>
@@ -939,8 +939,8 @@ MemoryContextSwitchTo(MemoryContext context)
      To be suitable to run inside a signal handler code has to be
      written very carefully. The fundamental problem is that, unless
      blocked, a signal handler can interrupt code at any time. If code
-     inside the signal handler uses the same state as code outside
-     chaos may ensue. As an example consider what happens if a signal
+     inside the signal handler uses the same state as code outside,
+     chaos may ensue. As an example, consider what happens if a signal
      handler tries to acquire a lock that's already held in the
      interrupted code.
     </para>
@@ -948,7 +948,7 @@ MemoryContextSwitchTo(MemoryContext context)
      Barring special arrangements code in signal handlers may only
      call async-signal safe functions (as defined in POSIX) and access
      variables of type <literal>volatile sig_atomic_t</literal>. A few
-     functions in <command>postgres</command> are also deemed signal safe, importantly
+     functions in <command>postgres</command> are also deemed signal safe; specifically,
      <function>SetLatch()</function>.
     </para>
     <para>
@@ -969,9 +969,9 @@ handle_sighup(SIGNAL_ARGS)
 }
 </programlisting>
      <varname>errno</varname> is saved and restored because
-     <function>SetLatch()</function> might change it. If that were not done
-     interrupted code that's currently inspecting <varname>errno</varname> might see the wrong
-     value.
+     <function>SetLatch()</function> might change it. If that were not done,
+     code interrupted by a signal might see the wrong value of
+     <varname>errno</varname>.
     </para>
    </simplesect>
 
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 3403269..5c17b10 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -3364,11 +3364,11 @@ if (!ptr)
   </indexterm>
 
    <para>
-    By default, a function is just a <quote>black box</quote> that the
-    database system knows very little about the behavior of.  However,
-    that means that queries using the function may be executed much less
+    By default, a function is a <quote>black box</quote> that the
+    database system knows very little about, which
+    means queries calling the function may be executed less
     efficiently than they could be.  It is possible to supply additional
-    knowledge that helps the planner optimize function calls.
+    information that helps the planner optimize function calls.
    </para>
 
    <para>
@@ -3381,7 +3381,7 @@ if (!ptr)
     The parallel safety property (<literal>PARALLEL
     UNSAFE</literal>, <literal>PARALLEL RESTRICTED</literal>, or
     <literal>PARALLEL SAFE</literal>) must also be specified if you hope
-    to use the function in parallelized queries.
+    queries calling the function to use parallel query.
     It can also be useful to specify the function's estimated execution
     cost, and/or the number of rows a set-returning function is estimated
     to return.  However, the declarative way of specifying those two
@@ -3393,7 +3393,7 @@ if (!ptr)
     It is also possible to attach a <firstterm>planner support
     function</firstterm> to a SQL-callable function (called
     its <firstterm>target function</firstterm>), and thereby provide
-    knowledge about the target function that is too complex to be
+    information about the target function that is too complex to be
     represented declaratively.  Planner support functions have to be
     written in C (although their target functions might not be), so this is
     an advanced feature that relatively few people will use.
diff --git a/src/bin/pg_upgrade/check.c b/src/bin/pg_upgrade/check.c
index 617270f..370c7aa 100644
--- a/src/bin/pg_upgrade/check.c
+++ b/src/bin/pg_upgrade/check.c
@@ -222,13 +222,13 @@ output_completion_banner(char *analyze_script_file_name,
 	/* Did we copy the free space files? */
 	if (GET_MAJOR_VERSION(old_cluster.major_version) >= 804)
 		pg_log(PG_REPORT,
-			   "Optimizer statistics are not transferred by pg_upgrade so,\n"
-			   "once you start the new server, consider running:\n"
+			   "Optimizer statistics are not transferred by pg_upgrade.\n"
+			   "Once you start the new server, consider running:\n"
 			   "    %s\n\n", analyze_script_file_name);
 	else
 		pg_log(PG_REPORT,
 			   "Optimizer statistics and free space information are not transferred\n"
-			   "by pg_upgrade so, once you start the new server, consider running:\n"
+			   "by pg_upgrade.  Once you start the new server, consider running:\n"
 			   "    %s\n\n", analyze_script_file_name);

-- 
2.7.4

--cWoXeonUoKmBZSoM
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="v3-0002-Add-comma-for-readability.patch"