Re: Documentation improvement patch - Mailing list pgsql-docs

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