From 90e3425ed751ded99e71174ece60a9fb6c63f03e Mon Sep 17 00:00:00 2001 From: jfbu Date: Sun, 22 Oct 2017 11:45:28 +0200 Subject: [PATCH] Fix #4149: Documentation: Help choosing latex_engine --- CHANGES | 1 + doc/config.rst | 19 +++++++++++++++++++ doc/latex.rst | 1 + 3 files changed, 21 insertions(+) diff --git a/CHANGES b/CHANGES index 139580a3e..7add2c4b0 100644 --- a/CHANGES +++ b/CHANGES @@ -36,6 +36,7 @@ Bugs fixed * #1020: ext.todo todolist not linking to the page in pdflatex * #3965: New quickstart generates wrong SPHINXBUILD in Makefile * #3739: ``:module:`` option is ignored at content of pyobjects +* #4149: Documentation: Help choosing :confval:`latex_engine` Testing -------- diff --git a/doc/config.rst b/doc/config.rst index e96c075e9..b615dc45a 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -1542,6 +1542,25 @@ These options influence LaTeX output. See further :doc:`latex`. * ``'lualatex'`` -- LuaLaTeX * ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``) + PDFLaTeX's support for Unicode characters covers those from the document + language (the LaTeX ``babel`` and ``inputenc`` packages map them to glyph + slots in the document font, at various encodings allowing each only 256 + characters; Sphinx uses by default (except for Cyrillic languages) the + ``times`` package), but stray characters from other scripts or special + symbols may require adding extra LaTeX packages or macros to the LaTeX + preamble. + + If your project uses such extra Unicode characters, switching the engine to + XeLaTeX or LuaLaTeX often provides a quick fix. They only work with UTF-8 + encoded sources and can (in fact, should) use OpenType fonts, either from + the system or the TeX install tree. Recent LaTeX releases will default with + these engines to the Latin Modern OpenType font, which has good coverage of + Latin and Cyrillic scripts (it is provided by standard LaTeX installation), + and Sphinx does not modify this default. Refer to the documentation of the + LaTeX ``polyglossia`` package to see how to instruct LaTeX to use some + other OpenType font if Unicode coverage proves insufficient (or use + directly ``\setmainfont`` et. al. as in :ref:`this example `.) + .. confval:: latex_documents This value determines how to group the document tree into LaTeX source files. diff --git a/doc/latex.rst b/doc/latex.rst index 61689bda1..eaf147c1c 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -29,6 +29,7 @@ The *latex* target does not benefit from pre-prepared themes like the cautionBgColor={named}{LightCyan}} \relax +.. _latex-basic: Basic customization -------------------