doc: Clean up pg_recvlogical reference page

This needed a general cleanup of wording, typos, outdated terminology,
formatting, and hard-to-understand and borderline incorrect information.

Also tweak the pg_receivexlog page a bit to make the two more
consistent.

2 files changed, 220 insertions, 197 deletions

diff --git a/doc/src/sgml/ref/pg_receivexlog.sgml b/doc/src/sgml/ref/pg_receivexlog.sgml
index b792aa5440..be26b84c1b 100644
--- a/doc/src/sgml/ref/pg_receivexlog.sgml
+++ b/doc/src/sgml/ref/pg_receivexlog.sgml
@@ -16,7 +16,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_receivexlog</refname>
-  <refpurpose>streams transaction logs from a <productname>PostgreSQL</productname> cluster</refpurpose>
+  <refpurpose>stream transaction logs from a <productname>PostgreSQL</productname> server</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -71,10 +71,6 @@ PostgreSQL documentation
  <refsect1>
   <title>Options</title>
 
-   <para>
-    The following command-line options control the location and format of the
-    output.
-
     <variablelist>
      <varlistentry>
       <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
@@ -88,12 +84,7 @@ PostgreSQL documentation
        </para>
       </listitem>
      </varlistentry>
-    </variablelist>
-   </para>
-   <para>
-    The following command-line options control the running of the program.
 
-    <variablelist>
      <varlistentry>
       <term><option>-n</option></term>
       <term><option>--no-loop</option></term>
@@ -106,6 +97,39 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>-s <replaceable class="parameter">interval</replaceable></option></term>
+      <term><option>--status-interval=<replaceable class="parameter">interval</replaceable></option></term>
+      <listitem>
+       <para>
+        Specifies the number of seconds between status packets sent back to the
+        server. This allows for easier monitoring of the progress from server.
+        A value of zero disables the periodic status updates completely,
+        although an update will still be sent when requested by the server, to
+        avoid timeout disconnect. The default value is 10 seconds.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-S <replaceable>slotname</replaceable></option></term>
+      <term><option>--slot=<replaceable class="parameter">slotname</replaceable></option></term>
+      <listitem>
+        <para>
+         Require <application>pg_receivexlog</application> to use an existing
+         replication slot (see <xref linkend="streaming-replication-slots">).
+         When this option is used, <application>pg_receivexlog</> will report
+         a flush position to the server, indicating when each segment has been
+         synchronized to disk so that the server can remove that segment if it
+         is not otherwise needed.  When using this parameter, it is important
+         to make sure that <application>pg_receivexlog</> cannot become the
+         synchronous standby through an incautious setting of
+         <xref linkend="guc-synchronous-standby-names">; it does not flush
+         data frequently enough for this to work correctly.
+        </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>-v</option></term>
       <term><option>--verbose</option></term>
       <listitem>
@@ -114,9 +138,7 @@ PostgreSQL documentation
        </para>
       </listitem>
      </varlistentry>
-
     </variablelist>
-   </para>
 
    <para>
     The following command-line options control the database connection parameters.
@@ -167,20 +189,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-s <replaceable class="parameter">interval</replaceable></option></term>
-      <term><option>--status-interval=<replaceable class="parameter">interval</replaceable></option></term>
-      <listitem>
-       <para>
-        Specifies the number of seconds between status packets sent back to the
-        server. This allows for easier monitoring of the progress from server.
-        A value of zero disables the periodic status updates completely,
-        although an update will still be sent when requested by the server, to
-        avoid timeout disconnect. The default value is 10 seconds.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><option>-U <replaceable>username</replaceable></option></term>
       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
       <listitem>
@@ -225,25 +233,6 @@ PostgreSQL documentation
        </para>
       </listitem>
      </varlistentry>
-
-     <varlistentry>
-      <term><option>-S <replaceable>slotname</replaceable></option></term>
-      <term><option>--slot=<replaceable class="parameter">slotname</replaceable></option></term>
-      <listitem>
-        <para>
-         Require <application>pg_receivexlog</application> to use an existing
-         replication slot (see <xref linkend="streaming-replication-slots">).
-         When this option is used, <application>pg_receivexlog</> will report
-         a flush position to the server, indicating when each segment has been
-         synchronized to disk so that the server can remove that segment if it
-         is not otherwise needed.  When using this parameter, it is important
-         to make sure that <application>pg_receivexlog</> cannot become the
-         synchronous standby through an incautious setting of
-         <xref linkend="guc-synchronous-standby-names">; it does not flush
-         data frequently enough for this to work correctly.
-        </para>
-      </listitem>
-     </varlistentry>
     </variablelist>
    </para>
 
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index 2a521c4f36..0343a13437 100644
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -16,39 +16,35 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_recvlogical</refname>
-  <refpurpose>Control logical decoding (see <xref linkend="logicaldecoding">)
-   streams over a walsender connection.</refpurpose>
+  <refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>pg_recvlogical</command>
-   <arg rep="repeat" choice="opt"><option>option</option></arg>
+   <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
- <refsect1 id="R1-APP-PGRECVLOGICAL-1">
+ <refsect1>
   <title>Description</title>
   <para>
    <command>pg_recvlogical</command> controls logical decoding replication
    slots and streams data from such replication slots.
   </para>
+
   <para>
    It creates a replication-mode connection, so it is subject to the same
-   constraints as <link
-   linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>,
-   plus those for logical replication (see <xref
-   linkend="logicaldecoding">).
+   constraints as <xref linkend="app-pgreceivexlog">, plus those for logical
+   replication (see <xref linkend="logicaldecoding">).
   </para>
-
  </refsect1>
 
  <refsect1>
   <title>Options</title>
 
    <para>
-    <application>pg_recvlogical</application> runs in one of three modes, which
-    control its primary action:
+    At least one of the following options must be specified to select an action:
 
     <variablelist>
 
@@ -56,129 +52,52 @@ PostgreSQL documentation
       <term><option>--create-slot</option></term>
       <listitem>
        <para>
-        Create a new logical replication slot with the name specified in
-        <option>--slot</option>, using the output plugin
-        <option>--plugin</option>, then exit. The slot is created for the
-        database given in <option>--dbname</option>.
+        Create a new logical replication slot with the name specified by
+        <option>--slot</option>, using the output plugin specified by
+        <option>--plugin</option>, for the database specified
+        by <option>--dbname</option>.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>--start</option></term>
+      <term><option>--drop-slot</option></term>
       <listitem>
        <para>
-        Begin streaming changes from the logical replication slot with the name
-        specified in <option>--slot</option>, continuing until terminated with a
-        signal. If the server side change stream ends with a server
-        shutdown or disconnect, retry in a loop unless
-        <option>--no-loop</option> is specified. The stream format is
-        determined by the output plugin specified when the slot was created.
-       </para>
-       <para>
-        You must connect to the same database used to create the slot.
+        Drop the replication slot with the name specified
+        by <option>--slot</option>, then exit.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>--drop-slot</option></term>
+      <term><option>--start</option></term>
       <listitem>
        <para>
-        Drop the replication slot with the name specified
-        in <option>--slot</option>, then exit.
+        Begin streaming changes from the logical replication slot specified
+        by <option>--slot</option>, continuing until terminated by a
+        signal. If the server side change stream ends with a server shutdown
+        or disconnect, retry in a loop unless
+        <option>--no-loop</option> is specified.
+       </para>
+
+       <para>
+        The stream format is determined by the output plugin specified when
+        the slot was created.
+       </para>
+
+       <para>
+        The connection must be to the same database used to create the slot.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
-
    </para>
 
    <para>
-    <application>pg_recvlogical</application> supports all the usual
-    <literal>libpq</literal>-based options. These are explained in detail in
-    the documentation for
-    <link linkend="APP-PSQL"><application>psql</application></link> and for
-    <link linkend="libpq"><literal>libpq</literal></link>.
-
-    <variablelist>
-
-      <varlistentry>
-       <term><option>-U <replaceable>user</replaceable></option></term>
-       <term><option>--username <replaceable>user</replaceable></option></term>
-       <listitem>
-        <para>
-         Username to connect as. Must have a suitable <literal>pg_hba.conf</literal>
-         entry allowing <literal>replication</literal> connections. Defaults to
-         current operating system user name.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-d <replaceable>database</replaceable></option></term>
-       <term><option>--dbname <replaceable>database</replaceable></option></term>
-       <listitem>
-        <para>
-         The database to connect to in <literal>replication</literal> mode; see
-         mode descriptions for details. May be
-         a <link linkend="LIBPQ-CONNSTRING">libpq connstring</link>
-         instead. Defaults to user name.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
-       <term><option>--host <replaceable>hostname-or-ip</replaceable></option></term>
-       <listitem>
-        <para>
-         Host or socket to connect
-         to. See <link linkend="APP-PSQL"><application>psql</application></link>
-         and <link linkend="libpq"><literal>libpq</literal></link>
-         documentation.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-p <replaceable>port</replaceable></option></term>
-       <term><option>--port <replaceable>port</replaceable></option></term>
-       <listitem>
-        <para>
-         Port number to connect to. See
-         <link linkend="R1-APP-PSQL-3"><application>psql</application></link>
-         for an explanation of default port choices when this is not
-         specified.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-w</option></term>
-       <term><option>--no-password</option></term>
-       <listitem>
-        <para>
-         Prevent prompting for a password. Will exit with an error code if a
-         password is required but not available.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-W</option></term>
-       <term><option>--password</option></term>
-       <listitem>
-        <para>
-         Provide a password for this connection. Please use the pgservice file
-         (see <xref linkend="libpq-pgservice">) or an environment variable
-         instead of this option.
-        </para>
-       </listitem>
-      </varlistentry>
-
-     </variablelist>
-
+    <option>--create-slot</option> and <option>--start</option> can be
+    specified together.  <option>--drop-slot</option> cannot be combined with
+    another action.
    </para>
 
    <para>
@@ -186,7 +105,6 @@ PostgreSQL documentation
     output and other replication behavior:
 
     <variablelist>
-
      <varlistentry>
       <term><option>-f <replaceable>filename</replaceable></option></term>
       <term><option>--file=<replaceable>filename</replaceable></option></term>
@@ -198,40 +116,62 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
+      <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
+      <listitem>
+       <para>
+        Specifies how often <application>pg_recvlogical</application> should
+        issue <function>fsync()</function> calls to ensure the output file is
+        safely flushed to disk.
+       </para>
+
+       <para>
+        The server will occasionally request the client to perform a flush and
+        report the flush position to the server.  This setting is in addition
+        to that, to perform flushes more frequently.
+       </para>
+
+       <para>
+        Specifying an interval of <literal>0</literal> disables
+        issuing <function>fsync()</function> calls altogether, while still
+        reporting progress to the server.  In this case, data could be lost in
+        the event of a crash.
+       </para>
+      </listitem>
+     </varlistentry>
 
      <varlistentry>
-      <term><option>-n</option></term>
-      <term><option>--no-loop</option></term>
+      <term><option>-I <replaceable>lsn</replaceable></option></term>
+      <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
       <listitem>
        <para>
-        When the connection to the server is lost, do not retry in a loop, just exit.
+        In <option>--start</option> mode, start replication from the given
+        LSN.  For details on the effect of this, see the documentation
+        in <xref linkend="logicaldecoding">
+        and <xref linkend="protocol-replication">. Ignored in other modes.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-o <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
-      <term><option>--option=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
+      <term><option>-n</option></term>
+      <term><option>--no-loop</option></term>
       <listitem>
        <para>
-        Pass the option <parameter>NAME</parameter> to the output plugin with,
-        if specified, the option value <parameter>NAME</parameter>. Which
-        options exist and their effects depends on the used output plugin.
+        When the connection to the server is lost, do not retry in a loop, just exit.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
-      <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
+      <term><option>-o <replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
+      <term><option>--option=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
       <listitem>
        <para>
-        How often should <application>pg_recvlogical</application> issue sync
-        commands to ensure the <parameter>--outputfile</parameter> is safely
-        flushed to disk without being asked by the server to do so. Specifying
-        an interval of <literal>0</literal> disables issuing fsyncs altogether,
-        while still reporting progress the server.  In this case, data may be
-        lost in the event of a crash.
+        Pass the option <replaceable>name</replaceable> to the output plugin with,
+        if specified, the option value <replaceable>value</replaceable>. Which
+        options exist and their effects depends on the used output plugin.
        </para>
       </listitem>
      </varlistentry>
@@ -241,7 +181,7 @@ PostgreSQL documentation
       <term><option>--plugin=<replaceable>plugin</replaceable></option></term>
       <listitem>
        <para>
-        When creating a slot, use the logical decoding output
+        When creating a slot, use the specified logical decoding output
         plugin. See <xref linkend="logicaldecoding">. This option has no
         effect if the slot already exists.
        </para>
@@ -253,9 +193,8 @@ PostgreSQL documentation
       <term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term>
       <listitem>
        <para>
-        This option has the same effect as the option of the same name in <link
-        linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>.
-        See the description there.
+        This option has the same effect as the option of the same name
+        in <xref linkend="app-pgreceivexlog">.  See the description there.
        </para>
       </listitem>
      </varlistentry>
@@ -274,36 +213,114 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-I <replaceable>lsn</replaceable></option></term>
-      <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
-      <listitem>
+       <term><option>-v</></term>
+       <term><option>--verbose</></term>
+       <listitem>
        <para>
-        In <option>--start</option> mode, start replication from the given
-        LSN.  For details on the effect of this, see the documentation
-        in <xref linkend="logicaldecoding">
-        and <xref linkend="protocol-replication">. Ignored in other modes.
+        Enables verbose mode.
        </para>
-      </listitem>
+       </listitem>
      </varlistentry>
     </variablelist>
-
    </para>
 
    <para>
-    The following additional options are available:
-
+    The following command-line options control the database connection parameters.
+ 
     <variablelist>
+      <varlistentry>
+       <term><option>-d <replaceable>database</replaceable></option></term>
+       <term><option>--dbname <replaceable>database</replaceable></option></term>
+       <listitem>
+        <para>
+         The database to connect to.  See the description of the actions for
+         what this means in detail.  This can be a libpq connection string;
+         see <xref linkend="LIBPQ-CONNSTRING"> for more information.  Defaults
+         to user name.
+        </para>
+       </listitem>
+      </varlistentry>
 
-     <varlistentry>
-       <term><option>-v</></term>
-       <term><option>--verbose</></term>
+      <varlistentry>
+       <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
+       <term><option>--host <replaceable>hostname-or-ip</replaceable></option></term>
        <listitem>
-       <para>
-        Enables verbose mode.
-       </para>
+        <para>
+         Specifies the host name of the machine on which the server is
+         running.  If the value begins with a slash, it is used as the
+         directory for the Unix domain socket. The default is taken
+         from the <envar>PGHOST</envar> environment variable, if set,
+         else a Unix domain socket connection is attempted.
+        </para>
        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-p <replaceable>port</replaceable></option></term>
+       <term><option>--port <replaceable>port</replaceable></option></term>
+       <listitem>
+        <para>
+         Specifies the TCP port or local Unix domain socket file
+         extension on which the server is listening for connections.
+         Defaults to the <envar>PGPORT</envar> environment variable, if
+         set, or a compiled-in default.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-U <replaceable>user</replaceable></option></term>
+       <term><option>--username <replaceable>user</replaceable></option></term>
+       <listitem>
+        <para>
+         Username to connect as.  Defaults to current operating system user
+         name.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-w</option></term>
+       <term><option>--no-password</option></term>
+       <listitem>
+        <para>
+         Never issue a password prompt.  If the server requires
+         password authentication and a password is not available by
+         other means such as a <filename>.pgpass</filename> file, the
+         connection attempt will fail.  This option can be useful in
+         batch jobs and scripts where no user is present to enter a
+         password.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-W</option></term>
+       <term><option>--password</option></term>
+       <listitem>
+        <para>
+         Force <application>pg_recvlogical</application> to prompt for a
+         password before connecting to a database.
+        </para>
+
+        <para>
+         This option is never essential, since
+         <application>pg_recvlogical</application> will automatically prompt
+         for a password if the server demands password authentication.
+         However, <application>pg_recvlogical</application> will waste a
+         connection attempt finding out that the server wants a password.
+         In some cases it is worth typing <option>-W</> to avoid the extra
+         connection attempt.
+        </para>
+      </listitem>
      </varlistentry>
+     </variablelist>
+   </para>
+
+   <para>
+    The following additional options are available:
 
+    <variablelist>
      <varlistentry>
        <term><option>-V</></term>
        <term><option>--version</></term>
@@ -324,8 +341,25 @@ PostgreSQL documentation
         </para>
        </listitem>
       </varlistentry>
-
     </variablelist>
    </para>
  </refsect1>
+
+ <refsect1>
+  <title>Environment</title>
+
+  <para>
+   This utility, like most other <productname>PostgreSQL</> utilities,
+   uses the environment variables supported by <application>libpq</>
+   (see <xref linkend="libpq-envars">).
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-pgreceivexlog"></member>
+  </simplelist>
+ </refsect1>
 </refentry>