Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1vBOn3-00G24L-61 for pgsql-docs@arkaria.postgresql.org; Wed, 22 Oct 2025 02:41:29 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1vBOn2-00Cwmh-6I for pgsql-docs@arkaria.postgresql.org; Wed, 22 Oct 2025 02:41:27 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1vBOn1-00CwmZ-La for pgsql-docs@lists.postgresql.org; Wed, 22 Oct 2025 02:41:26 +0000 Received: from mail.postgrespro.ru ([93.174.132.70]) by makus.postgresql.org with smtp (Exim 4.96) (envelope-from ) id 1vBOmx-0035DA-24 for pgsql-docs@lists.postgresql.org; Wed, 22 Oct 2025 02:41:25 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=postgrespro.ru; s=mx2023; t=1761100880; bh=VN/z6Si8o4QUGX5xJOHl1wvtQwRPxbeQhNGKybAfiTc=; h=Message-ID:Date:User-Agent:Subject:From:To:Cc:References: In-Reply-To:From; b=1KY2ojDKy1QrzxPGDK1NDnM31+HVPOXNmi7uKV6j6vuapHt6JvTqCgumjviFSi/93 SXZ0njurGmNE6/tT86Ia2/2TJkJ+OSIbfOXVWnj11uXDgCBsOLFm0JHH+55DkZZOMo CAIi7WLakbRsh0YnExpolgYKkt1u43EIac3gL/gfmLOrYhSESVOZX/ig0fq4BIy3l5 ngJrD4o0fveXhqwIewbaLQKlNdCYnLrWgMqBYHFcv6fghOMIz6V3i4siDj9+2qn2KH Xe+/lMaxSqIEegXLNUz5wHoBopKsqiIL65mLqXeULaDJcv33kozpqDWpaJ6Ko738o7 02qhyIGE0VSdg== Received: from [172.30.48.74] (debian11-template.l.postgrespro.ru [192.168.2.254]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (Client did not present a certificate) (Authenticated sender: o.sibiryakov@postgrespro.ru) by mail.postgrespro.ru (Postfix/465) with ESMTPSA id E001260BAC; Wed, 22 Oct 2025 05:41:19 +0300 (MSK) Content-Type: multipart/alternative; boundary="------------PojchZ0a1vH7K5fQFYqmKj4I" Message-ID: <102934c3-b59a-4bc6-9380-bb3d001c90b4@postgrespro.ru> Date: Wed, 22 Oct 2025 05:41:19 +0300 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: Documentation improvement patch From: Oleg To: Daniel Gustafsson Cc: pgsql-docs@lists.postgresql.org References: <3881A97B-0146-4389-9C39-3C596536750B@yesql.se> Content-Language: en-US In-Reply-To: X-KSMG-AntiPhishing: NotDetected, bases: 2025/10/22 01:52:00 X-KSMG-AntiSpam-Interceptor-Info: not scanned X-KSMG-AntiSpam-Status: not scanned, disabled by settings X-KSMG-AntiVirus: Kaspersky Secure Mail Gateway, version 2.1.0.7854, bases: 2025/10/22 00:09:00 #27790920 X-KSMG-AntiVirus-Status: NotDetected, skipped X-KSMG-LinksScanning: not scanned, disabled by settings X-KSMG-Message-Action: skipped X-KSMG-Rule-ID: 1 List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk This is a multi-part message in MIME format. --------------PojchZ0a1vH7K5fQFYqmKj4I Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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". > > /- COPY and other file-access functions. + the > COPY command and file-access functions. ... - > COPY and other file-access functions. + the > COPY command and file-access functions. ... - > COPY and other functions which allow executing a + > the COPY 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 "COPY 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 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? >> >> >> - COPY and other file-access functions. >> + the COPY command and file-access functions. >> ... >> - COPY and other file-access functions. >> + the COPY command and file-access functions. >> ... >> - COPY and other functions which allow executing a >> + the COPY 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 >> >> >> --------------PojchZ0a1vH7K5fQFYqmKj4I Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: 7bit

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