sphinx-doc / sphinx-doc/sphinx

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

Open
#5,252 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:latex help wanted
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:

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.