pg.ddx.io pgsql-committers@postgresql.org mailing list archive
help / color / mirror / Atom feedpgsql: doc: fix wording describing the checkpoint_flush_after GUC
6+ messages / 4 participants
[nested] [flat]
* pgsql: doc: fix wording describing the checkpoint_flush_after GUC
@ 2023-11-09 22:51 Bruce Momjian <bruce@momjian.us>
2023-11-13 11:31 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 6+ messages in thread
From: Bruce Momjian @ 2023-11-09 22:51 UTC (permalink / raw)
To: pgsql-committers@lists.postgresql.org
doc: fix wording describing the checkpoint_flush_after GUC
Reported-by: Evan Macbeth
Discussion: https://postgr.es/m/155208475619.1380.12815553062985622271@wrigleys.postgresql.org
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(-)
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC
2023-11-09 22:51 pgsql: doc: fix wording describing the checkpoint_flush_after GUC Bruce Momjian <bruce@momjian.us>
@ 2023-11-13 11:31 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 00:32 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Andres Freund <andres@anarazel.de>
0 siblings, 1 reply; 6+ messages in thread
From: Alvaro Herrera @ 2023-11-13 11:31 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-hackers@lists.postgresql.org
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)
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC
2023-11-09 22:51 pgsql: doc: fix wording describing the checkpoint_flush_after GUC Bruce Momjian <bruce@momjian.us>
2023-11-13 11:31 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
@ 2023-11-14 00:32 ` Andres Freund <andres@anarazel.de>
2023-11-14 16:49 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 6+ messages in thread
From: Andres Freund @ 2023-11-14 00:32 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-hackers@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC
2023-11-09 22:51 pgsql: doc: fix wording describing the checkpoint_flush_after GUC Bruce Momjian <bruce@momjian.us>
2023-11-13 11:31 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 00:32 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Andres Freund <andres@anarazel.de>
@ 2023-11-14 16:49 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 20:01 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Andres Freund <andres@anarazel.de>
0 siblings, 1 reply; 6+ messages in thread
From: Alvaro Herrera @ 2023-11-14 16:49 UTC (permalink / raw)
To: Andres Freund <andres@anarazel.de>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-hackers@lists.postgresql.org
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)
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC
2023-11-09 22:51 pgsql: doc: fix wording describing the checkpoint_flush_after GUC Bruce Momjian <bruce@momjian.us>
2023-11-13 11:31 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 00:32 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Andres Freund <andres@anarazel.de>
2023-11-14 16:49 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
@ 2023-11-14 20:01 ` Andres Freund <andres@anarazel.de>
2023-11-16 16:15 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Robert Haas <robertmhaas@gmail.com>
0 siblings, 1 reply; 6+ messages in thread
From: Andres Freund @ 2023-11-14 20:01 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-hackers@lists.postgresql.org
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/155208475619.1380.12815553062985622271@wrigleys.postgresql.org
> [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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC
2023-11-09 22:51 pgsql: doc: fix wording describing the checkpoint_flush_after GUC Bruce Momjian <bruce@momjian.us>
2023-11-13 11:31 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 00:32 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Andres Freund <andres@anarazel.de>
2023-11-14 16:49 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 20:01 ` Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC Andres Freund <andres@anarazel.de>
@ 2023-11-16 16:15 ` Robert Haas <robertmhaas@gmail.com>
0 siblings, 0 replies; 6+ messages in thread
From: Robert Haas @ 2023-11-16 16:15 UTC (permalink / raw)
To: Andres Freund <andres@anarazel.de>; +Cc: Alvaro Herrera <alvherre@alvh.no-ip.org>; Bruce Momjian <bruce@momjian.us>; pgsql-hackers@lists.postgresql.org
On Tue, Nov 14, 2023 at 3:01 PM Andres Freund <andres@anarazel.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
^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2023-11-16 16:15 UTC | newest]
Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-11-09 22:51 pgsql: doc: fix wording describing the checkpoint_flush_after GUC Bruce Momjian <bruce@momjian.us>
2023-11-13 11:31 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 00:32 ` Andres Freund <andres@anarazel.de>
2023-11-14 16:49 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-14 20:01 ` Andres Freund <andres@anarazel.de>
2023-11-16 16:15 ` Robert Haas <robertmhaas@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox