Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Help choosing latex_engine #4149

Closed
JulienPalard opened this issue Oct 13, 2017 · 4 comments
Closed

Documentation: Help choosing latex_engine #4149

JulienPalard opened this issue Oct 13, 2017 · 4 comments
Assignees
Milestone

Comments

@JulienPalard
Copy link
Contributor

#4136 was "simply" a wrong choice in how to handle UTF-8 characters, leading me to the conclusion: The documentation about latex_engine should help users choosing the right engine for their needs.

I'm not a native english speaker, so it may probably be enhanced, but I'd see something like:

.. confval:: latex_engine

   The LaTeX engine to build the docs.  The setting can have the following
   values:

   * ``'pdflatex'`` -- PDFLaTeX (default)
   * ``'xelatex'`` -- XeLaTeX (Uses Unicode, good for multilingual support)
   * ``'lualatex'`` -- LuaLaTeX (Uses Unicode, good for multilingual support)
   * ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``, good at rendering Japanese)
@jfbu
Copy link
Contributor

jfbu commented Oct 19, 2017

Would this be ok?

diff --git a/doc/config.rst b/doc/config.rst
index e96c075e9..243c374b0 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -1542,6 +1542,17 @@ These options influence LaTeX output. See further :doc:`latex`.
    * ``'lualatex'`` -- LuaLaTeX
    * ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``)
 
+   Contrarily to ``pdflatex`` which requires fonts prepared for TeX,
+   ``xelatex`` and ``lualatex`` can (and actually, should) use OpenType fonts
+   (from the TeX installation tree or system fonts). Sphinx does not modify
+   the font from its default for these engines: with recent LaTeX this is the
+   Latin Modern font in OpenType format (from the TeX installation tree).
+   These engines are said to be "Unicode" engines as they require UTF-8
+   sources and better support Unicode characters (assuming the glyph is
+   actually provided by the used font). In contrast, ``pdflatex`` support for
+   Unicode characters is often limited to those corresponding to the document
+   language, extra steps being needed to handle others.
+
 .. confval:: latex_documents
 
    This value determines how to group the document tree into LaTeX source files.

@JulienPalard
Copy link
Contributor Author

LGTM

@jfbu
Copy link
Contributor

jfbu commented Oct 22, 2017

Thanks for review; finally I rewrote entirely the added explanations. Fixed at 90e3425

@jfbu
Copy link
Contributor

jfbu commented Oct 22, 2017

Closing.

@jfbu jfbu closed this as completed Oct 22, 2017
@jfbu jfbu added this to the 1.6.5 milestone Oct 22, 2017
bdelepine added a commit to MetaSys-LISBP/IsoCor that referenced this issue Nov 13, 2018
Previous commit is make a broken PDF on RTD. This one is motivated by:
* sphinx-doc/sphinx#4149
* and the actual Sphinx doc that do states that "switching the engine to XeLaTeX or LuaLaTeX [...] is often easier than sticking with PDFLaTeX and trying to get it to work with the Unicode characters."
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 22, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants