Re: PostgreSQL 12: Cryptic documentation

On Sat, Aug 15, 2020 at 6:58 AM PG Doc comments form <noreply(at)postgresql(dot)org>
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/app-pgbasebackup.html
> Description:
>
> The pg_basebackup page says that the --waldir parameter "Specifies the
> location for the write-ahead log directory. waldir must be an absolute
> path.
> The write-ahead log directory can only be specified when the backup is in
> plain mode." But it says nothing at all about what it is actually used
> for.
>
> You may think it is obvious. And I thought I could guess - it would be the
> directory containing the WAL files for the database, right?

It's not the directory "of" the write-ahead log directory (i.e., existing)
but the directory "for" the write-ahead log directory (i.e. in the
backup). All information about the database being backed up can be gleaned
from the connection the pg_basebackup makes to the server.

Which makes me realise I must have been completely wrong and I have no idea
> what it for.
>

I believe its purpose is to allow the user to specify a different directory
for the necessary restoration WAL files to be placed in compared to the
working WAL directory that will be created under the pgdata directory.

As with most things there is always room for improvement. In this case,
though, I'm not seeing anything wrong with the direct wording provided.
The behavior of the program, and general context, means that the directory
must be one that is being created during the backup and WAL copied into
it. And the error message means that in the rare case that the users
mis-interprets it they will be told. And as in this case the mailing lists
are responsive to clearing up individual confusion should the need arise.

Adding here, and in other places, explicit documentation that "this
specifies a location in the backup" just makes the documentation more
verbose. Maybe in this case not enough to reject a proposed patch but
enough so that I at least don't have a desire to write one.

David J.