Thread

Commits

doc: Assorted documentation improvements
- fa0ffa28778f 19 (unreleased) landed

Documentation improvement patch

Oleg <o.sibiryakov@postgrespro.ru> — 2025-09-10T07:54:11Z

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

Re: Documentation improvement patch

Oleg <o.sibiryakov@postgrespro.ru> — 2025-10-10T06:38:14Z

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
>

Re: Documentation improvement patch

Daniel Gustafsson <daniel@yesql.se> — 2025-10-10T07:15:51Z

> On 10 Sep 2025, at 09:54, Oleg <o.sibiryakov@postgrespro.ru> 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

Re: Documentation improvement patch

Oleg <o.sibiryakov@postgrespro.ru> — 2025-10-13T10:51:52Z

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<o.sibiryakov@postgrespro.ru> 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
>
>
>

Re: Documentation improvement patch

Oleg <o.sibiryakov@postgrespro.ru> — 2025-10-22T02:41:19Z

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<o.sibiryakov@postgrespro.ru> 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
>>
>>
>>

Re: Documentation improvement patch

Daniel Gustafsson <daniel@yesql.se> — 2025-10-22T08:02:14Z

> On 13 Oct 2025, at 12:51, Oleg <o.sibiryakov@postgrespro.ru> 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

Re: Documentation improvement patch

Oleg <o.sibiryakov@postgrespro.ru> — 2025-10-25T19:01:16Z

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<o.sibiryakov@postgrespro.ru> 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
>
>
>

Re: Documentation improvement patch

Peter Eisentraut <peter@eisentraut.org> — 2025-10-30T10:15:26Z

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.

Re: Documentation improvement patch

Daniel Gustafsson <daniel@yesql.se> — 2025-11-14T09:04:03Z

> On 30 Oct 2025, at 11:15, Peter Eisentraut <peter@eisentraut.org> 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

Re: Documentation improvement patch

Peter Eisentraut <peter@eisentraut.org> — 2025-11-19T11:02:23Z

On 14.11.25 10:04, Daniel Gustafsson wrote:
>> On 30 Oct 2025, at 11:15, Peter Eisentraut <peter@eisentraut.org> 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).

Re: Documentation improvement patch

Daniel Gustafsson <daniel@yesql.se> — 2025-11-19T14:14:05Z

> On 19 Nov 2025, at 12:02, Peter Eisentraut <peter@eisentraut.org> 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

Re: Documentation improvement patch

Oleg <o.sibiryakov@postgrespro.ru> — 2025-11-25T07:08:18Z

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 <peter@eisentraut.org> 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
>
>
>