Date: Sun, 27 Dec 2020 14:26:05 -0600
From: Justin Pryzby <pryzby@telsasoft.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: pgsql-hackers@postgresql.org, Bruce Momjian <bruce@momjian.us>,
	Thomas Munro <thomas.munro@gmail.com>
Subject: Re: doc review for v14
Message-ID: <20201227202604.GC26311@telsasoft.com>
References: <20201222041153.GK30237@telsasoft.com>
 <X+RNUu+zotOjfL7K@paquier.xyz>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="Pk6IbRAofICFmK5e"
Content-Disposition: inline
In-Reply-To: <X+RNUu+zotOjfL7K@paquier.xyz>
User-Agent: Mutt/1.9.4 (2018-02-28)
Precedence: bulk


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

On Thu, Dec 24, 2020 at 05:12:02PM +0900, Michael Paquier wrote:
> I have applied most of it on HEAD, except 0011 and the things noted
> above.  Thanks again.

Thank you.

I see that I accidentally included ZSTD_COMPRESSION in pg_backup_archiver.h
while cherry-picking from the branch where I first fixed this.  Sorry :(

> 0001-pgindent-typos.not-a-patch touches pg_bsd_indent.

I'm hoping that someone will apply it there, but I realize that access to its
repository is tightly controlled :)

On Thu, Dec 24, 2020 at 05:12:02PM +0900, Michael Paquier wrote:
> Restraining more the set of options is something to consider, though
> it could be annoying.  I have discarded this one for now.

Even though its -d is unused, I guess since wouldn't serve any significant
purpose, we shouldn't make pg_restore -l -d fail for no reason.

I think a couple of these should be backpatched.
doc/src/sgml/ref/pg_dump.sgml
doc/src/sgml/sources.sgml
doc/src/sgml/cube.sgml?
doc/src/sgml/func.sgml?

-- 
Justin

--Pk6IbRAofICFmK5e
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="0001-typos-in-master.patch"

From 9c24fa421e423edb29fc866a70e935843dab2804 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sat, 14 Nov 2020 23:09:21 -0600
Subject: [PATCH 1/7] typos in master

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

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 58d168c763..55d79c02f5 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -639,7 +639,7 @@ NUMERIC
 
     <para>
      The <literal>NaN</literal> (not a number) value is used to represent
-     undefined calculational results.  In general, any operation with
+     undefined computational results.  In general, any operation with
      a <literal>NaN</literal> input yields another <literal>NaN</literal>.
      The only exception is when the operation's other inputs are such that
      the same output would be obtained if the <literal>NaN</literal> were to
-- 
2.17.0


--Pk6IbRAofICFmK5e
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0002-producement-fcec6caafa2346b6c9d3ad5065e417733bd63cd9.patch"

From b4f8290d322a2d783352aff3a4b134acafa0a13c Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sun, 25 Oct 2020 13:53:08 -0500
Subject: [PATCH 2/7] producement?  fcec6caafa2346b6c9d3ad5065e417733bd63cd9

Previously discussed at
https://www.postgresql.org/message-id/20201102062203.GA15770%40paquier.xyz

Should backpatch
---
 src/backend/utils/adt/xml.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/backend/utils/adt/xml.c b/src/backend/utils/adt/xml.c
index 4c299057a6..ab3151cefb 100644
--- a/src/backend/utils/adt/xml.c
+++ b/src/backend/utils/adt/xml.c
@@ -4535,11 +4535,11 @@ XmlTableFetchRow(TableFuncScanState *state)
 	xtCxt = GetXmlTableBuilderPrivateData(state, "XmlTableFetchRow");
 
 	/*
-	 * XmlTable returns table - set of composite values. The error context, is
-	 * used for producement more values, between two calls, there can be
-	 * created and used another libxml2 error context. It is libxml2 global
-	 * value, so it should be refreshed any time before any libxml2 usage,
-	 * that is finished by returning some value.
+	 * XmlTable returns a table-set of composite values. The error context is
+	 * used for providing more detail. Between two calls, other libxml2
+	 * error contexts might have been created and used ; since they're libxml2 
+	 * global values, they should be refreshed each time before any libxml2 usage
+	 * that finishes by returning some value.
 	 */
 	xmlSetStructuredErrorFunc((void *) xtCxt->xmlerrcxt, xml_errorHandler);
 
-- 
2.17.0


--Pk6IbRAofICFmK5e
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="0003-cannot.patch"

From e2b22163feb706ecba670108b6760526ddb1d57b Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sun, 15 Nov 2020 10:23:32 -0600
Subject: [PATCH 3/7] cannot

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

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 4899bacda7..8fc1427d0a 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1532,8 +1532,8 @@ SELCT 1/0;<!-- this typo is intentional -->
     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>
 
-- 
2.17.0


--Pk6IbRAofICFmK5e
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0004-Doc-review-for-min_dynamic_shared_memory-84b1c63ad.patch"

From 4f78473ed9063464e2510bbd433e3ebc3b9a773e Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sat, 19 Dec 2020 03:30:25 -0600
Subject: [PATCH 4/7] Doc review for min_dynamic_shared_memory: 84b1c63ad

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

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index ce1fed7dfb..6b2acab9f4 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1941,13 +1941,13 @@ include_dir 'conf.d'
       <listitem>
        <para>
         Specifies the amount of memory that should be allocated at server
-        startup time for use by parallel queries.  When this memory region is
+        startup for use by parallel queries.  When this memory region is
         insufficient or exhausted by concurrent queries, new parallel queries
         try to allocate extra shared memory temporarily from the operating
         system using the method configured with
         <varname>dynamic_shared_memory_type</varname>, which may be slower due
         to memory management overheads.  Memory that is allocated at startup
-        time with <varname>min_dynamic_shared_memory</varname> is affected by
+        with <varname>min_dynamic_shared_memory</varname> is affected by
         the <varname>huge_pages</varname> setting on operating systems where
         that is supported, and may be more likely to benefit from larger pages
         on operating systems where that is managed automatically.
-- 
2.17.0


--Pk6IbRAofICFmK5e
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0005-Doc-review-for-pg_stat_replication_slots-986816750.patch"

From 0ea9b2e4b30e3304b9db434319cca13bda079e99 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sat, 19 Dec 2020 04:26:03 -0600
Subject: [PATCH 5/7] Doc review for pg_stat_replication_slots: 986816750

---
 doc/src/sgml/monitoring.sgml | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 243b437351..d26fb57ab6 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -317,7 +317,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      <row>
       <entry><structname>pg_stat_replication_slots</structname><indexterm><primary>pg_stat_replication_slots</primary></indexterm></entry>
       <entry>One row per replication slot, showing statistics about
-       replication slot usage.
+       the replication slot's usage.
        See <link linkend="monitoring-pg-stat-replication-slots-view">
        <structname>pg_stat_replication_slots</structname></link> for details.
       </entry>
@@ -2600,10 +2600,10 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
         <structfield>spill_txns</structfield> <type>bigint</type>
        </para>
        <para>
-        Number of transactions spilled to disk after the memory used by
-        logical decoding of changes from WAL for this slot exceeds
+        Number of transactions spilled to disk because the memory used by
+        logical decoding of changes from WAL for this slot exceeded
         <literal>logical_decoding_work_mem</literal>. The counter gets
-        incremented both for toplevel transactions and subtransactions.
+        incremented for both toplevel transactions and subtransactions.
       </para></entry>
      </row>
 
@@ -2613,8 +2613,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
        </para>
        <para>
         Number of times transactions were spilled to disk while decoding changes
-        from WAL for this slot. Transactions may get spilled repeatedly, and
-        this counter gets incremented on every such invocation.
+        from WAL for this slot. A given transaction may be spilled multiple times, and
+        this counter is incremented each time.
       </para></entry>
      </row>
 
@@ -2636,10 +2636,10 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
        </para>
        <para>
         Number of in-progress transactions streamed to the decoding output plugin
-        after the memory used by logical decoding of changes from WAL for this
-        slot exceeds <literal>logical_decoding_work_mem</literal>. Streaming only
+        because the memory used by logical decoding of changes from WAL for this
+        slot exceeded <literal>logical_decoding_work_mem</literal>. Streaming only
         works with toplevel transactions (subtransactions can't be streamed
-        independently), so the counter does not get incremented for subtransactions.
+        independently), so the counter is not incremented for subtransactions.
        </para></entry>
      </row>
 
@@ -2650,8 +2650,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
        <para>
         Number of times in-progress transactions were streamed to the decoding
         output plugin while decoding changes from WAL for this slot. Transactions
-        may get streamed repeatedly, and this counter gets incremented on every
-        such invocation.
+        may be streamed multiple times, and this counter is incremented each time.
       </para></entry>
      </row>
 
@@ -4970,10 +4969,10 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
        </para>
        <para>
          Resets statistics to zero for a single replication slot, or for all
-         replication slots in the cluster.  The argument can be either the name
-         of the slot to reset the stats or NULL.  If the argument is NULL, all
-         counters shown in the <structname>pg_stat_replication_slots</structname>
-         view for all replication slots are reset.
+         replication slots in the cluster.  The argument can be either NULL or the name
+         of a slot for which stats are to be reset.  If the argument is NULL, all
+         counters in the <structname>pg_stat_replication_slots</structname>
+         view are reset for all replication slots.
        </para>
        <para>
          This function is restricted to superusers by default, but other users
-- 
2.17.0


--Pk6IbRAofICFmK5e
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0006-pg_restore-must-be-specified-and-list.patch"

From c73d4ac6b1ef5c0e6ca5b19863b424de95492cff Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Sat, 5 Dec 2020 22:43:12 -0600
Subject: [PATCH 6/7] pg_restore: "must be specified" and --list

This was discussed here, but the idea got lost.
https://www.postgresql.org/message-id/flat/20190612170201.GA11881%40alvherre.pgsql#2984347ab074e6f198bd294fa41884df
---
 src/bin/pg_dump/pg_restore.c   | 2 +-
 src/bin/pg_dump/t/001_basic.pl | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/bin/pg_dump/pg_restore.c b/src/bin/pg_dump/pg_restore.c
index 589b4aed53..f6e6e41329 100644
--- a/src/bin/pg_dump/pg_restore.c
+++ b/src/bin/pg_dump/pg_restore.c
@@ -305,7 +305,7 @@ main(int argc, char **argv)
 	/* Complain if neither -f nor -d was specified (except if dumping TOC) */
 	if (!opts->cparams.dbname && !opts->filename && !opts->tocSummary)
 	{
-		pg_log_error("one of -d/--dbname and -f/--file must be specified");
+		pg_log_error("one of -d/--dbname, -f/--file, or -l/--list must be specified");
 		exit_nicely(1);
 	}
 
diff --git a/src/bin/pg_dump/t/001_basic.pl b/src/bin/pg_dump/t/001_basic.pl
index 083fb3ad08..8280914c2a 100644
--- a/src/bin/pg_dump/t/001_basic.pl
+++ b/src/bin/pg_dump/t/001_basic.pl
@@ -63,8 +63,8 @@ command_fails_like(
 
 command_fails_like(
 	['pg_restore'],
-	qr{\Qpg_restore: error: one of -d/--dbname and -f/--file must be specified\E},
-	'pg_restore: error: one of -d/--dbname and -f/--file must be specified');
+	qr{\Qpg_restore: error: one of -d/--dbname, -f/--file, or -l/--list must be specified\E},
+	'pg_restore: error: one of -d/--dbname, -f/--file, or -l/--list must be specified');
 
 command_fails_like(
 	[ 'pg_restore', '-s', '-a', '-f -' ],
-- 
2.17.0


--Pk6IbRAofICFmK5e
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment;
 filename="0007-Remove-ZSTD_COMPRESSION-accidentially-included-at-90.patch"

From 70093215a5aed14686c7b5f9d24b38960824dd57 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Thu, 24 Dec 2020 02:38:52 -0600
Subject: [PATCH 7/7] Remove ZSTD_COMPRESSION, accidentially included at
 90fbf7c57

---
 src/bin/pg_dump/pg_backup_archiver.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/bin/pg_dump/pg_backup_archiver.h b/src/bin/pg_dump/pg_backup_archiver.h
index 0847573339..a8ea5c7eae 100644
--- a/src/bin/pg_dump/pg_backup_archiver.h
+++ b/src/bin/pg_dump/pg_backup_archiver.h
@@ -332,7 +332,6 @@ struct _archiveHandle
 	int			compression;	/*---------
 								 * Compression requested on open().
 								 * Possible values for compression:
-								 * -2	ZSTD_COMPRESSION
 								 * -1	Z_DEFAULT_COMPRESSION
 								 *  0	COMPRESSION_NONE
 								 * 1-9 levels for gzip compression
-- 
2.17.0


--Pk6IbRAofICFmK5e--