From 884246eb50a633eaaa214ddced8a8e32944f8769 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 10 Nov 2024 09:00:04 -0700 Subject: [PATCH] Resolves #13119: Add solution to referencing glossary terms with alternate word forms. --- doc/usage/restructuredtext/directives.rst | 41 +++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 441f225b877..7436ea4cd09 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -1156,6 +1156,47 @@ 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 ` 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.