doc/rados: explain replaceable parts of command

Add an explanation that directs the reader to replace the "X" part of
the command "ceph tell mon.X mon_status" with the value specific to the
reader's Ceph cluster (which is (probably) not "X").

In the future, such replaceable strings in commands may be bounded by
angle brackets ("<" and ">").

This improvement to the documentation was suggested on the [ceph-users]
email list by Joel Davidow. This email, an absolute model of user
engagement with an upstream project, can be reviewed here:
https://lists.ceph.io/hyperkitty/list/ceph-users@ceph.io/message/KF67F5TXFSSTPXV7EKL6JKLA5KZQDLDQ/

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit d071ad2575c86f300a9ba39df3c4949e5dc9c47d)

diff --git a/doc/rados/troubleshooting/troubleshooting-mon.rst b/doc/rados/troubleshooting/troubleshooting-mon.rst
index b53311fc419ae379ab1e0f7ac2f0e44fc9b4dffa..7a4976ed17897374be2f0d68003cf2cd3424e022 100644 (file)
--- a/doc/rados/troubleshooting/troubleshooting-mon.rst
+++ b/doc/rados/troubleshooting/troubleshooting-mon.rst
@@ -133,10 +133,14 @@ Understanding mon_status
 
 The status of a Monitor (as reported by the ``ceph tell mon.X mon_status``
 command) can be obtained via the admin socket. The ``ceph tell mon.X
-mon_status``  command outputs a great deal of information about the monitor
+mon_status`` command outputs a great deal of information about the monitor
 (including the information found in the output of the ``quorum_status``
 command).
 
+.. note:: The command ``ceph tell mon.X mon_status`` is not meant to be input
+   literally. The ``X`` portion of ``mon.X`` is meant to be replaced with a
+   value specific to your own Ceph cluster when you run the command.
+
 To understand this command's output, let us consider the following example, in
 which we see the output of ``ceph tell mon.c mon_status``::
 
@@ -165,24 +169,24 @@ which we see the output of ``ceph tell mon.c mon_status``::
                 "name": "c",
                 "addr": "127.0.0.1:6795\/0"}]}}
 
-This output reports that there are three monitors in the monmap (*a*, *b*, and
-*c*), that quorum is formed by only two monitors, and that *c* is in quorum as
-a *peon*.
+This output reports that there are three monitors in the monmap (``a``, ``b``,
+and ``c``), that quorum is formed by only two monitors, and that ``c`` is in
+quorum as a ``peon``.
 
 **Which monitor is out of quorum?**
 
-  The answer is **a** (that is, ``mon.a``). ``mon.a`` is out of quorum.
+  The answer is ``a`` (that is, ``mon.a``). ``mon.a`` is out of quorum.
 
 **How do we know, in this example, that mon.a is out of quorum?**
 
-  We know that ``mon.a`` is out of quorum because it has rank 0, and Monitors
-  with rank 0 are by definition out of quorum.
+  We know that ``mon.a`` is out of quorum because it has rank ``0``, and
+  Monitors with rank ``0`` are by definition out of quorum.
 
   If we examine the ``quorum`` set, we can see that there are clearly two
-  monitors in the set: *1* and *2*. But these are not monitor names. They are
-  monitor ranks, as established in the current ``monmap``. The ``quorum`` set
-  does not include the monitor that has rank 0, and according to the ``monmap``
-  that monitor is ``mon.a``.
+  monitors in the set: ``1`` and ``2``. But these are not monitor names. They
+  are monitor ranks, as established in the current ``monmap``. The ``quorum``
+  set does not include the monitor that has rank ``0``, and according to the
+  ``monmap`` that monitor is ``mon.a``.
 
 **How are monitor ranks determined?**
 
@@ -192,7 +196,7 @@ a *peon*.
   case, because ``127.0.0.1:6789`` (``mon.a``) is numerically less than the
   other two ``IP:PORT`` combinations (which are ``127.0.0.1:6790`` for "Monitor
   b" and ``127.0.0.1:6795`` for "Monitor c"), ``mon.a`` has the highest rank:
-  namely, rank 0.
+  namely, rank ``0``.
   
 
 Most Common Monitor Issues