pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedPostgreSQL 12: Cryptic documentation
3+ messages / 2 participants
[nested] [flat]
Commits from this thread:
2020-08-15 db659a3416 277e49eca7 Doc: various improvements for pg_basebackup reference page.
* PostgreSQL 12: Cryptic documentation
@ 2020-08-15 12:23 PG Doc comments form <noreply@postgresql.org>
2020-08-15 16:38 ` Re: PostgreSQL 12: Cryptic documentation Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 3+ messages in thread
From: PG Doc comments form @ 2020-08-15 12:23 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: robert@interactive.co.uk
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? But my attempt
to use it was met with "error: directory "/var/lib/pgsql/Walfiles" exists
but is not empty". But WAL files are part of the normal operation of the
database, aren't they? And so the directory _must_ exist, and it is not
surprising it has got something in it! But that seems to be a problem.
Which makes me realise I must have been completely wrong and I have no idea
what it for.
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: PostgreSQL 12: Cryptic documentation
2020-08-15 12:23 PostgreSQL 12: Cryptic documentation PG Doc comments form <noreply@postgresql.org>
@ 2020-08-15 16:38 ` Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 3+ messages in thread
From: Tom Lane @ 2020-08-15 16:38 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Robert Inder <robert@interactive.co.uk>; Pg Docs <pgsql-docs@lists.postgresql.org>
"David G. Johnston" <david.g.johnston@gmail.com> writes:
> 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.
Also, it's under a heading that says "The following command-line options
control the location and format of the output", which ought to make it
clear that it's not about the source server's WAL dir. (Although I notice
that whoever added the --max-rate parameter didn't read that heading :-()
Still, I see that the main -D parameter is described as "Directory to
write the output to", which seems like a clearer phrasing, so I'm inclined
to similarly reword the description of --waldir.
A more direct criticism of the --waldir description is that it's not
stated what happens if you don't provide that argument.
I notice some shaky grammar and other minor annoyances in this page,
so I'm kind of inclined to make an editorial pass over the whole thing.
regards, tom lane
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2020-08-15 16:38 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-08-15 12:23 PostgreSQL 12: Cryptic documentation PG Doc comments form <noreply@postgresql.org>
2020-08-15 16:38 ` Tom Lane <tgl@sss.pgh.pa.us>
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