Content-Type: text/plain;
	charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3776.700.51.11.2\))
Subject: Re: Documentation improvement patch
From: Daniel Gustafsson <daniel@yesql.se>
In-Reply-To: <e62bedb5-c26f-4d37-b4ed-ce9b55f1e980@postgrespro.ru>
Date: Fri, 10 Oct 2025 09:15:51 +0200
Cc: pgsql-docs@lists.postgresql.org
Content-Transfer-Encoding: quoted-printable
Message-Id: <3881A97B-0146-4389-9C39-3C596536750B@yesql.se>
References: <e62bedb5-c26f-4d37-b4ed-ce9b55f1e980@postgrespro.ru>
To: Oleg <o.sibiryakov@postgrespro.ru>
Archived-At: 
 <https://www.postgresql.org/message-id/3881A97B-0146-4389-9C39-3C596536750B%40yesql.se>
Precedence: bulk

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