Merge pull request #8716 from jfbu/latex_font_for_pdflatex

LaTeX: update default font configuration

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
 --------------------
@@ -60,6 +61,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
 --------

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]

doc/conf.py

@@ -58,20 +58,8 @@ latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
 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}

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
+   Font package inclusion. The default is::
-   for text, Helvetica for sans serif and Courier for monospace.
 
-   In order to support occasional Cyrillic (физика частиц) or Greek
+      r"""\usepackage{tgtermes}
-   letters (Σωματιδιακή φυσική) in a document whose language is
+      \usepackage{tgheros}
-   English or a Latin European one, the default set-up is enhanced (only for
+      \renewcommand\ttdefault{txtt}
-   ``'pdflatex'`` engine) to do:
+      """
 
-   .. code-block:: latex
+   For ``'xelatex'`` and ``'lualatex'`` however the default is to use
-
+   the GNU FreeFont.
-      \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)
 
    .. 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``
+   - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional
-   for support of Greek letters in the document, and also ``X2`` (or
+     Cyrillic letters (физика частиц),
-   ``T2A``) for Cyrillic letters, like this:
 
-   .. 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,
+      - Do not use this key for a :confval:`latex_engine` other than 
+        ``'pdflatex'``.
+
+      - 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
+      - The TeX installation may need some extra packages. For example,
-      mark-up.  This is not the case anymore, and the above must be used
+        on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
-      (only in case of ``'pdflatex'`` engine) if the source contains such
+        are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and
-      Unicode Greek.
+        ``cm-super`` are needed for support of Cyrillic.
-
-      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.
-
-   Default: ``'\\usepackage[T1]{fontenc}'``
 
    .. versionchanged:: 1.5
       Defaults to ``'\\usepackage{fontspec}'`` when
@@ -361,32 +328,37 @@ 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
+      occasional Greek or Cyrillic letters (``'pdflatex'``).
-      is provided natively by ``'platex'`` and only requires suitable
-      font with ``'xelatex'/'lualatex'``).
 
    .. 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``.
 
+``'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.
+
+   Ignored with :confval:`latex_engine` other than ``'pdflatex'``.
+
+   .. versionadded:: 4.0.0
+
 ``'textgreek'``
-   This is needed for ``pdflatex`` to support Unicode input of Greek
+   For the support of occasional Greek letters.
-   letters such as φύσις.  Expert users may want to load the ``textalpha``
-   package with its option ``normalize-symbols``.
 
-   .. hint::
+   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.
 
-      Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
+   It can also be used as ``r'\usepackage{textalpha,alphabeta}'`` to let
-      can be supported by ``'pdflatex'`` from setting this key to
+   ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context.
-      ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
+   For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`.
-      will render as :math:`\alpha`.  For wider Unicode support in math
-      input, see the discussion of :confval:`latex_engine`.
-
-   With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
-   key is ignored.
 
    Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not
    include the ``LGR`` option.
@@ -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
+   Customization of ``fancyvrb`` LaTeX package.
-   ``'\\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.
 
-   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'``
+      For ``'xelatex'`` and ``'lualatex'`` defaults to
-      (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
+      ``'\\fvset{fontsize=\\small}'`` as this
-      engines (and not ``\\fvset{fontsize=auto}``).
+      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:
 

doc/usage/builders/index.rst

@@ -179,6 +179,7 @@ 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``)
@@ -186,17 +187,14 @@ The builder's "name" must be given to the **-b** command-line option of
    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
+   * ``texlive-lang-cyrillic`` for Cyrillic (even individual letters), and,
-     :confval:`language` is set to a Cyrillic language, the package
+     ``cm-super`` or ``cm-super-minimal`` (if default fonts),
-     ``texlive-lang-cyrillic`` is required, and, with unmodified ``'fontpkg'``,
+   * ``texlive-lang-greek`` for Greek (even individual letters), and,
-     also ``cm-super`` or ``cm-super-minimal``,
+     ``cm-super`` or ``cm-super-minimal`` (if default fonts),
-   * to support occasional Greek letters or words (in text, not in
+   * ``texlive-xetex`` if :confval:`latex_engine` is ``'xelatex'``,
-     :rst:dir:`math` directive contents), ``texlive-lang-greek`` is required,
+   * ``texlive-luatex`` if :confval:`latex_engine` is ``'lualatex'``,
-     and, with unmodified ``'fontpkg'``, also ``cm-super`` or
+   * ``fonts-freefont-otf`` if :confval:`latex_engine` is ``'xelatex'``
-     ``cm-super-minimal``,
+     or ``'lualatex'``.
-   * for ``'xelatex'`` or ``'lualatex'`` (see :confval:`latex_engine`),
-     ``texlive-xetex`` resp. ``texlive-luatex``, and, if leaving unchanged
-     ``'fontpkg'``, ``fonts-freefont-otf``.
 
    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

sphinx/builders/latex/__init__.py

@@ -224,6 +224,8 @@ class LaTeXBuilder(Builder):
                 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']:

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 @@ DEFAULT_SETTINGS = {
     'maxlistdepth':    '',
     'sphinxpkgoptions':     '',
     'sphinxsetup':     '',
-    'fvset':           '\\fvset{fontsize=\\small}',
+    'fvset':           '\\fvset{fontsize=auto}',
     'passoptionstopackages': '',
     'geometry':        '\\usepackage{geometry}',
     'inputenc':        '',
@@ -88,6 +93,7 @@ DEFAULT_SETTINGS = {
     'babel':           '\\usepackage{babel}',
     'polyglossia':     '',
     'fontpkg':         PDFLATEX_DEFAULT_FONTPKG,
+    'fontsubstitution': PDFLATEX_DEFAULT_FONTSUBSTITUTION,
     'substitutefont':  '',
     'textcyrillic':    '',
     'textgreek':       '\\usepackage{textalpha}',
@@ -142,6 +148,8 @@ ADDITIONAL_SETTINGS = {
         '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 @@ ADDITIONAL_SETTINGS = {
         '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 @@ ADDITIONAL_SETTINGS = {
         'latex_engine': 'platex',
         'babel':        '',
         'classoptions': ',dvipdfmx',
-        'fontpkg':      '\\usepackage{times}',
+        'fontpkg':      PDFLATEX_DEFAULT_FONTPKG,
+        'fontsubstitution': '',
         'textgreek':    '',
         'fncychap':     '',
         'geometry':     '\\usepackage[dvipdfm]{geometry}',
@@ -170,7 +181,8 @@ ADDITIONAL_SETTINGS = {
         'latex_engine': 'uplatex',
         'babel':        '',
         'classoptions': ',dvipdfmx',
-        'fontpkg':      '\\usepackage{times}',
+        'fontpkg':      PDFLATEX_DEFAULT_FONTPKG,
+        'fontsubstitution': '',
         'textgreek':    '',
         'fncychap':     '',
         'geometry':     '\\usepackage[dvipdfm]{geometry}',

sphinx/templates/latex/latex.tex_t

@@ -29,6 +29,7 @@
 <%= substitutefont %>
 <%= textcyrillic %>
 <%= fontpkg %>
+<%= fontsubstitution %>
 <%= textgreek %>
 <%= fncychap %>
 \usepackage<%= sphinxpkgoptions %>{sphinx}

tests/test_build_latex.py

@@ -524,7 +524,7 @@ def test_babel_with_no_language_settings(app, status, warning):
     print(warning.getvalue())
     assert '\\documentclass[letterpaper,10pt,english]{sphinxmanual}' in result
     assert '\\usepackage{babel}' in result
-    assert '\\usepackage{times}' in result
+    assert '\\usepackage{tgtermes}' in result
     assert '\\usepackage[Bjarne]{fncychap}' in result
     assert ('\\addto\\captionsenglish{\\renewcommand{\\contentsname}{Table of content}}\n'
             in result)
@@ -549,7 +549,7 @@ def test_babel_with_language_de(app, status, warning):
     print(warning.getvalue())
     assert '\\documentclass[letterpaper,10pt,ngerman]{sphinxmanual}' in result
     assert '\\usepackage{babel}' in result
-    assert '\\usepackage{times}' in result
+    assert '\\usepackage{tgtermes}' in result
     assert '\\usepackage[Sonny]{fncychap}' in result
     assert ('\\addto\\captionsngerman{\\renewcommand{\\contentsname}{Table of content}}\n'
             in result)
@@ -574,7 +574,7 @@ def test_babel_with_language_ru(app, status, warning):
     print(warning.getvalue())
     assert '\\documentclass[letterpaper,10pt,russian]{sphinxmanual}' in result
     assert '\\usepackage{babel}' in result
-    assert '\\usepackage{times}' not in result
+    assert '\\usepackage{tgtermes}' not in result
     assert '\\usepackage[Sonny]{fncychap}' in result
     assert ('\\addto\\captionsrussian{\\renewcommand{\\contentsname}{Table of content}}\n'
             in result)
@@ -599,7 +599,7 @@ def test_babel_with_language_tr(app, status, warning):
     print(warning.getvalue())
     assert '\\documentclass[letterpaper,10pt,turkish]{sphinxmanual}' in result
     assert '\\usepackage{babel}' in result
-    assert '\\usepackage{times}' in result
+    assert '\\usepackage{tgtermes}' in result
     assert '\\usepackage[Sonny]{fncychap}' in result
     assert ('\\addto\\captionsturkish{\\renewcommand{\\contentsname}{Table of content}}\n'
             in result)
@@ -624,7 +624,7 @@ def test_babel_with_language_ja(app, status, warning):
     print(warning.getvalue())
     assert '\\documentclass[letterpaper,10pt,dvipdfmx]{sphinxmanual}' in result
     assert '\\usepackage{babel}' not in result
-    assert '\\usepackage{times}' in result
+    assert '\\usepackage{tgtermes}' in result
     assert '\\usepackage[Sonny]{fncychap}' not in result
     assert '\\renewcommand{\\contentsname}{Table of content}\n' in result
     assert '\\shorthandoff' not in result
@@ -648,7 +648,7 @@ def test_babel_with_unknown_language(app, status, warning):
     print(warning.getvalue())
     assert '\\documentclass[letterpaper,10pt,english]{sphinxmanual}' in result
     assert '\\usepackage{babel}' in result
-    assert '\\usepackage{times}' in result
+    assert '\\usepackage{tgtermes}' in result
     assert '\\usepackage[Sonny]{fncychap}' in result
     assert ('\\addto\\captionsenglish{\\renewcommand{\\contentsname}{Table of content}}\n'
             in result)
@@ -676,7 +676,7 @@ def test_polyglossia_with_language_de(app, status, warning):
     assert '\\documentclass[letterpaper,10pt,german]{sphinxmanual}' in result
     assert '\\usepackage{polyglossia}' in result
     assert '\\setmainlanguage[spelling=new]{german}' in result
-    assert '\\usepackage{times}' not in result
+    assert '\\usepackage{tgtermes}' not in result
     assert '\\usepackage[Sonny]{fncychap}' in result
     assert ('\\addto\\captionsgerman{\\renewcommand{\\contentsname}{Table of content}}\n'
             in result)
@@ -702,7 +702,7 @@ def test_polyglossia_with_language_de_1901(app, status, warning):
     assert '\\documentclass[letterpaper,10pt,german]{sphinxmanual}' in result
     assert '\\usepackage{polyglossia}' in result
     assert '\\setmainlanguage[spelling=old]{german}' in result
-    assert '\\usepackage{times}' not in result
+    assert '\\usepackage{tgtermes}' not in result
     assert '\\usepackage[Sonny]{fncychap}' in result
     assert ('\\addto\\captionsgerman{\\renewcommand{\\contentsname}{Table of content}}\n'
             in result)