public inbox for [email protected]
help / color / mirror / Atom feedFrom: Daniel Gustafsson <[email protected]>
To: Peter Eisentraut <[email protected]>
Cc: Oleg <[email protected]>
Cc: [email protected]
Subject: Re: Documentation improvement patch
Date: Fri, 14 Nov 2025 10:04:03 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
> On 30 Oct 2025, at 11:15, Peter Eisentraut <[email protected]> wrote:
> - Change the definition of a replication slot.
> + Changes the definition of a replication slot.
>
> I think these are intentionally written in imperative style. Compare the synopses of the main SQL commands: "change the definition of a domain" etc.
I agree, I too think these are intentionally written like this. The document
isn't entirely consistent and does mix style quite a bit but I don't think
these changes change the needle enough to make.
Attached is a v3 with the remaining changes and a stab at commit message that I
think we should go ahead with.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] v3-0001-doc-Assorted-documentation-improvements.patch (12.2K, 2-v3-0001-doc-Assorted-documentation-improvements.patch)
download | inline diff:
From a641eb6ed524d1af9e3b6fb9cc8e954a3e4831e0 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <[email protected]>
Date: Fri, 14 Nov 2025 09:46:24 +0100
Subject: [PATCH v3] doc: Assorted documentation improvements
A set of wording improvements and spelling fixes.
Author: Oleg Sibiryakov <[email protected]>
Reviewed-by: Daniel Gustafsson <[email protected]>
Reviewed-by: Peter Eisentraut <[email protected]>
Discussion: https://postgr.es/m/[email protected]
---
doc/src/sgml/config.sgml | 6 +++---
doc/src/sgml/installation.sgml | 2 +-
doc/src/sgml/postgres-fdw.sgml | 2 +-
doc/src/sgml/postgres.sgml | 2 +-
doc/src/sgml/protocol.sgml | 10 +++++-----
doc/src/sgml/ref/pg_recvlogical.sgml | 8 ++++----
doc/src/sgml/ref/pgbench.sgml | 2 +-
doc/src/sgml/regress.sgml | 8 ++++----
doc/src/sgml/system-views.sgml | 2 +-
doc/src/sgml/xfunc.sgml | 4 ++--
10 files changed, 23 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index d7e48f61905..21f49f4764d 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1234,7 +1234,7 @@ include_dir 'conf.d'
</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>
@@ -1400,7 +1400,7 @@ include_dir 'conf.d'
<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>
@@ -2436,7 +2436,7 @@ include_dir 'conf.d'
</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.
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
@@ -3170,7 +3170,7 @@ ninja install
<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
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
@@ -1226,7 +1226,7 @@ postgres=# SELECT postgres_fdw_disconnect_all();
<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>
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
@@ -49,7 +49,7 @@ break is not needed in a wider output rendering.
</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
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index d1b9af11b07..aa3c5130d94 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1636,7 +1636,7 @@ SELCT 1/0;<!-- this typo is intentional -->
<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
@@ -2228,7 +2228,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</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>
@@ -2502,7 +2502,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</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>;
@@ -2898,7 +2898,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<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
@@ -2982,7 +2982,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</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>
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
@@ -84,7 +84,7 @@ PostgreSQL documentation
</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>
@@ -104,7 +104,7 @@ PostgreSQL documentation
</para>
<para>
- The <option>--slot</option> is required for this action.
+ The <option>--slot</option> option is required for this action.
</para>
</listitem>
</varlistentry>
@@ -121,8 +121,8 @@ PostgreSQL documentation
</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>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index ecfc3d2f2b7..2e401d1ceb8 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2858,7 +2858,7 @@ statement latencies in milliseconds, failures and retries:
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>
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
@@ -254,7 +254,7 @@ make check-world -j8 >/dev/null
<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:
@@ -325,7 +325,7 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<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>
@@ -356,7 +356,7 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<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>
@@ -366,7 +366,7 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<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>
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
@@ -53,7 +53,7 @@
<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>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 7dcd7d32329..55a99c0ff34 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2399,7 +2399,7 @@ PG_FUNCTION_INFO_V1(funcname);
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>
@@ -3940,7 +3940,7 @@ extern bool InjectionPointDetach(const char *name);
</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>.
--
2.39.3 (Apple Git-146)
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected]
Subject: Re: Documentation improvement patch
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox