PostgreSQL 15 minor documentation improvements

Hello!

I’ve noticed that some changes concerning replacement of archive_command
by archive_library in the documentation for PostgreSQL 15 do not quite
fit in:

1. https://www.postgresql.org/docs/15/continuous-archiving.html
Archiving of these files happens automatically since you have already
configured <varname>archive_library</varname>. - what about using
archive_command? Should it be "...since you have already configured
<varname>archive_library</varname> or <varname>archive_command</varname>"?

2. The same page.
If the archive process has fallen behind because of failures of the
archive library, it will keep retrying until the archive succeeds and
the backup is complete. - again, what about archive command?

3. https://www.postgresql.org/docs/15/app-pgbasebackup.html

All WAL records required for the backup must contain sufficient
full-page writes, which requires you to enable |full_page_writes| on the
primary and not to use a tool in your |archive_library| to remove
full-page writes from WAL files. - the same question here. I believe
that we can write in general: and not to use a tool to remove full-page
writes from WAL files (?).

I have prepared a small patch with possible changes of these places, and
also a separate patch with some improvements concerning missed/inapt
tags. Please have a look.

--
Best regards,
Maxim Yablokov
Technical writer-translator
Postgres Professional <https://postgrespro.com/>

On Wed, Aug 17, 2022 at 06:09:13PM +0300, Максим Яблоков wrote:
> I have prepared a small patch with possible changes of these places, and
> also a separate patch with some improvements concerning missed/inapt tags.
> Please have a look.

archive_command is used only when archive_library is not set AFAIK,
but an archive_library could also freely use an archive_command if it
wishes to. But, yes, I agree that the current wording in backup.sgml
is kind of confusing because of this reason, so I am fine to have a
reference to both archive_library *and* archive_command in this area
of the docs.

All WAL records required for the backup must contain sufficient full-page writes,
which requires you to enable <varname>full_page_writes</varname> on the primary and
- not to use a tool in your <varname>archive_library</varname> to remove
- full-page writes from WAL files.
+ not to use a tool to remove full-page writes from WAL files.

Hmm. My opinion here is to do a simplification, and remove simply the
last part of the paragraph about tools that manipulate WAL files
as the first sentence makes it clear, in my opinion, that if those
FPWs are not around the server could become kaput.

Most of the changes in PGSQL15_tags_fix.patch seem right to me.
Still, you'd better check that the docs compile, as of:

> --- a/doc/src/sgml/basebackup-to-shell.sgml
> +++ b/doc/src/sgml/basebackup-to-shell.sgml
> @@ -12,9 +12,9 @@
> called <literal>shell</literal>. This makes it possible to run
> <literal>pg_basebackup --target=shell</literal> or, depending on how this
> module is configured,
> - <literal>pg_basebackup --target=shell:DETAIL_STRING</literal>, and cause
> - a server command chosen by the server administrator to be executed for
> - each tar archive generated by the backup process. The command will receive
> + <literal>pg_basebackup --target=shell:<replaceable>DETAIL_STRING<replaceable></literal>,

I am pretty sure that this line is going to cause a compilation
failure of the docs. Anyway, this should be use a <command> markup,
no?
--
Michael