sphinx-doc/sphinx

[RFC] LaTeX: choose some default for ``\\sphinxnonalphabeticalgroupname`` (xindy indexing)

Open

#5,252 opened on Aug 1, 2018

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)batch import
builder:latexhelp wanted

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:

capture d ecran 2018-08-01 a 18 36 47

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

capture d ecran 2018-08-01 a 18 46 18

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):

capture d ecran 2018-08-01 a 18 48 36

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):

capture d ecran 2018-08-01 a 19 08 54

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

Tech stack
python
Domain
documentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
Basic knowledge of LaTeXUnderstanding of Sphinx indexingFamiliarity with xindy
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
35
Research direction
Examine the behavior of xindy indexing in Sphinx by reviewing the referenced code in sphinx/writers/latex.py (lines 679-695). Understand how `\sphinxnonalphabeticalgroupname` is currently used. Investigate alternatives for a better default than 'Non alphabetical'. Look at how makeindex separates 'Symbols' and 'Numbers' and consider if xindy can be configured similarly. Check the Sphinx documentation for feedback on this change.