sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.57k stars 2.12k forks source link

Auto-pluralize glossary terms (via flag, maybe) #7574

Open tuukkamustonen opened 4 years ago

tuukkamustonen commented 4 years ago

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

When referring to glossary items, you have to follow the exact form, and have to specify singular and plural form separately:

.. glossary::

   foo
      Text.

This works: One :term:`foo`.

This does not work: Many :term:`foos`.

Workaround #1: Many :term:`foos <foo>`. But it's annoyingly verbose.

Workaround #2: Many :term:`foo`\s. But it's kinda ugly and rendered output is ugly too.

.. glossary::

   workaround
   workarounds
      Text.

Workaround #3: Many :term:`workarounds`. But then glossary looks awful.

.. |foos| replace:: :term:`foos <foo>`

Workaround #4: Many |foos|. But the syntax is completely different, you lose static validation (depends on editor) and so on.

Describe the solution you'd like

How about simply auto-building the plural form for glossary targets? Adding s would work for English (for most cases) but probably not for other languages, so it should be configurable.

Describe alternatives you've considered

No idea.

tk0miya commented 4 years ago

+1; Reasonable!

electric-coder commented 2 months ago

@jayaddison #12707 looking at the terms before looking at the groups (must be my left-to-right reading habit), I'd say:

Workaround 1: Many :term:`foos <foo>`. But it's annoyingly verbose.

Currently it's the best choice (and not at all bad).

Adding s would work for English (for most cases) but probably not for other languages, so it should be configurable.

The terms a user may want to synonymize in the glossary can be entirely subjective (semantic/conceptual) with any morphological relation being just the most common and intuitive.

Thinking just of morphology (and that's still limiting), you could also want to group derivations, compounds, prefixing, infixes, circumfixation and introflection. (Any word formation process we care to think of...)

What might be needed for the terms alone, is an additional option to suppress them visually (to avoid showing plurals and singulars in a glossary), so e.g:

.. glossary::
   :hide: term2, workarounds

   term 1
   term 2
      Definition of both terms.

   workaround
   workarounds
      Text.

I don't think such a solution would change anything to the otherwise regular cross-reference syntax - instead thinking of the glossary as a convenient general-purpose grouping directive. An argument can be made that writing custom cross-references :term:`workaround <workarounds>` isn't all that tedious, but on the upside it would add flexibility, conciseness and overall syntactic sugar to the reST code. Unless I'm mistake currently this would require hiding the second term using CSS.