Feedback-ID: ia2694551:Fastmail
Date: Tue, 14 Nov 2023 17:49:59 +0100
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Andres Freund <andres@anarazel.de>
Cc: Bruce Momjian <bruce@momjian.us>, pgsql-hackers@lists.postgresql.org
Subject: Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC
Message-ID: <202311141649.sjwd4c5kzzl6@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20231114003256.huzptjmwb6c2prrb@awork3.anarazel.de>
Archived-At: 
 <https://www.postgresql.org/message-id/202311141649.sjwd4c5kzzl6%40alvherre.pgsql>
Precedence: bulk

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/155208475619.1380.12815553062985622271@wrigleys.postgresql.org
[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)