Dear Daniel,
Thank you for your prompt feedback.
Attached, please find the updated documentation patch, which
incorporates your suggestions from both the first and second rounds of
review.
--
Oleg Sibiryakov
On 22.10.2025 11:02, Daniel Gustafsson wrote:
On 13 Oct 2025, at 12:51, Oleg<[email protected]> wrote:
- <command>COPY</command> and other functions which allow executing a
+ the <command>COPY</command> command and functions, which allow executing a
I'm not sure about these, I think we use COPY without the the "the COPY
command" decoration in many places so I think it's more consistent like this.
I actually think we should add the decoration here because "<command>COPY</command>
and other file-access functions"
sounds a bit confusing since COPY is not a file-access function and we seem to
put it in the list. Even though I
agree that everybody knows COPY is a command, not a function.
We refer to SQL commands by just their names all over the documentation without
saying "an EXPLAIN command" etc, and I think this falls in that same category.
- to call functions defined in the standard internal library, by using an
+ to call functions defined in the standard internal function library by using
an
interface similar to their SQL signature.
Isn't it a bit redundant to say "internal function library" when we are already
talking about function definitions?
I agree that it may seem redundant, I added "function" here for the sake of
consistency with lines 1829/1830 (if applied to the master branch)
where the documentation mentions "standard internal function library".
I hadn't seen that, but with that in mind I agree that being consistent is good
so I'll withdraw that comment.
--
Daniel Gustafsson
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 0a2a8b49fdb..71c2bbf7615 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1232,11 +1232,11 @@ include_dir 'conf.d'
<primary><varname>oauth_validator_libraries</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
- The library/libraries to use for validating OAuth connection tokens. If
+ Sets the library/libraries to use for validating OAuth connection tokens. If
only one validator library is provided, it will be used by default for
any OAuth connections; otherwise, all
<link linkend="auth-oauth"><literal>oauth</literal> HBA entries</link>
must explicitly set a <literal>validator</literal> chosen from this
list. If set to an empty string (the default), OAuth connections will be
@@ -1398,11 +1398,11 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
Specifies a list of cipher suites that are allowed by connections using
<acronym>TLS</acronym> version 1.3. Multiple cipher suites can be
- specified by using a colon separated list. If left blank, the default
+ specified by using a colon-separated list. If left blank, the default
set of cipher suites in <productname>OpenSSL</productname> will be used.
</para>
<para>
This parameter can only be set in the
@@ -2430,11 +2430,11 @@ include_dir 'conf.d'
<primary><varname>max_files_per_process</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
- Sets the maximum number of open files each server subprocess is
+ Sets the maximum number of files each server subprocess is
allowed to open simultaneously; files already opened in the
postmaster are not counted toward this limit. The default is one
thousand files.
</para>
<para>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 593202f4fb2..fe8d73e1f8c 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -3168,11 +3168,11 @@ ninja install
<term><option>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
<listitem>
<para>
Enable additional test suites, which are not run by default because
they are not secure to run on a multiuser system, require special
- software to run, or are resource intensive. The argument is a
+ software to run, or are resource-intensive. The argument is a
whitespace-separated list of tests to enable. See
<xref linkend="regress-additional"/> for details. If the
<envar>PG_TEST_EXTRA</envar> environment variable is set when the
tests are run, it overrides this setup-time option.
</para>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 781a01067f7..9b032fbf675 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -1224,11 +1224,11 @@ postgres=# SELECT postgres_fdw_disconnect_all();
<variablelist>
<varlistentry>
<term><literal>PostgresFdwCleanupResult</literal></term>
<listitem>
<para>
- Waiting for transaction abort on remote server.
+ Waiting for transaction abort on a remote server.
</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index af476c82fcc..2101442c90f 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -47,11 +47,11 @@ break is not needed in a wider output rendering.
important aspects of the <productname>PostgreSQL</productname> system.
It makes no attempt to be a comprehensive treatment of the topics it covers.
</para>
<para>
- After you have successfully completed this tutorial you will want to
+ After you have successfully completed this tutorial, you will want to
read the <xref linkend="sql"/> section to gain a better understanding
of the SQL language, or <xref linkend="client-interfaces"/> for
information about developing applications with
<productname>PostgreSQL</productname>. Those who provision and
manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9d755232873..39e2d1ca7a2 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1634,11 +1634,11 @@ SELCT 1/0;<!-- this typo is intentional -->
</para>
<para>
Likewise the server expects the client to not begin
the <acronym>SSL</acronym> negotiation until it receives the server's
- single byte response to the <acronym>SSL</acronym> request. If the
+ single-byte response to the <acronym>SSL</acronym> request. If the
client begins the <acronym>SSL</acronym> negotiation immediately without
waiting for the server response to be received it can reduce connection
latency by one round-trip. However this comes at the cost of not being
able to handle the case where the server sends a negative response to the
<acronym>SSL</acronym> request. In that case instead of continuing with either GSSAPI or an
@@ -2226,11 +2226,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> [ <literal>TEMPORARY</literal> ] { <literal>PHYSICAL</literal> | <literal>LOGICAL</literal> <replaceable class="parameter">output_plugin</replaceable> } [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ]
<indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Create a physical or logical replication
+ Creates a physical or logical replication
slot. See <xref linkend="streaming-replication-slots"/> for more about
replication slots.
</para>
<variablelist>
@@ -2258,11 +2258,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry>
<term><literal>TEMPORARY</literal></term>
<listitem>
<para>
- Specify that this replication slot is a temporary one. Temporary
+ Specifies that this replication slot is a temporary one. Temporary
slots are not saved to disk and are automatically dropped on error
or when the session has finished.
</para>
</listitem>
</varlistentry>
@@ -2394,11 +2394,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>ALTER_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ( <replaceable class="parameter">option</replaceable> [, ...] )
<indexterm><primary>ALTER_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Change the definition of a replication slot.
+ Changes the definition of a replication slot.
See <xref linkend="streaming-replication-slots"/> for more about
replication slots. This command is currently only supported for logical
replication slots.
</para>
@@ -2451,11 +2451,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>READ_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable>
<indexterm><primary>READ_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Read some information associated with a replication slot. Returns a tuple
+ Reads some information associated with a replication slot. Returns a tuple
with <literal>NULL</literal> values if the replication slot does not
exist. This command is currently only supported for physical replication
slots.
</para>
@@ -2500,11 +2500,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>START_REPLICATION</literal> [ <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ] [ <literal>PHYSICAL</literal> ] <replaceable class="parameter">XXX/XXX</replaceable> [ <literal>TIMELINE</literal> <replaceable class="parameter">tli</replaceable> ]
<indexterm><primary>START_REPLICATION</primary></indexterm>
</term>
<listitem>
<para>
- Instructs server to start streaming WAL, starting at
+ Instructs the server to start streaming WAL, starting at
WAL location <replaceable class="parameter">XXX/XXX</replaceable>.
If <literal>TIMELINE</literal> option is specified,
streaming starts on timeline <replaceable class="parameter">tli</replaceable>;
otherwise, the server's current timeline is selected. The server can
reply with an error, for example if the requested section of WAL has already
@@ -2896,11 +2896,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry id="protocol-replication-start-replication-slot-logical">
<term><literal>START_REPLICATION</literal> <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <literal>LOGICAL</literal> <replaceable class="parameter">XXX/XXX</replaceable> [ ( <replaceable>option_name</replaceable> [ <replaceable>option_value</replaceable> ] [, ...] ) ]</term>
<listitem>
<para>
- Instructs server to start streaming WAL for logical replication,
+ Instructs the server to start streaming WAL for logical replication,
starting at either WAL location <replaceable
class="parameter">XXX/XXX</replaceable> or the slot's
<literal>confirmed_flush_lsn</literal> (see <xref
linkend="view-pg-replication-slots"/>), whichever is greater. This
behavior makes it easier for clients to avoid updating their local LSN
@@ -2980,11 +2980,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<literal>DROP_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <optional> <literal>WAIT</literal> </optional>
<indexterm><primary>DROP_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Drops a replication slot, freeing any reserved server-side resources.
+ Instructs the server to drop a replication slot, freeing any reserved server-side resources.
</para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">slot_name</replaceable></term>
@@ -3191,11 +3191,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry>
<term><literal>MAX_RATE</literal> <replaceable>rate</replaceable></term>
<listitem>
<para>
- Limit (throttle) the maximum amount of data transferred from server
+ Limits (throttle) the maximum amount of data transferred from server
to client per unit of time. The expected unit is kilobytes per second.
If this option is specified, the value must either be equal to zero
or it must fall within the range from 32 kB through 1 GB (inclusive).
If zero is passed or the option is not specified, no restriction is
imposed on the transfer.
@@ -3205,11 +3205,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry>
<term><literal>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
<listitem>
<para>
- If true, include information about symbolic links present in the
+ If true, includes information about symbolic links present in the
directory <filename>pg_tblspc</filename> in a file named
<filename>tablespace_map</filename>. The tablespace map file includes
each symbolic link name as it exists in the directory
<filename>pg_tblspc/</filename> and the full path of that symbolic link.
The default is false.
@@ -3255,11 +3255,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
Specifies the checksum algorithm that should be applied to each file included
in the backup manifest. Currently, the available
algorithms are <literal>NONE</literal>, <literal>CRC32C</literal>,
<literal>SHA224</literal>, <literal>SHA256</literal>,
<literal>SHA384</literal>, and <literal>SHA512</literal>.
- The default is <literal>CRC32C</literal>.
+ The defv2ault is <literal>CRC32C</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index 263ebdeeab4..2a0de0cfb63 100644
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -82,11 +82,11 @@ PostgreSQL documentation
<option>--plugin</option>, for the database specified
by <option>--dbname</option>.
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option> are required
+ The <option>--slot</option> and <option>--dbname</option> options are required
for this action.
</para>
<para>
The <option>--enable-two-phase</option> and <option>--enable-failover</option>
@@ -102,11 +102,11 @@ PostgreSQL documentation
Drop the replication slot with the name specified
by <option>--slot</option>, then exit.
</para>
<para>
- The <option>--slot</option> is required for this action.
+ The <option>--slot</option> option is required for this action.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -119,12 +119,12 @@ PostgreSQL documentation
or disconnect, retry in a loop unless
<option>--no-loop</option> is specified.
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option>,
- <option>--file</option> are required for this action.
+ The <option>--slot</option>, <option>--dbname</option>, and
+ <option>--file</option> options are required for this action.
</para>
<para>
The stream format is determined by the output plugin specified when
the slot was created.
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index a5edf612443..8c92be6eb21 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2823,11 +2823,11 @@ statement latencies in milliseconds, failures and retries:
<para>
Errors when the thread manages its clients (e.g. the client could not
start a connection to the database server / the socket for connecting
the client to the database server has become invalid). In such cases
all clients of this thread stop while other threads continue to work.
- However, <option>--exit-on-abort</option> is specified, all of the
+ However, if <option>--exit-on-abort</option> is specified, all of the
threads stop immediately in this case.
</para>
</listitem>
<listitem>
<para>
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index 8838fe7f022..6812e3f11e0 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -252,11 +252,11 @@ make check-world -j8 >/dev/null
</para>
<para>
Some test suites are not run by default, either because they are not secure
to run on a multiuser system, because they require special software or
- because they are resource intensive. You can decide which test suites to
+ because they are resource-intensive. You can decide which test suites to
run additionally by setting the <command>make</command> or environment
variable <varname>PG_TEST_EXTRA</varname> to a whitespace-separated list,
for example:
<programlisting>
make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
@@ -323,11 +323,11 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<para>
Runs an additional test suite in
<filename>src/bin/pg_upgrade/t/002_pg_upgrade.pl</filename> which
cycles the regression database through <command>pg_dump</command>/
<command>pg_restore</command>. Not enabled by default because it
- is resource intensive.
+ is resource-intensive.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -354,21 +354,21 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<term><literal>wal_consistency_checking</literal></term>
<listitem>
<para>
Uses <literal>wal_consistency_checking=all</literal> while running
certain tests under <filename>src/test/recovery</filename>. Not
- enabled by default because it is resource intensive.
+ enabled by default because it is resource-intensive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>xid_wraparound</literal></term>
<listitem>
<para>
Runs the test suite under <filename>src/test/modules/xid_wraparound</filename>.
- Not enabled by default because it is resource intensive.
+ Not enabled by default because it is resource-intensive.
</para>
</listitem>
</varlistentry>
</variablelist>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7971498fe75..0e623e7fb86 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -51,11 +51,11 @@
</thead>
<tbody>
<row>
<entry><link linkend="view-pg-aios"><structname>pg_aios</structname></link></entry>
- <entry>In-use asynchronous IO handles</entry>
+ <entry>in-use asynchronous IO handles</entry>
</row>
<row>
<entry><link linkend="view-pg-available-extensions"><structname>pg_available_extensions</structname></link></entry>
<entry>available extensions</entry>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 04bf919b343..ad1751a7dbf 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2397,11 +2397,11 @@ PG_FUNCTION_INFO_V1(funcname);
<para>
To call another version-1 function, you can use
<function>DirectFunctionCall<replaceable>n</replaceable>(func,
arg1, ..., argn)</function>. This is particularly useful when you want
- to call functions defined in the standard internal library, by using an
+ to call functions defined in the standard internal function library by using an
interface similar to their SQL signature.
</para>
<para>
These convenience functions and similar ones can be found
@@ -3938,11 +3938,11 @@ extern bool InjectionPointDetach(const char *name);
<filename>src/test/modules/injection_points</filename> in the PostgreSQL
source tree.
</para>
<para>
- Enabling injections points requires
+ Enabling injection points requires
<option>--enable-injection-points</option> with
<command>configure</command> or <option>-Dinjection_points=true</option>
with <application>Meson</application>.
</para>
</sect2>
@@ -3955,11 +3955,11 @@ extern bool InjectionPointDetach(const char *name);
of cumulative statistics registered in the
<link linkend="monitoring-stats-setup">Cumulative Statistics System</link>.
</para>
<para>
- First, define a <literal>PgStat_KindInfo</literal> that includes all
+ First, define <literal>PgStat_KindInfo</literal> that includes all
the information related to the custom type registered. For example:
<programlisting>
static const PgStat_KindInfo custom_stats = {
.name = "custom_stats",
.fixed_amount = false,
