public inbox for [email protected]
help / color / mirror / Atom feedDocumentation improvement patch
12+ messages / 3 participants
[nested] [flat]
* Documentation improvement patch
@ 2025-09-10 07:54 Oleg <[email protected]>
2025-10-10 06:38 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
0 siblings, 2 replies; 12+ messages in thread
From: Oleg @ 2025-09-10 07:54 UTC (permalink / raw)
To: [email protected]
Dear all,
I have prepared a patch containing some minor inconsistencies in the
documentation. Please, take a look.
I will be looking forward to your feedback.
The patch shall be applied to the REL_18_STABLE branch.
--
Regards,
Oleg Sibiryakov
Technical Writer
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
Attachments:
[text/x-patch] doc_improvements_postgresql-18.patch (9.2K, 3-doc_improvements_postgresql-18.patch)
download | inline diff:
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index d1e103ed779..e589a8d6884 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>
@@ -2432,7 +2432,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/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 d336ee38f58..80eadfc0e1a 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
@@ -2394,7 +2394,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</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.
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 ab252d9fc74..e2b2a0ea26f 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2826,7 +2826,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..8b014d657b3 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -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 d5ce93dd893..9229e0fa601 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/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index ed18704a9c2..169f787fdd1 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -747,17 +747,17 @@ GRANT pg_signal_backend TO admin_user;
<para>
<literal>pg_read_server_files</literal> allows reading files from any
location the database can access on the server using
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
</para>
<para>
<literal>pg_write_server_files</literal> allows writing to files in any
location the database can access on the server using
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
</para>
<para>
<literal>pg_execute_server_program</literal> allows executing programs
on the database server as the user the database runs as using
- <command>COPY</command> and other functions which allow executing a
+ the <command>COPY</command> command and functions, which allow executing a
server-side program.
</para>
</listitem>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 2d81afce8cb..1418de07398 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2400,7 +2400,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>
@@ -3947,7 +3947,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>.
@@ -3964,7 +3964,7 @@ extern bool InjectionPointDetach(const char *name);
</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 = {
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
@ 2025-10-10 06:38 ` Oleg <[email protected]>
1 sibling, 0 replies; 12+ messages in thread
From: Oleg @ 2025-10-10 06:38 UTC (permalink / raw)
To: [email protected]
Dear PostgreSQL Community,
This is a kind reminder regarding my documentation patch submitted a
month ago.
I am still very interested in contributing these improvements and would
be grateful for a review when time permits.
The patch can be also applied to the master branch.
Thank you for your consideration.
--
Regards,
Oleg Sibiryakov
Technical Writer
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
On 10.09.2025 10:54, Oleg wrote:
>
> Dear all,
>
> I have prepared a patch containing some minor inconsistencies in the
> documentation. Please, take a look.
>
> I will be looking forward to your feedback.
>
> The patch shall be applied to the REL_18_STABLE branch.
>
> --
> Regards,
> Oleg Sibiryakov
> Technical Writer
> Postgres Professional, The Russian Postgres Company
> https://postgrespro.ru
>
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
@ 2025-10-10 07:15 ` Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
1 sibling, 1 reply; 12+ messages in thread
From: Daniel Gustafsson @ 2025-10-10 07:15 UTC (permalink / raw)
To: Oleg <[email protected]>; +Cc: [email protected]
> On 10 Sep 2025, at 09:54, Oleg <[email protected]> wrote:
>
> Dear all,
> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
> I will be looking forward to your feedback.
Thanks for the patch, while most of these are obvious improvements I have a few
comments on some:
- Change the definition of a replication slot.
+ Changes the definition of a replication slot.
Reading this page it seems we are mixing tense in many places, some say "Change
the" and "Read some" and elsewhere we use "Drops the". Maybe a more holistic
approach would be better for this page to improve consistency?
- Not enabled by default because it is resource intensive.
+ Not enabled by default because it is resource-intensive.
We use both spellings in multiple places, shouldn't all be changed?
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
...
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
...
- <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.
- 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?
> The patch shall be applied to the REL_18_STABLE branch.
As you mentioned downthread, this is also for master. Our workflow is to
always apply to master and backpatch from there.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
@ 2025-10-13 10:51 ` Oleg <[email protected]>
2025-10-22 02:41 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
0 siblings, 2 replies; 12+ messages in thread
From: Oleg @ 2025-10-13 10:51 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: [email protected]
Thank you for your feedback, Daniel.
My thoughts are below:
/- Change the definition of a replication slot. + Changes the definition
of a replication slot. Reading this page it seems we are mixing tense in
many places, some say "Change the" and "Read some" and elsewhere we use
"Drops the". Maybe a more holistic approach would be better for this
page to improve consistency? /I agree, let's add "s" in all cases for the sake of consistency.
/- Not enabled by default because it is resource intensive. + Not
enabled by default because it is resource-intensive. We use both
spellings in multiple places, shouldn't all be changed?/
Agreed, changing all instances to "resource-intensive".
/- <command>COPY</command> and other file-access functions. + the
<command>COPY</command> command and file-access functions. ... -
<command>COPY</command> and other file-access functions. + the
<command>COPY</command> command and file-access functions. ... -
<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.
/- 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".
Please, let me know what you think of the last two points for me to send the updated patch.
--
Oleg Sibiryakov
On 10.10.2025 10:15, Daniel Gustafsson wrote:
>> On 10 Sep 2025, at 09:54, Oleg<[email protected]> wrote:
>>
>> Dear all,
>> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
>> I will be looking forward to your feedback.
> Thanks for the patch, while most of these are obvious improvements I have a few
> comments on some:
>
>
> - Change the definition of a replication slot.
> + Changes the definition of a replication slot.
> Reading this page it seems we are mixing tense in many places, some say "Change
> the" and "Read some" and elsewhere we use "Drops the". Maybe a more holistic
> approach would be better for this page to improve consistency?
>
>
> - Not enabled by default because it is resource intensive.
> + Not enabled by default because it is resource-intensive.
> We use both spellings in multiple places, shouldn't all be changed?
>
>
> - <command>COPY</command> and other file-access functions.
> + the <command>COPY</command> command and file-access functions.
> ...
> - <command>COPY</command> and other file-access functions.
> + the <command>COPY</command> command and file-access functions.
> ...
> - <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.
>
>
> - 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?
>
>> The patch shall be applied to the REL_18_STABLE branch.
> As you mentioned downthread, this is also for master. Our workflow is to
> always apply to master and backpatch from there.
>
> --
> Daniel Gustafsson
>
>
>
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
@ 2025-10-22 02:41 ` Oleg <[email protected]>
1 sibling, 0 replies; 12+ messages in thread
From: Oleg @ 2025-10-22 02:41 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: [email protected]
Dear Daniel,
Could you please provide your feedback on the last two points?
Once I have it, I will send the updated patch immediately to finalize
the improvements.
Thank you,
Oleg
On 13.10.2025 13:51, Oleg wrote:
> Thank you for your feedback, Daniel.
> My thoughts are below:
> /- Change the definition of a replication slot. + Changes the
> definition of a replication slot. Reading this page it seems we are
> mixing tense in many places, some say "Change the" and "Read some" and
> elsewhere we use "Drops the". Maybe a more holistic approach would be
> better for this page to improve consistency? /I agree, let's add "s" in all cases for the sake of consistency.
>
> /- Not enabled by default because it is resource intensive. + Not
> enabled by default because it is resource-intensive. We use both
> spellings in multiple places, shouldn't all be changed?/
>
> Agreed, changing all instances to "resource-intensive".
>
> /- <command>COPY</command> and other file-access functions. + the
> <command>COPY</command> command and file-access functions. ... -
> <command>COPY</command> and other file-access functions. + the
> <command>COPY</command> command and file-access functions. ... -
> <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.
>
> /- 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".
>
> Please, let me know what you think of the last two points for me to send the updated patch.
>
> --
> Oleg Sibiryakov
> On 10.10.2025 10:15, Daniel Gustafsson wrote:
>>> On 10 Sep 2025, at 09:54, Oleg<[email protected]> wrote:
>>>
>>> Dear all,
>>> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
>>> I will be looking forward to your feedback.
>> Thanks for the patch, while most of these are obvious improvements I have a few
>> comments on some:
>>
>>
>> - Change the definition of a replication slot.
>> + Changes the definition of a replication slot.
>> Reading this page it seems we are mixing tense in many places, some say "Change
>> the" and "Read some" and elsewhere we use "Drops the". Maybe a more holistic
>> approach would be better for this page to improve consistency?
>>
>>
>> - Not enabled by default because it is resource intensive.
>> + Not enabled by default because it is resource-intensive.
>> We use both spellings in multiple places, shouldn't all be changed?
>>
>>
>> - <command>COPY</command> and other file-access functions.
>> + the <command>COPY</command> command and file-access functions.
>> ...
>> - <command>COPY</command> and other file-access functions.
>> + the <command>COPY</command> command and file-access functions.
>> ...
>> - <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.
>>
>>
>> - 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?
>>
>>> The patch shall be applied to the REL_18_STABLE branch.
>> As you mentioned downthread, this is also for master. Our workflow is to
>> always apply to master and backpatch from there.
>>
>> --
>> Daniel Gustafsson
>>
>>
>>
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
@ 2025-10-22 08:02 ` Daniel Gustafsson <[email protected]>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <[email protected]>
1 sibling, 1 reply; 12+ messages in thread
From: Daniel Gustafsson @ 2025-10-22 08:02 UTC (permalink / raw)
To: Oleg <[email protected]>; +Cc: [email protected]
> 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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
@ 2025-10-25 19:01 ` Oleg <[email protected]>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
0 siblings, 1 reply; 12+ messages in thread
From: Oleg @ 2025-10-25 19:01 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: [email protected]
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
>
>
>
Attachments:
[text/x-patch] doc_improvements_postgresql-18_v2.patch (19.8K, 3-doc_improvements_postgresql-18_v2.patch)
download | inline diff:
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,
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <[email protected]>
@ 2025-10-30 10:15 ` Peter Eisentraut <[email protected]>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 12+ messages in thread
From: Peter Eisentraut @ 2025-10-30 10:15 UTC (permalink / raw)
To: Oleg <[email protected]>; Daniel Gustafsson <[email protected]>; +Cc: [email protected]
On 25.10.25 21:01, Oleg wrote:
> 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.
<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.
I think these are intentionally written in imperative style. Compare
the synopses of the main SQL commands: "change the definition of a
domain" etc.
- First, define a <literal>PgStat_KindInfo</literal> that includes all
+ First, define <literal>PgStat_KindInfo</literal> that includes all
I think this change is incorrect. You are being asked to define an
instance of PgStat_KindInfo, not PgStat_KindInfo itself (which already
exists).
The remaining changes look ok to me.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
@ 2025-11-14 09:04 ` Daniel Gustafsson <[email protected]>
2025-11-19 11:02 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
0 siblings, 1 reply; 12+ messages in thread
From: Daniel Gustafsson @ 2025-11-14 09:04 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: Oleg <[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)
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
@ 2025-11-19 11:02 ` Peter Eisentraut <[email protected]>
2025-11-19 14:14 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 12+ messages in thread
From: Peter Eisentraut @ 2025-11-19 11:02 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: Oleg <[email protected]>; [email protected]
On 14.11.25 10:04, Daniel Gustafsson wrote:
>> 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.
The following changes are left in your patch that should not be changed
per the above discussion (all in doc/src/sgml/protocol.sgml):
- Create a physical or logical replication
+ Creates a physical or logical replication
- Instructs server to start streaming WAL, starting at
+ Instructs the server to start streaming WAL, starting at
- Instructs server to start streaming WAL for logical replication,
+ Instructs the server to start streaming WAL for logical replication,
Separately, maybe this could be improved further:
- 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
I think it would be more correct to say something like "... number of
files each server subprocess is allowed to have open simultaneously ..."
(not how many open actions are happening concurrently).
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-11-19 11:02 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
@ 2025-11-19 14:14 ` Daniel Gustafsson <[email protected]>
2025-11-25 07:08 ` Re: Documentation improvement patch Oleg <[email protected]>
0 siblings, 1 reply; 12+ messages in thread
From: Daniel Gustafsson @ 2025-11-19 14:14 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: Oleg <[email protected]>; [email protected]
> On 19 Nov 2025, at 12:02, Peter Eisentraut <[email protected]> wrote:
> The following changes are left in your patch that should not be changed per the above discussion (all in doc/src/sgml/protocol.sgml):
I did consider these to be separate but re-reading I agree that they should be
removed.
> Separately, maybe this could be improved further:
>
> - 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
>
> I think it would be more correct to say something like "... number of files each server subprocess is allowed to have open simultaneously ..." (not how many open actions are happening concurrently).
I wonder if the original intent was to write "Sets the maximum number of open
files each server subprocess is allowed to have simultaneously;"? That being
said, your suggestion is better so I'll go with that.
I will push the patch with the above changes a bit later today.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <[email protected]>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
2025-11-19 11:02 ` Re: Documentation improvement patch Peter Eisentraut <[email protected]>
2025-11-19 14:14 ` Re: Documentation improvement patch Daniel Gustafsson <[email protected]>
@ 2025-11-25 07:08 ` Oleg <[email protected]>
0 siblings, 0 replies; 12+ messages in thread
From: Oleg @ 2025-11-25 07:08 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; Peter Eisentraut <[email protected]>; +Cc: [email protected]
Daniel, Peter, thank you for the thorough review of the patch.
--
Oleg Sibiryakov
On 19.11.2025 17:14, Daniel Gustafsson wrote:
>> On 19 Nov 2025, at 12:02, Peter Eisentraut <[email protected]> wrote:
>> The following changes are left in your patch that should not be changed per the above discussion (all in doc/src/sgml/protocol.sgml):
> I did consider these to be separate but re-reading I agree that they should be
> removed.
>
>> Separately, maybe this could be improved further:
>>
>> - 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
>>
>> I think it would be more correct to say something like "... number of files each server subprocess is allowed to have open simultaneously ..." (not how many open actions are happening concurrently).
> I wonder if the original intent was to write "Sets the maximum number of open
> files each server subprocess is allowed to have simultaneously;"? That being
> said, your suggestion is better so I'll go with that.
>
> I will push the patch with the above changes a bit later today.
>
> --
> Daniel Gustafsson
>
>
>
^ permalink raw reply [nested|flat] 12+ messages in thread
end of thread, other threads:[~2025-11-25 07:08 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-09-10 07:54 Documentation improvement patch Oleg <[email protected]>
2025-10-10 06:38 ` Oleg <[email protected]>
2025-10-10 07:15 ` Daniel Gustafsson <[email protected]>
2025-10-13 10:51 ` Oleg <[email protected]>
2025-10-22 02:41 ` Oleg <[email protected]>
2025-10-22 08:02 ` Daniel Gustafsson <[email protected]>
2025-10-25 19:01 ` Oleg <[email protected]>
2025-10-30 10:15 ` Peter Eisentraut <[email protected]>
2025-11-14 09:04 ` Daniel Gustafsson <[email protected]>
2025-11-19 11:02 ` Peter Eisentraut <[email protected]>
2025-11-19 14:14 ` Daniel Gustafsson <[email protected]>
2025-11-25 07:08 ` Oleg <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox