IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #8716 from jfbu/latex_font_for_pdflatex

Browse Source 
LaTeX: update default font configuration
This commit is contained in:
Jean-François B 2021-01-23 09:22:18 +01:00 committed by GitHub
commit 38c6143470
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 112 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGES
View File

@ -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
--------

2
bindep.txt
View File

@ -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]

12
doc/conf.py
View File

@ -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}

158
doc/latex.rst
View File

@ -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:

23
doc/usage/builders/index.rst
View File

@ -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

2
sphinx/builders/latex/__init__.py
View File

@ -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']:

20
sphinx/builders/latex/constants.py
View File

@ -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}',

1
sphinx/templates/latex/latex.tex_t
View File

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

16
tests/test_build_latex.py
View File

@ -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)