LaTeX: use unicode-math with xelatex and lualatex

Fixes #12714.

Related: #2290, #2348.

Author: jfbu

CHANGES.rst

@@ -10,6 +10,19 @@ Dependencies
 Incompatible changes
 --------------------
 
+* LaTeX: The inclusion of ``amssymb`` LaTeX package is done after the contents
+  of :confval:`latex_elements`\ ``['fontpkg']``, and originates in the new
+  ``'fontpkgmath'`` key of :confval:`latex_elements`.
+
+  - Thus, move custom math font set-up from ``'fontpkg'`` to ``'fontpkgmath'``
+    if needed.
+  - Regarding Unicode latex engines, they do not use ``amssymb`` anymore but
+    XITS Math font via ``unicode-math``, as default of ``'fontpkgmath'``.
+    This fixes some issues and provides math glyphs much better matching GNU
+    FreeSerif which is the default text font.
+  - For ``'pdflatex'`` as :confval:`latex_engine`, it is planned to replace at
+    Sphinx 9 usage of ``amssymb`` by ``stix2`` in order for the math glyphs to
+    much better match the default Times-like text font.
 * #12763: Remove unused internal class ``sphinx.util.Tee``.
   Patch by Adam Turner.
 
@@ -69,6 +82,9 @@ Bugs fixed
   Patch by Hugo van Kemenade.
 * #12645: Correctly support custom gettext output templates.
   Patch by Jeremy Bowman.
+* #12714: LaTeX: Let ``\mathbf{\Lambda}`` work as expected if
+  :confval:`latex_engine` is ``'xelatex'`` or ``'lualatex'``, via usage
+  of ``unicode-math`` with XITS Math font.
 * #12717: LaTeX: let :option:`-q <sphinx-build -q>` (quiet) option for
   :program:`sphinx-build -M latexpdf` or :program:`make latexpdf` (``O=-q``)
   get passed to :program:`latexmk`.  Let :option:`-Q <sphinx-build -Q>`

bindep.txt

@@ -16,6 +16,8 @@ texlive-tex-gyre [platform:rpm]
 texlive-pict2e [platform:rpm]
 texlive-fontawesome5 [platform:rpm]
 texlive-xcolor [platform:rpm]
+texlive-unicode-math [platform:rpm]
+texlive-xits [platform:rpm]
 latexmk [platform:rpm]
 
 texlive-latex-recommended [platform:dpkg]

doc/latex.rst

@@ -202,6 +202,43 @@ Keys that you may want to override include:
       more complete TeX fonts and associated LaTeX packages.  The monospace
       font has been changed to better match the Times clone.
 
+   .. versionchanged:: 8.1.0 Custom configuration of math fonts, if any,
+      should be done via the ``'fontpkgmath'`` key, which is new at 8.1.0.
+
+.. _fontpkgmath:
+
+``'fontpkgmath'``
+   LaTeX configuration for math fonts, which is executed after contents of
+   ``'fontpkg'``.  It defaults to:
+
+   - :code-tex:`r'\\usepackage{amssymb}'` if :confval:`latex_engine` is set to
+     ``'pdflatex'`` (or ``'uplatex'``).
+
+   - :code-tex:`r'\\usepackage{unicode-math}'` for ``'xelatex'`` and
+     ``'lualatex'`` with extras to set the math font to XITS Math.  It also
+     allows mark-up such as :code-tex:`\\mathbf{\\Gamma}` (which is already
+     legit both for HTML and for PDF via ``'pdflatex'``).
+
+     .. hint::
+
+        Use :code-tex:`\\boldsymbol` for boldening *lowercase* Greek letter,
+        :code-tex:`\\boldsymbol{\\alpha\\beta\\gamma}`.
+
+   .. versionadded:: 8.1.0
+      The default TeX math fonts, and their AMS extensions loaded via
+      :code-tex:`\\usepackage{amssymb}` (a package whose usage could formerly
+      not be canceled, only overriden via additional math packages in
+      ``'fontpkg'``), do not fit well with most text fonts (they are much
+      thinner), the quasi sole exceptions being the original Computer Modern
+      text fonts and their close derivatives the Latin Modern text fonts.
+
+      Sphinx sets up per default a Times-alike font for text, which does not
+      fit well with LaTeX default math fonts (in particuler for Greek
+      letters).  This is solved for ``'xelatex'`` and ``'lualatex'`` via usage
+      of XITS Math font.  A possibility in future for ``'pdflatex'`` could be
+      for Sphinx to use the ``'fontpkgmath'`` key to inject usage of the
+      ``stix2`` package in replacement of ``amssymb``.
+
 ``'fncychap'``
    Inclusion of the "fncychap" package (which makes fancy chapter titles),
    default :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English documentation

doc/usage/builders/index.rst

@@ -237,8 +237,7 @@ The most common builders are:
 
    * ``texlive-latex-recommended``
    * ``texlive-fonts-recommended``
-   * ``texlive-fonts-extra`` (needed for ``fontawesome5``, see the 7.4.0
-     change notice below)
+   * ``texlive-fonts-extra``
    * ``tex-gyre`` (if :confval:`latex_engine` left to default)
    * ``texlive-latex-extra``
    * ``latexmk``
@@ -249,8 +248,9 @@ The most common builders are:
    .. versionchanged:: 7.4.0
       LaTeX package ``xcolor`` is now required (it is part of Ubuntu
       ``texlive-latex-recommended`` anyhow).  The LaTeX package
-      ``fontawesome5`` is recommended.  See the :ref:`'sphinxsetup'
-      <latexsphinxsetup>` ``iconpackage`` key for more.
+      ``fontawesome5`` is recommended (part of Ubuntu ``texlive-fonts-extra``).
+      See the :ref:`'sphinxsetup' <latexsphinxsetup>` ``iconpackage`` key for
+      more.
 
    Additional packages are needed in some circumstances:
 

doc/usage/configuration.rst

@@ -2806,20 +2806,6 @@ These options influence LaTeX output.
       this, the :ref:`fontenc` key of :ref:`latex_elements
       <latex_elements_confval>` must be used appropriately.
 
-   .. note::
-
-      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 :ref:`preamble` key of :ref:`latex_elements
-      <latex_elements_confval>`).
-      You may prefer ``r'\usepackage[math-style=literal]{unicode-math}'``
-      to keep a Unicode literal such as ``α`` (U+03B1) as-is in output,
-      rather than being rendered as :math:`\alpha`.
-
    .. versionchanged:: 2.1.0
       Use ``'xelatex'`` (and LaTeX package ``xeCJK``)
       by default for Chinese documents.
@@ -2833,6 +2819,13 @@ These options influence LaTeX output.
    .. versionchanged:: 4.0
       Use ``'uplatex'`` by default for Japanese documents.
 
+   .. versionchanged:: 8.1.0
+      ``'xelatex'`` and ``'lualatex'`` trigger inclusion of the LaTeX
+      ``unicode-math`` package and as a result, Unicode literals are
+      allowed in math mode (but their shapes may be normalized by
+      ``unicode-math``).  You can customize this via the
+      :ref:`fontpkgmath` key of :confval:`latex_elements`.
+
 .. confval:: latex_documents
    :type: :code-py:`Sequence[tuple[str, str, str, str, str, bool]]`
    :default: The default LaTeX documents

sphinx/builders/latex/constants.py

@@ -10,6 +10,10 @@
 \renewcommand{\ttdefault}{txtt}
 '''
 
+PDFLATEX_DEFAULT_FONTPKGMATH = r'''
+\usepackage{amssymb}% will become stix2 with suitable options at Sphinx 9
+'''
+
 PDFLATEX_DEFAULT_FONTSUBSTITUTION = r'''
 \expandafter\ifx\csname T@LGR\endcsname\relax
 \else
@@ -58,12 +62,50 @@
 ]
 '''
 
+XELATEX_DEFAULT_FONTPKGMATH = r'''
+\usepackage{unicode-math}
+\setmathfont{XITSMath-Regular.otf}[
+    StylisticSet=1,% choice of shape for "\mathcal"
+    BoldFont=XITSMath-Bold.otf,
+    NFSSFamily=XITS,
+]
+\makeatletter
+\AtBeginDocument{%
+  % work around unicode-math problems with \mathbf{\Gamma} et al.
+  \SetMathAlphabet{\mathrm}{normal}{TU}{XITS}{m}{n}
+  \SetMathAlphabet{\mathbf}{normal}{TU}{XITS}{b}{n}
+  \SetMathAlphabet{\mathrm}{bold}{TU}{XITS}{b}{n}
+  \SetMathAlphabet{\mathbf}{bold}{TU}{XITS}{b}{n}
+  \def\Gamma{Γ}
+  \def\Delta{Δ}
+  \def\Theta{Θ}
+  \def\Lambda{Λ}
+  \def\Xi{Ξ}
+  \def\Pi{Π}
+  \def\Sigma{Σ}
+  \def\Upsilon{Υ}
+  \def\Phi{Φ}
+  \def\Psi{Ψ}
+  \def\Omega{Ω}
+  % Make subscripts a bit larger for legibility
+  \def\defaultscriptratio{.8}
+  \def\defaultscriptscriptratio{.6}
+  \DeclareMathSizes{9}{9}{7}{5}
+  \DeclareMathSizes{\@xpt}{\@xpt}{8}{6}
+  \DeclareMathSizes{\@xipt}{\@xipt}{8.76}{6.57}
+  \DeclareMathSizes{\@xiipt}{\@xiipt}{9.6}{7.2}
+  \DeclareMathSizes{\@xivpt}{\@xivpt}{11.52}{8.64}
+}
+\makeatother
+'''
+
 XELATEX_GREEK_DEFAULT_FONTPKG = (XELATEX_DEFAULT_FONTPKG +
                                  '\n\\newfontfamily\\greekfont{FreeSerif}' +
                                  '\n\\newfontfamily\\greekfontsf{FreeSans}' +
                                  '\n\\newfontfamily\\greekfonttt{FreeMono}')
 
 LUALATEX_DEFAULT_FONTPKG = XELATEX_DEFAULT_FONTPKG
+LUALATEX_DEFAULT_FONTPKGMATH = XELATEX_DEFAULT_FONTPKGMATH
 
 DEFAULT_SETTINGS: dict[str, Any] = {
     'latex_engine':    'pdflatex',
@@ -82,11 +124,12 @@
     'utf8extra':       '',
     'cmappkg':         '\\usepackage{cmap}',
     'fontenc':         '\\usepackage[T1]{fontenc}',
-    'amsmath':         '\\usepackage{amsmath,amssymb,amstext}',
+    'amsmath':         '\\usepackage{amsmath,amstext}',
     'multilingual':    '',
     'babel':           '\\usepackage{babel}',
     'polyglossia':     '',
     'fontpkg':         PDFLATEX_DEFAULT_FONTPKG,
+    'fontpkgmath':     PDFLATEX_DEFAULT_FONTPKGMATH,
     'fontsubstitution': PDFLATEX_DEFAULT_FONTSUBSTITUTION,
     'substitutefont':  '',
     'textcyrillic':    '',
@@ -142,6 +185,7 @@
         'fontenc':     ('\\usepackage{fontspec}\n'
                         '\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'),
         'fontpkg':      XELATEX_DEFAULT_FONTPKG,
+        'fontpkgmath':  XELATEX_DEFAULT_FONTPKGMATH,
         'fvset':        '\\fvset{fontsize=\\small}',
         'fontsubstitution': '',
         'textgreek':    '',
@@ -155,6 +199,7 @@
         'fontenc':     ('\\usepackage{fontspec}\n'
                         '\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'),
         'fontpkg':      LUALATEX_DEFAULT_FONTPKG,
+        'fontpkgmath':  LUALATEX_DEFAULT_FONTPKGMATH,
         'fvset':        '\\fvset{fontsize=\\small}',
         'fontsubstitution': '',
         'textgreek':    '',
@@ -166,6 +211,7 @@
         'babel':        '',
         'classoptions': ',dvipdfmx',
         'fontpkg':      PDFLATEX_DEFAULT_FONTPKG,
+        'fontpkgmath':  PDFLATEX_DEFAULT_FONTPKGMATH,
         'fontsubstitution': '',
         'textgreek':    '',
         'fncychap':     '',
@@ -176,6 +222,7 @@
         'babel':        '',
         'classoptions': ',dvipdfmx',
         'fontpkg':      PDFLATEX_DEFAULT_FONTPKG,
+        'fontpkgmath':  PDFLATEX_DEFAULT_FONTPKGMATH,
         'fontsubstitution': '',
         'textgreek':    '',
         'fncychap':     '',

sphinx/templates/latex/latex.tex.jinja

@@ -46,6 +46,7 @@
 <%= substitutefont %>
 <%= textcyrillic %>
 <%= fontpkg %>
+<%= fontpkgmath %>
 <%= fontsubstitution %>
 <%= textgreek %>
 <%= fncychap %>