Merge pull request #5134 from jfbu/latex_xindy

Add new config value ``latex_use_xindy``

doc/conf.py

@@ -72,6 +72,7 @@ latex_elements = {
 ''',
 }
 latex_show_urls = 'footnote'
+latex_use_xindy = True
 
 autodoc_member_order = 'groupwise'
 todo_include_todos = True

doc/usage/configuration.rst

@@ -1872,6 +1872,40 @@ information.
 
    .. versionadded:: 1.6
 
+.. confval:: latex_use_xindy
+
+   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 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
+
 .. confval:: latex_elements
 
    .. versionadded:: 0.5