Capitalization not needed to be the same for the term in the glossary and when referenced with the term role

[dbitouze]

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

Terms in the glossary and referenced with the term role need to use the same capitalization. That's not convenient:

• either the term is capitalized in the glossary (okay) and we have to use it capitalized in the documentation (not okay),
• or the term isn't capitalize in the glossary (not okay) and we can (have to) use it not capitalized in the documentation (okay almost everywhere).

Describe the solution you'd like Be able to not use the same capitalization for the term in the glossary and when referenced with the term role in order to make the following (“Environment”/“environment”) just work:

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

and:

We consider here the following :term:`environment`, which is [...]

[picnixz]

I think people usually put the term in a non-caps in glossary, and if needed, don't use it at the beginning of a sentence.

Now, if you want your glossary to only have capitalized entries, we could change it (but in general most if not all entries are actually not capitalized, which is similar to what you would find in a regular dictionary).

As such, I am willing to instead add an option where you could also use non-capitalized in terms. However, I personnally think that this feature is not needed and you should instead write capitalized in the glossary and use them as non-capitalized. If you really need the capitaliized, use :term:`Word \<word>`.

[dbitouze]

I think people usually put the term in a non-caps in glossary, and if needed, don't use it at the beginning of a sentence.

I think glossaries are anything but definition lists and, as exemplified e.g. in the Read the Docs Sphinx Theme documentation, entries in definition lists are usually capitalized. BTW, the entries are also capitalized in the glossary's example of the same documentation.

Now, if you want your glossary to only have capitalized entries, we could change it (but in general most if not all entries are actually not capitalized, which is similar to what you would find in a regular dictionary).

In fact, what caught my eye is the heterogeneous layout of definition lists and glossaries in the MyST documentation.

As such, I am willing to instead add an option where you could also use non-capitalized in terms.

Would be very nice!

However, I personally think that this feature is not needed and you should instead write capitalized in the glossary and use them as non-capitalized.

??? Well, that's exactly what I want :wink: (maybe I was not clear, sorry). But, AFAICS, what you suggest I should use is currently not possible.

If you really need the capitalized, use :term:`Word <word>`.

Let's me clarify what is my feature request:

• entries capitalized in the glossary,
• corresponding terms used non-capitalized in the text.

[picnixz]

Ah sorry, I meant "you write them non-capitalized and use them non-capitalized. If you want them to be capitalized, use the other form (with the title)".

AFAICS, what you suggest I should use is currently not possible.

Oh, then I would prefer only fixing this.

I think glossaries are anything but definition lists

Sorry to disagree here. I personally think that it should be like this. Also it is consistent with MLA or APA norms where glossary items only consist of lowercase words unless it's a proper noun. By the way the Sphinx documentation (not the RTD theme) illustrates the glossary using lowercase entries and iirc, the same holds for the official Python documentation where terms are lowercase.

[picnixz]

@dbitouze A quick follow-up

I don't know if I was imprecise, but

See the :term:`XYZ <xyz>`

.. glossary::

   xyz

      the xyz

seems to work, namely XYZ is linked to the term xyz and rendered as capitalized. So, I don't need to fix what I thought was broken according to your comment.

[dbitouze]

@dbitouze A quick follow-up

I don't know if I was imprecise, but

[...]

seems to work, namely XYZ is linked to the term xyz and rendered as capitalized. [...]

Indeed, that works as expected, thanks. But that's not very handy. My feature request is to be able to just type (see the missing <xyz> in :term:`XYZ`:

See the :term:`XYZ`

.. glossary::

   xyz

      the xyz

[picnixz]

Mmh, well we could allow case-insensitive lookups but it might not necessarily be easy actually to implement.

We could restrict it to glossary terms but I think references are looked up independently of whether they are glossary or not. Now, we could always assume that the reference of a term, if no title is specified, is the lowercase of what is given. However this would enforce the fact that lowercase terms are expected to be in the glossary.

The reason why it would be like is the following:

• you create some ref with a capitalozed word and expect to link the non-capitalized version.
• sphinx does many other things
• sphinx resolves the references in one go (glossary, classes, whatever). This is the point I am not entirely sure about, I don't remember if the references are resolved when processing the term directly or later on in a homogeneous way. If it's part of a homogeneous process, we need to specialize it for glossary only (because I don't want case-insensitive lookup for any other roles).

I need to investigate more about its feasibility. If it's not too much work, we could do something for only the term role but otherwise I think it's better not to overcomplexify the way references are resolved. On the other hand, it's actually quite simple to do it via an extension actually by handling the missing-reference (don't remember its exact name) event (I think it would trigger that event, if it's not the case, we could fire the event and that would need a PR)

[dbitouze]

(Just a little comment.) It's just the other way round I'm after:

See the :term:`xyz`

.. glossary::

   Xyz

      the xyz

[picnixz]

Well, either way would require the same approach so it doesn't really matter for me. However, I would personally recommend following APA norms in general.

[electric-coder]

@picnixz

Mmh, well we could allow case-insensitive lookups

I'm against the FR from the OP. As you pointed out in your first answer :term:`Word <word>` is enough to cover any use case.

As you also say:

overcomplexify

I don't see a real need for an additional option while Sphinx has bugs with standard library types. It also seems the OP hadn't found the usual solution for writing cross-references with costum labels. The small overhead of using search&replace doesn't justify more complexity and the proposed solution is conceptually wrong because for completeness it would have to include features like capitalization and pluralization but those would be language dependent and thus aren't trivial to implement.

[dbitouze]

@picnixz

Mmh, well we could allow case-insensitive lookups

I'm against the FR from the OP. As you pointed out in your first answer :term:`Word <word>` is enough to cover any use case.

Enough but not handy.

As you also say:

overcomplexify

I don't see a real need for an additional option while Sphinx has bugs with standard library types.

Okay.

It also seems the OP hadn't found the usual solution for writing cross-references with costum labels.

I don't see your point and the connection with my FR.

The small overhead of using search&replace

I don't see your point and the connection with my FR.

doesn't justify more complexity and the proposed solution is conceptually wrong because for completeness it would have to include features like capitalization and pluralization but those would be language dependent and thus aren't trivial to implement.

That's would indeed by nice. That's what the glossaries and glossaries-extra LaTeX packages provide.

[picnixz]

After thinking a bit, I am against the FR. The first reason is because, while it may be "enough but not handy", I think we should enforce standard norms when writing glossaries. I am not sure that what you request is applicable to a lot of projects. On the other hand, you have the following solutions:

• Improve the glossary directive yourself and patch it in an extension. By the way, we already support localization in the glossary using term : key syntax (see the docs).
• Use a role dispatcher extension which changes how term is handled (same idea as for how IntersphinxRole is handled).
• (the solution I would go for) Implement an event handler handling missing references and patch them iff they are arising from term role. Note that I don't know if such missing references can be handled in the first place so you'll need to check (just create an event handler). See the docs or the source code to understand how to create such handler (and the exact name of the event).

[dbitouze]

After thinking a bit, I am against the FR.

Too bad!

The first reason is because, while it may be "enough but not handy", I think we should enforce standard norms when writing glossaries.

I didn't find anything regarding APA norm for glossaries. Okay MLA advises lowercase. But here is an example of a glossary with capitalized entries.

I am not sure that what you request is applicable to a lot of projects. On the other hand, you have the following solutions:

• Improve the glossary directive yourself and patch it in an extension.

Well, beyond my scope, I'm afraid.

By the way, we already support localization in the glossary using term : key syntax (see the docs).

I had a look at the documentation, but didn't see how it could serve my purpose, sorry.

• Use a role dispatcher extension which changes how term is handled (same idea as for how IntersphinxRole is handled).

Well, beyond my scope, I'm afraid.

• (the solution I would go for) Implement an event handler handling missing references and patch them iff they are arising from term role. Note that I don't know if such missing references can be handled in the first place so you'll need to check (just create an event handler). See the docs or the source code to understand how to create such handler (and the exact name of the event).

Well, beyond my scope, I'm afraid.

Meanwhile, I found a stopgap, making use of (MyST)-Markdown substitutions[^1] (sort of LaTeX's \newcommand):

---
myst:
  substitutions:
    xyz: '{term}`xyz <Xyz>`'
---

Then, with a glossary such as:

{.glossary}
Xyz
: Definition of xyz

I can reference “xyz” with {{ xyz }}.

Thanks anyway.

[^1]: My source files are (MyST)-Markdown ones.

[picnixz]

I had a look at the documentation, but didn't see how it could serve my purpose, sorry.

Ah, actually it was in response of i18n concerns (so not related to your original question).

Closing the issue since you could find an alternative.