Improve recovery target settings documentation.

Commit 815d71dee hadn't bothered to update the documentation to match the
behavioral change, and a lot of other text in this section was badly in
need of copy-editing.

doc/src/sgml/recovery-config.sgml

@@ -152,16 +152,18 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
   <sect1 id="recovery-target-settings">
 
     <title>Recovery Target Settings</title>
+
      <para>
       By default, recovery will recover to the end of the WAL log. The
       following parameters can be used to specify an earlier stopping point.
       At most one of <varname>recovery_target</>,
       <varname>recovery_target_name</>, <varname>recovery_target_time</>, or
-      <varname>recovery_target_xid</> can be specified.
+      <varname>recovery_target_xid</> can be used; if more than one of these
+      is specified in the configuration file, the last entry will be used.
      </para>
-     <variablelist>
 
-     <varlistentry id="recovery-target" xreflabel="recovery_target_name">
+     <variablelist>
+     <varlistentry id="recovery-target" xreflabel="recovery_target">
       <term><varname>recovery_target</varname><literal> = 'immediate'</literal>
       <indexterm>
         <primary><varname>recovery_target</> recovery parameter</primary>
@@ -189,8 +191,8 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       </term>
       <listitem>
        <para>
-        This parameter specifies the named restore point, created with
-        <function>pg_create_restore_point()</> to which recovery will proceed.
+        This parameter specifies the named restore point (created with
+        <function>pg_create_restore_point()</>) to which recovery will proceed.
        </para>
       </listitem>
      </varlistentry>
@@ -231,13 +233,13 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       </listitem>
      </varlistentry>
      </variablelist>
+
      <para>
        The following options further specify the recovery target, and affect
        what happens when the target is reached:
      </para>
 
      <variablelist>
-
      <varlistentry id="recovery-target-inclusive"
                    xreflabel="recovery_target_inclusive">
       <term><varname>recovery_target_inclusive</varname> (<type>boolean</type>)
@@ -247,12 +249,12 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       </term>
       <listitem>
        <para>
-        Specifies whether we stop just after the specified recovery target
+        Specifies whether to stop just after the specified recovery target
         (<literal>true</literal>), or just before the recovery target
         (<literal>false</literal>).
-        Applies to both <xref linkend="recovery-target-time">
-        and <xref linkend="recovery-target-xid">, whichever one is
-        specified for this recovery.  This indicates whether transactions
+        Applies when either <xref linkend="recovery-target-time">
+        or <xref linkend="recovery-target-xid"> is specified.
+        This setting controls whether transactions
         having exactly the target commit time or ID, respectively, will
         be included in the recovery.  Default is <literal>true</>.
        </para>
@@ -280,27 +282,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       </listitem>
      </varlistentry>
 
-     <varlistentry id="pause-at-recovery-target"
-                   xreflabel="pause_at_recovery_target">
-      <term><varname>pause_at_recovery_target</varname> (<type>boolean</type>)
-      <indexterm>
-        <primary><varname>pause_at_recovery_target</> recovery parameter</primary>
-      </indexterm>
-      </term>
-      <listitem>
-       <para>
-        Alias for recovery_target_action, <literal>true</> is same as
-        recovery_target_action = <literal>pause</> and <literal>false</>
-        is same as recovery_target_action = <literal>promote</>.
-       </para>
-       <para>
-        This setting has no effect if <xref linkend="guc-hot-standby"> is not
-        enabled, or if no recovery target is set.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry id="action-at-recovery-target"
+     <varlistentry id="recovery-target-action"
                    xreflabel="recovery_target_action">
       <term><varname>recovery_target_action</varname> (<type>enum</type>)
       <indexterm>
@@ -311,35 +293,35 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
        <para>
         Specifies what action the server should take once the recovery target is
         reached. The default is <literal>pause</>, which means recovery will
-        be paused. <literal>promote</> means recovery process will finish and
-        the server will start to accept connections.
+        be paused. <literal>promote</> means the recovery process will finish
+        and the server will start to accept connections.
         Finally <literal>shutdown</> will stop the server after reaching the
         recovery target.
        </para>
        <para>
-        The intended use of <literal>pause</> setting is to allow queries to be
-        executed against the database to check if this recovery target is the
-        most desirable point for recovery. The paused state can be resumed by
-        using <function>pg_xlog_replay_resume()</> (See
+        The intended use of the <literal>pause</> setting is to allow queries
+        to be executed against the database to check if this recovery target
+        is the most desirable point for recovery.
+        The paused state can be resumed by
+        using <function>pg_xlog_replay_resume()</> (see
         <xref linkend="functions-recovery-control-table">), which then
         causes recovery to end. If this recovery target is not the
-        desired stopping point, then shutdown the server, change the
+        desired stopping point, then shut down the server, change the
         recovery target settings to a later target and restart to
         continue recovery.
        </para>
        <para>
-        The <literal>shutdown</> setting is useful to have instance ready at
-        exact replay point desired.
-        The instance will still be able to replay more WAL records (and in fact
-        will have to replay WAL records since last checkpoint next time it is
-        started).
+        The <literal>shutdown</> setting is useful to have the instance ready
+        at the exact replay point desired.  The instance will still be able to
+        replay more WAL records (and in fact will have to replay WAL records
+        since the last checkpoint next time it is started).
        </para>
        <para>
         Note that because <filename>recovery.conf</> will not be renamed when
         <varname>recovery_target_action</> is set to <literal>shutdown</>,
         any subsequent start will end with immediate shutdown unless the
-        configuration is changed or the <filename>recovery.conf</> is removed
-        manually.
+        configuration is changed or the <filename>recovery.conf</> file is
+        removed manually.
        </para>
        <para>
         This setting has no effect if no recovery target is set.
@@ -349,6 +331,28 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       </listitem>
      </varlistentry>
 
+     <varlistentry id="pause-at-recovery-target"
+                   xreflabel="pause_at_recovery_target">
+      <term><varname>pause_at_recovery_target</varname> (<type>boolean</type>)
+      <indexterm>
+        <primary><varname>pause_at_recovery_target</> recovery parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        This is an obsolete version of <varname>recovery_target_action</>.
+        Setting it to <literal>true</> is the same as
+        <varname>recovery_target_action</> = <literal>pause</>,
+        while <literal>false</> is the same as
+        <varname>recovery_target_action</> = <literal>promote</>.
+       </para>
+       <para>
+        This setting has no effect if <xref linkend="guc-hot-standby"> is not
+        enabled, or if no recovery target is set.
+       </para>
+      </listitem>
+     </varlistentry>
+
      </variablelist>
    </sect1>