From 02cc1dfbc3594719f60a640d813717edba63ea50 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Wed, 4 Jun 2025 23:30:36 +0200
Subject: [PATCH 1/2] DOC: Use two underscores for links with embedded URLs

Closes #13613.
---
 doc/usage/restructuredtext/basics.rst | 29 +++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 5d60ea81de4..0028c2331c0 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -208,11 +208,32 @@ Hyperlinks
 External links
 ~~~~~~~~~~~~~~
 
-Use ```Link text <https://domain.invalid/>`_`` for inline web links.  If the
-link text should be the web address, you don't need special markup at all, the
-parser finds links and mail addresses in ordinary text.
+URLs and email addresses in text are automatically linked an do not need
+explicit markup at all.
 
-.. important:: There must be a space between the link text and the opening \< for the URL.
+To create text with a link, it's advisable to put the URL below the paragraph
+like this (:duref:`ref <hyperlink-targets>`)::
+
+   This is a paragraph that contains `a link`_.
+
+   .. _a link: https://domain.invalid/
+
+This keeps the paragraph more readable in source code.
+
+Alternatively, you can embed the URL using the syntax
+```Link text <https://domain.invalid/>`__``
+(:duref:`ref <embedded-uris-and-aliases>`).
+
+.. important::
+
+   There must be a space between the link text and the opening \< for the URL.
+
+   Use two trailing underscores when embedding the URL. - Technically, a
+   single underscore works as well, but that would create a named reference
+   instead of an anonymous one. Named references typically do not have a
+   benefit when the URL is embedded. However, they have the disadvantage that
+   you must make sure that you do not use "Link text" in another link in your
+   document.
 
 You can also separate the link and the target definition (:duref:`ref
 <hyperlink-targets>`), like this::

From 69d2ecb8c60add9d48606c94fef56e3513bbe2c3 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 7 Jun 2025 17:03:02 +0100
Subject: [PATCH 2/2] wordsmithing

---
 doc/usage/restructuredtext/basics.rst | 31 ++++++++++++++++-----------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 0028c2331c0..ea61b80fc85 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -208,11 +208,13 @@ Hyperlinks
 External links
 ~~~~~~~~~~~~~~
 
-URLs and email addresses in text are automatically linked an do not need
+URLs and email addresses in text are automatically linked and do not need
 explicit markup at all.
+For example, https://domain.invalid/ is written with no special markup
+in the source of this document, and is recognised as an external hyperlink.
 
-To create text with a link, it's advisable to put the URL below the paragraph
-like this (:duref:`ref <hyperlink-targets>`)::
+To create text with a link, the best approach is generally to put the URL
+below the paragraph as follows (:duref:`ref <hyperlink-targets>`)::
 
    This is a paragraph that contains `a link`_.
 
@@ -220,20 +222,25 @@ like this (:duref:`ref <hyperlink-targets>`)::
 
 This keeps the paragraph more readable in source code.
 
-Alternatively, you can embed the URL using the syntax
-```Link text <https://domain.invalid/>`__``
+Alternatively, you can embed the URL within the prose for an 'inline link'.
+This can lead to longer lines, but has the benefit of keeping the link text
+and the URL pointed to in the same place.
+This uses the following syntax: ```Link text <https://domain.invalid/>`__``
 (:duref:`ref <embedded-uris-and-aliases>`).
 
 .. important::
 
-   There must be a space between the link text and the opening \< for the URL.
+   There must be a space between the link text
+   and the opening angle bracket ('``<``') for the URL.
 
-   Use two trailing underscores when embedding the URL. - Technically, a
-   single underscore works as well, but that would create a named reference
-   instead of an anonymous one. Named references typically do not have a
-   benefit when the URL is embedded. However, they have the disadvantage that
-   you must make sure that you do not use "Link text" in another link in your
-   document.
+.. tip::
+
+   Use two trailing underscores when embedding the URL.
+   Technically, a single underscore works as well,
+   but that would create a named reference instead of an anonymous one.
+   Named references typically do not have a benefit when the URL is embedded.
+   Moreover, they have the disadvantage that you must make sure that you
+   do not use the same "Link text" for another link in your document.
 
 You can also separate the link and the target definition (:duref:`ref
 <hyperlink-targets>`), like this::