Document how to reference glossary terms with alternate word forms.

[vwheeler63]

The problem being solved is well described in Issue #13119. However, for convenience, the short version is that it is a common use case (for me at least) to refer to glossary terms in text that uses alternate forms of the word. Example from Issue: term = understandability, which is the correct term for the glossary, but I link to it in text that uses alternate forms of the word when referring to the same concept: understand, understood, understanding, understandable.

This PR documents a solution for this use case that works well while still using the .. glossary:: directive, which was not previously documented.

Resolves #13119

Feature

Documentation covering the solution to the above.

Purpose

To help others not have to go through the experimenting and testing I had to go through to find a solution that worked.

Detail

See Issue #13119.

Relates

Covered above.

[vwheeler63]

Actually, I just found out this doesn't work as I had hoped -- it only navigates to the PAGE, not to the definition. So it's back to the Issue #13119 to ask for a solution to this use case.

[vwheeler63]

And this morning, I discovered the correct way to handle the problem I ran into and documented it under the :term: role instead of the imperfect solution I submitted under the .. glossary:: directive documentation.

[electric-coder]

This change is wrong and it would only mislead readers because it's too verbose and directories play no part since the terms are cross-reference targets not directories https://github.com/sphinx-doc/sphinx/pull/13120/commits/b0c664089cf497262d1918bf71c9d35ccd9c3815:

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>`

You should add a single sentence saying: "This role also supports Custom link text from the general cross-reference syntax." (With a link to the relevant bullet-point above.)

[vwheeler63]

This change is wrong...

"source directory" is a glossary entry in the example given on this page.

However, I agree with you that it could be misleading and it begs for a better example. I think what you suggested entirely covers what needs to be communicated, so I have changed it per your guidance.

[electric-coder]

@vwheeler63 Sorry I made a mistake, the "Custom link text" should be all lower case to blend into the prose, so: "custom link text". My fault :(

[vwheeler63]

...should be all lower case...

No problem whatsoever! :-)