Content-Type: multipart/alternative;
 boundary="------------5cM82wc3iD4wNcswfHJ10Lmj"
Message-ID: <b9ff5247-04a0-4fe5-9e2f-454b0c7bde7f@postgrespro.ru>
Date: Mon, 13 Oct 2025 13:51:52 +0300
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: Documentation improvement patch
To: Daniel Gustafsson <daniel@yesql.se>
Cc: pgsql-docs@lists.postgresql.org
References: <e62bedb5-c26f-4d37-b4ed-ce9b55f1e980@postgrespro.ru>
 <3881A97B-0146-4389-9C39-3C596536750B@yesql.se>
Content-Language: en-US
From: Oleg <o.sibiryakov@postgrespro.ru>
In-Reply-To: <3881A97B-0146-4389-9C39-3C596536750B@yesql.se>
Archived-At: 
 <https://www.postgresql.org/message-id/b9ff5247-04a0-4fe5-9e2f-454b0c7bde7f%40postgrespro.ru>
Precedence: bulk

This is a multi-part message in MIME format.
--------------5cM82wc3iD4wNcswfHJ10Lmj
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

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
>
>
>
--------------5cM82wc3iD4wNcswfHJ10Lmj
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <pre>Thank you for your feedback, Daniel.</pre>
    <pre>My thoughts are below:</pre>
    <pre wrap="" class="moz-quote-pre"><i>-       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>I agree, let's add "s" in all cases for the sake of consistency.

<i>-       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?</i>

Agreed, changing all instances to "resource-intensive".

<i>-       &lt;command&gt;COPY&lt;/command&gt; and other file-access functions.
+       the &lt;command&gt;COPY&lt;/command&gt; command and file-access functions.
        ...
-       &lt;command&gt;COPY&lt;/command&gt; and other file-access functions.
+       the &lt;command&gt;COPY&lt;/command&gt; command and file-access functions.
        ...
-       &lt;command&gt;COPY&lt;/command&gt; and other functions which allow executing a
+       the &lt;command&gt;COPY&lt;/command&gt; 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>I actually think we should add the decoration here because "&lt;command&gt;COPY&lt;/command&gt; 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.

<i>
-     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>

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 <b>function</b> library".

Please, let me know what you think of the last two points for me to send the updated patch.

--
Oleg Sibiryakov
</pre>
    <p></p>
    <div class="moz-cite-prefix">On 10.10.2025 10:15, Daniel Gustafsson
      wrote:<br>
    </div>
    <blockquote type="cite"
      cite="mid:3881A97B-0146-4389-9C39-3C596536750B@yesql.se">
      <blockquote type="cite">
        <pre wrap="" class="moz-quote-pre">On 10 Sep 2025, at 09:54, Oleg <a class="moz-txt-link-rfc2396E" href="mailto:o.sibiryakov@postgrespro.ru">&lt;o.sibiryakov@postgrespro.ru&gt;</a> 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.
</pre>
      </blockquote>
      <pre wrap="" class="moz-quote-pre">
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?


-       &lt;command&gt;COPY&lt;/command&gt; and other file-access functions.
+       the &lt;command&gt;COPY&lt;/command&gt; command and file-access functions.
        ...
-       &lt;command&gt;COPY&lt;/command&gt; and other file-access functions.
+       the &lt;command&gt;COPY&lt;/command&gt; command and file-access functions.
        ...
-       &lt;command&gt;COPY&lt;/command&gt; and other functions which allow executing a
+       the &lt;command&gt;COPY&lt;/command&gt; 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?

</pre>
      <blockquote type="cite">
        <pre wrap="" class="moz-quote-pre">The patch shall be applied to the REL_18_STABLE branch.
</pre>
      </blockquote>
      <pre wrap="" class="moz-quote-pre">
As you mentioned downthread, this is also for master.  Our workflow is to
always apply to master and backpatch from there.

--
Daniel Gustafsson


</pre>
    </blockquote>
  </body>
</html>

--------------5cM82wc3iD4wNcswfHJ10Lmj--