Merge pull request #5693 from jfbu/latex_doc_unicode_in_math

LaTeX (doc): explain how to allow Unicode input in math

doc/usage/configuration.rst

@@ -1796,16 +1796,27 @@ information.
 
    ``'pdflatex'``\ 's support for Unicode characters is limited.
 
-   If your project uses Unicode characters, setting the engine to
-   ``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font
-   with wide-enough glyph coverage (since Sphinx 2.0, the default font is the
-   FreeFont family) is often easier than trying to make
-   ``'pdflatex'`` work with the extra Unicode characters.
-
    .. note::
 
-      2.0 adds to ``'pdflatex'`` automatic support in Latin language document
+      2.0 adds to ``'pdflatex'`` support in Latin language document of
-      of occasional Cyrillic or Greek letters or words.
+      occasional Cyrillic or Greek letters or words.  This is not automatic,
+      see the discussion of the :confval:`latex_elements` ``'fontenc'`` key.
+
+   If your project uses Unicode characters, setting the engine to
+   ``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font
+   with wide-enough glyph coverage is often easier than trying to make
+   ``'pdflatex'`` work with the extra Unicode characters.  Since Sphinx 2.0
+   the default is the GNU FreeFont which covers well Latin, Cyrillic and Greek.
+
+   Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`,
+   LaTeX requires some extra configuration to support Unicode literals in
+   :rst:dir:`math`: the only comprehensive solution (as far as we know) is to
+   use ``'xelatex'`` or ``'lualatex'`` *and* to add
+   ``r'\usepackage{unicode-math}'`` (e.g. via the :confval:`latex_elements`
+   ``'preamble'`` key).  You may prefer
+   ``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode
+   literal such as ``α`` (U+03B1) for example as is in output, rather than
+   being rendered as :math:`\alpha`.
 
 .. confval:: latex_documents
 
@@ -2164,34 +2175,28 @@ information.
         "fontenc" package inclusion, defaults to
         ``'\\usepackage[T1]{fontenc}'``.
 
-        One can (``'pdflatex'`` only) add ``LGR`` for support of Greek letters
+        If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
-        or words in the document, and ``X2`` (or ``T2A``) for Cyrillic ones:
+        for support of Greek letters in the document, and also ``X2`` (or
+        ``T2A``) for Cyrillic letters, like this:
 
         .. code-block:: latex
 
            r'\usepackage[LGR,X2,T1]{fontenc}'
 
-        (A Cyrillic document will naturally use ``T2A`` or ``X2`` in last
-        position, as it has then to be the main encoding for the document
-        fonts).
-
         .. attention::
 
            Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
-           mark-up. This is not the case anymore, thus if such Greek letters
+           mark-up.  This is not the case anymore, and the above must be used
-           are used in the text (we are not discussing here Greek letters
+           (only in case of ``'pdflatex'`` engine) if the source contains such
-           using the math font, from math markup ``\alpha`` etc...) it is then
+           Unicode Greek.
-           mandatory to declare the ``LGR`` font encoding, i.e.
-           ``r'\usepackage[LGR,T1]{fontenc}'`` if no support for Cyrillic is
-           needed. On Ubuntu xenial, package ``texlive-lang-greek`` is then
-           required (and also ``cm-super`` if the ``'fontpkg'`` setting is not
-           modified).
 
-        .. hint::
+           On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
-
+           (for the latter, only if the ``'fontpkg'`` setting is left to its
-           Ubuntu package ``cm-super-minimal`` requires that the LaTeX
+           default) are needed for ``LGR`` to work.  In place of ``cm-super``
-           document executes ``\usepackage[10pt]{type1ec}`` before loading
+           one can install smaller ``cm-super-minimal``, but it requires the
-           ``fontenc``.  Thus, use this key with this extra at its start.
+           LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
+           loading ``fontenc``.  Thus, use this key with this extra at its
+           start if needed.
 
         .. versionchanged:: 1.5
            Defaults to ``'\\usepackage{fontspec}'`` when
@@ -2212,12 +2217,20 @@ information.
         The default (``'pdflatex'`` only) is
         ``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was
         modified by user to include ``LGR`` option.  If not, the key
-        value will be forced to be empty string.
+        value will be forced to be the empty string.
 
         This is needed for ``pdfLaTeX`` to support Unicode input of Greek
         letters such as φύσις.  Expert users may want to load the ``textalpha``
         package with its option ``normalize-symbols``.
 
+        .. hint::
+
+           Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
+           can be supported by ``'pdflatex'`` from setting this key to
+           ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
+           will render as :math:`\alpha`.  For wider Unicode support in math
+           input, see the discussion of :confval:`latex_engine`.
+
         With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
         key is ignored.
 

doc/usage/restructuredtext/directives.rst

@@ -1063,6 +1063,15 @@ or use Python raw strings (``r"raw"``).
 
 .. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex
 
+.. seealso::
+
+   :ref:`math-support`
+      Rendering options for math with HTML builders.
+
+   :confval:`latex_engine`
+      Explains how to configure LaTeX builder to support Unicode literals in
+      math mark-up.
+
 
 Grammar production displays
 ---------------------------