From 884246eb50a633eaaa214ddced8a8e32944f8769 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 10 Nov 2024 09:00:04 -0700 Subject: [PATCH 1/8] 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. From b0c664089cf497262d1918bf71c9d35ccd9c3815 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Mon, 11 Nov 2024 05:02:57 -0700 Subject: [PATCH 2/8] 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 ` + .. _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 ` 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. From 3273a74f6dadfd2839a7f57618c71db64c7032e0 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Mon, 11 Nov 2024 05:07:34 -0700 Subject: [PATCH 3/8] fix: syntax correction --- doc/usage/referencing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index ec4c74013b0..d35a6067976 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -257,7 +257,7 @@ The following role creates a cross-reference to a term in a 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:: + as the ``:ref:`` role uses:: :term:`root directory ` From eb06e5d94338e6cab3bfd3d9a80f1477b7f7b57c Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Mon, 11 Nov 2024 05:17:15 -0700 Subject: [PATCH 4/8] fix: consistency with rest of document --- doc/usage/referencing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index d35a6067976..8b922222896 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -255,8 +255,8 @@ The following role creates a cross-reference to a term in a 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 + the glossary term is "source directory" and you want to link to it in a + paragraph using the term "root directory"), you can do so using the same syntax as the ``:ref:`` role uses:: :term:`root directory ` From 4ec2d56132ebe1b46a56260c7d5755053d760f77 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Mon, 11 Nov 2024 08:04:53 -0700 Subject: [PATCH 5/8] fix: refer to already-existing documentation. --- doc/usage/referencing.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 8b922222896..5104548ef1e 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -256,10 +256,8 @@ The following role creates a cross-reference to a term in a 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 term "root directory"), you can do so using the same syntax - as the ``:ref:`` role uses:: - - :term:`root directory ` + paragraph using the term "root directory"), you can do so using + :ref:`custom link text `. .. _any-role: From f74c557daa85b5872fd08b75b9827490f49e42d3 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Mon, 11 Nov 2024 08:48:28 -0700 Subject: [PATCH 6/8] feat: clarify meaning --- doc/usage/referencing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 5104548ef1e..669e7b0ec0a 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -257,7 +257,7 @@ The following role creates a cross-reference to a term in a 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 term "root directory"), you can do so using - :ref:`custom link text `. + :ref:`custom link text ` inside the back-quotes. .. _any-role: From e2ec29a9e53d3f6e98f762dd44a6d24879880d74 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Mon, 11 Nov 2024 10:13:46 -0700 Subject: [PATCH 7/8] fix: simplify and clarify --- doc/usage/referencing.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 669e7b0ec0a..baa74393b45 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -254,10 +254,8 @@ 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 term "root directory"), you can do so using - :ref:`custom link text ` inside the back-quotes. + This role also supports :ref:`Custom link text ` from the general + cross-reference syntax. .. _any-role: From ace8b12fac122d322d8ba9a5a5a10589bc532f44 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Mon, 11 Nov 2024 14:19:07 -0700 Subject: [PATCH 8/8] fix: correct capitalization --- doc/usage/referencing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index baa74393b45..2597c9ce597 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -254,7 +254,7 @@ 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. - This role also supports :ref:`Custom link text ` from the general + This role also supports :ref:`custom link text ` from the general cross-reference syntax.