LaTeX: add hyperref support to general index as handled by xindy

- achieve hyperlinked page numbers in general index, despite xindy's
  incompatibility with hyperref,

- obtain compatibility of pdflatex with xindy for documents with
  Cyrillic scripts,

- use xindy by default with xelatex/lualatex because any non-ascii
  character as first letter of an indexed term breaks PDF build if using
  makeindex with lualatex, and produces incoherent index with xelatex.

This commit also switches off xindy logs (which were activated in parent
commits) as they are voluminous and not of immediate use to Sphinx user.
This commit is contained in:
jfbu
2018-07-06 19:05:38 +02:00
parent a68d06a1da
commit 60b160431a
12 changed files with 381 additions and 83 deletions

View File

@@ -1874,28 +1874,35 @@ information.
.. confval:: latex_use_xindy
If ``True`` (default ``False``), the PDF build from the LaTeX files
created by Sphinx will use :program:`xindy` (doc__) rather than
:program:`makeindex`. This means that utf-8 initials in indexed
words will be handled correctly, and entries will be ordered
according to the rules appropriate to the :confval:`language`.
Currently, this uses :program:`texindy` and only (most) European
languages with Latin scripts are supported. For usages requiring
direct use of ``xindy``, user will have to customize the files
:file:`Makefile` and :file:`latexmkrc` which are written to LaTeX
build repertory. This can be done via
:confval:`latex_additional_files` and customized such files located
in source repertory.
If ``True``, the PDF build from the LaTeX files created by Sphinx
will use :program:`xindy` (doc__) rather than :program:`makeindex`
for preparing the index of general terms (from :rst:dir:`index`
usage). This means that words with UTF-8 characters will get
ordered correctly for the :confval:`language`.
__ http://xindy.sourceforge.net/
This option is recommended in case of :confval:`latex_engine` set
to ``xelatex`` or ``lualatex`` (it is even mandatory for the latter
as the PDF build is broken if some indexed terms start with a
non-ascii character). It is without effect in case of
:confval:`platex` (Japanese documents). Even if
:confval:`latex_engine` is left to its default, the option is
recommended as soon as indexed terms use non-ascii characters.
- This option is ignored if :confval:`latex_engine` is ``'platex'``
(Japanese documents) as :program:`mendex` is used in that case.
- The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as
:program:`makeindex`, if any indexed term starts with a non-ascii
character, creates ``.ind`` file containing invalid bytes for
UTF-8 encoding. With ``'lualatex'`` this then breaks the PDF
build. Notice that :program:`xindy` supports most but not
all European languages.
- The default is ``False`` for ``'pdflatex'`` but ``True`` is
recommended for non-English documents as soon as some indexed
terms use non-ascii characters from the language script.
Cyrillic scripts are (transparently) supported with
``'pdflatex'`` thanks to a specific Sphinx-contributed ``xindy``
style file :file:`cyrLICRutf8.xdy`.
As :program:`xindy` does not support the same range of languages
as ``LaTeX/babel`` does, the default :program:`makeindex` for
``'pdflatex'`` may be preferred in some circumstances, although
the index will be ill-formed probably.
.. versionadded:: 1.8