diff --git a/CHANGES b/CHANGES index 641779ddc..f9c046ca6 100644 --- 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 -------------------- @@ -60,6 +61,8 @@ Bugs fixed * #8380: html search: Paragraphs in search results are not identified as ``

`` * #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 index dfee52c28..0c599b9f2 100644 --- 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 index 9f018bc7b..deccc2e9a 100644 --- a/doc/conf.py +++ b/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} diff --git a/doc/latex.rst b/doc/latex.rst index 35e38acb4..2ff14af2d 100644 --- 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. + Font package inclusion. The default is:: - 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: + r"""\usepackage{tgtermes} + \usepackage{tgheros} + \renewcommand\ttdefault{txtt} + """ - .. 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) + 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. + - Do not use this key for a :confval:`latex_engine` other than + ``'pdflatex'``. - 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. + - If Greek is main language, do not use this key. Since Sphinx 2.2.1, + ``xelatex`` will be used automatically as :confval:`latex_engine`. - 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}'`` + - 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,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 - 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``. +``'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 - letters such as φύσις. Expert users may want to load the ``textalpha`` - package with its option ``normalize-symbols``. + For the support of occasional Greek letters. - .. 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` - 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`. - - With ``'platex'`` (Japanese), ``'xelatex'`` or ``'lualatex'``, this - key is ignored. + 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. @@ -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 index c45a8062f..74853fee9 100644 --- a/doc/usage/builders/index.rst +++ b/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 - :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 index dc5b66518..efe922fa5 100644 --- a/sphinx/builders/latex/__init__.py +++ b/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']: diff --git a/sphinx/builders/latex/constants.py b/sphinx/builders/latex/constants.py index 0b20c7cef..e929736a7 100644 --- 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 @@ 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}', diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t index 5082254e7..88efab8f0 100644 --- a/sphinx/templates/latex/latex.tex_t +++ b/sphinx/templates/latex/latex.tex_t @@ -29,6 +29,7 @@ <%= substitutefont %> <%= textcyrillic %> <%= fontpkg %> +<%= fontsubstitution %> <%= textgreek %> <%= fncychap %> \usepackage<%= sphinxpkgoptions %>{sphinx} diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index 58b9bc419..c4584a15e 100644 --- a/tests/test_build_latex.py +++ b/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)