Need documentation on how to reference Glossary entries using alternate terms

[vwheeler63]

Is your feature request related to a problem? Please describe.

I was originally going to ask for a feature: to add glossary-entry anchors into the namespace used by the :ref: directive so that glossary entries could be linked to in documentation that uses different terms (e.g. different forms of the same word). In the process of describing it and doing tests, I THOUGHT I discovered a solution that would work for me, but as it turns out, it doesn't work as intended. I will leave the below in place since it describes the use case very well, but am revising this as a feature request:

That since a term in a glossary creates the HTML anchor <a id="term-actual_term">, that this identifier be additionally placed in the same namespace that is used by the :ref: role so that when a term needs to be linked to from another form of the same word (e.g. "understandability" vs "understandable", calling from my example below) that a :ref: role can be used to link to it like this:

:ref:`understandable <term-understandability>`

An alternate, but also workable, solution would be to make the "explicit link targets" within a glossary list (as illustrated below) actually add the anchor <a id="link_label"> into the HTML output as it normally does for "explicit link targets". It is currently not doing that when the "explicit link target" is in a glossary list.

Kind regards, Vic

---

Here is my real situation and it is a valid and frequently-encountered use case for many large technical documents I maintain — all of which have glossaries. Taking an example from one of these documents (about my company's Coding Standards), I have an existing glossary-like set-up using the standard facilities of the :ref: role. Here is the entry I will use for illustration:

.. _understandability:

understandability
    Understandability is the ease with which the reader can fully understanding what the
    CPU (and any peripherals involved) will be doing when executing a block of code, plus
    its impacts on the system.  Understandability is inversely proportional to the time
    it takes for a programmer to reach *full understanding* of the code he is reading.

    ... omitted for sake of brevity...

Now that all works for a glossary using the .. glossary:: directive as long as I use exactly that term to link to it using the :term: role. However, in my actual document, I link to it using many different terms from many different .rst files. The terms used are:

• understand
• understood
• understanding
• understandable

Using the :ref: role, of course I can handle these cases like this (taking "understand" as an example):

:ref:`understand <understandability>`

or I can load up the entry with "explicit link targets" using alternate spellings like this so the generated HTML gets an "anchor" (<a id="alternate term">) for each one:

.. _understandability:
.. _understand:
.. _understood:
.. _understanding:
.. _understandable:

understandability
    ... omitted for sake of brevity...

and then reference it like this:

:ref:`understand`

However, until I found the solution below, I had found no way of handling this use case with the .. glossary:: directive.

I note that in the HTML output that the glossary entries create an anchor like this: <a id="term-understandability">, so I tried

:ref:`understand <term-understandability>`

but sadly, that doesn't work either.

I also tried inserting "explicit link targets" into the glossary like this (so I could continue to reference it using :ref:'understand'):

.. glossary::
    term1
        definition1

.. _understand:

    understandability
        ... omitted for sake of brevity...

But then the .. _understand: link target terminates the glossary definition list, so everything that comes after it is no longer in the glossary.

Solution

An obscure solution is to indent the "explicit link target" like this (using the same syntax [indenting] as adding "link targets" to items in a list):

.. glossary::
    term1
        definition1

        .. _understand:

    understandability
        ... omitted for sake of brevity...

This does work, allowing me to link to it like this:

:ref:`understand`

But it took me several hours of testing and experimenting (and finally remembering the way to add an "explicit link target" into an unordered list) before I found this solution. Unfortunately, it is not yet documented under the .. glossary:: directive, but should be, since it is such a common use case.

Note:

I rejected the solution of doing it with just reStructuredText link targets like this because it would create a maintenance nightmare due to the number of places (every .rst file) where this would have to be done:

text text text understand_ text text text 
...
.. _understand:  ../relative/path/to/online/doc/document_name.html#term-understandability

It would work but would just be a very bad idea for future maintenance, and would have to be done everywhere I link to that term in my glossary. Eeek!

Describe the solution you'd like The above solution clearly documented under the .. glossary:: directive so that other writers like me can successfully deal with the above frequently-encountered use case.

Describe alternatives you've considered See above.

Additional context All given above.

I will be submitting a PR to handle this shortly.

[electric-coder]

This is a lengthy post and I'm wondering why not take advantage of the :term: role since it shares the normal cross-reference syntax like: :term:`title <target>`? Hence for this example:

.. glossary::

    understandability
        ... omitted for sake of brevity...

I would then reference it in the docs as:

• :term:`understand <understandability>`
• :term:`understood <understandability>`
• :term:`understanding <understandability>`
• :term:`understandable <understandability>`

This would give you a single entry in the general index: understandability and its cross-references can be found using full-text search for <understandability>. Besides you'd always use the specialized :term: instead of having to use the more general :ref:, this is the general solution using cross-reference syntax when you want to reference different inflections/derivations from a citation form (sometimes also called lexeme) of a word.

[vwheeler63]

I'm wondering why not take advantage of the :term: role since it shares the normal cross-reference syntax

Brilliant! That works beautifully! And that is what I was missing! So my PR will change to adding a paragraph describing the above to the :term: role instead of the non-perfect solution I submitted under the .. glossary:: directive documentation.