mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user