Обсуждение: Re: pgsql: doc: fix wording describing the checkpoint_flush_after GUC
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/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)
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
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