Open jayaddison opened 1 month ago
What I'd expect is for only the first letter of the category name (F for fermions in the example case above) to be displayed and used for grouping of the entries.
Conceivably you wouldn't want to limit the user to single letter alphabetical groupings. I always found the groupings feature to be limited and not sufficiently flexible both with the glossary and index directives.
It would make sense to allow for every entry to be grouped by a custom name and even dispensing the default single letters entirely (there's no configuration option for that). Which raises another issue: should the directive include entries in both F
and fermions
? Or not include in F
if an entry was included in fermions
?
What's the use of fermions
if everything gets grouped into F
anyway?
What's the use of
fermions
if everything gets grouped intoF
anyway?
In HTML output, I'd expect a glossary entry with a classification/grouping (such as electron : fermions
) to be placed into a container with other definitions that share the same classification:
Or, approximated as an ASCII-art diagram:
A
ähnlich
B
boson
F
fermion
fermions
electron
myon
tauon
U
über
As shown this has a couple of strange drawbacks:
It uses the singular/plural to distinguish the regular glossary entry from the grouping - there might not always be a convenient singular/plural that naturally puts the group in a lexicographically desirable place, as number contrast might not be defined by a sufix contrast (see ntša/dintša/mantša).
I don't think it's possible to create a cross-reference directly to the grouping if you want it - that defeats usefulness of the grouping feature since you can't mention it with a link elsewhere.
The glossary is limited in functionality by defaulting to letter links instead of allowing thematic hypernymy groupings on top.
But yes, if you want to limited the glossary to only allowing letter links on top (enforcing uniformity) than this change does contribute to making the directive more consistent - a feature some users might find desirable.
As shown this has a couple of strange drawbacks:
It uses the singular/plural to distinguish the regular glossary entry from the grouping - there might not always be a convenient singular/plural that naturally puts the group in a lexicographically desirable place, as number contrast might not be defined by a sufix contrast (see ntša/dintša/mantša).
I don't think it's possible to create a cross-reference directly to the grouping if you want it - that defeats usefulness of the grouping feature since you can't mention it with a link elsewhere.
Perhaps situations where a defined term is also used as a grouping (classification) term could be handled by consolidating them both into a single entry in the index, containing child entries for the members of the group?
index.rst
test-glossary
=============
.. glossary::
:sorted:
boson
Particle with integer spin.
*fermion*
Particle with half-integer spin.
tauon : fermion
A half-spin elementary particle with an electric charge of -1.
myon : fermion
A negatively-charged elementary particle with a 1/2-spin; heavier than
an electron, but not as heavy as a tauon.
electron : fermion
A negatively-charged elementary particle, fundamentally important in
the field of electricity.
über
Gewisse
ähnlich
Dinge
A
ähnlich
B
boson
F
fermion
electron
myon
tauon
U
über
I haven't forgotten about this post, but in the meanwhile I haven't found the time to test the glossary and think about what would be ideal here.
Describe the bug
The Sphinx
glossary
directive has a feature that allows for entries to have 'grouping keys' -- essentially a way to declare that a definition within the glossary belongs to a parent category.I think this is how the glossary of fermions in our
test-glossary
testroot should be organised -- multiple distinct types of fermion are defined there, and so each of them could be described differently and also be placed into a common category, such asfermions
.Here is a minimal example derived from that:
When we use the
html
builder from this input, the actual bug occurs: the outputgenindex.html
contains category names in full within the list of single-character alphabet headings --A | B | F | fermions | U
instead of the expectedA | B | F | U
.What I'd expect is for only the first letter of the category name (
F
forfermions
in the example case above) to be displayed and used for grouping of the entries.How to Reproduce
conf.py
index.rst
Environment Information
Sphinx extensions
Additional context
Discovered during development of #12699.