docs: convert command reference sections to <refentry> format

Note that most entries still need a bit more tidying up, consistent structuring,
provision of more examples etc.

doc/repmgr-cluster-cleanup.sgml

@@ -1,23 +1,41 @@
-<chapter id="repmgr-cluster-cleanup" xreflabel="repmgr cluster cleanup">
+<refentry id="repmgr-cluster-cleanup">
   <indexterm>
     <primary>repmgr cluster cleanup</primary>
   </indexterm>
-  <title>repmgr cluster cleanup</title>
+ <refmeta>
+    <refentrytitle>repmgr cluster cleanup</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr cluster cleanup</refname>
+    <refpurpose>purge monitoring history</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       Purges monitoring history from the <literal>repmgr.monitoring_history</literal> table to
       prevent excessive table growth. Use the <literal>-k/--keep-history</literal> to specify the
       number of days of monitoring history to retain. This command can be used
       manually or as a cronjob.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Usage</title>
     <para>
       This command requires a valid <filename>repmgr.conf</filename> file for the node on which it is
       executed; no additional arguments are required.
     </para>
-  <note>
+  </refsect1>
-   <simpara>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <para>
       Monitoring history will only be written if <application>repmgrd</application> is active, and
       <varname>monitoring_history</varname> is set to <literal>true</literal> in
       <filename>repmgr.conf</filename>.
-   </simpara>
+    </para>
-  </note>
+  </refsect1>
-</chapter>
+</refentry>

doc/repmgr-cluster-crosscheck.sgml

@@ -1,8 +1,20 @@
-<chapter id="repmgr-cluster-crosscheck" xreflabel="repmgr cluster crosscheck">
+<refentry id="repmgr-cluster-crosscheck">
   <indexterm>
     <primary>repmgr cluster crosscheck</primary>
   </indexterm>
-  <title>repmgr cluster crosscheck</title>
+
+
+  <refmeta>
+    <refentrytitle>repmgr cluster crosscheck</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr cluster crosscheck</refname>
+    <refpurpose>cross-checks connections between each combination of nodes</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       <command>repmgr cluster crosscheck</command> is similar to <xref linkend="repmgr-cluster-matrix">,
         but cross-checks connections between each combination of nodes. In "Example 3" in
@@ -20,9 +32,11 @@
     </para>
     <para>
       What happened is that <command>repmgr cluster crosscheck</command> merged its own
-   <command>repmgr cluster matrix</command> with the <command>repmgr cluster matrix</command>
+      <command><link linkend="repmgr-cluster-matrix">repmgr cluster matrix</link></command> with the
-   output from <literal>node2</literal>; the latter is able to connect to <literal>node3</literal>
+      <command>repmgr cluster matrix</command> output from <literal>node2</literal>; the latter is
+      able to connect to <literal>node3</literal>
       and therefore determine the state of outbound connections from that node.
     </para>
-</chapter>
+  </refsect1>
+</refentry>
 

doc/repmgr-cluster-event.sgml

@@ -1,11 +1,30 @@
-<chapter id="repmgr-cluster-event" xreflabel="repmgr cluster event">
+<refentry id="repmgr-cluster-event">
   <indexterm>
     <primary>repmgr cluster event</primary>
   </indexterm>
- <title>repmgr cluster event</title>
+
+  <refmeta>
+    <refentrytitle>repmgr cluster event</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr cluster event</refname>
+    <refpurpose>output a formatted list of cluster events</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
     <para>
-  This outputs a formatted list of cluster events, as stored in the
+      Outputs a formatted list of cluster events, as stored in the <literal>repmgr.events</literal> table.
-  <literal>repmgr.events</literal> table. Output is in reverse chronological order, and
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Usage</title>
+
+    <para>
+      Output is in reverse chronological order, and
       can be filtered with the following options:
       <itemizedlist spacing="compact" mark="bullet">
         <listitem>
@@ -25,8 +44,11 @@
         </listitem>
       </itemizedlist>
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
     <para>
-  Example:
       <programlisting>
     $ repmgr -f /etc/repmgr.conf cluster event --event=standby_register
      Node ID | Name  | Event            | OK | Timestamp           | Details
@@ -34,4 +56,5 @@
      3       | node3 | standby_register | t  | 2017-08-17 10:28:55 | standby registration succeeded
      2       | node2 | standby_register | t  | 2017-08-17 10:28:53 | standby registration succeeded</programlisting>
     </para>
-</chapter>
+  </refsect1>
+</refentry>

doc/repmgr-cluster-matrix.sgml

@@ -1,17 +1,34 @@
-<chapter id="repmgr-cluster-matrix" xreflabel="repmgr cluster matrix">
+<refentry id="repmgr-cluster-matrix">
   <indexterm>
     <primary>repmgr cluster matrix</primary>
   </indexterm>
-  <title>repmgr cluster matrix</title>
+
+  <refmeta>
+    <refentrytitle>repmgr cluster matrix</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr cluster matrix</refname>
+    <refpurpose>
+      runs repmgr cluster show on each node and summarizes output
+    </refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
-    <command>repmgr cluster matrix</command> runs  <command>repmgr cluster show</command> on each
+      <command>repmgr cluster matrix</command> runs <command><link linkend="repmgr-cluster-show">repmgr cluster show</link></command> on each
       node and arranges the results in a matrix, recording success or failure.
     </para>
     <para>
       <command>repmgr cluster matrix</command> requires a valid <filename>repmgr.conf</filename>
-    file on each node.  Additionally passwordless <command>ssh</command> connections are required between
+      file on each node. Additionally, passwordless <command>ssh</command> connections are required between
       all nodes.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
     <para>
     Example 1 (all nodes up):
     <programlisting>
@@ -79,5 +96,6 @@
     In this case, the <xref linkend="repmgr-cluster-crosscheck"> command will produce a more
     useful result.
   </para>
-</chapter>
+  </refsect1>
+</refentry>
 

doc/repmgr-cluster-show.sgml

@@ -1,21 +1,46 @@
-<chapter id="repmgr-cluster-show" xreflabel="repmgr cluster show">
+<refentry id="repmgr-cluster-show">
   <indexterm>
     <primary>repmgr cluster show</primary>
   </indexterm>
-  <title>repmgr cluster show</title>
+
+  <refmeta>
+    <refentrytitle>repmgr cluster show</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr cluster show</refname>
+    <refpurpose>display information about each registered node in the replication cluster</refpurpose>
+  </refnamediv>
+
+
+  <refsect1>
+    <title>Description</title>
     <para>
-    Displays information about each active node in the replication cluster. This
+      Displays information about each registered node in the replication cluster. This
       command polls each registered server and shows its role (<literal>primary</literal> /
       <literal>standby</literal> / <literal>bdr</literal>) and status. It polls each server
       directly and can be run on any node in the cluster; this is also useful when analyzing
       connectivity from a particular node.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
     <para>
       This command requires either a valid <filename>repmgr.conf</filename> file or a database
       connection string to one of the registered nodes; no additional arguments are needed.
     </para>
+
+    <para>
+      To show database connection errors when polling nodes, run the command in
+      <literal>--verbose</literal> mode.
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
     <para>
-    Example:
     <programlisting>
     $ repmgr -f /etc/repmgr.conf cluster show
 
@@ -25,14 +50,11 @@
      2  | node2 | standby |   running | node1    | default  | host=db_node2 dbname=repmgr user=repmgr
      3  | node3 | standby |   running | node1    | default  | host=db_node3 dbname=repmgr user=repmgr</programlisting>
   </para>
-
+  </refsect1>
+  <refsect1>
+    <title>Notes</title>
     <para>
-    To show database connection errors when polling nodes, run the command in
+      The column <literal>Role</literal> shows the expected server role according to the
-    <literal>--verbose</literal> mode.
-  </para>
-
-  <para>
-    Note that the column <literal>Role</literal> shows the expected server role according to the
       &repmgr; metadata. <literal>Status</literal> shows whether the server is running or unreachable.
       If the node has an unexpected role not reflected in the &repmgr; metadata, e.g. a node was manually
       promoted to primary, this will be highlighted with an exclamation mark, e.g.:
@@ -49,7 +71,16 @@
       node "node1" (ID: 1) is registered as an active primary but is unreachable
       node "node2" (ID: 2) is registered as standby but running as primary</programlisting>
     </para>
+    <para>
+      Node availability is tested by connecting from the node where
+      <command>repmgr cluster show</command> is executed, and does not necessarily imply the node
+      is down. See <xref linkend="repmgr-cluster-matrix"> and <xref linkend="repmgr-cluster-crosscheck"> to get
+          a better overviews of connections between nodes.
+    </para>
+  </refsect1>
 
+  <refsect1>
+    <title>Options</title>
     <para>
       <command>repmgr cluster show</command> accepts an optional parameter <literal>--csv</literal>, which
       outputs the replication cluster's status in a simple CSV format, suitable for
@@ -80,11 +111,6 @@
         </listitem>
       </itemizedlist>
     </para>
+  </refsect1>
 
-  <para>
+</refentry>
-   Note that the availability is tested by connecting from the node where
-   <command>repmgr cluster show</command> is executed, and does not necessarily imply the node
-   is down. See <xref linkend="repmgr-cluster-matrix"> and <xref linkend="repmgr-cluster-crosscheck"> to get
-    a better overviews of connections between nodes.
-  </para>
-</chapter>

doc/repmgr-node-check.sgml

@@ -1,30 +1,46 @@
-<chapter id="repmgr-node-check" xreflabel="repmgr node check">
+<refentry id="repmgr-node-check">
   <indexterm>
     <primary>repmgr node check</primary>
   </indexterm>
-  <title>repmgr node check</title>
+
+  <refmeta>
+    <refentrytitle>repmgr node check</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr node check</refname>
+    <refpurpose>performs some health checks on a node from a replication perspective</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       Performs some health checks on a node from a replication perspective.
       This command must be run on the local node.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
     <para>
-   Sample output (execute <command>repmgr node check</command>):
       <programlisting>
+       $ repmgr -f /etc/repmgr.conf node check
        Node "node1":
             Server role: OK (node is primary)
             Replication lag: OK (N/A - node is primary)
             WAL archiving: OK (0 pending files)
             Downstream servers: OK (2 of 2 downstream nodes attached)
-            Replication slots: OK (node has no replication slots)
+            Replication slots: OK (node has no replication slots)</programlisting>
-   </programlisting>
     </para>
+  </refsect1>
+  <refsect1>
+    <title>Individual checks</title>
     <para>
-   Additionally each check can be performed individually by supplying
+      Each check can be performed individually by supplying
       an additional command line parameter, e.g.:
       <programlisting>
         $ repmgr node check --role
-     OK (node is primary)
+        OK (node is primary)</programlisting>
-   </programlisting>
     </para>
     <para>
    Parameters for individual checks are as follows:
@@ -67,4 +83,5 @@
    Individual checks can also be output in a Nagios-compatible format by additionally
    providing the option <literal>--nagios</literal>.
   </para>
-</chapter>
+  </refsect1>
+</refentry>

doc/repmgr-node-rejoin.sgml

@@ -1,19 +1,27 @@
-<chapter id="repmgr-node-rejoin" xreflabel="repmgr node rejoin">
+<refentry id="repmgr-node-rejoin">
 
   <indexterm>
     <primary>repmgr node rejoin</primary>
   </indexterm>
 
-  <title>repmgr node rejoin</title>
+  <refmeta>
+    <refentrytitle>repmgr node rejoin</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr node rejoin</refname>
+    <refpurpose>rejoin a dormant (stopped) node to the replication cluster</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       Enables a dormant (stopped) node to be rejoined to the replication cluster.
     </para>
-  <note>
+    <para>
-   <simpara>
+      This can optionally use <application>pg_rewind</application> to re-integrate
-     Currently <command>repmgr node rejoin</command> can only be used to attach
+      a node which has diverged from the rest of the cluster, typically a failed primary.
-     a standby to the current primary, not another standby.
+    </para>
-   </simpara>
-  </note>
 
     <tip>
       <para>
@@ -21,10 +29,27 @@
         <xref linkend="repmgr-standby-follow">.
       </para>
     </tip>
+  </refsect1>
+
+
+  <refsect1>
+    <title>Usage</title>
 
     <para>
-    This can optionally use <application>pg_rewind</application> to re-integrate a node which has diverged
+      <programlisting>
-    from the rest of the cluster, typically a failed primary.
+      repmgr node rejoin -d '$conninfo'</programlisting>
+
+      where <literal>$conninfo</literal> is the conninfo string of any reachable node in the cluster.
+      <filename>repmgr.conf</filename> for the stopped node *must* be supplied explicitly if not
+      otherwise available.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+    <para>
+      Currently <command>repmgr node rejoin</command> can only be used to attach
+      a standby to the current primary, not another standby.
     </para>
     <para>
       The node must have been shut down cleanly; if this was not the case, it will
@@ -42,17 +67,9 @@
           postgres --single -D /var/lib/pgsql/data/ &lt; /dev/null</programlisting>
       </para>
     </tip>
-  <para>
+  </refsect1>
-    Usage:
-    <programlisting>
-      repmgr node rejoin -d '$conninfo'</programlisting>
 
-    where <literal>$conninfo</literal> is the conninfo string of any reachable node in the cluster.
+  <refsect1 id="repmgr-node-rejoin-pg-rewind">
-    <filename>repmgr.conf</filename> for the stopped node *must* be supplied explicitly if not
-    otherwise available.
-  </para>
-
-  <sect1 id="repmgr-node-rejoin-pg-rewind">
     <title>Using <command>pg_rewind</command></title>
     <para>
       <command>repmgr node rejoin</command> can optionally use <command>pg_rewind</command> to re-integrate a
@@ -118,5 +135,14 @@
     NOTICE: NODE REJOIN successful
     DETAIL: node 1 is now attached to node 2</programlisting>
     </para>
-  </sect1>
+
-</chapter>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+     <xref linkend="repmgr-standby-follow">
+    </para>
+  </refsect1>
+</refentry>

doc/repmgr-node-status.sgml

@@ -1,16 +1,30 @@
-
+<refentry id="repmgr-node-status">
-<chapter id="repmgr-node-status" xreflabel="repmgr node status">
   <indexterm>
     <primary>repmgr node status</primary>
   </indexterm>
-  <title>repmgr node status</title>
+
+  <refmeta>
+    <refentrytitle>repmgr node status</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr node status</refname>
+    <refpurpose>show overview of a node's basic information and replication status</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       Displays an overview of a node's basic information and replication
       status. This command must be run on the local node.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
     <para>
-   Sample output (execute <command>repmgr node status</command>):
     <programlisting>
+        $ repmgr -f /etc/repmgr.comf node status
         Node "node1":
             PostgreSQL version: 10beta1
             Total data size: 30 MB
@@ -20,10 +34,14 @@
             Archive command: (none)
             Replication connections: 2 (of maximal 10)
             Replication slots: 0 (of maximal 10)
-            Replication lag: n/a
+            Replication lag: n/a</programlisting>
-   </programlisting>
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
     <para>
       See <xref linkend="repmgr-node-check"> to diagnose issues.
     </para>
-</chapter>
+  </refsect1>
+</refentry>

doc/repmgr-primary-register.sgml

@@ -1,12 +1,30 @@
-<chapter id="repmgr-primary-register" xreflabel="repmgr primary register">
+<refentry id="repmgr-primary-register">
-  <indexterm><primary>repmgr primary register</primary></indexterm>
+  <indexterm>
-  <title>repmgr primary register</title>
+    <primary>repmgr primary register</primary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr primary register</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr primary register</refname>
+    <refpurpose>initialise a repmgr installation and register the primary node</refpurpose>
+  </refnamediv>
+
+
+  <refsect1>
+    <title>Description</title>
     <para>
       <command>repmgr primary register</command> registers a primary node in a
       streaming replication cluster, and configures it for use with repmgr, including
       installing the &repmgr; extension. This command needs to be executed before any
       standby nodes are registered.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
     <para>
       Execute with the <literal>--dry-run</literal> option to check what would happen without
       actually registering the primary.
@@ -28,5 +46,6 @@
         <filename>/path/to/repmgr.conf</filename>).
     </para>
     </note>
+  </refsect1>
 
-</chapter>
+</refentry>

doc/repmgr-primary-unregister.sgml

@@ -1,11 +1,26 @@
-<chapter id="repmgr-primary-unregister" xreflabel="repmgr primary unregister">
+<refentry id="repmgr-primary-unregister">
-  <indexterm><primary>repmgr primary unregister</primary></indexterm>
+  <indexterm>
-  <title>repmgr primary unregister</title>
+    <primary>repmgr primary unregister</primary>
+  </indexterm>
+  <refmeta>
+    <refentrytitle>repmgr primary unregister</refentrytitle>
+  </refmeta>
+  <refnamediv>
+    <refname>repmgr primary unregister</refname>
+    <refpurpose>unregister an inactive primary node</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       <command>repmgr primary register</command> unregisters an inactive primary node
       from the &repmgr; metadata. This is typically when the primary has failed and is
       being removed from the cluster after a new primary has been promoted.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
     <para>
       Execute with the <literal>--dry-run</literal> option to check what would happen without
       actually unregistering the node.
@@ -15,4 +30,5 @@
       <command>repmgr master unregister</command> can be used as an alias for
       <command>repmgr primary unregister</command>/
     </para>
-</chapter>
+  </refsect1>
+</refentry>

doc/repmgr-standby-clone.sgml

@@ -1,9 +1,20 @@
-<chapter id="repmgr-standby-clone" xreflabel="repmgr standby clone">
+<refentry id="repmgr-standby-clone">
   <indexterm>
     <primary>repmgr standby clone</primary>
     <seealso>cloning</seealso>
   </indexterm>
-  <title>repmgr standby clone</title>
+
+  <refmeta>
+    <refentrytitle>repmgr standby clone</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr standby clone</refname>
+    <refpurpose>clone a PostgreSQL standby node from another PostgreSQL node</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       <command>repmgr standby clone</command> clones a PostgreSQL node from another
       PostgreSQL node, typically the primary, but optionally from any other node in
@@ -17,9 +28,10 @@
         <command>repmgr standby register</command> must be executed to notify &repmgr; of its presence.
       </simpara>
     </note>
+  </refsect1>
 
 
-  <sect1 id="repmgr-standby-clone-config-file-copying" xreflabel="Copying configuration files">
+  <refsect1 id="repmgr-standby-clone-config-file-copying" xreflabel="Copying configuration files">
    <title>Handling configuration files</title>
 
    <para>
@@ -51,9 +63,9 @@
      configuration management tool such as Ansible, Chef, Puppet or Salt.
     </simpara>
    </tip>
-  </sect1>
+  </refsect1>
 
-  <sect1 id="repmgr-standby-clone-wal-management" xreflabel="Managing WAL during the cloning process">
+  <refsect1 id="repmgr-standby-clone-wal-management" xreflabel="Managing WAL during the cloning process">
    <title>Managing WAL during the cloning process</title>
    <para>
     When initially cloning a standby, you will need to ensure
@@ -86,6 +98,6 @@
       <literal>--wal-method</literal>.
     </simpara>
    </note>
-  </sect1>
+  </refsect1>
-</chapter>
+</refentry>
 

doc/repmgr-standby-follow.sgml

@@ -1,8 +1,20 @@
-<chapter id="repmgr-standby-follow" xreflabel="repmgr standby follow">
+<refentry id="repmgr-standby-follow">
   <indexterm>
     <primary>repmgr standby follow</primary>
   </indexterm>
-  <title>repmgr standby follow</title>
+
+  <refmeta>
+    <refentrytitle>repmgr standby follow</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr standby follow</refname>
+    <refpurpose>attach a standby to a new primary</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
     <para>
       Attaches the standby to a new primary. This command requires a valid
       <filename>repmgr.conf</filename> file for the standby, either specified
@@ -18,8 +30,11 @@
       To re-add an inactive node to the replication cluster, see
       <xref linkend="repmgr-node-rejoin">
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
     <para>
-    Example execution:
       <programlisting>
       $ repmgr -f /etc/repmgr.conf standby follow
       INFO: setting node 3's primary to node 2
@@ -31,5 +46,13 @@
       NOTICE: STANDBY FOLLOW successful
       DETAIL: node 3 is now attached to node 2</programlisting>
     </para>
-</chapter>
+  </refsect1>
+
+ <refsect1>
+    <title>See also</title>
+    <para>
+     <xref linkend="repmgr-node-rejoin">
+    </para>
+  </refsect1>
+</refentry>
 

doc/repmgr-standby-promote.sgml

@@ -1,8 +1,19 @@
-<chapter id="repmgr-standby-promote" xreflabel="repmgr standby promote">
+<refentry id="repmgr-standby-promote">
   <indexterm>
     <primary>repmgr standby promote</primary>
   </indexterm>
-  <title>repmgr standby promote</title>
+
+  <refmeta>
+    <refentrytitle>repmgr standby promote</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr standby promote</refname>
+    <refpurpose>promote a standby to a primary</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       Promotes a standby to a primary if the current primary has failed. This
       command requires a valid <filename>repmgr.conf</filename> file for the standby, either
@@ -15,8 +26,11 @@
       by using <xref linkend="repmgr-standby-follow">; if <application>repmgrd</application>
         is active, it will handle this automatically.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
     <para>
-    Example execution:
       <programlisting>
       $ repmgr -f /etc/repmgr.conf standby promote
       NOTICE: promoting standby to primary
@@ -24,7 +38,7 @@
       server promoting
       DEBUG: setting node 2 as primary and marking existing primary as failed
       NOTICE: STANDBY PROMOTE successful
-      DETAIL: server "node2" (ID: 2) was successfully promoted to primary
+      DETAIL: server "node2" (ID: 2) was successfully promoted to primary</programlisting>
-    </programlisting>
     </para>
-</chapter>
+  </refsect1>
+</refentry>

doc/repmgr-standby-register.sgml

@@ -1,6 +1,19 @@
-<chapter id="repmgr-standby-register" xreflabel="repmgr standby register">
+<refentry id="repmgr-standby-register" xreflabel="repmgr standby register">
-  <indexterm><primary>repmgr standby register</primary></indexterm>
+  <indexterm>
-  <title>repmgr standby register</title>
+    <primary>repmgr standby register</primary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr standby register</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr standby register</refname>
+    <refpurpose>add a standby's information to the &repmgr; metadata</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
       <command>repmgr standby register</command> adds a standby's information to
       the &repmgr; metadata. This command needs to be executed to enable
@@ -22,8 +35,9 @@
           <filename>/path/to/repmgr.conf</filename>).
       </para>
     </note>
+  </refsect1>
 
-  <sect1 id="repmgr-standby-register-wait" xreflabel="repmgr standby register --wait">
+  <refsect1 id="repmgr-standby-register-wait" xreflabel="repmgr standby register --wait">
    <title>Waiting for the registration to propagate to the standby</title>
    <para>
      Depending on your environment and workload, it may take some time for
@@ -37,9 +51,9 @@
     until the record is synchronised before exiting. An optional timeout (in
     seconds) can be added to this option (e.g. <literal>--wait-sync=60</literal>).
    </para>
-  </sect1>
+  </refsect1>
 
-  <sect1 id="repmgr-standby-register-inactive-node" xreflabel="Registering an inactive node">
+  <refsect1 id="repmgr-standby-register-inactive-node" xreflabel="Registering an inactive node">
    <title>Registering an inactive node</title>
    <para>
     Under some circumstances you may wish to register a standby which is not
@@ -59,5 +73,5 @@
     When used with <command>repmgr standby register</command>, care should be taken that use of the
     <literal>-F/--force</literal> option does not result in an incorrectly configured cluster.
    </para>
-  </sect1>
+  </refsect1>
-</chapter>
+</refentry>

doc/repmgr-standby-switchover.sgml

@@ -1,8 +1,20 @@
-<chapter id="repmgr-standby-switchover" xreflabel="repmgr standby switchover">
+<refentry id="repmgr-standby-switchover">
   <indexterm>
     <primary>repmgr standby switchover</primary>
   </indexterm>
-  <title>repmgr standby switchover</title>
+
+  <refmeta>
+    <refentrytitle>repmgr standby switchover</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr standby switchover</refname>
+    <refpurpose>promote a standby to primary and demote the existing primary to a standby</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
     <para>
       Promotes a standby to primary and demotes the existing primary to a standby.
       This command must be run on the standby to be promoted, and requires a
@@ -13,6 +25,11 @@
     these to follow the new primary if the option <literal>--siblings-follow</literal>
       is specified.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
+
     <para>
       Execute with the <literal>--dry-run</literal> option to test the switchover as far as
       possible without actually changing the status of either node.
@@ -21,7 +38,13 @@
       <application>repmgrd</application> should not be active on any nodes while a switchover is being
       executed. This restriction may be lifted in a later version.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
     <para>
       For more details see the section <xref linkend="performing-switchover">.
     </para>
-</chapter>
+  </refsect1>
+
+</refentry>

doc/repmgr-standby-unregister.sgml

@@ -1,10 +1,27 @@
-<chapter id="repmgr-standby-unregister" xreflabel="repmgr standby unregister">
+<refentry id="repmgr-standby-unregister">
-  <indexterm><primary>repmgr standby unregister</primary></indexterm>
+  <indexterm>
-  <title>repmgr standby unregister</title>
+    <primary>repmgr standby unregister</primary>
+  </indexterm>
+
+  <refmeta>
+    <refentrytitle>repmgr standby unregister</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>repmgr standby unregister</refname>
+    <refpurpose>remove a standby's information from the &repmgr; metadata</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
     <para>
-    Unregisters a standby with `repmgr`. This command does not affect the actual
+      Unregisters a standby with &repmgr;. This command does not affect the actual
       replication, just removes the standby's entry from the &repmgr; metadata.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Execution</title>
     <para>
       To unregister a running standby, execute:
       <programlisting>
@@ -22,8 +39,8 @@
       command on the primary server will unregister the standby with
       id <literal>3</literal>:
       <programlisting>
-    repmgr standby unregister -f /etc/repmgr.conf --node-id=3
+        repmgr standby unregister -f /etc/repmgr.conf --node-id=3</programlisting>
-   </programlisting>
     </para>
-</chapter>
+  </refsect1>
+</refentry>