From: Zac Dover <zac.dover@proton.me>
Date: Mon, 31 Jul 2023 09:27:29 +0000 (+1000)
Subject: doc/start: update linking conventions
X-Git-Tag: v17.2.7~219^2
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=00bd6a5e3ace898bfbb3ceb23e5830e19dbf3f1b;p=ceph.git

doc/start: update linking conventions

Update the "External Links" section of doc/start/documenting-ceph.rst.

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

diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst
index f86bad7bf6a5e..3e08846752521 100644
--- a/doc/start/documenting-ceph.rst
+++ b/doc/start/documenting-ceph.rst
@@ -981,7 +981,8 @@ External Links
 
 .. _external_link_with_inline_text:
 
-This is the formula for links to addresses external to the Ceph documentation:
+Use the formula immediately below to render links that direct the reader to
+addresses external to the Ceph documentation:
 
 ::
 
@@ -994,10 +995,13 @@ This is the formula for links to addresses external to the Ceph documentation:
 
    To link to addresses that are external to the Ceph documentation, 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.
+   external address. This is precisely the opposite of the convention for
+   inline text that links to a location inside the Ceph documentation. See
+   :ref:`here <internal_link_with_inline_text>` for an exemplar of this
+   convention.
+
+   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>`".