doc: Improve some markups and some wording around archiving modules

This commit adds or fixes used markups in a couple of places in the docs
(for <command>, <systemitem> and <literal>).  While on it, clarify some
of the documentation added recently for archiving modules with
archive_command, that would still be used as default choice if no
external module is defined (though an archive module could as well use
an archive_command).

Author: Maxim Yablokov
Discussion: https://postgr.es/m/b47ec4e8-6f6a-2aba-038e-d5db150b245e@postgrespro.ru
Backpatch-through: 15

doc/src/sgml/adminpack.sgml

@@ -22,9 +22,10 @@
   functions in <xref linkend="functions-admin-genfile-table"/>, which
   provide read-only access.)
   Only files within the database cluster directory can be accessed, unless the
-  user is a superuser or given privileges of one of the pg_read_server_files,
+  user is a superuser or given privileges of one of the
-  or pg_write_server_files roles, as appropriate for the function, but either a
+  <literal>pg_read_server_files</literal> or
-  relative or absolute path is allowable.
+  <literal>pg_write_server_files</literal> roles, as appropriate for the
+  function, but either a relative or absolute path is allowable.
  </para>
 
  <table id="functions-adminpack-table">

doc/src/sgml/archive-modules.sgml

@@ -112,9 +112,9 @@ typedef bool (*ArchiveFileCB) (const char *file, const char *path);
     was successfully archived, which may include recycling or removing the
     original WAL file.  If <literal>false</literal> is returned, the server will
     keep the original WAL file and retry archiving later.
-    <literal>file</literal> will contain just the file name of the WAL file to
+    <replaceable>file</replaceable> will contain just the file name of the WAL
-    archive, while <literal>path</literal> contains the full path of the WAL
+    file to archive, while <replaceable>path</replaceable> contains the full
-    file (including the file name).
+    path of the WAL file (including the file name).
    </para>
   </sect2>
 

doc/src/sgml/backup.sgml

@@ -668,9 +668,10 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0
    <para>
     If the archive function emits an <literal>ERROR</literal> or
     <literal>FATAL</literal>, the archiver process aborts and gets restarted by
-    the postmaster.  If you are archiving via shell command, FATAL is emitted if
+    the postmaster.  If you are archiving via shell command,
-    the command is terminated by a signal (other than
+    <literal>FATAL</literal> is emitted if the command is terminated by a signal
-    <systemitem>SIGTERM</systemitem> that is used as part of a server shutdown)
+    (other than <systemitem>SIGTERM</systemitem>
+    that is used as part of a server shutdown)
     or an error by the shell with an exit status greater than 125 (such as
     command not found).  In such cases, the failure is not reported in
     <xref linkend="pg-stat-archiver-view"/>.
@@ -872,8 +873,9 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
    <listitem>
     <para>
      Connect to the server (it does not matter which database) as a user with
-     rights to run pg_backup_start (superuser, or a user who has been granted
+     rights to run <function>pg_backup_start</function> (superuser,
-     EXECUTE on the function) and issue the command:
+     or a user who has been granted <literal>EXECUTE</literal> on the
+     function) and issue the command:
 <programlisting>
 SELECT pg_backup_start(label => 'label', fast => false);
 </programlisting>
@@ -945,11 +947,12 @@ SELECT * FROM pg_backup_stop(wait_for_archive => true);
      On a standby, <varname>archive_mode</varname> must be <literal>always</literal> in order
      for <function>pg_backup_stop</function> to wait.
      Archiving of these files happens automatically since you have
-     already configured <varname>archive_library</varname>. In most cases this
+     already configured <varname>archive_library</varname> or
-     happens quickly, but you are advised to monitor your archive
+     <varname>archive_command</varname>.
-     system to ensure there are no delays.
+     In most cases this happens quickly, but you are advised to monitor your
-     If the archive process has fallen behind
+     archive system to ensure there are no delays.
-     because of failures of the archive library, it will keep retrying
+     If the archive process has fallen behind because of failures of the
+     archive library or archive command, it will keep retrying
      until the archive succeeds and the backup is complete.
      If you wish to place a time limit on the execution of
      <function>pg_backup_stop</function>, set an appropriate

doc/src/sgml/basebackup-to-shell.sgml

@@ -10,11 +10,11 @@
  <para>
   <filename>basebackup_to_shell</filename> adds a custom basebackup target
   called <literal>shell</literal>. This makes it possible to run
-  <literal>pg_basebackup --target=shell</literal> or, depending on how this
+  <command>pg_basebackup --target=shell</command> or, depending on how this
   module is configured,
-  <literal>pg_basebackup --target=shell:DETAIL_STRING</literal>, and cause
+  <command>pg_basebackup --target=shell:<replaceable>DETAIL_STRING</replaceable></command>,
-  a server command chosen by the server administrator to be executed for
+  and cause a server command chosen by the server administrator to be executed
-  each tar archive generated by the backup process. The command will receive
+  for each tar archive generated by the backup process. The command will receive
   the contents of the archive via standard input.
  </para>
 

doc/src/sgml/ref/alter_publication.sgml

@@ -121,7 +121,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
       with different column lists is not supported. So, changing the column
       lists of the tables being subscribed could cause inconsistency of column
       lists among publications, in which case <command>ALTER PUBLICATION</command>
-      will be successful but later the WalSender on the publisher or the
+      will be successful but later the walsender on the publisher or the
       subscriber may throw an error. In this scenario, the user needs to
       recreate the subscription after adjusting the column list or drop the
       problematic publication using

doc/src/sgml/ref/pg_basebackup.sgml

@@ -101,9 +101,7 @@ PostgreSQL documentation
     <listitem>
      <para>
       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
+      which requires you to enable <varname>full_page_writes</varname> on the primary.
-      not to use a tool in your <varname>archive_library</varname> to remove
-      full-page writes from WAL files.
      </para>
     </listitem>
    </itemizedlist>

doc/src/sgml/ref/psql-ref.sgml

@@ -4625,10 +4625,10 @@ testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
     and SQL object names in many (by no means all) contexts.  For example,
     at the start of a command, typing <literal>ins</literal> and pressing
     TAB will fill in <literal>insert into </literal>.  Then, typing a few
-    characters of a table or schema name and pressing TAB will fill in the
+    characters of a table or schema name and pressing <literal>TAB</literal>
-    unfinished name, or offer a menu of possible completions when there's
+    will fill in the unfinished name, or offer a menu of possible completions
-    more than one.  (Depending on the library in use, you may need to
+    when there's more than one.  (Depending on the library in use, you may need to
-    press TAB more than once to get a menu.)
+    press <literal>TAB</literal> more than once to get a menu.)
     </para>
 
     <para>
@@ -4657,7 +4657,7 @@ $endif
      of <application>psql</application>.  This prevents tab completion,
      use or recording of command line history, and editing of multi-line
      commands.  It is particularly useful when you need to copy-and-paste
-     text that contains TAB characters.
+     text that contains <literal>TAB</literal> characters.
     </para>
    </refsect3>
   </refsect2>