doc/start: refine "Quirks of RST"

Refine the language that was added yesterday, language that explains how
certain aspects of RST work.

Signed-off-by: Zac Dover <zac.dover@gmail.com>
(cherry picked from commit cdc7b6035414ea46b1e583d21a3a821f041c5417)

diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst
index 83df00ab0f102b2a404385c298f45b3a3d6a2182..d0f818efcad1b1d8c71c0f2680b3f3bb69b63b7b 100644 (file)
--- a/doc/start/documenting-ceph.rst
+++ b/doc/start/documenting-ceph.rst
@@ -673,6 +673,8 @@ the ``.rst`` source files will work even if the source files are moved within
 the ``ceph/doc`` directory. See `Cross referencing arbitrary locations`_ for
 details.
 
+.. _start_external_hyperlink_example:
+
 External Hyperlink Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -685,12 +687,14 @@ For example, RST that links to the Sphinx Python Document Generator homepage
 and generates a sentence reading "Click here to learn more about Python
 Sphinx." looks like this: 
 
-* ``Click `here <https://www.sphinx-doc.org>`_ to learn more about Python
-  Sphinx.`` 
+::
+
+    ``Click `here <https://www.sphinx-doc.org>`_ to learn more about Python
+    Sphinx.`` 
 
 And here it is, rendered:
 
-* Click `here <https://www.sphinx-doc.org>`_ to learn more about Python Sphinx. 
+Click `here <https://www.sphinx-doc.org>`_ to learn more about Python Sphinx. 
 
 Pay special attention to the underscore after the backtick. If you forget to
 include it and this is your first day working with RST, there's a chance that
@@ -730,20 +734,22 @@ This is the formula for links to addresses external to the Ceph documentation:
    
    Do not fail to include the underscore after the final backtick.
 
-   The convention for linking to addresses external to the Ceph documentation
-   and defining inline text is a convention that includes a space between the
-   inline text and the less-than sign that precedes the external address. This
-   is precisely the opposite of :ref:`the convention for inline text that links
-   to a location inside the Ceph
-   documentation<internal_link_with_inline_text>`. 
+   To link to addresses that are external to the Ceph documentation, you have
+   to include a space between the inline text and the angle bracket that
+   precedes the external address. This is precisely the opposite of :ref:`the
+   convention for inline text that links to a location inside the Ceph
+   documentation<internal_link_with_inline_text>`. If this seems inconsistent
+   and confusing to you, then you're right. It is inconsistent and confusing.
 
+See also ":ref:`External Hyperlink Example<start_external_hyperlink_example>`".
 
 Internal Links
 ~~~~~~~~~~~~~~
 
-To link to a section in the Ceph documentation, you must define a target link
-before the section and then link to that target from another location in the
-documentation. Here are the formulas for targets and links to those targets:
+To link to a section that is in the Ceph documentation, you must (1) define a
+target link before the section and then (2) link to that target from another
+location in the documentation. Here are the formulas for targets and links to
+those targets:
 
 Target::
 
@@ -766,10 +772,11 @@ Link to target with inline text::
 
 .. note:: 
 
-   There is no space between "inline text" and the less-than sign that
+   There is no space between "inline text" and the angle bracket that
    immediately follows it. This is precisely the opposite of :ref:`the
    convention for inline text that links to a location outside of the Ceph
-   documentation<external_link_with_inline_text>`. 
+   documentation<external_link_with_inline_text>`. If this seems inconsistent
+   and confusing to you, then you're right. It is inconsistent and confusing.
 
 
 .. _Python Sphinx: https://www.sphinx-doc.org