update ceph source to reef 18.2.1

[ceph.git] / ceph / doc / start / documenting-ceph.rst

diff --git a/ceph/doc/start/documenting-ceph.rst b/ceph/doc/start/documenting-ceph.rst
index f9b13452dc70ae2909d8e7ef7a3477b21a8c0410..02d4dccc44afa3ce8ae57f3d187ed27fbfbe50ea 100644 (file)
--- a/ceph/doc/start/documenting-ceph.rst
+++ b/ceph/doc/start/documenting-ceph.rst
@@ -973,6 +973,15 @@ convention was preferred because it made the documents more readable in a
 command line interface. As of 2023, though, we have no preference for one over
 the other. Use whichever convention makes the text easier to read.
 
+Using a part of a sentence as a hyperlink, `like this <docs.ceph.com>`_, is
+discouraged. The convention of writing "See X" is preferred. Here are some
+preferred formulations:
+
+#. For more information, see `docs.ceph.com <docs.ceph.com>`_.
+
+#. See `docs.ceph.com <docs.ceph.com>`_.
+
+
 Quirks of ReStructured Text
 ---------------------------
 
@@ -981,7 +990,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 +1004,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>`".