LaTeX: new 'fontpkgmath' key of latex_elements, use unicode-math

Fixes sphinx-doc#12714.

Related: sphinx-doc#2290, sphinx-doc#2348.

Author: jfbu

CHANGES.rst

@@ -7,6 +7,20 @@ 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.
+
 Deprecated
 ----------
 
@@ -26,5 +40,9 @@ Bugs fixed
   so that it now runs after the docutils ``Footnotes`` resolution transform.
   Patch by Chris Sewell.
 
+* #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.
+
 Testing
 -------

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

@@ -169,15 +169,16 @@ Keys that you may want to override include:
       For French with ``'lualatex'`` the default is to use ``babel``.
 
 ``'fontpkg'``
-   Font package inclusion. The default is::
+   Font package inclusion. The default with ``'pdflatex'`` is::
 
       r"""\usepackage{tgtermes}
       \usepackage{tgheros}
       \renewcommand\ttdefault{txtt}
       """
 
-   For ``'xelatex'`` and ``'lualatex'`` however the default is to use
-   the GNU FreeFont.
+   For ``'xelatex'`` and ``'lualatex'`` the default is to use the GNU
+   FreeSerif, FreeSans, and FreeMono fonts
+   (via ``\setmainfont`` etc...  syntax from LaTeX package ``fontspec``).
 
    .. versionchanged:: 1.2
       Defaults to ``''`` when the :confval:`language` uses the Cyrillic
@@ -186,16 +187,50 @@ Keys that you may want to override include:
    .. versionchanged:: 2.0
       Incorporates some font substitution commands to help support occasional
       Greek or Cyrillic in a document using ``'pdflatex'`` engine.
+      At 4.0.0 these commands were moved to the ``'fontsubstitution'`` key.
 
    .. versionchanged:: 4.0.0
 
-      - The font substitution commands added at ``2.0`` have been moved
-        to the ``'fontsubstitution'`` key, as their presence here made
-        it complicated for user to customize the value of ``'fontpkg'``.
-      - The default font setting has changed: it still uses Times and
-        Helvetica clones for serif and sans serif, but via better, more
-        complete TeX fonts and associated LaTeX packages.  The
-        monospace font has been changed to better match the Times clone.
+      The default font setting was changed.  As shown above it still uses
+      Times and Helvetica clones for serif and sans serif, but via better,
+      more complete TeX fonts and associated LaTeX packages.  The monospace
+      font has been changed to better match the Times clone.
+
+   .. versionchanged:: 8.1.0 Configuration of math fonts should be done via
+      the ``'fontpkgmath'`` key, which is new at 8.1.0.  For ``'pdflatex'``
+      this key injects ``\usepackage{amssymb}`` which is thus now executed
+      after the contents of ``'fontpkg'``.
+
+``'fontpkgmath'``
+   LaTeX package for math fonts.  It defaults to:
+
+   - ``r'\usepackage{amssymb}'`` if :confval:`latex_engine` is set to
+     ``'pdflatex'`` (or ``'uplatex'``).
+
+   - ``r'\usepackage{unicode-math}'`` for ``'xelatex'`` and ``'lualatex'``
+     with extras to set the math font to XITS Math (which is an excellent
+     match to FreeSerif text font).  It also makes mark-up such as
+     ``\mathbf{\Gamma}`` work as it does for HTML and ``'pdflatex'``.
+
+     .. hint:: Use ``\boldsymbol`` for boldening *lowercase* Greek letter, for
+        example
+        ``\mathbf{\Gamma\Delta\Lambda}\boldsymbol{\alpha\beta\gamma}``.
+
+   .. versionadded:: 8.1.0 The default TeX math fonts, and their AMS extensions
+      loaded from ``\usepackage{amssymb}``, do not fit well with most text
+      fonts, the quasi sole exceptions being the original Computer Modern fonts
+      and their close derivatives the Latin Modern fonts.
+
+      Sphinx sets up per default a Times-alike font for text, which thus does
+      not fit well with default math.  It is planned at Sphinx 9, for
+      ``'pdflatex'`` :confval:`latex_engine`, to use the ``'fontpkgmath'`` key
+      to inject usage of the ``stix2`` package (with suitable options) and not
+      as currently ``amssymb``.  For ``'xelatex'`` and ``'lualatex'`` the
+      switch to XITS Math was done at 8.1.0 to fix immediately some issues
+      with ``\mathbf`` and take this opportunity for math mode to better match
+      GNU FreeSerif, which is the default text font with these engines.  It
+      also means that math glyphs can be copied from PDF output as Unicode
+      characters.
 
 ``'fncychap'``
    Inclusion of the "fncychap" package (which makes fancy chapter titles),

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:
 

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 %>