Re: PostgreSQL 15 minor documentation improvements

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