Date: Mon, 12 Apr 2021 23:39:57 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: pgsql-hackers@postgresql.org, Bruce Momjian <bruce@momjian.us>
Subject: Re: doc review for v14
Message-ID: <20210413043957.GB6091@telsasoft.com>
References: <YBD/jjCqGoSFeUWW@paquier.xyz>
 <YBO6ZGbYRoc5Rkra@paquier.xyz>
 <20210210235557.GQ20012@telsasoft.com>
 <20210222080345.GA23313@telsasoft.com>
 <YDX924cg0EKAgW8v@paquier.xyz>
 <20210301004647.GF20769@telsasoft.com>
 <YDxpXjWpLj2Ww2n7@paquier.xyz>
 <20210301043354.GJ20769@telsasoft.com>
 <20210408164008.GJ6592@telsasoft.com>
 <YG/gH7++Msr16JYQ@paquier.xyz>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="TB36FDmn/VVEgNH/"
Content-Disposition: inline
In-Reply-To: <YG/gH7++Msr16JYQ@paquier.xyz>
User-Agent: Mutt/1.9.4 (2018-02-28)
Archived-At: 
 <https://www.postgresql.org/message-id/20210413043957.GB6091%40telsasoft.com>
Precedence: bulk


--TB36FDmn/VVEgNH/
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Fri, Apr 09, 2021 at 02:03:27PM +0900, Michael Paquier wrote:
> On Thu, Apr 08, 2021 at 11:40:08AM -0500, Justin Pryzby wrote:
> > Another round of doc review, not yet including all of yesterday's commits.
> 
> Thanks for compiling all that.  I got through the whole set and
> applied the most relevant parts on HEAD.  Some of them applied down to
> 9.6, so I have fixed it down where needed, for the parts that did not
> conflict too heavily.

Thanks.  Rebased with remaining, queued fixes.

-- 
Justin

--TB36FDmn/VVEgNH/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0001-doc-review-Add-support-for-PROVE_TESTS-and-PROVE_FLA.patch"

From 58b6a3ae7d76f6160bc7ad531f400da2fe0710eb Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Thu, 4 Mar 2021 19:32:05 -0600
Subject: [PATCH 1/7] doc review: Add support for PROVE_TESTS and PROVE_FLAGS
 in MSVC scripts

5bca69a76b3046a85c60c48271c1831fd5affa51
---
 doc/src/sgml/install-windows.sgml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml
index 64687b12e6..cb6bb05dc5 100644
--- a/doc/src/sgml/install-windows.sgml
+++ b/doc/src/sgml/install-windows.sgml
@@ -499,8 +499,8 @@ $ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib';
 
   <para>
    The TAP tests run with <command>vcregress</command> support the
-   environment variables <varname>PROVE_TESTS</varname>, that is expanded
-   automatically using the name patterns given, and
+   environment variables <varname>PROVE_TESTS</varname>, which is
+   expanded as a glob pattern, and
    <varname>PROVE_FLAGS</varname>. These can be set on a Windows terminal,
    before running <command>vcregress</command>:
 <programlisting>
-- 
2.17.0


--TB36FDmn/VVEgNH/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0002-doc-review-Pass-all-scan-keys-to-BRIN-consistent-fun.patch"

From 705507708c977e8172a2e091378099e630bad1b0 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Tue, 23 Mar 2021 13:39:36 -0500
Subject: [PATCH 2/7] doc review: Pass all scan keys to BRIN consistent
 function at once

commit a1c649d889bdf6e74e9382e1e28574d7071568de
---
 doc/src/sgml/brin.sgml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d2f12bb605..d2476481af 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -833,7 +833,7 @@ typedef struct BrinOpcInfo
       Returns whether all the ScanKey entries are consistent with the given
       indexed values for a range.
       The attribute number to use is passed as part of the scan key.
-      Multiple scan keys for the same attribute may be passed at once, the
+      Multiple scan keys for the same attribute may be passed at once; the
       number of entries is determined by the <literal>nkeys</literal> parameter.
      </para>
     </listitem>
-- 
2.17.0


--TB36FDmn/VVEgNH/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0003-doc-review-BRIN-minmax-multi-indexes.patch"

From b9bf3485cbd243bc09fcfd0f043ee8162b779e2f Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Fri, 26 Mar 2021 23:14:57 -0500
Subject: [PATCH 3/7] doc review: BRIN minmax-multi indexes

ab596105b55f1d7fbd5a66b66f65227d210b047d
---
 doc/src/sgml/brin.sgml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d2476481af..ce7c210575 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -730,7 +730,7 @@ LOG:  request for BRIN range summarization for index "brin_wi_idx" page 128 was
      for <xref linkend="sql-altertable"/>. When set to a positive value,
      each block range is assumed to contain this number of distinct non-null
      values. When set to a negative value, which must be greater than or
-     equal to -1, the number of distinct non-null is assumed linear with
+     equal to -1, the number of distinct non-null values is assumed to grow linearly with
      the maximum possible number of tuples in the block range (about 290
      rows per block). The default value is <literal>-0.1</literal>, and
      the minimum number of distinct non-null values is <literal>16</literal>.
@@ -1214,7 +1214,7 @@ typedef struct BrinOpcInfo
 
  <para>
   The minmax-multi operator class is also intended for data types implementing
-  a totally ordered sets, and may be seen as a simple extension of the minmax
+  a totally ordered set, and may be seen as a simple extension of the minmax
   operator class. While minmax operator class summarizes values from each block
   range into a single contiguous interval, minmax-multi allows summarization
   into multiple smaller intervals to improve handling of outlier values.
-- 
2.17.0


--TB36FDmn/VVEgNH/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0004-reltuples-not-relpages-Set-pg_class.reltuples-for-pa.patch"

From 61ee22354dc000000eb60fcbd88d83dbc5b9316f Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sat, 10 Apr 2021 20:56:35 -0500
Subject: [PATCH 4/7] reltuples not relpages: Set pg_class.reltuples for
 partitioned tables

commit 0e69f705cc1a3df273b38c9883fb5765991e04fe
Author: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date:   Fri Apr 9 11:29:08 2021 -0400
---
 src/backend/commands/analyze.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/backend/commands/analyze.c b/src/backend/commands/analyze.c
index cffcd54302..8aa329a2a0 100644
--- a/src/backend/commands/analyze.c
+++ b/src/backend/commands/analyze.c
@@ -660,7 +660,7 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
 	{
 		/*
 		 * Partitioned tables don't have storage, so we don't set any fields in
-		 * their pg_class entries except for relpages, which is necessary for
+		 * their pg_class entries except for reltuples, which is necessary for
 		 * auto-analyze to work properly.
 		 */
 		vac_update_relstats(onerel, -1, totalrows,
-- 
2.17.0


--TB36FDmn/VVEgNH/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0005-preprending-Multirange-datatypes.patch"

From 690d1446413fff5fb6eea6c839753aeb3f2846c2 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Mon, 12 Apr 2021 23:31:26 -0500
Subject: [PATCH 5/7] preprending: Multirange datatypes

6df7a9698bb036610c1e8c6d375e1be38cb26d5f
---
 src/backend/catalog/pg_type.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/backend/catalog/pg_type.c b/src/backend/catalog/pg_type.c
index ec5d122432..d50db2314e 100644
--- a/src/backend/catalog/pg_type.c
+++ b/src/backend/catalog/pg_type.c
@@ -988,7 +988,7 @@ makeMultirangeTypeName(const char *rangeTypeName, Oid typeNamespace)
  * makeUniqueTypeName
  *		Generate a unique name for a prospective new type
  *
- * Given a typeName, return a new palloc'ed name by preprending underscores
+ * Given a typeName, return a new palloc'ed name by prepending underscores
  * until a non-conflicting name results.
  *
  * If tryOriginal, first try with zero underscores.
-- 
2.17.0


--TB36FDmn/VVEgNH/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0006-lock-Make-use-of-in-core-query-id-added-by-commit-5f.patch"

From 39cb334d833a65e4ccc8436c76aa6e76b59e44b1 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Thu, 8 Apr 2021 00:11:53 -0500
Subject: [PATCH 6/7] lock: Make use of in-core query id added by commit
 5fd9dfa5f5

4f0b0966c866ae9f0e15d7cc73ccf7ce4e1af84b
---
 src/backend/utils/activity/backend_status.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/backend/utils/activity/backend_status.c b/src/backend/utils/activity/backend_status.c
index 6110113e56..5c1b2c25ed 100644
--- a/src/backend/utils/activity/backend_status.c
+++ b/src/backend/utils/activity/backend_status.c
@@ -1032,10 +1032,10 @@ pgstat_get_my_queryid(void)
 	if (!MyBEEntry)
 		return 0;
 
-	/* There's no need for a look around pgstat_begin_read_activity /
+	/* There's no need for a lock around pgstat_begin_read_activity /
 	 * pgstat_end_read_activity here as it's only called from
 	 * pg_stat_get_activity which is already protected, or from the same
-	 * backend which mean that there won't be concurrent write.
+	 * backend which means that there won't be concurrent writes.
 	 */
 	return MyBEEntry->st_queryid;
 }
-- 
2.17.0


--TB36FDmn/VVEgNH/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0007-WIP-doc-review-Add-DECLARE-STATEMENT-command-to-ECPG.patch"

From c6cb6a73fc5b0c6809f741b2bef7dabb0a854d9c Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Fri, 2 Apr 2021 09:23:42 -0500
Subject: [PATCH 7/7] WIP: doc review: Add DECLARE STATEMENT command to ECPG

ad8305a43d1890768a613d3fb586b44f17360f29
---
 doc/src/sgml/ecpg.sgml | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 56f5d9b5db..8f2908823a 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -354,14 +354,14 @@ current=testdb1 (should be testdb1)
   </para>
 
   <para>
-  The third option is to declare sql identifier linked to
+  The third option is to declare a SQL identifier linked to
   the connection, for example:
 <programlisting>
 EXEC SQL AT <replaceable>connection-name</replaceable> DECLARE <replaceable>statement-name</replaceable> STATEMENT;
 EXEC SQL PREPARE <replaceable>statement-name</replaceable> FROM :<replaceable>dyn-string</replaceable>;
 </programlisting>
-   Once you link a sql identifier to a connection, you execute a dynamic SQL
-   without AT clause. Note that this option behaves like preprocessor directives,
+   Once you link a SQL identifier to a connection, you execute dynamic SQL
+   without an AT clause. Note that this option behaves like preprocessor directives,
    therefore the link is enabled only in the file.
   </para>
   <para>
@@ -6911,14 +6911,14 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
     <title>Description</title>
 
     <para>
-     <command>DECLARE STATEMENT</command> declares SQL statement identifier.
+     <command>DECLARE STATEMENT</command> declares a SQL statement identifier.
      SQL statement identifier can be associated with the connection.
-     When the identifier is used by dynamic SQL statements, these SQLs are executed
-     by using the associated connection.
+     When the identifier is used by dynamic SQL statements, the statements are executed
+     using the associated connection.
      The namespace of the declaration is the precompile unit, and multiple declarations to
-     the same SQL statement identifier is not allowed.
+     the same SQL statement identifier are not allowed.
 
-     Note that if the precompiler run in the Informix compatibility mode and some SQL statement
+     Note that if the precompiler runs in Informix compatibility mode and some SQL statement
      is declared, "database" can not be used as a cursor name.
     </para>
    </refsect1>
-- 
2.17.0


--TB36FDmn/VVEgNH/--