From bf431ed0d7ec1423edf72c717887bdea7ad1f277 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Sun, 25 Aug 2024 17:07:49 +0200 Subject: [PATCH] LaTeX: do not use ``\small`` with FreeMono, but ``Scale=0.9`` (#12822) --- CHANGES.rst | 5 ++++ doc/latex.rst | 44 ++++++++++++++++++------------ sphinx/builders/latex/constants.py | 4 +-- 3 files changed, 33 insertions(+), 20 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 707f2627ed4..85bf74f26f7 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -12,6 +12,11 @@ Incompatible changes * #12763: Remove unused internal class ``sphinx.util.Tee``. Patch by Adam Turner. +* #12822: LaTeX: for Unicode engines, the :ref:`fvset` default is changed to + ``'\\fvset{fontsize=auto}'`` from ``'\\fvset{fontsize=\\small}'``. + Code-blokcs are unchanged as FreeMono is now loaded with ``Scale=0.9``. + An adjustement to existing projects is needed only if they used a custom + :ref:`fontpkg` configuration and did not set :ref:`fvset`. Deprecated ---------- diff --git a/doc/latex.rst b/doc/latex.rst index 96ae4ace1a4..fce61480941 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -185,7 +185,7 @@ Keys that you may want to override include: :code-tex:`\\setmainfont`, :code-tex:`\\setsansfont` and :code-tex:`\\setmonofont` commands of LaTeX package ``fontspec`` (included via :ref:`fontenc`) are used to set up the OpenType fonts GNU FreeSerif, - FreeSans, and FreeMono as document fonts. + FreeSans, and FreeMono (scaled with ratio ``0.9``) as document fonts. .. versionchanged:: 1.2 Defaults to ``''`` when the :confval:`language` uses the Cyrillic @@ -202,6 +202,13 @@ 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 + The monospace font FreeMono used with Unicode engines is loaded at scale + ``0.9``. This replaces the former mechanism via :ref:`fvset` which + configured code-blocks to use :code-tex:`\\small`. Inline literals now + fit better in their surrounding text, and it is easier to set up custom + fonts, as :ref:`fvset` does not intervene anymore by default. + ``'fncychap'`` Inclusion of the "fncychap" package (which makes fancy chapter titles), default :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English documentation @@ -416,7 +423,7 @@ Keys that don't need to be overridden unless in special cases are: ``'fontsubstitution'`` Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or - ``T2A``). In case ``'fontpkg'`` key is configured for usage with some + ``T2A``). In case :ref:`fontpkg` key is configured for usage with some TeX fonts known to be available in the ``LGR`` or ``X2`` encodings, set this one to be the empty string. Else leave to its default. @@ -468,7 +475,7 @@ Keys that don't need to be overridden unless in special cases are: The location in the LaTeX file has been moved to after :code-tex:`\\usepackage{sphinx}` and :code-tex:`\\sphinxsetup{..}`, hence also after - insertion of ``'fontpkg'`` key. This is in order to handle the paper + insertion of :ref:`fontpkg` key. This is in order to handle the paper layout options in a special way for Japanese documents: the text width will be set to an integer multiple of the *zenkaku* width, and the text height to an integer multiple of the baseline. See the @@ -559,13 +566,17 @@ Keys that don't need to be overridden unless in special cases are: Default: :code-tex:`r'\\printindex'` +.. _fvset: + ``'fvset'`` Customization of ``fancyvrb`` LaTeX package. - The default value is :code-tex:`r'\\fvset{fontsize=auto}'` which means that the - font size will adjust correctly if a code-block ends up in a footnote. - You may need to modify this if you use custom fonts: - :code-tex:`r'\\fvset{fontsize=\\small}'` if the monospace font is Courier-like. + The default value is :code-tex:`r'\\fvset{fontsize=auto}'` which means that + the font size will adjust correctly if a code-block ends up in a footnote. + You may need to modify this when using a custom monospace font, for example + set it to :code-tex:`r'\\fvset{fontsize=\\small}'` if it is Courier-like + (for Unicode engines, it is recommended to use rather the ``Scale`` + interface of :code-tex:`\\setmonofont` LaTeX command from ``fontspec``). Default: :code-tex:`r'\\fvset{fontsize=auto}'` @@ -584,6 +595,12 @@ Keys that don't need to be overridden unless in special cases are: Changed default for Chinese documents to :code-tex:`r'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'` + .. versionchanged:: 8.1.0 + Changed default for ``'xelatex'`` and ``'lualatex'`` to be also + :code-tex:`r'\\fvset{fontsize=auto}'`. The rescaling for default + monospace font FreeMono is now set via the LaTeX package ``fontspec`` + interface rather. See :ref:`fontpkg`. + Keys that are set by other options and therefore should not be overridden are: ``'docclass'`` @@ -1439,19 +1456,12 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and tokens; it does color the line numbers, but if one wants to color *only* them one has to go through the ``fancyvrb`` interface. - - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of - the :confval:`latex_elements` key ``'fvset'``. For ``'lualatex'`` or - ``'xelatex'`` Sphinx includes in the preamble already - :code-tex:`\\fvset{fontsize=\\small}` and this induces ``fancyvrb`` - into overriding a :code-tex:`\\footnotesize` coming from - ``pre_TeXextras``. One has to use - :code-tex:`pre_TeXextras=\\fvset{fontsize=\\footnotesize}` syntax. - Simpler to set directly the :confval:`latex_elements` key - ``'fvset'``... + - ``pre_TeXextras=\footnotesize`` (as an example) is equivalent to setting + :ref:`fvset` key value to :code-tex:`r'\\fvset{fontsize=\\footnotesize}'`. Consider these options experimental and that some implementation details may change. For example if the ``pre_TeXextras`` LaTeX commands were put - by Sphinx in another location it could override the ``'fvset'`` effect, + by Sphinx in another location it could override the :ref:`fvset` effect, perhaps this is what will be done in a future release. - Rounded boxes are done using the pict2e_ interface to some basic PDF diff --git a/sphinx/builders/latex/constants.py b/sphinx/builders/latex/constants.py index 9da66e82698..4da2de36f38 100644 --- a/sphinx/builders/latex/constants.py +++ b/sphinx/builders/latex/constants.py @@ -49,7 +49,7 @@ BoldFont = *Bold, BoldItalicFont = *BoldOblique, ] -\setmonofont{FreeMono}[ +\setmonofont{FreeMono}[Scale=0.9, Extension = .otf, UprightFont = *, ItalicFont = *Oblique, @@ -142,7 +142,6 @@ 'fontenc': ('\\usepackage{fontspec}\n' '\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'), 'fontpkg': XELATEX_DEFAULT_FONTPKG, - 'fvset': '\\fvset{fontsize=\\small}', 'fontsubstitution': '', 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' @@ -155,7 +154,6 @@ 'fontenc': ('\\usepackage{fontspec}\n' '\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'), 'fontpkg': LUALATEX_DEFAULT_FONTPKG, - 'fvset': '\\fvset{fontsize=\\small}', 'fontsubstitution': '', 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0'