Various documentation fixes

doc/cloning-standbys.sgml

@@ -5,8 +5,8 @@
 
  <sect1 id="cloning-from-barman" xreflabel="Cloning from Barman">
    <indexterm>
-     <primary>cloning</primary>
+    <primary>cloning</primary>
-     <secondary>from Barman</secondary>
+    <secondary>from Barman</secondary>
    </indexterm>
    <title>Cloning a standby from Barman</title>
    <para>
@@ -192,7 +192,7 @@
      </programlisting>
    </para>
    <para>
-    Replication slots must be enabled in <filename>postgresql.conf</filename>` by
+    Replication slots must be enabled in <filename>postgresql.conf</filename> by
     setting the parameter <varname>max_replication_slots</varname> to at least the
     number of expected standbys (changes to this parameter require a server restart).
    </para>

doc/configuration-file-settings.sgml

@@ -1,4 +1,9 @@
 <sect1 id="configuration-file-settings" xreflabel="configuration file settings">
+  <indexterm>
+    <primary>repmgr.conf</primary>
+    <secondary>settings</secondary>
+  </indexterm>
+
  <title>Configuration file settings</title>
  <para>
    Each <filename>repmgr.conf</filename> file must contain the following parameters:

doc/configuration-file.sgml

@@ -1,4 +1,9 @@
 <sect1 id="configuration-file" xreflabel="configuration file location">
+  <indexterm>
+    <primary>repmgr.conf</primary>
+    <secondary>location</secondary>
+  </indexterm>
+
   <title>Configuration file location</title>
   <para>
     <application>repmgr</application> and <application>repmgrd</application>
@@ -7,7 +12,7 @@
     <filename>repmgr.conf</filename> must contain a number of required parameters, including
     the database connection string for the local node and the location
     of its data directory; other values will be inferred from defaults if
-    not explicitly supplied. See section `configuration file parameters`
+    not explicitly supplied. See section <xref linkend="configuration-file-settings">
     for more details.
   </para>
 
@@ -15,7 +20,7 @@
    The configuration file will be searched for in the following locations:
    <itemizedlist spacing="compact" mark="bullet">
     <listitem>
-     <para>a configuration file specified by the `-f/--config-file` command line option</para>
+     <para>a configuration file specified by the <literal>-f/--config-file</literal> command line option</para>
     </listitem>
     <listitem>
      <para>
@@ -37,10 +42,10 @@
   </para>
 
   <para>
-   Note that if a file is explicitly specified with <application>-f/--config-file</application>,
+   Note that if a file is explicitly specified with <literal>-f/--config-file</literal>,
-   an error will be raised if it is not found or not readable and no attempt will be made to
+   an error will be raised if it is not found or not readable, and no attempt will be made to
    check default locations; this is to prevent <application>repmgr</application> unexpectedly
-   reading the wrong file.
+   reading the wrong configuraton file.
   </para>
 
 </sect1>

doc/event-notifications.sgml

@@ -1,12 +1,12 @@
 <chapter id="event-notifications" xreflabel="event notifications">
  <title>Event Notifications</title>
  <para>
-  Each time `repmgr` or `repmgrd` perform a significant event, a record
+  Each time &repmgr; or <command>repmgrd</command> perform a significant event, a record
-  of that event is written into the `repmgr.events` table together with
+  of that event is written into the <literal>repmgr.events</literal> table together with
   a timestamp, an indication of failure or success, and further details
   if appropriate. This is useful for gaining an overview of events
   affecting the replication cluster. However note that this table has
-  advisory character and should be used in combination with the `repmgr`
+  advisory character and should be used in combination with the &repmgr;
   and PostgreSQL logs to obtain details of any events.
  </para>
  <para>
@@ -28,8 +28,8 @@
  <para>
   Additionally, event notifications can be passed to a user-defined program
   or script which can take further action, e.g. send email notifications.
-  This is done by setting the `event_notification_command` parameter in
+  This is done by setting the <literal>event_notification_command</literal> parameter in
-  `repmgr.conf`.
+  <filename>repmgr.conf</filename>.
  </para>
  <para>
   This parameter accepts the following format placeholders:

doc/follow-new-primary.sgml

@@ -1,4 +1,9 @@
 <chapter id="follow-new-primary" xreflabel="Following a new primary">
+ <indexterm>
+  <primary>Following a new primary</primary>
+  <seealso>repmgr standby follow</seealso>
+ </indexterm>
+
  <title>Following a new primary</title>
  <para>
    Following the failure or removal of the replication cluster's existing primary
@@ -22,7 +27,8 @@
   </programlisting>
  </para>
  <para>
-   The standby is now replicating from the new primary and `repmgr cluster show`
+   The standby is now replicating from the new primary and
+   <command><link linkend="repmgr-cluster-show">repmgr cluster show</link></command>
    output reflects this:
    <programlisting>
     $ repmgr -f /etc/repmgr.conf cluster show

doc/install-packages.sgml

@@ -1,32 +1,47 @@
 <sect1 id="installation-packages" xreflabel="Installing from packages">
  <title>Installing &repmgr; from packages</title>
  <para>
-We recommend installing `repmgr` using the available packages for your
+  We recommend installing &repmgr; using the available packages for your
-system.
+  system.
  </para>
 
  <sect2 id="installation-packages-redhat" xreflabel="Installing from packages on RHEL, Fedora and CentOS">
-   <title>RedHat/Fedora/CentOS</title>
+
-   <para>
+  <indexterm>
-     RPM packages for `repmgr` are available via Yum through
+   <primary>installation</primary>
-     the PostgreSQL Global Development Group RPM repository
+   <secondary>on Redhat/CentOS/Fedora etc.</secondary>
-     ( <ulink url="https://yum.postgresql.org/">http://yum.postgresql.org/</>).
+  </indexterm>
-     Follow the instructions for your distribution (RedHat, CentOS,
+
-     Fedora, etc.) and architecture as detailed at yum.postgresql.org.
+  <title>RedHat/Fedora/CentOS</title>
-   </para>
+  <para>
-   <para>
+   RPM packages for &repmgr; are available via Yum through
-     2ndQuadrant also provides its own RPM packages which are made available
+   the PostgreSQL Global Development Group RPM repository
-     at the same time as each `repmgr` release, as it can take some days for
+   (<ulink url="https://yum.postgresql.org/">http://yum.postgresql.org/</>).
-     them to become available via the main PGDG repository. See here for details:
+   Follow the instructions for your distribution (RedHat, CentOS,
-     <ulink url="http://repmgr.org/yum-repository.html">http://repmgr.org/yum-repository.html</>
+   Fedora, etc.) and architecture as detailed there.
-   </para>
+  </para>
- </sect2>
+  <para>
- <sect2 id="installation-packages-debian" xreflabel="Installing from packages on Debian or Ubuntu">
+   <ulink url="https://2ndquadrant.com">2ndQuadrant</ulink> also provides its
-  <title>Debian/Ubuntu</title>
+   own RPM packages which are made available
-  <para>.deb packages for `repmgr` are available from the
+   at the same time as each &repmgr; release, as it can take some days for
-  PostgreSQL Community APT repository (<ulink url="http://apt.postgresql.org/">http://apt.postgresql.org/</> ).
+   them to become available via the main PGDG repository. See here for details:
-  Instructions can be found in the APT section of the PostgreSQL Wiki
+   <ulink url="http://repmgr.org/yum-repository.html">http://repmgr.org/yum-repository.html</>
-  (<ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</> ).
   </para>
  </sect2>
+
+ <sect2 id="installation-packages-debian" xreflabel="Installing from packages on Debian or Ubuntu">
+
+  <indexterm>
+   <primary>installation</primary>
+   <secondary>on Debian/Ubuntu etc.</secondary>
+  </indexterm>
+
+  <title>Debian/Ubuntu</title>
+  <para>.deb packages for &repmgr; are available from the
+  PostgreSQL Community APT repository (<ulink url="http://apt.postgresql.org/">http://apt.postgresql.org/</>).
+  Instructions can be found in the APT section of the PostgreSQL Wiki
+  (<ulink url="https://wiki.postgresql.org/wiki/Apt">https://wiki.postgresql.org/wiki/Apt</>).
+  </para>
+ </sect2>
+
 </sect1>

doc/install-requirements.sgml

@@ -7,17 +7,14 @@
   </para>
 
   <para>
-   From version 4.0, repmgr is compatible with all PostgreSQL versions from 9.4, including PostgreSQL 10.
+   From version 4.0, repmgr is compatible with all PostgreSQL versions from 9.3, including PostgreSQL 10.
-  </para>
+   Note that some &repmgr; functionality is not available in PostgreSQL 9.3 and PostgreSQL 9.4.
-  <para>
-   PostgreSQL 9.3 is supported by repmgr 3.3.
   </para>
 
   <note>
-    <simpara>
+   <simpara>
-If upgrading from `repmgr 3`, please see the separate upgrade guide
+    If upgrading from &repmgr; 3.x, please see the section <xref linkend="upgrading-from-repmgr-3">.
-`doc/upgrading-from-repmgr3.md`.
+   </simpara>
-    </simpara>
   </note>
 
   <para>
@@ -26,42 +23,44 @@ If upgrading from `repmgr 3`, please see the separate upgrade guide
   </para>
 
   <para>
-   `repmgr` must be installed on each server in the replication cluster.
+   &repmgr; must be installed on each server in the replication cluster.
    If installing repmgr from packages, the package version must match the PostgreSQL
    version. If installing from source, repmgr must be compiled against the same
    major version.
   </para>
 
   <para>
-   A dedicated system user for `repmgr` is *not* required; as many `repmgr` and
+   A dedicated system user for &repmgr; is *not* required; as many &repmgr; and
-  `repmgrd` actions require direct access to the PostgreSQL data directory,
+   <command>repmgrd</command> actions require direct access to the PostgreSQL data directory,
-  these commands should be executed by the `postgres` user.
+   these commands should be executed by the <literal>postgres</literal> user.
   </para>
 
-
   <para>
-   Passwordless `ssh` connectivity between all servers in the replication cluster
+   Passwordless <command>ssh</command> connectivity between all servers in the replication cluster
    is not required, but is necessary in the following cases:
    <itemizedlist>
      <listitem>
-       <simpara>if you need `repmgr` to copy configuration files from outside the PostgreSQL
+       <simpara>if you need &repmgr; to copy configuration files from outside the PostgreSQL
-  data directory (in which case `rsync` is also required)</simpara>
+       data directory (in which case <command>rsync</command> is also required)</simpara>
      </listitem>
      <listitem>
-       <simpara>to perform switchover operations</simpara>
+       <simpara>to perform <link linkend="performing-switchover">switchover operations</link></simpara>
      </listitem>
      <listitem>
-       <simpara>when executing `repmgr cluster matrix` and `repmgr cluster crosscheck`</simpara>
+       <simpara>
+        when executing <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command>
+        and <command><link linkend="repmgr-cluster-crosscheck">repmgr cluster crosscheck</link></command>
+       </simpara>
      </listitem>
    </itemizedlist>
   </para>
 
   <tip>
    <simpara>
-    We recommend using a session multiplexer utility such as `screen` or
+    We recommend using a session multiplexer utility such as <command>screen</command> or
-    `tmux` when performing long-running actions (such as cloning a database)
+    <command>tmux</command> when performing long-running actions (such as cloning a database)
-    on a remote server - this will ensure the `repmgr` action won't be prematurely
+    on a remote server - this will ensure the &repmgr; action won't be prematurely
-    terminated if your `ssh` session to the server is interrupted or closed.
+    terminated if your <command>ssh</command> session to the server is interrupted or closed.
     </simpara>
   </tip>
  </sect1>

doc/install-source.sgml

@@ -1,4 +1,9 @@
 <sect1 id="installation-source" xreflabel="Installing from source code">
+  <indexterm>
+   <primary>installation</primary>
+   <secondary>from source</secondary>
+  </indexterm>
+
  <title>Installing &repmgr; from source</title>
 
  <sect2 id="installation-source-prereqs">
@@ -132,7 +137,8 @@
     ./configure && make install
    </programlisting>
 
-   Ensure `pg_config` for the target PostgreSQL version is in `$PATH`.
+   Ensure <command>pg_config</command> for the target PostgreSQL version is in
+   <varname>$PATH</varname>.
   </para>
  </sect2>
 

doc/install.sgml

@@ -1,4 +1,8 @@
 <chapter id="installation" xreflabel="Installation">
+ <indexterm>
+  <primary>installation</primary>
+ </indexterm>
+
  <title>Installation</title>
 
  <para>

doc/overview.sgml

@@ -5,6 +5,11 @@
   This chapter provides a high-level overview of repmgr's components and functionality.
  </para>
  <sect1 id="repmgr-concepts" xreflabel="Concepts">
+
+  <indexterm>
+    <primary>concepts</primary>
+  </indexterm>
+
   <title>Concepts</title>
 
   <para>
@@ -15,13 +20,13 @@
    streaming replication</>.
   </para>
   <para>
-   The following terms are used throughout the `repmgr` documentation.
+   The following terms are used throughout the &repmgr; documentation.
    <variablelist>
     <varlistentry>
      <term>replication cluster</term>
      <listitem>
       <simpara>
-       In the `repmgr` documentation, "replication cluster" refers to the network
+       In the &repmgr; documentation, "replication cluster" refers to the network
        of PostgreSQL servers connected by streaming replication.
       </simpara>
      </listitem>
@@ -31,7 +36,7 @@
      <term>node</term>
      <listitem>
       <simpara>
-       A node is a server within a replication cluster.
+       A node is a single PostgreSQL server within a replication cluster.
       </simpara>
      </listitem>
     </varlistentry>
@@ -41,7 +46,7 @@
      <listitem>
       <simpara>
        The node a standby server connects to, in order to receive streaming replication.
-       This is either the primary server or in the case of cascading replication, another
+       This is either the primary server, or in the case of cascading replication, another
        standby.
       </simpara>
      </listitem>
@@ -52,7 +57,7 @@
      <listitem>
       <simpara>
        This is the action which occurs if a primary server fails and a suitable standby
-       is  promoted as the new primary. The `repmgrd` daemon supports automatic failover
+       is  promoted as the new primary. The <command>repmgrd</command> daemon supports automatic failover
        to minimise downtime.
       </simpara>
      </listitem>
@@ -66,7 +71,7 @@
        it's necessary to take a primary server offline; in this case a controlled
        switchover is necessary, whereby a suitable standby is promoted and the
        existing primary removed from the replication cluster in a controlled manner.
-       The `repmgr` command line client provides this functionality.
+       The &repmgr; command line client provides this functionality.
       </simpara>
      </listitem>
     </varlistentry>
@@ -88,7 +93,7 @@
  <sect1 id="repmgr-components" xreflabel="Components">
   <title>Components</title>
   <para>
-  `repmgr` is a suite of open-source tools to manage replication and failover
+  &repmgr; is a suite of open-source tools to manage replication and failover
   within a cluster of PostgreSQL servers. It supports and enhances PostgreSQL's
   built-in streaming replication, which provides a single read/write primary server
   and one or more read-only standbys containing near-real time copies of the primary
@@ -147,11 +152,12 @@
  <sect1 id="repmgr-user-metadata" xreflabel="Repmgr user and metadata">
   <title>Repmgr user and metadata</title>
   <para>
-   In order to effectively manage a replication cluster, `repmgr` needs to store
+   In order to effectively manage a replication cluster, &repmgr; needs to store
    information about the servers in the cluster in a dedicated database schema.
-   This schema is automatically by the `repmgr` extension, which is installed
+   This schema is automatically by the &repmgr; extension, which is installed
-   during the first step in initialising a `repmgr`-administered cluster
+   during the first step in initialising a &repmgr;-administered cluster
-   (`repmgr primary register`) and contains the following objects:
+   (<command><link linkend="repmgr-primary-register">repmgr primary register</link></command>)
+   and contains the following objects:
    <variablelist>
     <varlistentry>
      <term>Tables</term>
@@ -159,14 +165,15 @@
       <para>
        <itemizedlist>
         <listitem>
-          <simpara>repmgr.events: records events of interest</simpara>
+          <simpara><literal>repmgr.events</literal>: records events of interest</simpara>
         </listitem>
         <listitem>
-          <simpara>repmgr.nodes: connection and status information for each server in the
+          <simpara><literal>repmgr.nodes</literal>: connection and status information for each server in the
     replication cluster</simpara>
         </listitem>
         <listitem>
-          <simpara>repmgr.monitoring_history: historical standby monitoring information written by `repmgrd`</simpara>
+          <simpara><literal>repmgr.monitoring_history</literal>: historical standby monitoring information
+            written by <command>repmgrd</command></simpara>
         </listitem>
        </itemizedlist>
       </para>
@@ -178,12 +185,12 @@
       <para>
        <itemizedlist>
         <listitem>
-          <simpara>repmgr.show_nodes: based on the table `repl_nodes`, additionally showing the
+          <simpara>repmgr.show_nodes: based on the table <literal>repmgr.nodes</literal>, additionally showing the
-     name of the server's upstream node</simpara>
+           name of the server's upstream node</simpara>
         </listitem>
         <listitem>
-          <simpara>repmgr.replication_status: when `repmgrd`'s monitoring is enabled, shows current monitoring
+          <simpara>repmgr.replication_status: when <command>repmgrd</command>'s monitoring is enabled, shows
-    status for each standby.</simpara>
+            current monitoring status for each standby.</simpara>
         </listitem>
        </itemizedlist>
       </para>
@@ -193,16 +200,16 @@
   </para>
 
   <para>
-   The `repmgr` metadata schema can be stored in an existing database or in its own
+   The &repmgr; metadata schema can be stored in an existing database or in its own
-   dedicated database. Note that the `repmgr` metadata schema cannot reside on a database
+   dedicated database. Note that the &repmgr; metadata schema cannot reside on a database
-   server which is not part of the replication cluster managed by `repmgr`.
+   server which is not part of the replication cluster managed by &repmgr;.
   </para>
   <para>
-   A database user must be available for `repmgr` to access this database and perform
+   A database user must be available for &repmgr; to access this database and perform
    necessary changes. This user does not need to be a superuser, however some operations
-   such as initial installation of the `repmgr` extension will require a superuser
+   such as initial installation of the &repmgr; extension will require a superuser
    connection (this can be specified where required with the command line option
-   `--superuser`).
+   <literal>--superuser</literal>).
   </para>
  </sect1>
 

doc/repmgr-cluster-matrix.sgml

@@ -9,7 +9,7 @@
   </para>
   <para>
     <command>repmgr cluster matrix</command> requires a valid <filename>repmgr.conf</filename>
-    file on each node.  Additionally passwordless `ssh` connections are required between
+    file on each node.  Additionally passwordless <command>ssh</command> connections are required between
     all nodes.
   </para>
   <para>
@@ -46,7 +46,7 @@
   <para>
     The other two nodes are up; the corresponding rows have <literal>x</literal> in the
     column corresponding to <literal>node3</literal>, meaning that inbound connections to
-    that node have failed, and `*` in the columns corresponding to
+    that node have failed, and <literal>*</literal> in the columns corresponding to
     <literal>node1</literal> and <literal>node2</literal>, meaning that inbound connections
     to these nodes have succeeded.
   </para>

doc/repmgr-cluster-show.sgml

@@ -32,7 +32,7 @@
     <literal>--verbose</literal> mode.
   </para>
   <para>
-    The `cluster show` command accepts an optional parameter <literal>--csv</literal>, which
+    <command>cluster show</command> accepts an optional parameter <literal>--csv</literal>, which
     outputs the replication cluster's status in a simple CSV format, suitable for
     parsing by scripts:
     <programlisting>

doc/repmgr-standby-clone.sgml

@@ -58,7 +58,7 @@
    <para>
     When initially cloning a standby, you will need to ensure
     that all required WAL files remain available while the cloning is taking
-    place. To ensure this happens when using the default `pg_basebackup` method,
+    place. To ensure this happens when using the default <command>pg_basebackup</command> method,
     &repmgr; will set <command>pg_basebackup</command>'s <literal>--xlog-method</literal>
     parameter to <literal>stream</literal>,
     which will ensure all WAL files generated during the cloning process are

doc/switchover.sgml

@@ -1,4 +1,9 @@
 <chapter id="performing-switchover" xreflabel="Performing a switchover with repmgr">
+
+ <indexterm>
+  <primary>switchover</primary>
+ </indexterm>
+
  <title>Performing a switchover with repmgr</title>
  <para>
   A typical use-case for replication is a combination of primary and standby
@@ -39,7 +44,7 @@
   </simpara>
   <simpara>
    Please also read carefully the sections <xref linkend="preparing-for-switchover"> and
-  `Caveats` below.
+   <xref linkend="switchover-caveats"> below.
   </simpara>
  </note>
 
@@ -81,7 +86,7 @@
     If WAL file archiving is set up, check that there is no backlog of files waiting
     to be archived, as PostgreSQL will not finally shut down until all these have been
     archived. If there is a backlog exceeding <varname>archive_ready_warning</varname> WAL files,
-    `repmgr` will emit a warning before attempting to perform a switchover; you can also check
+    &repmgr; will emit a warning before attempting to perform a switchover; you can also check
     manually with <command>repmgr node check --archive-ready</command>.
    </para>
    <para>
@@ -198,7 +203,7 @@
    </itemizedlist>
   </para>
   <para>
-   We hope to remove some of these restrictions in future versions of `repmgr`.
+   We hope to remove some of these restrictions in future versions of &repmgr;.
   </para>
  </sect1>
 </chapter>

doc/upgrading-repmgr.sgml

@@ -1,5 +1,11 @@
 <chapter id="upgrading-repmgr" xreflabel="Upgrading repmgr">
+
+ <indexterm>
+  <primary>upgrading</primary>
+ </indexterm>
+
  <title>Upgrading repmgr</title>
+
  <para>
   &repmgr; is updated regularly with point releases (e.g. 4.0.1 to 4.0.2)
   containing bugfixes and other minor improvements. Any substantial new
@@ -17,8 +23,13 @@
   file used by <command>repmgrd</command>; check the release notes for details.
  </para>
 
- <sect1 id="upgrading-from-repmgr-3">
+ <sect1 id="upgrading-from-repmgr-3" xreflabel="Upgrading from repmgr 3.x">
-  <title>Upgrading from repmgr 3</title>
+  <indexterm>
+   <primary>upgrading</primary>
+   <secondary>from repmgr 3.x</secondary>
+  </indexterm>
+
+  <title>Upgrading from repmgr 3.x</title>
   <para>
    The upgrade process consists of two steps:
    <orderedlist>
@@ -162,8 +173,8 @@
     <command>repmgr</command> binary.
    </para>
    <para>
-    Install <literal>repmgr4</literal>; any <literal>repmgr3</literal> packages should be uninstalled
+    Install <literal>repmgr 4</literal> packages; any <literal>repmgr 3.x</literal> packages
-    (if not automatically uninstalled already).
+    should be uninstalled (if not automatically uninstalled already by your packaging system).
    </para>
    <sect3>
     <title>Upgrading from repmgr 3.1.1 or earlier</title>
@@ -203,7 +214,8 @@
     </para>
     <note>
       <simpara>there must be only one schema matching <literal>repmgr_%</literal> in the
-        database, otherwise this step may not work.</simpara>
+        database, otherwise this step may not work.
+      </simpara>
     </note>
    </sect3>
    <sect3>