On Tue, Apr 11, 2023 at 09:53:00AM -0500, Justin Pryzby wrote:
> On Tue, Apr 11, 2023 at 03:43:12PM +0100, Thom Brown wrote:
> > On Tue, 11 Apr 2023 at 15:39, Justin Pryzby <pry...@telsasoft.com> wrote:
> > >
> > > On Tue, Apr 11, 2023 at 03:36:02PM +0100, Thom Brown wrote:
> > > > I've attached a patch with a few typo and grammatical fixes.
> > >
> > > I think you actually sent the "git-diff" manpage :(
> >
> > Oh dear, well that's a first. Thanks for pointing out.
>
> Thanks. I think these are all new in v16, right ?
>
> I noticed some of these too - I'll send a patch pretty soon.
The first attachment fixes for typos in user-facing docs new in v16,
combining Thom's changes with the ones that I'd found. If that's
confusing, I'll resend my patches separately.
The other four numbered patches could use extra review.
--
Justin
diff --git a/doc/src/sgml/archive-modules.sgml
b/doc/src/sgml/archive-modules.sgml
index 7cf44e82e23..7064307d9e6 100644
--- a/doc/src/sgml/archive-modules.sgml
+++ b/doc/src/sgml/archive-modules.sgml
@@ -50,7 +50,7 @@
<function>_PG_archive_module_init</function>. The result of the function
must be a pointer to a struct of type
<structname>ArchiveModuleCallbacks</structname>, which contains everything
- that the core code needs to know how to make use of the archive module. The
+ that the core code needs to know to make use of the archive module. The
return value needs to be of server lifetime, which is typically achieved by
defining it as a <literal>static const</literal> variable in global scope.
@@ -82,7 +82,7 @@ typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit)
(void);
<para>
The <function>startup_cb</function> callback is called shortly after the
module is loaded. This callback can be used to perform any additional
- initialization required. If the archive module has a state, it can use
+ initialization required. If the archive module has any state, it can use
<structfield>state->private_data</structfield> to store it.
<programlisting>
@@ -143,7 +143,7 @@ typedef bool (*ArchiveFileCB) (ArchiveModuleState *state,
const char *file, cons
process exits (e.g., after an error) or the value of
<xref linkend="guc-archive-library"/> changes. If no
<function>shutdown_cb</function> is defined, no special action is taken in
- these situations. If the archive module has a state, this callback should
+ these situations. If the archive module has any state, this callback
should
free it to avoid leaks.
<programlisting>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index b9d73deced2..bcdc085010a 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -810,7 +810,7 @@ host all all ::1/128
trust
host all all localhost trust
# The same using a regular expression for DATABASE, that allows connection
-# to the database db1, db2 and any databases with a name beginning by "db"
+# to the database db1, db2 and any databases with a name beginning with "db"
# and finishing with a number using two to four digits (like "db1234" or
# "db12").
#
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index f81c2045ec4..20b8b5ae1de 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11835,7 +11835,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844)
id(24688,24696,0,0,0,1)
option of
<link linkend="sql-createsubscription"><command>CREATE
SUBSCRIPTION</command></link>
is enabled, otherwise, serialize each change. When set to
- <literal>buffered</literal>, the decoding will stream or serialize
+ <literal>buffered</literal>, decoding will stream or serialize
changes when <varname>logical_decoding_work_mem</varname> is reached.
</para>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index e6a7514100e..9c3b2018896 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -27084,8 +27084,9 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number *
ps.setting::int + :offset
</para>
<para>
Take a snapshot of running transactions and write it to WAL, without
- having to wait bgwriter or checkpointer to log one. This is useful for
- logical decoding on standby, as logical slot creation has to wait
+ having to wait for <literal>bgwriter</literal> or
+ <literal>checkpointer</literal> to log one. This is useful for
+ logical decoding on a standby, as logical slot creation has to wait
until such a record is replayed on the standby.
</para></entry>
</row>
diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 29ece7c42ee..e813e2b620a 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -257,7 +257,7 @@ typedef struct IndexAmRoutine
Access methods that do not point to individual tuples, but to block ranges
(like <acronym>BRIN</acronym>), may allow the <acronym>HOT</acronym>
optimization
to continue. This does not apply to attributes referenced in index
- predicates, an update of such attribute always disables
<acronym>HOT</acronym>.
+ predicates, an update of such an attribute always disables
<acronym>HOT</acronym>.
</para>
</sect1>
diff --git a/doc/src/sgml/install-windows.sgml
b/doc/src/sgml/install-windows.sgml
index 2db44db2fd9..cbc70a039c2 100644
--- a/doc/src/sgml/install-windows.sgml
+++ b/doc/src/sgml/install-windows.sgml
@@ -550,7 +550,7 @@ $ENV{PROVE_TESTS}='t/020*.pl t/010*.pl'
<varlistentry>
<term><varname>OPENSSL</varname></term>
<listitem><para>
- Path to a <application>openssl</application> command. The default is
+ Path to an <application>openssl</application> command. The default is
<literal>openssl</literal>, which will search for a command by that
name in the configured <envar>PATH</envar>.
</para></listitem>
diff --git a/doc/src/sgml/logicaldecoding.sgml
b/doc/src/sgml/logicaldecoding.sgml
index ebe0376e3e6..aac72581378 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -326,11 +326,12 @@ postgres=# select * from
pg_logical_slot_get_changes('regression_slot', NULL, NU
connection is alive (for example a node restart would break it). Then, the
primary may delete system catalog rows that could be needed by the logical
decoding on the standby (as it does not know about the catalog_xmin on the
- standby). Existing logical slots on standby also get invalidated if
wal_level
- on primary is reduced to less than 'logical'. This is done as soon as the
- standby detects such a change in the WAL stream. It means, that for
walsenders
- that are lagging (if any), some WAL records up to the wal_level parameter
change
- on the primary won't be decoded.
+ standby). Existing logical slots on the standby also get invalidated if
+ <varname>wal_level</varname> on the primary is reduced to less than
+ <literal>logical</literal>.
+ This is done as soon as the standby detects such a change in the WAL
stream.
+ It means that, for walsenders which are lagging (if any), some WAL
records up
+ to the wal_level parameter change on the primary won't be decoded.
</para>
<para>
@@ -340,7 +341,7 @@ postgres=# select * from
pg_logical_slot_get_changes('regression_slot', NULL, NU
primary. Thus, slot creation may need to wait for some activity to happen
on the primary. If the primary is idle, creating a logical slot on
standby may take noticeable time. This can be sped up by calling the
- <function>pg_log_standby_snapshot</function> on the primary.
+ <function>pg_log_standby_snapshot</function> function on the primary.
</para>
<caution>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 3f33a1c56c9..a37331ec524 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -4740,7 +4740,7 @@ SELECT pid, wait_event_type, wait_event FROM
pg_stat_activity WHERE wait_event i
</para>
<para>
Number of uses of logical slots in this database that have been
- canceled due to old snapshots or a too low <xref
linkend="guc-wal-level"/>
+ canceled due to old snapshots or too low a <xref
linkend="guc-wal-level"/>
on the primary
</para></entry>
</row>
diff --git a/doc/src/sgml/pgbuffercache.sgml b/doc/src/sgml/pgbuffercache.sgml
index 43c52e38298..27fdfc67a39 100644
--- a/doc/src/sgml/pgbuffercache.sgml
+++ b/doc/src/sgml/pgbuffercache.sgml
@@ -214,7 +214,7 @@
<structfield>buffers_used</structfield> <type>int4</type>
</para>
<para>
- Number of unused shared buffers
+ Number of used shared buffers
</para></entry>
</row>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 9e66987cf7f..a122794df3c 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -515,7 +515,7 @@ OPTIONS (ADD password_required 'false');
When multiple remote subtransactions are involved in the current local
subtransaction, by default <filename>postgres_fdw</filename> commits or
aborts those remote subtransactions serially when the local subtransaction
- is committed or abortd.
+ is committed or aborted.
Performance can be improved with the following options:
</para>
@@ -525,8 +525,8 @@ OPTIONS (ADD password_required 'false');
<term><literal>parallel_commit</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- This option controls whether <filename>postgres_fdw</filename> commits
- in parallel remote transactions opened on a foreign server in a local
+ This option controls whether <filename>postgres_fdw</filename> commits,
+ in parallel, remote transactions opened on a foreign server in a local
transaction when the local transaction is committed. This setting also
applies to remote and local subtransactions. This option can only be
specified for foreign servers, not per-table. The default is
diff --git a/doc/src/sgml/ref/create_publication.sgml
b/doc/src/sgml/ref/create_publication.sgml
index e3e1d04e73a..606aa64ecfa 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -205,7 +205,7 @@ CREATE PUBLICATION <replaceable
class="parameter">name</replaceable>
There can be a case where a subscription combines multiple
publications. If a partitioned table is published by any
subscribed publications which set
- <literal>publish_via_partition_root</literal> = true, changes on this
+ <literal>publish_via_partition_root = true</literal>, changes on this
partitioned table (or on its partitions) will be published using
the identity and schema of this partitioned table rather than
that of the individual partitions.
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index 0e19da90d38..c5c74b86a20 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -85,7 +85,7 @@ PostgreSQL documentation
<term><option>--admin=<replaceable
class="parameter">role</replaceable></option></term>
<listitem>
<para>
- Indicates role that will be immediately added as a member of the new
+ Indicates a role that will be immediately added as a member of the new
role with admin option, giving it the right to grant membership in the
new role to others. Multiple roles to add as members (with admin
option) of the new role can be specified by writing multiple
@@ -153,7 +153,7 @@ PostgreSQL documentation
<term><option>--role=<replaceable
class="parameter">role</replaceable></option></term>
<listitem>
<para>
- Indicates role to which this role will be added immediately as a new
+ Indicates a role to which this role will be added immediately as a new
member. Multiple roles to which this role will be added as a member
can be specified by writing multiple
<option>-g</option> switches.
diff --git a/doc/src/sgml/ref/pg_waldump.sgml b/doc/src/sgml/ref/pg_waldump.sgml
index 7685d3d15b9..300edc9fc41 100644
--- a/doc/src/sgml/ref/pg_waldump.sgml
+++ b/doc/src/sgml/ref/pg_waldump.sgml
@@ -295,7 +295,7 @@ PostgreSQL documentation
<row>
<entry>FORK</entry>
<entry>
- The name of the fork the full page image came from, as of
+ The name of the fork the full page image came from, such as
<literal>_main</literal>, <literal>_fsm</literal>,
<literal>_vm</literal>, or <literal>_init</literal>.
</entry>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index f4f25d1b076..dc422373d6f 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -2903,17 +2903,16 @@ lo_import 152801
<para>
<literal>full</literal>: the expanded header is not truncated,
- and will be as wide as the widest output
- line.
+ and will be as wide as the widest output line.
</para>
<para>
- <literal>column</literal>: truncate the header line at the
+ <literal>column</literal>: truncate the header line to the
width of the first column.
</para>
<para>
- <literal>page</literal>: truncate the header line at the terminal
+ <literal>page</literal>: truncate the header line to the terminal
width.
</para>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index c6ad2546f93..71455dfdc79 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -129,7 +129,7 @@ REINDEX [ ( <replaceable
class="parameter">option</replaceable> [, ...] ) ] { DA
<para>
Recreate all indexes within the current database, except system
catalogs.
- Indexes on shared system catalogs are not processed.
+ Indexes on system catalogs are not processed.
This form of <command>REINDEX</command> cannot be executed inside a
transaction block.
</para>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index dbe23db54f0..f3bdc7e87eb 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2008,7 +2008,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
<literal>sslmode=verify-ca</literal> or
<literal>verify-full</literal> and have the appropriate root certificate
file installed (<xref linkend="libq-ssl-certificates"/>). Alternatively the
- system CA pool can be used using <literal>sslrootcert=system</literal>; in
+ system CA pool can be selected using <literal>sslrootcert=system</literal>;
in
this case, <literal>sslmode=verify-full</literal> is forced for safety,
since
it is generally trivial to obtain certificates which are signed by a public
CA.
>From 241948d229e578b3db13d2c480a34962eaed8bb1 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryz...@telsasoft.com>
Date: Sat, 18 Mar 2023 21:10:44 -0500
Subject: [PATCH 1/4] WIP: v16 docs: Add support for file inclusions in HBA and
ident configuration files
a54b658ce77b6705eb1f997b416c2e820a77946c
---
doc/src/sgml/client-auth.sgml | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index bcdc085010a..bd82461f0e0 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -104,13 +104,13 @@
Each record can be an include directive or an authentication record.
Include directives specify files that can be included, that contain
additional records. The records will be inserted in place of the
- include records. These records only contain two fields:
+ include directives. Include directives only contain two fields:
<literal>include</literal>, <literal>include_if_exists</literal> or
<literal>include_dir</literal> directive and the file or directory to be
- included. The file or directory can be a relative of absolute path, and can
+ included. The file or directory can be a relative or absolute path, and can
be double-quoted. For the <literal>include_dir</literal> form, all files
- not starting with a <literal>.</literal> and ending with
- <literal>.conf</literal> will be included. Multiple files within an include
+ ending with <literal>.conf</literal> and not starting with a <literal>.</literal>
+ will be included. Multiple files within an include
directory are processed in file name order (according to C locale rules,
i.e., numbers before letters, and uppercase letters before lowercase ones).
</para>
--
2.34.1
>From ef053ae1c40546449d1e77fdd48e0d689a9e41d4 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryz...@telsasoft.com>
Date: Sun, 19 Mar 2023 18:45:58 -0500
Subject: [PATCH 2/4] WIP: v16 docs: Add pg_stat_io view, providing more
detailed IO statistics
a9c70b46dbe152e094f137f7e6ba9cd3a638ee25
---
doc/src/sgml/monitoring.sgml | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index a37331ec524..201408bf20a 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -679,9 +679,9 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<structname>pg_statio_</structname> set of views are useful for determining
the effectiveness of the buffer cache. They can be used to calculate a cache
hit ratio. Note that while <productname>PostgreSQL</productname>'s I/O
- statistics capture most instances in which the kernel was invoked in order
- to perform I/O, they do not differentiate between data which had to be
- fetched from disk and that which already resided in the kernel page cache.
+ statistics capture most instances which required a system call in order
+ to perform I/O, they do not differentiate between data which was already
+ present in the kernel page cache and that which had to be fetched from disk.
Users are advised to use the <productname>PostgreSQL</productname>
statistics views in combination with operating system utilities for a more
complete picture of their database's I/O performance.
@@ -3770,8 +3770,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<para>
<literal>normal</literal>: The default or standard
<varname>io_context</varname> for a type of I/O operation. For
- example, by default, relation data is read into and written out from
- shared buffers. Thus, reads and writes of relation data to and from
+ example, relation data is read into and written out from
+ a general pool of shared buffers. Thus, reads and writes of relation data to and from
shared buffers are tracked in <varname>io_context</varname>
<literal>normal</literal>.
</para>
@@ -3781,14 +3781,14 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<literal>vacuum</literal>: I/O operations performed outside of shared
buffers while vacuuming and analyzing permanent relations. Temporary
table vacuums use the same local buffer pool as other temporary table
- IO operations and are tracked in <varname>io_context</varname>
+ I/O operations and are tracked in <varname>io_context</varname>
<literal>normal</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>bulkread</literal>: Certain large read I/O operations
- done outside of shared buffers, for example, a sequential scan of a
+ done in a ring buffer of limited size of shared buffers, for example, a sequential scan of a
large table.
</para>
</listitem>
@@ -3979,7 +3979,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
Some backend types never perform I/O operations on some I/O objects and/or
in some I/O contexts. These rows are omitted from the view. For example, the
checkpointer does not checkpoint temporary tables, so there will be no rows
- for <varname>backend_type</varname> <literal>checkpointer</literal> and
+ with <varname>backend_type</varname> <literal>checkpointer</literal> and
<varname>io_object</varname> <literal>temp relation</literal>.
</para>
--
2.34.1
>From d7a5c78d4492007e116384810f39d2f55ecb8355 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryz...@telsasoft.com>
Date: Sat, 18 Mar 2023 21:41:42 -0500
Subject: [PATCH 3/4] WIP: v16 docs: Add enable_presorted_aggregate GUC
3226f47282a05979483475d1e4a11aab8c1bfc39
---
doc/src/sgml/config.sgml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 20b8b5ae1de..68e344c7bf0 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -5440,15 +5440,15 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
</term>
<listitem>
<para>
- Controls if the query planner will produce a plan which will provide
- rows which are presorted in the order required for the query's
+ Enables or disables the query planner's use of plans which presort
+ rows in the order required for the query's
<literal>ORDER BY</literal> / <literal>DISTINCT</literal> aggregate
functions. When disabled, the query planner will produce a plan which
will always require the executor to perform a sort before performing
aggregation of each aggregate function containing an
<literal>ORDER BY</literal> or <literal>DISTINCT</literal> clause.
When enabled, the planner will try to produce a more efficient plan
- which provides input to the aggregate functions which is presorted in
+ which provides input to the aggregate functions in
the order they require for aggregation. The default value is
<literal>on</literal>.
</para>
--
2.34.1
>From e233dd5e5448ffe51996872b3bc1cf1b2c0e79ce Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryz...@telsasoft.com>
Date: Tue, 4 Apr 2023 19:37:34 -0500
Subject: [PATCH 4/4] WIP: v16 docs: Add more details about
pg_stat_get_xact_blocks_{fetched,hit}
e126d817c7af989c47366b0e344ee83d761f334a
d69c404c4cc5985d8ae5b5ed38bed3400b317f82
---
doc/src/sgml/monitoring.sgml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 201408bf20a..af3745dc46a 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -5805,8 +5805,8 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<returnvalue>bigint</returnvalue>
</para>
<para>
- Returns the number of block read requests for table or index, in the
- current transaction. This number minus
+ Returns the number of block read requests for the given table or index,
+ in the current transaction. This number minus
<function>pg_stat_get_xact_blocks_hit</function> gives the number of
kernel <function>read()</function> calls; the number of actual
physical reads is usually lower due to kernel-level buffering.
@@ -5822,9 +5822,9 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<returnvalue>bigint</returnvalue>
</para>
<para>
- Returns the number of block read requests for table or index, in the
- current transaction, found in cache (not triggering kernel
- <function>read()</function> calls).
+ Returns the number of block read requests for the given table or index,
+ in the current transaction, which were found in the postgresql buffer cache (not
+ requiring kernel <function>read()</function> calls).
</para></entry>
</row>
--
2.34.1
