Re: A question about wording in messages

On 2022-Sep-14, Kyotaro Horiguchi wrote:

> At Tue, 13 Sep 2022 22:38:46 -0400, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote in
> > Kyotaro Horiguchi <horikyota(dot)ntt(at)gmail(dot)com> writes:
> > > I saw the following message recently modified.
> > >> This controls the maximum distance we can read ahead in the WAL to prefetch referenced data blocks.
> > > Maybe the "we" means "PostgreSQL program and you" but I see it
> > > somewhat out of place.
> >
> > +1, I saw that today and thought it was outside our usual style.
> > The whole thing is awfully verbose for a GUC description, too.
> > Maybe
> >
> > "Maximum distance to read ahead in WAL to prefetch data blocks."

I failed to notice this issue. I agree it's unusual and +1 for changing it.

> It seems to sufficiently work for average users and rather easy to
> read, but it looks a short description.

> So, taking the middle of them, how about the following?
>
> Short: Buffer size for reading ahead in the WAL during recovery.
> Extra: This controls the maximum distance to read ahead in WAL to prefetch data blocks."

But why do we care that it's short? We don't need it to be long .. we
only need it to explain what it needs to explain.

After spending way too much time editing this line, I ended up with
exactly what Tom proposed, so +1 for his version. I think "This
controls" adds nothing very useful, and we don't have it anywhere else,
except tcp_keepalives_count from where I also propose to remove it.

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Hay quien adquiere la mala costumbre de ser infeliz" (M. A. Evans)