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

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

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGES.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@ Dependencies
Incompatible changes
--------------------

* LaTeX: The inclusion of ``amssymb`` LaTeX package is done after the contents
of :ref:`fontpkg`, and originates in the new :ref:`fontpkgmath` key of
:ref:`latex_elements <latex_elements_confval>`. Thus, move custom math
set-up from :ref:`fontpkg` to :ref:`fontpkgmath` to avoid getting overridden
by ``amssymb``. Regarding Unicode latex engines, they do not use
``amssymb`` anymore, but ``unicode-math`` with the XITS Math font (refs:
#12714).
* #12763: Remove unused internal class ``sphinx.util.Tee``.
Patch by Adam Turner.

Expand Down Expand Up @@ -69,6 +76,10 @@ 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.
Patch by Jean-François B.
* #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>`
Expand Down
2 changes: 2 additions & 0 deletions bindep.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Comment on lines +19 to +20
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, it seems all are "subpackages" of texlive which we require earlier in this bindep.txt for Fedora, see also here, so I am not sure we really need this and/or any of the other lines.

As per Ubuntu, unicode-math is part of texlive-latex-recommended, and XITS Math of texlive-fonts-extras which we both require already.

latexmk [platform:rpm]

texlive-latex-recommended [platform:dpkg]
Expand Down
37 changes: 37 additions & 0 deletions doc/latex.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions doc/usage/builders/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Expand All @@ -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:

Expand Down
21 changes: 7 additions & 14 deletions doc/usage/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
53 changes: 52 additions & 1 deletion sphinx/builders/latex/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@
\renewcommand{\ttdefault}{txtt}
'''

PDFLATEX_DEFAULT_FONTPKGMATH = r'''
\usepackage{amssymb}% may become stix2 at some future version
'''

PDFLATEX_DEFAULT_FONTSUBSTITUTION = r'''
\expandafter\ifx\csname T@LGR\endcsname\relax
\else
Expand Down Expand Up @@ -58,12 +62,54 @@
]
'''

XELATEX_DEFAULT_FONTPKGMATH = r'''
\usepackage{unicode-math}
\setmathfont{XITSMath-Regular.otf}[
StylisticSet=1,% choice of shape for "\mathcal"
BoldFont=XITSMath-Bold.otf,
ItalicFont=XITS-Italic.otf,% text only (\mathit)
BoldItalicFont=XITS-BoldItalic.otf,% text only
NFSSFamily=XITS,
]
\makeatletter
\AtBeginDocument{%
% work around unicode-math problems with \mathbf{\Gamma} et al.
\SetMathAlphabet{\mathrm}{normal}{TU}{XITS}{m}{n}
\SetMathAlphabet{\mathit}{normal}{TU}{XITS}{m}{it}
\SetMathAlphabet{\mathbf}{normal}{TU}{XITS}{b}{n}
\SetMathAlphabet{\mathrm}{bold}{TU}{XITS}{b}{n}
\SetMathAlphabet{\mathit}{bold}{TU}{XITS}{b}{it}
\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}
Comment on lines +94 to +101
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This brings legibility benefits. When time will come at Sphinx 9 for using stix2 in place of amssymb for pdflatex engine, these settings will be re-used probably identically and are then completely necessary to work around some obvious rendering problems with stix2 such as stipub/stix_type1#4.

}
\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',
Expand All @@ -82,11 +128,12 @@
'utf8extra': '',
'cmappkg': '\\usepackage{cmap}',
'fontenc': '\\usepackage[T1]{fontenc}',
'amsmath': '\\usepackage{amsmath,amssymb,amstext}',
'amsmath': '\\usepackage{amsmath,amstext}',
jfbu marked this conversation as resolved.
Show resolved Hide resolved
'multilingual': '',
'babel': '\\usepackage{babel}',
'polyglossia': '',
'fontpkg': PDFLATEX_DEFAULT_FONTPKG,
'fontpkgmath': PDFLATEX_DEFAULT_FONTPKGMATH,
'fontsubstitution': PDFLATEX_DEFAULT_FONTSUBSTITUTION,
'substitutefont': '',
'textcyrillic': '',
Expand Down Expand Up @@ -142,6 +189,7 @@
'fontenc': ('\\usepackage{fontspec}\n'
'\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'),
'fontpkg': XELATEX_DEFAULT_FONTPKG,
'fontpkgmath': XELATEX_DEFAULT_FONTPKGMATH,
'fvset': '\\fvset{fontsize=\\small}',
'fontsubstitution': '',
'textgreek': '',
Expand All @@ -155,6 +203,7 @@
'fontenc': ('\\usepackage{fontspec}\n'
'\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'),
'fontpkg': LUALATEX_DEFAULT_FONTPKG,
'fontpkgmath': LUALATEX_DEFAULT_FONTPKGMATH,
'fvset': '\\fvset{fontsize=\\small}',
'fontsubstitution': '',
'textgreek': '',
Expand All @@ -166,6 +215,7 @@
'babel': '',
'classoptions': ',dvipdfmx',
'fontpkg': PDFLATEX_DEFAULT_FONTPKG,
'fontpkgmath': PDFLATEX_DEFAULT_FONTPKGMATH,
'fontsubstitution': '',
'textgreek': '',
'fncychap': '',
Expand All @@ -176,6 +226,7 @@
'babel': '',
'classoptions': ',dvipdfmx',
'fontpkg': PDFLATEX_DEFAULT_FONTPKG,
'fontpkgmath': PDFLATEX_DEFAULT_FONTPKGMATH,
'fontsubstitution': '',
'textgreek': '',
'fncychap': '',
Expand Down
1 change: 1 addition & 0 deletions sphinx/templates/latex/latex.tex.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
<%= substitutefont %>
<%= textcyrillic %>
<%= fontpkg %>
<%= fontpkgmath %>
<%= fontsubstitution %>
<%= textgreek %>
<%= fncychap %>
Expand Down