From b0c664089cf497262d1918bf71c9d35ccd9c3815 Mon Sep 17 00:00:00 2001
From: Victor Wheeler <vaw_info998@comcast.net>
Date: Mon, 11 Nov 2024 05:02:57 -0700
Subject: [PATCH] Resolves #13119:  Add solution to referencing glossary terms
 with alternate word forms.

---
 doc/usage/referencing.rst                 |  7 ++++
 doc/usage/restructuredtext/directives.rst | 41 -----------------------
 2 files changed, 7 insertions(+), 41 deletions(-)

diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst
index c13757e5c83..ec4c74013b0 100644
--- a/doc/usage/referencing.rst
+++ b/doc/usage/referencing.rst
@@ -254,6 +254,13 @@ The following role creates a cross-reference to a term in a
    If you use a term that's not explained in a glossary, you'll get a warning
    during build.
 
+   If you need to link to a glossary term using an alternate form of the word (e.g.
+   the glossary term is *"source directory"* and you want to link to it in a
+   paragraph using the word *"root directory"*), you can do so using the same syntax
+   as the `:ref:` role uses::
+
+      :term:`root directory <source directory>`
+
 
 .. _any-role:
 
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index 7436ea4cd09..441f225b877 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/doc/usage/restructuredtext/directives.rst
@@ -1156,47 +1156,6 @@ Glossary
    text only have "term" part. In this case, translated "localized term" will be
    categorized in "key" group.
 
-   **Referencing Glossary Terms with Other Terms:**
-
-   If you need to link to a glossary term using an alternate form of the word (e.g.
-   the gloosary term is *"source directory"* and you want to link to it in a
-   paragraph using the word *"root directory"*), you can do so by adding an "explicit
-   link target" to the glossary term using the same syntax as is used to add an
-   "explicit link target" to items in a list::
-
-      .. glossary::
-
-         environment
-            A structure where information about all documents under the root is
-            saved, and used for cross-referencing.  The environment is pickled
-            after the parsing stage, so that successive runs only need to read
-            and parse new and changed documents.
-
-            .. _source directory:
-            .. _root directory:
-
-         source directory
-            The directory which, including its subdirectories, contains all
-            source files for one Sphinx project.
-
-   .. note::
-
-      The explicit link target must be indented even with the definition above it.
-
-   That term can now be linked to like this::
-
-      All source files for this project is required to be under the
-      :ref:`root directory <source directory>` of the project.
-
-   or::
-
-      All source files for this project is required to be under the
-      :ref:`root directory` of the project.
-
-   .. note::
-
-      This does not work at this time for the first glossary entry since the glossary
-      parser tries to interpret the "explicit link target" as a glossary entry.
 
    .. versionchanged:: 1.1
       Now supports multiple terms and inline markup in terms.