diff --git a/CHANGES.rst b/CHANGES.rst index 5785d62ef95..023f5967d17 100644 --- a/CHANGES.rst +++ b/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 ` (quiet) option for :program:`sphinx-build -M latexpdf` or :program:`make latexpdf` (``O=-q``) get passed to :program:`latexmk`. Let :option:`-Q ` diff --git a/bindep.txt b/bindep.txt index 88470492b35..5034121c8da 100644 --- a/bindep.txt +++ b/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] diff --git a/doc/latex.rst b/doc/latex.rst index 96ae4ace1a4..9b1023148df 100644 --- a/doc/latex.rst +++ b/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 diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index e293399282e..23b81f8a91f 100644 --- a/doc/usage/builders/index.rst +++ b/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' - ` ``iconpackage`` key for more. + ``fontawesome5`` is recommended (part of Ubuntu ``texlive-fonts-extra``). + See the :ref:`'sphinxsetup' ` ``iconpackage`` key for + more. Additional packages are needed in some circumstances: diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 8ae9a0cc55a..e76449330a4 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2806,20 +2806,6 @@ These options influence LaTeX output. this, the :ref:`fontenc` key of :ref:`latex_elements ` must be used appropriately. - .. note:: - - Contrarily to :ref:`MathJaX math rendering in HTML output `, - 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 - `). - 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 diff --git a/sphinx/builders/latex/constants.py b/sphinx/builders/latex/constants.py index 9da66e82698..87d0744b4ae 100644 --- a/sphinx/builders/latex/constants.py +++ b/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': '', diff --git a/sphinx/templates/latex/latex.tex.jinja b/sphinx/templates/latex/latex.tex.jinja index deb030504db..374204e39b9 100644 --- a/sphinx/templates/latex/latex.tex.jinja +++ b/sphinx/templates/latex/latex.tex.jinja @@ -46,6 +46,7 @@ <%= substitutefont %> <%= textcyrillic %> <%= fontpkg %> +<%= fontpkgmath %> <%= fontsubstitution %> <%= textgreek %> <%= fncychap %>