pgsql: doc: fix wording describing the checkpoint_flush_after GUC

doc: fix wording describing the checkpoint_flush_after GUC

Reported-by: Evan Macbeth

Discussion: https://postgr.es/m/[email protected]

Backpatch-through: master

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/5ba1ac99a8d8623604d3152be8fd9a201ba5240b

Modified Files
--------------
doc/src/sgml/wal.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

On 2023-Nov-09, Bruce Momjian wrote:

> doc: fix wording describing the checkpoint_flush_after GUC

Hmm. Is this new wording really more clear than the original wording?
I agree the original may not have been the most simple, but I don't
think it was wrong English.

I'm not suggesting to revert this change, but rather I'd like to prevent
future changes of this type. Just saying it'd be sad to turn all the
Postgres documentation to using Basic English or whatever.

--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"La fuerza no está en los medios físicos
sino que reside en una voluntad indomable" (Gandhi)

Hi,

On 2023-11-13 12:31:42 +0100, Alvaro Herrera wrote:
> On 2023-Nov-09, Bruce Momjian wrote:
>
> > doc: fix wording describing the checkpoint_flush_after GUC
>
> Hmm. Is this new wording really more clear than the original wording?
> I agree the original may not have been the most simple, but I don't
> think it was wrong English.

I think it was somewhat wrong (I probably wrote it) or at least awkwardly
formulated. "force the OS that pages .. should be flushed" doesn't make a ton
of sense.

OTOH, the new formulation doesn't seem great either. The request(s) that we
make to the OS are not guaranteed to be followed, so the "should be" was
actually a correct part of the sentence.

It probably should be something like:
On Linux and POSIX platforms <xref linkend="guc-checkpoint-flush-after"/>
allows to request that the OS flushes pages written by the checkpoint to disk
after a configurable number of bytes. Otherwise, these [...]

> I'm not suggesting to revert this change, but rather I'd like to prevent
> future changes of this type. Just saying it'd be sad to turn all the
> Postgres documentation to using Basic English or whatever.

+1 for the general notion.

Greetings,

Andres Freund

Hola-hallo,

On 2023-Nov-13, Andres Freund wrote:

> On 2023-11-13 12:31:42 +0100, Alvaro Herrera wrote:
> > On 2023-Nov-09, Bruce Momjian wrote:
> >
> > > doc: fix wording describing the checkpoint_flush_after GUC
> >
> > Hmm. Is this new wording really more clear than the original wording?
> > I agree the original may not have been the most simple, but I don't
> > think it was wrong English.
>
> I think it was somewhat wrong (I probably wrote it) or at least awkwardly
> formulated. "force the OS that pages .. should be flushed" doesn't make a ton
> of sense.

Heh, you know what? I was mistaken. There was indeed a grammatical
error being fixed. The complaint [1] was that "you" was missing in the
sentence, and apparently that's correct [2].

[1] https://postgr.es/m/[email protected]
[2] https://english.stackexchange.com/a/60285

So the core of the requested change was to turn "allows to force" into
"allows you to force". And this means that your new proposal:

> It probably should be something like:
> On Linux and POSIX platforms <xref linkend="guc-checkpoint-flush-after"/>
> allows to request that the OS flushes pages written by the checkpoint to disk
> after a configurable number of bytes. Otherwise, these [...]

would still fall afoul of the reported problem, because it still says
"allows to request", which is bad English.

> OTOH, the new formulation doesn't seem great either. The request(s) that we
> make to the OS are not guaranteed to be followed, so the "should be" was
> actually a correct part of the sentence.

Hmm, I hadn't noticed that nuance. Your text looks OK to me, except
that "... after a configurable number of bytes" reads odd after what's
already in the sentence. I would rewrite it in a different form, maybe

On Linux and POSIX platforms, checkpoint_flush_after specifies the
number of bytes written by a checkpoint after which the OS is requested
to flush pages to disk. Otherwise, these pages ...

Cheers

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Ninguna manada de bestias tiene una voz tan horrible como la humana" (Orual)

Hi,

On 2023-11-14 17:49:59 +0100, Alvaro Herrera wrote:
> On 2023-Nov-13, Andres Freund wrote:
> > On 2023-11-13 12:31:42 +0100, Alvaro Herrera wrote:
> > > On 2023-Nov-09, Bruce Momjian wrote:
> > >
> > > > doc: fix wording describing the checkpoint_flush_after GUC
> > >
> > > Hmm. Is this new wording really more clear than the original wording?
> > > I agree the original may not have been the most simple, but I don't
> > > think it was wrong English.
> >
> > I think it was somewhat wrong (I probably wrote it) or at least awkwardly
> > formulated. "force the OS that pages .. should be flushed" doesn't make a ton
> > of sense.
>
> Heh, you know what? I was mistaken. There was indeed a grammatical
> error being fixed. The complaint [1] was that "you" was missing in the
> sentence, and apparently that's correct [2].

> [1] https://postgr.es/m/[email protected]
> [2] https://english.stackexchange.com/a/60285

Hm, I really can't get excited about this. To me the "you" sounds worse, but
whatever...

> > OTOH, the new formulation doesn't seem great either. The request(s) that we
> > make to the OS are not guaranteed to be followed, so the "should be" was
> > actually a correct part of the sentence.
>
> Hmm, I hadn't noticed that nuance. Your text looks OK to me, except
> that "... after a configurable number of bytes" reads odd after what's
> already in the sentence. I would rewrite it in a different form, maybe
>
> On Linux and POSIX platforms, checkpoint_flush_after specifies the
> number of bytes written by a checkpoint after which the OS is requested
> to flush pages to disk. Otherwise, these pages ...

That works for me!

Greetings,

Andres Freund

On Tue, Nov 14, 2023 at 3:01 PM Andres Freund <andres(at)anarazel(dot)de> wrote:
> Hm, I really can't get excited about this. To me the "you" sounds worse, but
> whatever...

To me, it seems flat-out incorrect without the "you".

It might be better to rephrase the whole thing entirely so that it
doesn't need to address the reader, like allows you to force ->
forces.

--
Robert Haas
EDB: http://www.enterprisedb.com