sphinx-doc / sphinx-doc/sphinx
[RFC] LaTeX: choose some default for ``\\sphinxnonalphabeticalgroupname`` (xindy indexing)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
1.8 will have latex_use_xindy option.
With makeindex the index contains Symbols and Numbers entries. With xindy I currently did not separate them (for lack of expertise) and they are merged into a single heading called provisorily Non-alphabetical: https://github.com/sphinx-doc/sphinx/blob/53ea40555f1a71802a45d06f4be8da367338526b/sphinx/writers/latex.py#L679-L695
This is thus the \sphinxnonalphabeticalgroupname macro which contains the translatable Non-alphabetical string. Here is for example how it currently looks like with Sphinx own documentation:

Here is how it looks like in a buid I made of CPython docs (library.pdf), in French, which uses xelatex hence xindy:

Suggestions are welcome for better choice than Non-alphabetical.
I am not sure how to separate into Symbols and Numbers. It is quite possible to leave the default to an empty string.
remark: the legacy "Symbols" is not quite appropriate as the example of CPython docs shows. Here is from official CPython build in English (which uses pdflatex+makeindex):

edit remark: with xindy (and current way of Sphinx to use it) names like -create are indexed ignoring the initial hyphens, here is how it looks like in the index of library.pdf in French (xelatex+xindy):

In contrast with legacy makeindex as in screenshot above they end up in the "Symbols" group. (which sounds bad).
In both cases indexed terms like __abs__() end up in the Symbols/Non-Alphabetical group. With xindy, it would be possible easily to configure it to move such __abs__() indexed term in A letter group rather than Symbols/Non-Alphabetical group.
- Sphinx version: 1.8+
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read sphinx/writers/latex.py around lines 679-695 and trace how latex_use_xindy generates the non-alphabetical index group. Review the linked examples and determine an agreed default for the translated group name; the work is done when that default is implemented and its generated LaTeX output is verified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- latex, python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100