fine tune v11 release notes

From eaf42cd9f014a2420339afbd89be2e5f35cf49e7 Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" <jonathan.katz@excoventures.com>
Date: Sat, 13 Oct 2018 15:38:18 -0400
Subject: [PATCH 1/2] Updates to CREATE INDEX documentation.

Includes clarifications on new functionality availability in PostgreSQL 11,
as well as some language cleanups

Author: Justin Pryzby
Reviewed-by: Jonathan Katz
---
 doc/src/sgml/ref/create_index.sgml | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 3c1223b324..3424733851 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -612,11 +612,12 @@ Indexes:
 
    <para>
     Regular index builds permit other regular index builds on the
-    same table to occur in parallel, but only one concurrent index build
-    can occur on a table at a time.  In both cases, no other types of schema
-    modification on the table are allowed meanwhile.  Another difference
-    is that a regular <command>CREATE INDEX</command> command can be performed within
-    a transaction block, but <command>CREATE INDEX CONCURRENTLY</command> cannot.
+    same table to occur simultaneously, but only one concurrent index build
+    can occur on a table at a time.  In either case, schema modification of the
+    table is not allowed while the index is being built.  Another difference is
+    that a regular <command>CREATE INDEX</command> command can be performed
+    within a transaction block, but <command>CREATE INDEX CONCURRENTLY</command>
+    cannot.
    </para>
   </refsect2>
  </refsect1>
@@ -650,7 +651,7 @@ Indexes:
    ordering. For example, we might want to sort a complex-number data
    type either by absolute value or by real part. We could do this by
    defining two operator classes for the data type and then selecting
-   the proper class when making an index.  More information about
+   the proper class when creating an index.  More information about
    operator classes is in <xref linkend="indexes-opclass"/> and in <xref
    linkend="xindex"/>.
   </para>
@@ -673,7 +674,7 @@ Indexes:
    valid, once all partitions acquire the index.)  Note, however, that
    any partition that is created in the future using
    <command>CREATE TABLE ... PARTITION OF</command> will automatically
-   contain the index regardless of whether this option was specified.
+   contain the index regardless of <literal>ONLY</literal> being specified.
   </para>
 
   <para>
-- 
2.14.3 (Apple Git-98)

From 3af6130cbc551b75b7c7433a5cd0dfb6b01071db Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" <jonathan.katz@excoventures.com>
Date: Sat, 13 Oct 2018 15:59:10 -0400
Subject: [PATCH 2/2] Updates for PostgreSQL 11 Release notes.

Includes grammatical fixes and clarifications.

Author: Justin Pryzby
Reviewed-by: Jonathan Katz
---
 doc/src/sgml/release-11.sgml | 88 ++++++++++++++++++++++----------------------
 1 file changed, 43 insertions(+), 45 deletions(-)

diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml
index ca42f28cc9..5df6a418e9 100644
--- a/doc/src/sgml/release-11.sgml
+++ b/doc/src/sgml/release-11.sgml
@@ -32,19 +32,19 @@
        <listitem>
         <para>
          <command>UPDATE</command> statements that change a partition key
-         now move affected rows to the appropriate partitions
+         now cause affected rows to be moved to the appropriate partitions
         </para>
        </listitem>
        <listitem>
         <para>
          Improved <command>SELECT</command> performance from enhanced partition
-         elimination strategies during query processing and execution
+         elimination strategies during query planning and execution
         </para>
        </listitem>
        <listitem>
         <para>
-         Support for <literal>PRIMARY KEY</literal>, <literal>FOREIGN
-         KEY</literal>, indexes, and triggers on partitioned tables
+         Added support on partitioned tables for <literal>PRIMARY
+         KEY</literal>, <literal>FOREIGN KEY</literal>, indexes, and triggers
         </para>
        </listitem>
        <listitem>
@@ -118,9 +118,9 @@
 
     <listitem>
      <para>
-      Many other useful performance improvements, including making
-      <command>ALTER TABLE .. ADD COLUMN</command> with a
-      non-null column default faster
+      Many other useful performance improvements, including a significant
+      speedup to the <command>ALTER TABLE .. ADD COLUMN</command> with a
+      non-null column default as it no longer rewrites the full table.
      </para>
     </listitem>
 
@@ -163,7 +163,7 @@
        </para>
 
        <para>
-        Previously database attributes like
+        Previously, database attributes like
         <command>GRANT</command>/<command>REVOKE</command> permissions and
         <command>ALTER DATABASE SET</command> and <command>ALTER ROLE IN
         DATABASE SET</command> variable settings were only dumped by <link
@@ -192,7 +192,7 @@
        <para>
         A restore of <application>pg_dumpall</application> will now create
         databases with their original locale and encoding, and will fail if
-        the creation fails.  Previously <command>CREATE DATABASE</command>
+        the creation fails.  Previously, <command>CREATE DATABASE</command>
         would be dumped without such specifications if the database locale
         and encoding matched the old cluster's defaults.
        </para>
@@ -317,7 +317,7 @@
        </para>
 
        <para>
-        Previously _bytes_ were skipped.
+        Previously, <emphasis>bytes</emphasis> were skipped.
        </para>
       </listitem>
 
@@ -353,7 +353,7 @@
        <para>
         Per the SQL standard, relative paths start from the document node of
         the XML input document, not the root node as these functions
-        formerly did it.
+        previously did.
        </para>
       </listitem>
 
@@ -450,7 +450,7 @@
        </para>
 
        <para>
-        Previously index options names like ("FillFactor" = 50) were
+        Previously, index options names like ("FillFactor" = 50) were
         automatically lower-cased.  This quoted capitalization will now
         generate an error.
        </para>
@@ -519,7 +519,8 @@
 -->
 
        <para>
-        Allow faster partition elimination during query processing (Amit
+        Allow faster partition elimination during query planning (Amit
+???
         Langote, David Rowley, Dilip Kumar)
        </para>
 
@@ -539,7 +540,7 @@
        </para>
 
        <para>
-        Previously partition elimination could only happen at planning
+        Previously, partition elimination could only happen at planning
         time, meaning many joins and prepared queries could not use
         partition elimination.
        </para>
@@ -653,7 +654,7 @@
 
        <para>
         Creation of a trigger on partitioned tables automatically creates
-        triggers on all partition tables, and on newly-created ones.
+        triggers on all existing and future partitions.
         This also allows deferred unique constraints on partitioned tables.
        </para>
       </listitem>
@@ -666,9 +667,8 @@
 -->
 
        <para>
-        Allow equality joins between partitioned tables with identically
-        partitioned child tables to join the child tables directly
-        (Ashutosh Bapat)
+        Allow partitioned tables to be joined directly for equality joins with
+        identically partitioned child tables.  (Ashutosh Bapat)
        </para>
 
        <para>
@@ -725,7 +725,7 @@
 -->
 
        <para>
-        Allow btree indexes to be built in parallel (Peter Geoghegan,
+        Allow parallel building of a btree index (Peter Geoghegan,
         Rushabh Lathia, Heikki Linnakangas)
        </para>
       </listitem>
@@ -867,7 +867,7 @@ same commits as above
        <para>
         Allow indexes to <link
         linkend="sql-createindex"><literal>INCLUDE</literal></link> columns
-        that are not part of the unique constraint but are available
+        that are not part of the indexed columns but are available
         for index-only scans (Anastasia Lubennikova, Alexander Korotkov,
         Teodor Sigaev)
        </para>
@@ -901,7 +901,7 @@ same commits as above
        </para>
 
        <para>
-        Previously for each hash index entry, we need to refind the scan
+        Previously, for each hash index entry, we needed to refind the scan
         position within the page.  This cuts down on lock/unlock traffic.
        </para>
       </listitem>
@@ -1004,8 +1004,8 @@ same commits as above
        </para>
 
        <para>
-        Previously most-common-values (<acronym>MCV</acronym>) were
-        chosen based on their significance compared to all column
+        Previously, the most-common-values (<acronym>MCV</acronym>) were
+        chosen based on their frequency compared to all column
         values.  Now, <acronym>MCV</acronym> are chosen based on their
         significance compared to the non-<acronym>MCV</acronym> values.
         This improves the statistics for uniform (fewer) and non-uniform
@@ -1024,7 +1024,7 @@ same commits as above
        </para>
 
        <para>
-        Previously such cases used the same selectivity as &gt; and
+        Previously, such cases used the same selectivity as &gt; and
         &lt;, respectively.  This change is particularly useful for
         <literal>BETWEEN</literal> with small ranges.
        </para>
@@ -1095,8 +1095,8 @@ same commits as above
 
        <para>
         This feature requires <application>LLVM</application> to be
-        available, and it is not currently enabled by default, even in
-        builds that support it.
+        available. Even in builds that include <application>LLVM</application>,
+        <acronym>JIT</acronym> compilation is disabled by default.
        </para>
       </listitem>
 
@@ -1172,7 +1172,7 @@ same commits as above
        </para>
 
        <para>
-        Previously only non-join <command>UPDATE</command>s and
+        Previously, only non-join <command>UPDATE</command>s and
         <command>DELETE</command>s were pushed.
        </para>
 
@@ -1351,7 +1351,7 @@ same commits as above
         <literal>pg_execute_server_program</literal>.  These roles now also
         control who can use <command>COPY</command> and extension <link
         linkend="file-fdw"><application>file_fdw</application></link>.
-        Previously only superusers could use these functions, and that
+        Previously, only superusers could use these functions, and that
         is still the default behavior.
        </para>
       </listitem>
@@ -1390,8 +1390,7 @@ same commits as above
        </para>
 
        <para>
-        Previously, superusers were exclusively granted access to these
-        functions.
+        Previously, only superusers were granted access to these functions.
        </para>
 
        <para>
@@ -1415,7 +1414,7 @@ same commits as above
        <para>
         <productname>PostgreSQL</productname> only allows superusers to
         access <application>postgres_fdw</application> tables without
-        passwords, e.g. via <literal>peer</literal>.  Previously the
+        passwords, e.g. via <literal>peer</literal>.  Previously, the
         session owner had to be a superuser to allow such access;  now
         the view owner is checked instead.
        </para>
@@ -1519,7 +1518,7 @@ same commits as above
        </para>
 
        <para>
-        Previously the 16MB default could only be changed at compile time.
+        Previously, the 16MB default could only be changed at compile time.
        </para>
       </listitem>
 
@@ -1529,13 +1528,12 @@ same commits as above
 -->
 
        <para>
-        No longer retain <acronym>WAL</acronym> that spans two checkpoints
+        Retain <acronym>WAL</acronym> for a single checkpoint, only.
         (Simon Riggs)
        </para>
 
        <para>
-        The retention of <acronym>WAL</acronym> records for only one
-        checkpoint is required.
+        Previously, <acronym>WAL</acronym> was retained for two checkpoints.
        </para>
       </listitem>
 
@@ -1610,7 +1608,7 @@ same commits as above
 -->
 
        <para>
-        Allow heap pages checksums to be checked during streaming base
+        Allow checksums of heap pages to be verified during streaming base
         backup (Michael Banck)
        </para>
       </listitem>
@@ -1626,7 +1624,7 @@ same commits as above
        </para>
 
        <para>
-        This allows efficient advancement replication slots when the
+        This allows efficient advancing of replication slots when the
         contents do not need to be consumed.  This is performed by
         <function>pg_replication_slot_advance()</function>.
        </para>
@@ -1894,7 +1892,7 @@ same commits as above
        <para>
         Allow <function>to_char()</function> and
         <function>to_timestamp()</function> to specify the time zone's
-        hours and minutes from <acronym>UTC</acronym> (Nikita Glukhov,
+        offset from <acronym>UTC</acronym> in hours and minutes (Nikita Glukhov,
         Andrew Dunstan)
        </para>
 
@@ -1970,7 +1968,7 @@ same commits as above
         PROCEDURE</command></link> command and invoked via <link
         linkend="sql-call"><command>CALL</command></link>.  The new
         <command>ALTER</command>/<command>DROP ROUTINE</command> commands
-        allows altering/dropping of procedures, functions, and aggregates.
+        allow for altering/dropping of procedures, functions, and aggregates.
        </para>
       </listitem>
 
@@ -2019,7 +2017,7 @@ same commits as above
        </para>
 
        <para>
-        Previously such circumstances generated errors.
+        Previously, such circumstances generated errors.
        </para>
       </listitem>
 
@@ -2188,7 +2186,7 @@ same commits as above
        </para>
 
        <para>
-        Previously partition information would not be displayed for a
+        Previously, partition information would not be displayed for a
         partitioned table if it had no partitions.  Also indicate which
         partitions are themselves partitioned.
        </para>
@@ -2270,7 +2268,7 @@ same commits as above
        </para>
 
        <para>
-        Previously tab completion queries could fail.
+        Previously, tab completion queries could fail.
        </para>
 
       </listitem>
@@ -2789,9 +2787,9 @@ same commits as above
 -->
 
        <para>
-        Make the computation of system column
+        Make the computation of
         <structname>pg_class</structname>.<structfield>reltuples</structfield>
-        consistent (Tomas Vondra)
+        by VACUUM consistent with computation by ANALYZE (Tomas Vondra)
        </para>
       </listitem>
 
@@ -2951,7 +2949,7 @@ same commits as above
        </para>
 
        <para>
-        Previously only superusers could call adminpack functions;
+        Previously, only superusers could call adminpack functions;
         now role permissions are checked.
        </para>
       </listitem>
-- 
2.14.3 (Apple Git-98)

diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml
index 5df6a41..5594d43 100644
--- a/doc/src/sgml/release-11.sgml
+++ b/doc/src/sgml/release-11.sgml
@@ -49,8 +49,8 @@
        </listitem>
        <listitem>
         <para>
-         Having a "default" partition for storing data that does not match any
-         of the remaining partitions
+         Allow creation of a "default" partition for storing rows which are
+         excluded by bounds of all other partitions.
         </para>
        </listitem>
       </itemizedlist>
@@ -63,7 +63,7 @@
       <itemizedlist>
        <listitem>
         <para>
-         B-tree indexes can now be built in parallel with
+         A B-tree index can now be built in parallel with
          <command>CREATE INDEX</command>
         </para>
        </listitem>
@@ -118,9 +118,9 @@
 
     <listitem>
      <para>
-      Many other useful performance improvements, including a significant
-      speedup to the <command>ALTER TABLE .. ADD COLUMN</command> with a
-      non-null column default as it no longer rewrites the full table.
+      Many other useful performance improvements, including the ability to avoid
+      a table rewrite when using <command>ALTER TABLE .. ADD COLUMN</command>
+      with a non-null column default.
      </para>
     </listitem>
 
@@ -591,8 +591,8 @@
 -->
 
        <para>
-        Allow <literal>UNIQUE</literal> indexes on partitioned tables if
-        the partition key guarantees uniqueness (&Aacute;lvaro Herrera,
+        Allow <literal>UNIQUE</literal> indexes on partitioned tables when
+        the partition key is included in the index key (&Aacute;lvaro Herrera,
         Amit Langote)
        </para>
       </listitem>
@@ -603,15 +603,18 @@
 -->
 
        <para>
-        Allow indexes on a partitioned table to be automatically created
-        in any child partitions (&Aacute;lvaro Herrera)
+        Support indexes on partitioned tables (&Aacute;lvaro Herrera)
+       </para>
+
+       <para>
+        This is not a global index, but rather a mechanism to create indexes on
+        on each partition of a partitioned table.  
        </para>
 
        <para>
         The new command <link linkend="sql-alterindex"><command>ALTER
-        INDEX ATTACH PARTITION</command></link> allows indexes to be
-        attached to partitions.  This does not behave as a global index
-        since the contents are private to each index.
+        INDEX ATTACH PARTITION</command></link> allows an index on a partition
+        to be inherited by the index on its partitioned tables.
        </para>
       </listitem>
 
@@ -654,7 +657,7 @@
 
        <para>
         Creation of a trigger on partitioned tables automatically creates
-        triggers on all existing and future partitions.
+        triggers on all existing and any future partitions.
         This also allows deferred unique constraints on partitioned tables.
        </para>
       </listitem>
@@ -667,14 +670,16 @@
 -->
 
        <para>
-        Allow partitioned tables to be joined directly for equality joins with
-        identically partitioned child tables.  (Ashutosh Bapat)
+        Allow joins between partitioned tables to be performed directly
+        on partitions.  (Ashutosh Bapat)
        </para>
 
        <para>
-        This feature is disabled by default
-        but can be enabled by changing <link
-        linkend="guc-enable-partitionwise-join"><varname>enable_partitionwise_join</varname></link>.
+        This applies to equality joins between partitioned tables whose
+        partitions have exactly the same partition bounds.
+        This feature is disabled by default but can be enabled by changing
+        <link linkend="guc-enable-partitionwise-join"><varname>enable_partitionwise_join</varname></link>.
+
        </para>
       </listitem>
 
@@ -685,14 +690,13 @@
 -->
 
        <para>
-        Perform aggregation on each partition, and then merge the results
-        (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
+        Allow aggregate functions on partitioned tables to be evaluated
+        directly on partitions.  (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
        </para>
 
        <para>
-        This feature is disabled by default
-        but can be enabled by changing <link
-        linkend="guc-enable-partitionwise-aggregate"><varname>enable_partitionwise_aggregate</varname></link>.
+        This feature is disabled by default but can be enabled by changing
+        <link linkend="guc-enable-partitionwise-aggregate"><varname>enable_partitionwise_aggregate</varname></link>.
        </para>
       </listitem>
 
@@ -763,7 +767,7 @@ same commits as above
 -->
 
        <para>
-        Allow partition scans to more efficiently use parallel workers
+        Allow partition scans to use parallel workers
         (Amit Khandekar, Robert Haas, Amul Sul)
        </para>
       </listitem>
@@ -873,8 +877,9 @@ same commits as above
        </para>
 
        <para>
-        This is also useful for including columns that don't have btree
-        support.
+        This is also useful for including columns in a unique or
+        exclusion constraint which shouldn't participate in uniqueness, or
+        for including columns that don't have btree support.
        </para>
       </listitem>
 
@@ -886,8 +891,8 @@ same commits as above
 
        <para>
         Remember the highest btree index page to optimize future
-        monotonically increasing index additions (Pavan Deolasee, Peter
-        Geoghegan)
+        insertions of values for the case that those values are increasing
+        monotonically (Pavan Deolasee, Peter Geoghegan)
        </para>
       </listitem>
 
@@ -1008,8 +1013,8 @@ same commits as above
         chosen based on their frequency compared to all column
         values.  Now, <acronym>MCV</acronym> are chosen based on their
         significance compared to the non-<acronym>MCV</acronym> values.
-        This improves the statistics for uniform (fewer) and non-uniform
-        (more) distributions.
+        This allows improved estimates for both uniform and non-uniform
+        distributions.
        </para>
       </listitem>
 
@@ -1051,8 +1056,8 @@ same commits as above
 -->
 
        <para>
-        Improve row count optimizer estimates for <literal>EXISTS</literal>
-        and <literal>NOT EXISTS</literal> queries (Tom Lane)
+        Improve row count estimates for <literal>EXISTS</literal> and
+        <literal>NOT EXISTS</literal> queries (Tom Lane)
        </para>
       </listitem>
 
@@ -1095,7 +1100,7 @@ same commits as above
 
        <para>
         This feature requires <application>LLVM</application> to be
-        available. Even in builds that include <application>LLVM</application>,
+        available.  Even in builds that include <application>LLVM</application>,
         <acronym>JIT</acronym> compilation is disabled by default.
        </para>
       </listitem>
@@ -1488,11 +1493,11 @@ same commits as above
 
        <para>
         Allow server options related to memory and file sizes to be
-        specified as number of bytes (Beena Emerson)
+        specified in units of bytes (Beena Emerson)
        </para>
 
        <para>
-        The new unit is "B".  This is in addition to "kB", "MB", "GB"
+        The new suffix is "B".  This is in addition to "kB", "MB", "GB"
         and "TB".
        </para>
 
@@ -1528,12 +1533,12 @@ same commits as above
 -->
 
        <para>
-        Retain <acronym>WAL</acronym> for a single checkpoint, only.
+        Retain <acronym>WAL</acronym> spanning a single checkpoint, only.
         (Simon Riggs)
        </para>
 
        <para>
-        Previously, <acronym>WAL</acronym> was retained for two checkpoints.
+        Previously, <acronym>WAL</acronym> spanning two checkpoints was retained.
        </para>
       </listitem>
 
@@ -1704,9 +1709,8 @@ same commits as above
 -->
 
        <para>
-        Allow <command>ALTER TABLE</command> to add a column with
-        a non-null default without a table rewrite (Andrew Dunstan,
-        Serge Rielau)
+        When adding a column with a non-null default, avoid rewriting the table.
+        (Andrew Dunstan, Serge Rielau)
        </para>
       </listitem>
 
@@ -1750,6 +1754,7 @@ same commits as above
        </para>
 
        <para>
+DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
         Also, if any table mentioned in <command>VACUUM</command> uses
         a column list, then the <command>ANALYZE</command> keyword must be
         supplied; previously, <command>ANALYZE</command> was implied in
@@ -2028,7 +2033,7 @@ same commits as above
 
        <para>
         Add extension <application>jsonb_plpython</application> to
-        transform <type>JSONB </type>to/from PL/Python types (Anthony
+        transform <type>JSONB</type> to/from PL/Python types (Anthony
         Bykov)
        </para>
       </listitem>
@@ -2040,7 +2045,7 @@ same commits as above
 
        <para>
         Add extension <application>jsonb_plperl</application> to transform
-        <type>JSONB </type>to/from PL/Perl types (Anthony Bykov)
+        <type>JSONB</type> to/from PL/Perl types (Anthony Bykov)
        </para>
 
       </listitem>
@@ -2119,7 +2124,7 @@ same commits as above
 
        <para>
         Add <application>psql</application> command \gdesc to display
-        the column names and types of the query output (Pavel Stehule)
+        the names and types of the columns in query results (Pavel Stehule)
        </para>
       </listitem>
 
@@ -2152,7 +2157,7 @@ same commits as above
        </para>
 
        <para>
-        Specifically , the syntax <literal>:{?variable_name}</literal>
+        Specifically, the syntax <literal>:{?variable_name}</literal>
         allows a variable's existence to be tested in an \if statement.
        </para>
       </listitem>
@@ -2288,7 +2293,7 @@ same commits as above
 -->
 
        <para>
-        Add <application>pgbench</application> expressions support for
+        Add <application>pgbench</application> expression support for
         NULLs, booleans, and some functions and operators (Fabien Coelho)
        </para>
       </listitem>
@@ -2356,7 +2361,7 @@ same commits as above
 
        <para>
         Allow <application>pgbench</application> to do exponentiation
-        with <function>pow()</function> and  <function>power()</function>
+        with <function>pow()</function> and <function>power()</function>
         (Ra&uacute;l Mar&iacute;n Rodr&iacute;guez)
        </para>
       </listitem>
@@ -2789,7 +2794,7 @@ same commits as above
        <para>
         Make the computation of
         <structname>pg_class</structname>.<structfield>reltuples</structfield>
-        by VACUUM consistent with computation by ANALYZE (Tomas Vondra)
+        by VACUUM consistent with the computation by ANALYZE (Tomas Vondra)
        </para>
       </listitem>
 

diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 7bd1da3..e079d23 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -673,7 +673,7 @@ Indexes:
    valid, once all partitions acquire the index.)  Note, however, that
    any partition that is created in the future using
    <command>CREATE TABLE ... PARTITION OF</command> will automatically
-   contain the index regardless of whether <literal>ONLY</literal> was
+   contain the index regardless of <literal>ONLY</literal> being
    specified.
   </para>
 
diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml
index a945502..bb7d4c5 100644
--- a/doc/src/sgml/release-11.sgml
+++ b/doc/src/sgml/release-11.sgml
@@ -49,7 +49,7 @@
        </listitem>
        <listitem>
         <para>
-	 Allow creation of a "default" partition for storing rows which are
+         Allow creation of a "default" partition for storing rows which are
          excluded by bounds of all other partitions.
         </para>
        </listitem>
@@ -591,8 +591,9 @@
 -->
 
        <para>
-        Allow <literal>UNIQUE</literal> indexes on partitioned tables if
-        the partition key is included in the index (&Aacute;lvaro Herrera, Amit Langote)
+        Allow <literal>UNIQUE</literal> indexes on partitioned tables when
+        the partition key is included in the index key (&Aacute;lvaro Herrera,
+        Amit Langote)
        </para>
       </listitem>
 
@@ -606,14 +607,14 @@
        </para>
 
        <para>
-	This is not a global index, but rather a mechanism to create indexes on
-	on each partition of a partitioned table.  
+        This is not a global index, but rather a mechanism to create indexes on
+        on each partition of a partitioned table.  
        </para>
 
        <para>
         The new command <link linkend="sql-alterindex"><command>ALTER
-	INDEX ATTACH PARTITION</command></link> allows an index on a partition
-	to be inherited by the index on its partitioned tables.
+        INDEX ATTACH PARTITION</command></link> allows an index on a partition
+        to be inherited by the index on its partitioned tables.
        </para>
       </listitem>
 
@@ -656,7 +657,7 @@
 
        <para>
         Creation of a trigger on partitioned tables automatically creates
-        triggers on all existing and future partitions.
+        triggers on all existing and any future partitions.
         This also allows deferred unique constraints on partitioned tables.
        </para>
       </listitem>
@@ -669,14 +670,16 @@
 -->
 
        <para>
-        Allow partitioned tables to be joined directly for equality joins with
-        identically partitioned child tables.  (Ashutosh Bapat)
+        Allow joins between partitioned tables to be performed directly
+        on partitions.  (Ashutosh Bapat)
        </para>
 
        <para>
-        This feature is disabled by default
-        but can be enabled by changing <link
-        linkend="guc-enable-partitionwise-join"><varname>enable_partitionwise_join</varname></link>.
+        This applies to equality joins between partitioned tables whose
+        partitions have exactly the same partition bounds.
+        This feature is disabled by default but can be enabled by changing
+        <link linkend="guc-enable-partitionwise-join"><varname>enable_partitionwise_join</varname></link>.
+
        </para>
       </listitem>
 
@@ -687,14 +690,13 @@
 -->
 
        <para>
-        Allow first performing aggregate functions on each partition and then
-        merging the results.  (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
+        Allow aggregate functions on partitioned tables to be evaluated
+        directly on partitions.  (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
        </para>
 
        <para>
-        This feature is disabled by default
-        but can be enabled by changing <link
-        linkend="guc-enable-partitionwise-aggregate"><varname>enable_partitionwise_aggregate</varname></link>.
+        This feature is disabled by default but can be enabled by changing
+        <link linkend="guc-enable-partitionwise-aggregate"><varname>enable_partitionwise_aggregate</varname></link>.
        </para>
       </listitem>
 
@@ -875,8 +877,9 @@ same commits as above
        </para>
 
        <para>
-        This is also useful for including columns that don't have btree
-        support.
+        This is also useful for including columns in a unique or
+        exclusion constraint which shouldn't participate in uniqueness, or
+        for including columns that don't have btree support.
        </para>
       </listitem>
 
@@ -1097,7 +1100,8 @@ same commits as above
 
        <para>
         This feature requires <application>LLVM</application> to be
-        available, and it is currently disabled by default.
+        available.  Even in builds that include <application>LLVM</application>,                                                                                                                                                
+        <acronym>JIT</acronym> compilation is disabled by default.                                                                                                                                                             
        </para>
       </listitem>
 
@@ -1493,7 +1497,7 @@ same commits as above
        </para>
 
        <para>
-        The new unit suffix is "B".  This is in addition to "kB", "MB", "GB"
+        The new suffix is "B".  This is in addition to "kB", "MB", "GB"
         and "TB".
        </para>
 
@@ -1529,12 +1533,12 @@ same commits as above
 -->
 
        <para>
-        Retain <acronym>WAL</acronym> for a single checkpoint, only.
+        Retain <acronym>WAL</acronym> spanning a single checkpoint, only.
         (Simon Riggs)
        </para>
 
        <para>
-        Previously, <acronym>WAL</acronym> was retained for two checkpoints.
+        Previously, <acronym>WAL</acronym> spanning two checkpoints was retained.
        </para>
       </listitem>
 
@@ -1626,7 +1630,6 @@ same commits as above
 
        <para>
         This allows efficient advancing of replication slots when the
-????
         contents do not need to be consumed.  This is performed by
         <function>pg_replication_slot_advance()</function>.
        </para>
@@ -1706,8 +1709,8 @@ same commits as above
 -->
 
        <para>
-        Allow <command>ALTER TABLE</command> to avoid a table rewrite when
-        adding a column with a non-null default (Andrew Dunstan, Serge Rielau)
+        When adding a column with a non-null default, avoid rewriting the table.
+        (Andrew Dunstan, Serge Rielau)
        </para>
       </listitem>
 
@@ -1970,7 +1973,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
         PROCEDURE</command></link> command and invoked via <link
         linkend="sql-call"><command>CALL</command></link>.  The new
         <command>ALTER</command>/<command>DROP ROUTINE</command> commands
-        allow altering/dropping of procedures, functions, and aggregates.
+        allow for altering/dropping of procedures, functions, and aggregates.
        </para>
       </listitem>
 
@@ -2030,7 +2033,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
 
        <para>
         Add extension <application>jsonb_plpython</application> to
-        transform <type>JSONB </type>to/from PL/Python types (Anthony
+        transform <type>JSONB</type> to/from PL/Python types (Anthony
         Bykov)
        </para>
       </listitem>
@@ -2042,7 +2045,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
 
        <para>
         Add extension <application>jsonb_plperl</application> to transform
-        <type>JSONB </type>to/from PL/Perl types (Anthony Bykov)
+        <type>JSONB</type> to/from PL/Perl types (Anthony Bykov)
        </para>
 
       </listitem>
@@ -2121,7 +2124,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
 
        <para>
         Add <application>psql</application> command \gdesc to display
-        the column names and types of the query output (Pavel Stehule)
+        the names and types of the columns in query results (Pavel Stehule)
        </para>
       </listitem>
 
@@ -2154,7 +2157,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
        </para>
 
        <para>
-        Specifically , the syntax <literal>:{?variable_name}</literal>
+        Specifically, the syntax <literal>:{?variable_name}</literal>
         allows a variable's existence to be tested in an \if statement.
        </para>
       </listitem>
@@ -2290,7 +2293,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
 -->
 
        <para>
-        Add <application>pgbench</application> expressions support for
+        Add <application>pgbench</application> expression support for
         NULLs, booleans, and some functions and operators (Fabien Coelho)
        </para>
       </listitem>
@@ -2358,7 +2361,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
 
        <para>
         Allow <application>pgbench</application> to do exponentiation
-        with <function>pow()</function> and  <function>power()</function>
+        with <function>pow()</function> and <function>power()</function>
         (Ra&uacute;l Mar&iacute;n Rodr&iacute;guez)
        </para>
       </listitem>
@@ -2791,7 +2794,7 @@ DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
        <para>
         Make the computation of
         <structname>pg_class</structname>.<structfield>reltuples</structfield>
-        by VACUUM consistent with computation by ANALYZE (Tomas Vondra)
+        by VACUUM consistent with the computation by ANALYZE (Tomas Vondra)
        </para>
       </listitem>
 

diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml
index 188222f..cdf41af 100644
--- a/doc/src/sgml/release-11.sgml
+++ b/doc/src/sgml/release-11.sgml
@@ -31,8 +31,8 @@
        </listitem>
        <listitem>
         <para>
-         Add support for <literal>PRIMARY KEY</literal>, <literal>FOREIGN
-         KEY</literal>, indexes, and triggers on partitioned tables
+         Add support on partitioned tables for <literal>PRIMARY
+         KEY</literal>, <literal>FOREIGN KEY</literal>, indexes, and triggers
         </para>
        </listitem>
        <listitem>
@@ -65,7 +65,7 @@
        <listitem>
         <para>
          <command>CREATE INDEX</command> can now use parallel processing
-         while building B-tree indexes
+         while building a B-tree index
         </para>
        </listitem>
        <listitem>
@@ -117,9 +117,9 @@
 
     <listitem>
      <para>
-      Many other useful performance improvements, including a significant
-      speedup to <command>ALTER TABLE ... ADD COLUMN</command> with a
-      non-null column default, as it no longer rewrites the table data
+      Many other useful performance improvements, including the ability to avoid
+      a table rewrite when using <command>ALTER TABLE .. ADD COLUMN</command>
+      with a non-null column default.
      </para>
     </listitem>
 
@@ -587,15 +587,18 @@
 -->
 
        <para>
-        Allow indexes on a partitioned table to be automatically created
-        in new child partitions (&Aacute;lvaro Herrera)
+        Support indexes on partitioned tables (&Aacute;lvaro Herrera)
+       </para>
+
+       <para>
+        This is not a global index, but rather a mechanism to create an indexes
+        on each partition of a partitioned table.  
        </para>
 
        <para>
         The new command <link linkend="sql-alterindex"><command>ALTER
-        INDEX ATTACH PARTITION</command></link> allows indexes to be
-        attached to partitions.  This does not behave as a global index
-        since the contents are private to each index.
+        INDEX ATTACH PARTITION</command></link> allows an index on a partition
+        to be inherited by the index on its partitioned table.
        </para>
       </listitem>
 
@@ -733,8 +736,8 @@
 -->
 
        <para>
-        Perform aggregation on each partition, and then merge the results
-        (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
+        Allow aggregate functions on partitioned tables to be evaluated
+        directly on partitions.  (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
        </para>
 
        <para>
@@ -1101,8 +1104,8 @@ same commits as above
 -->
 
        <para>
-        Improve optimizer's row count estimates for <literal>EXISTS</literal>
-        and <literal>NOT EXISTS</literal> queries (Tom Lane)
+        Improve row count estimates for <literal>EXISTS</literal> and
+        <literal>NOT EXISTS</literal> queries (Tom Lane)
        </para>
       </listitem>
 
@@ -1146,7 +1149,7 @@ same commits as above
 
        <para>
         This feature requires <application>LLVM</application> to be
-        available.  It is not currently enabled by default, even in
+        available.  It is disabled by default, even in
         builds that support it.
        </para>
       </listitem>
@@ -1564,11 +1567,11 @@ same commits as above
 
        <para>
         Allow server options related to memory and file sizes to be
-        specified as a number of bytes (Beena Emerson)
+        specified in units of bytes (Beena Emerson)
        </para>
 
        <para>
-        The new unit is <quote>B</quote>.  This is in addition to the
+        The new suffix is <quote>B</quote>.  This is in addition to the
         existing units <quote>kB</quote>, <quote>MB</quote>, <quote>GB</quote>
         and <quote>TB</quote>.
        </para>
@@ -1605,7 +1608,7 @@ same commits as above
 -->
 
        <para>
-        Retain <acronym>WAL</acronym> data for only a single checkpoint
+        Retain <acronym>WAL</acronym> data for a single checkpoint, only.
         (Simon Riggs)
        </para>
 
@@ -1801,6 +1804,7 @@ same commits as above
        </para>
 
        <para>
+DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
         Also, if any table mentioned in <command>VACUUM</command> uses
         a column list, then the <command>ANALYZE</command> keyword must be
         supplied; previously, <command>ANALYZE</command> was implied in
@@ -2199,8 +2203,7 @@ same commits as above
 
        <para>
         Add <application>psql</application> command <literal>\gdesc</literal>
-        to display the column names and types of the query output (Pavel
-        Stehule)
+        to display the names and types of the columns in query results (Pavel Stehule)
        </para>
       </listitem>