Re: Missing information on '-X' in section 26.3.6.1.

On Wed, Jan 24, 2024 at 2:19 AM Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:

> > On 23 Jan 2024, at 21:43, David G. Johnston <david(dot)g(dot)johnston(at)gmail(dot)com>
> wrote:
> >
> > On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <
> noreply(at)postgresql(dot)org <mailto:noreply(at)postgresql(dot)org>> wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/16/continuous-archiving.html <
> https://www.postgresql.org/docs/16/continuous-archiving.html>
> > Description:
> >
> > I noticed, that in section 26.3.6.1. it's not specified, what the -X
> > parameter should be set to (stream or fetch, or whether it even
> matters). I
> > could continue with trial and error, but it confused me a bit.
> >
> > The -X parameter is documented to have a default; but since both fetch
> and stream are documented to give you the same end result it doesn't
> matter. Of course you cannot specify the none method.
>
> Agreed. Still, it doesn't hurt to spell out what we take for granted but a
> newcomer have to figure out in order to make the documentation easy to
> follow
> for new users. Something like the attached would be enough I think.
>
>
So I once again find a larger issue here, mostly unrelated to the complaint
at hand.

This entire paragraph is in the Continuous Archiving & PITR section but the
entire standalone concept is in opposition to that. It is also in a "Tips"
section but doesn't really read as a tip.

Thinking on it further, and as the tip talks about, what we are really
doing here is describing a standalone physical file system backup in
contrast to a pg_dump backup. We already have a chapter that does this -
the previous one named "File System Level Backup".

The attached patch moves this paragraph there. I distilled the paragraph
down to its essence, but am open to being a bit more wordy, and consider
more how this fits into the existing content of that page. I'm only really
married to two things - mentioning the -X argument to pg_basebackup here is
a bad idea and the content does not fit in the existing Tip area of
continuous archiving section.

David J.