LaTeX: update default font configuration

This replaces times package with tgtermes and tgheros (clones of Times and Helvetica with better LaTeX support) and the monospace font from txfonts package (txtt). This font is better matched with Times-like fonts than Courier clones. The changes applies to pdflatex/platex/uplatex. Fixes: #8711
sphinx-doc · Jan 20, 2021 · a00b78c · a00b78c
1 parent 3ed7590
commit a00b78c
Show file tree

Hide file tree

Showing 8 changed files with 108 additions and 121 deletions.
diff --git a/CHANGES b/CHANGES
@@ -6,6 +6,7 @@ Dependencies
 
 * Drop python 3.5 support
 * Drop docutils 0.12 and 0.13 support
+* LaTeX: add ``tex-gyre`` font dependency
 
 Incompatible changes
 --------------------
@@ -56,6 +57,8 @@ Bugs fixed
 * #8380: html search: Paragraphs in search results are not identified as ``<p>``
 * #8342: Emit a warning if a unknown domain is given for directive or role (ex.
   ``:unknown:doc:``)
+* #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning (and font
+  change) with late TeXLive 2019
 
 Testing
 --------

diff --git a/bindep.txt b/bindep.txt
@@ -12,10 +12,12 @@ texlive-luatex85 [platform:rpm]
 texlive-anyfontsize [platform:rpm]
 texlive-ctablestack [platform:rpm]
 texlive-gnu-freefont [platform:rpm]
+texlive-tex-gyre [platform:rpm]
 latexmk [platform:rpm]
 
 texlive-latex-recommended [platform:dpkg]
 texlive-fonts-recommended [platform:dpkg]
+tex-gyre [platform:dpkg]
 texlive-latex-extra [platform:dpkg]
 texlive-luatex [platform:dpkg]
 latexmk [platform:dpkg]
diff --git a/doc/conf.py b/doc/conf.py
@@ -58,20 +58,8 @@
 latex_logo = '_static/sphinx.png'
 latex_elements = {
     'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
-    'fontpkg': r'''
-\usepackage[sc]{mathpazo}
-\usepackage[scaled]{helvet}
-\usepackage{courier}
-\substitutefont{LGR}{\rmdefault}{cmr}
-\substitutefont{LGR}{\sfdefault}{cmss}
-\substitutefont{LGR}{\ttdefault}{cmtt}
-\substitutefont{X2}{\rmdefault}{cmr}
-\substitutefont{X2}{\sfdefault}{cmss}
-\substitutefont{X2}{\ttdefault}{cmtt}
-''',
     'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}',
     'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}',
-    'fvset': '\\fvset{fontsize=auto}',
     # fix missing index entry due to RTD doing only once pdflatex after makeindex
     'printindex': r'''
 \IfFileExists{\jobname.ind}

diff --git a/doc/latex.rst b/doc/latex.rst
@@ -133,57 +133,33 @@ Keys that you may want to override include:
       ``babel``, not ``polyglossia``.
 
 ``'fontpkg'``
-   Font package inclusion. The default of ``'\\usepackage{times}'`` uses Times
-   for text, Helvetica for sans serif and Courier for monospace.
-
-   In order to support occasional Cyrillic (физика частиц) or Greek
-   letters (Σωματιδιακή φυσική) in a document whose language is
-   English or a Latin European one, the default set-up is enhanced (only for
-   ``'pdflatex'`` engine) to do:
-
-   .. code-block:: latex
-
-      \substitutefont{LGR}{\rmdefault}{cmr}
-      \substitutefont{LGR}{\sfdefault}{cmss}
-      \substitutefont{LGR}{\ttdefault}{cmtt}
-      \substitutefont{X2}{\rmdefault}{cmr}
-      \substitutefont{X2}{\sfdefault}{cmss}
-      \substitutefont{X2}{\ttdefault}{cmtt}
-
-   This is activated only under the condition that the ``'fontenc'`` key is
-   configured to load the ``LGR`` (Greek) and/or ``X2`` (Cyrillic)
-   pdflatex-font encodings (if the :confval:`language` is set to a Cyrillic
-   language, this ``'fontpkg'`` key must be used as "times" package has no
-   direct support for it; then keep only ``LGR`` lines from the above, if
-   support is needed for Greek in the text).
-
-   The ``\substitutefont`` command is from the eponymous LaTeX package, which
-   is loaded by Sphinx if needed (on Ubuntu Xenial it is part of
-   ``texlive-latex-extra`` which is a Sphinx requirement).
-
-   Only if the document actually does contain Unicode Greek letters (in text)
-   or Cyrillic letters, will the above default set-up cause additional
-   requirements for the PDF build. On Ubuntu Xenial, these are the
-   ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and (with the above
-   choice of fonts) the ``cm-super`` (or ``cm-super-minimal``) packages.
-
-   For ``'xelatex'`` and ``'lualatex'``, the default is to use the FreeFont
-   family: this OpenType font family supports both Cyrillic and Greek scripts
-   and is available as separate Ubuntu Xenial package ``fonts-freefont-otf``.
-   It is not necessary to install the much larger ``texlive-fonts-extra``
-   package.
-
-   ``'platex'`` (Japanese documents) engine supports individual Cyrillic and
-   Greek letters with no need of extra user set-up.
-
-   Default: ``'\\usepackage{times}'`` (or ``''`` when using a Cyrillic script)
+   Font package inclusion. The default is::
+
+      r"""\usepackage{tgtermes}
+      \usepackage{tgheros}
+      \renewcommand\ttdefault{txtt}
+      """
+
+   For ``'xelatex'`` and ``'lualatex'`` however the default is to use
+   the GNU FreeFont.
 
    .. versionchanged:: 1.2
       Defaults to ``''`` when the :confval:`language` uses the Cyrillic
       script.
 
    .. versionchanged:: 2.0
-      Added support for individual Greek and Cyrillic letters:
+      Incorporates some font substitution commands to help support occasional
+      Greek or Cyrillic in a document using ``'pdflatex'`` engine.
+
+   .. 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.
+
 
 ``'fncychap'``
    Inclusion of the "fncychap" package (which makes fancy chapter titles),
@@ -314,37 +290,28 @@ Keys that don't need to be overridden unless in special cases are:
    .. versionadded:: 1.2
 
 ``'fontenc'``
-   "fontenc" package inclusion.
+   Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to:
 
-   If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
-   for support of Greek letters in the document, and also ``X2`` (or
-   ``T2A``) for Cyrillic letters, like this:
+   - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional
+     Cyrillic letters (физика частиц),
 
-   .. code-block:: latex
+   - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional
+     Greek letters (Σωματιδιακή φυσική).
 
-      r'\usepackage[LGR,X2,T1]{fontenc}'
+   Use ``[LGR,X2,T1]`` rather if both are needed.
 
    .. attention::
 
-      If Greek is main language, do not use this key.  Since Sphinx 2.2.1,
-      ``xelatex`` will be used automatically as :confval:`latex_engine`.
-      Formerly, Sphinx did not support producing PDF via LaTeX with Greek as
-      main language.
-
-      Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
-      mark-up.  This is not the case anymore, and the above must be used
-      (only in case of ``'pdflatex'`` engine) if the source contains such
-      Unicode Greek.
+      - Do not use this key for a :confval:`latex_engine` other than 
+        ``'pdflatex'``.
 
-      On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
-      (for the latter, only if the ``'fontpkg'`` setting is left to its
-      default) are needed for ``LGR`` to work.  In place of ``cm-super``
-      one can install smaller ``cm-super-minimal``, but it requires the
-      LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
-      loading ``fontenc``.  Thus, use this key with this extra at its
-      start if needed.
+      - If Greek is main language, do not use this key.  Since Sphinx 2.2.1,
+        ``xelatex`` will be used automatically as :confval:`latex_engine`.
 
-   Default: ``'\\usepackage[T1]{fontenc}'``
+      - The TeX installation may need some extra packages. For example,
+        on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
+        are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and
+        ``cm-super`` are needed for support of Cyrillic.
 
    .. versionchanged:: 1.5
       Defaults to ``'\\usepackage{fontspec}'`` when
@@ -361,35 +328,40 @@ Keys that don't need to be overridden unless in special cases are:
 
    .. versionchanged:: 2.0
       Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
-      occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
-      is provided natively by ``'platex'`` and only requires suitable
-      font with ``'xelatex'/'lualatex'``).
+      occasional Greek or Cyrillic letters (``'pdflatex'``).
 
    .. versionchanged:: 2.3.0
-      ``'xelatex'`` also executes
+      ``'xelatex'`` executes
       ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid
       contractions of ``--`` into en-dash or transforms of straight quotes
       into curly ones in PDF (in non-literal text paragraphs) despite
       :confval:`smartquotes` being set to ``False``.
 
-``'textgreek'``
-   This is needed for ``pdflatex`` to support Unicode input of Greek
-   letters such as φύσις.  Expert users may want to load the ``textalpha``
-   package with its option ``normalize-symbols``.
+``'fontsubstitution'``
+   Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or
+   ``T2A``).  In case ``'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.
 
-   .. hint::
+   Ignored with :confval:`latex_engine` other than ``'pdflatex'``.
 
-      Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
-      can be supported by ``'pdflatex'`` from setting this key to
-      ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
-      will render as :math:`\alpha`.  For wider Unicode support in math
-      input, see the discussion of :confval:`latex_engine`.
+   .. versionadded:: 4.0.0
 
-   With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
-   key is ignored.
+``'textgreek'``
+   For the support of occasional Greek letters.
+
+   It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as
+   :confval:`latex_engine` and defaults to either the empty string or
+   to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on
+   whether the ``'fontenc'`` key was used with ``LGR`` or not.  Only
+   expert LaTeX users may want to customize this key.
+
+   It can also be used as ``r'\usepackage{textalpha,alphabeta}'`` to let
+   ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context.
+   For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`.
 
-   Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not
-       include the ``LGR`` option.
+   For wider Unicode support in math input, see the discussion of
+   :confval:`latex_engine`.
 
    .. versionadded:: 2.0
 
@@ -500,19 +472,25 @@ Keys that don't need to be overridden unless in special cases are:
    Default: ``'\\printindex'``
 
 ``'fvset'``
-   Customization of ``fancyvrb`` LaTeX package. The default value of
-   ``'\\fvset{fontsize=\\small}'`` is used to adjust for the large character
-   width of the monospace font, used in code-blocks.  You may need to modify
-   this if you use custom fonts.
+   Customization of ``fancyvrb`` LaTeX package.
 
-   Default: ``'\\fvset{fontsize=\\small}'``
+   The default value is ``'\\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:
+   ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like.
+
+   Default: ``'\\fvset{fontsize=auto}'``
 
    .. versionadded:: 1.8
 
    .. versionchanged:: 2.0
-      Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
-      (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
-      engines (and not ``\\fvset{fontsize=auto}``).
+      For ``'xelatex'`` and ``'lualatex'`` defaults to
+      ``'\\fvset{fontsize=\\small}'`` as this
+      is adapted to the relative widths of the FreeFont family.
+
+   .. versionchanged:: 4.0.0
+      Changed default for ``'pdflatex'``. Previously it was using 
+      ``'\\fvset{fontsize=\\small}'``.
 
 Keys that are set by other options and therefore should not be overridden are:
 

diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst
@@ -179,24 +179,22 @@ The builder's "name" must be given to the **-b** command-line option of
 
    * ``texlive-latex-recommended``
    * ``texlive-fonts-recommended``
+   * ``tex-gyre`` (if :confval:`latex_engine` is ``'pdflatex'``)
    * ``texlive-latex-extra``
    * ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X
      for functioning of ``make latexpdf``)
 
    Additional packages are needed in some circumstances (see the discussion of
    the ``'fontpkg'`` key of :confval:`latex_elements` for more information):
 
-   * to support occasional Cyrillic letters or words, and a fortiori if
-     :confval:`language` is set to a Cyrillic language, the package
-     ``texlive-lang-cyrillic`` is required, and, with unmodified ``'fontpkg'``,
-     also ``cm-super`` or ``cm-super-minimal``,
-   * to support occasional Greek letters or words (in text, not in
-     :rst:dir:`math` directive contents), ``texlive-lang-greek`` is required,
-     and, with unmodified ``'fontpkg'``, also ``cm-super`` or
-     ``cm-super-minimal``,
-   * for ``'xelatex'`` or ``'lualatex'`` (see :confval:`latex_engine`),
-     ``texlive-xetex`` resp. ``texlive-luatex``, and, if leaving unchanged
-     ``'fontpkg'``, ``fonts-freefont-otf``.
+   * ``texlive-lang-cyrillic`` for Cyrillic (even individual letters), and,
+     ``cm-super`` or ``cm-super-minimal`` (if default fonts),
+   * ``texlive-lang-greek`` for Greek (even individual letters), and,
+     ``cm-super`` or ``cm-super-minimal`` (if default fonts),
+   * ``texlive-xetex`` if :confval:`latex_engine` is ``'xelatex'``,
+   * ``texlive-luatex`` if :confval:`latex_engine` is ``'lualatex'``,
+   * ``fonts-freefont-otf`` if :confval:`latex_engine` is ``'xelatex'``
+     or ``'lualatex'``.
 
    The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution
    is based on a TeXLive 2015 snapshot dated March 2016.
@@ -207,6 +205,9 @@ The builder's "name" must be given to the **-b** command-line option of
    .. versionchanged:: 2.0
       Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).
 
+   .. versionchanged:: 4.0.0
+      TeX Gyre fonts dependency for the default LaTeX font configuration.
+
    .. note::
 
       Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows).  This

diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py
@@ -224,6 +224,8 @@ def init_multilingual(self) -> None:
                 self.context['substitutefont'] = '\\usepackage{substitutefont}'
             else:
                 self.context['textgreek'] = ''
+            if self.context['substitutefont'] == '':
+                self.context['fontsubstitution'] = ''
 
         # 'babel' key is public and user setting must be obeyed
         if self.context['babel']:

diff --git a/sphinx/builders/latex/constants.py b/sphinx/builders/latex/constants.py
@@ -11,7 +11,12 @@
 from typing import Any, Dict
 
 PDFLATEX_DEFAULT_FONTPKG = r'''
-\usepackage{times}
+\usepackage{tgtermes}
+\usepackage{tgheros}
+\renewcommand{\ttdefault}{txtt}
+'''
+
+PDFLATEX_DEFAULT_FONTSUBSTITUTION = r'''
 \expandafter\ifx\csname T@LGR\endcsname\relax
 \else
 % LGR was declared as font encoding
@@ -76,7 +81,7 @@
     'maxlistdepth':    '',
     'sphinxpkgoptions':     '',
     'sphinxsetup':     '',
-    'fvset':           '\\fvset{fontsize=\\small}',
+    'fvset':           '\\fvset{fontsize=auto}',
     'passoptionstopackages': '',
     'geometry':        '\\usepackage{geometry}',
     'inputenc':        '',
@@ -88,6 +93,7 @@
     'babel':           '\\usepackage{babel}',
     'polyglossia':     '',
     'fontpkg':         PDFLATEX_DEFAULT_FONTPKG,
+    'fontsubstitution': PDFLATEX_DEFAULT_FONTSUBSTITUTION,
     'substitutefont':  '',
     'textcyrillic':    '',
     'textgreek':       '\\usepackage{textalpha}',
@@ -142,6 +148,8 @@
         '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'
                         '{\\leavevmode\\nobreak\\ }'),
@@ -153,6 +161,8 @@
         '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'
                         '{\\leavevmode\\nobreak\\ }'),
@@ -161,7 +171,8 @@
         'latex_engine': 'platex',
         'babel':        '',
         'classoptions': ',dvipdfmx',
-        'fontpkg':      '\\usepackage{times}',
+        'fontpkg':      PDFLATEX_DEFAULT_FONTPKG,
+        'fontsubstitution': '',
         'textgreek':    '',
         'fncychap':     '',
         'geometry':     '\\usepackage[dvipdfm]{geometry}',
@@ -170,7 +181,8 @@
         'latex_engine': 'uplatex',
         'babel':        '',
         'classoptions': ',dvipdfmx',
-        'fontpkg':      '\\usepackage{times}',
+        'fontpkg':      PDFLATEX_DEFAULT_FONTPKG,
+        'fontsubstitution': '',
         'textgreek':    '',
         'fncychap':     '',
         'geometry':     '\\usepackage[dvipdfm]{geometry}',