From 077e9afd29929aa1892bc4fb547284c094a5fe24 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 26 Jul 2018 19:20:45 +0200 Subject: [PATCH 1/4] LaTeX: fix usage of PAPER envvar, which got broken at Sphinx 1.5 Fix: #5234 --- doc/man/sphinx-build.rst | 11 ++++++++++- sphinx/make_mode.py | 2 +- sphinx/templates/quickstart/Makefile_t | 4 ++-- sphinx/templates/quickstart/make.bat_t | 4 ++-- 4 files changed, 15 insertions(+), 6 deletions(-) diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index fdd0d36c2..3d9ee579d 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -273,7 +273,16 @@ variables to customize behavior: .. describe:: PAPER - The value for '"papersize"` key of :confval:`latex_elements`. + This sets the ``'papersize'`` key of :confval:`latex_elements`: + i.e. ``PAPER=a4`` sets it to ``'a4paper'`` and ``PAPER=letter`` to + ``'letterpaper'``. + + .. note:: + + Usage of this environment variable got broken at Sphinx 1.5 as + ``a4`` or ``letter`` ended up as option to LaTeX document in + place of the needed ``a4paper``, resp. ``letterpaper``. Fixed at + 1.7.7. .. describe:: SPHINXBUILD diff --git a/sphinx/make_mode.py b/sphinx/make_mode.py index aecad31b4..f71448ef2 100644 --- a/sphinx/make_mode.py +++ b/sphinx/make_mode.py @@ -143,7 +143,7 @@ class Make(object): papersize = os.getenv('PAPER', '') opts = self.opts if papersize in ('a4', 'letter'): - opts.extend(['-D', 'latex_elements.papersize=' + papersize]) + opts.extend(['-D', 'latex_elements.papersize=' + papersize + 'paper']) if doctreedir is None: doctreedir = self.builddir_join('doctrees') diff --git a/sphinx/templates/quickstart/Makefile_t b/sphinx/templates/quickstart/Makefile_t index bf752404e..3af40947c 100644 --- a/sphinx/templates/quickstart/Makefile_t +++ b/sphinx/templates/quickstart/Makefile_t @@ -9,8 +9,8 @@ SOURCEDIR = {{ rsrcdir }} BUILDDIR = {{ rbuilddir }} # Internal variables. -PAPEROPT_a4 = -D latex_elements.papersize=a4 -PAPEROPT_letter = -D latex_elements.papersize=letter +PAPEROPT_a4 = -D latex_elements.papersize=a4paper +PAPEROPT_letter = -D latex_elements.papersize=letterpaper # $(O) is meant as a shortcut for $(SPHINXOPTS) ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) $(SOURCEDIR) # the i18n builder cannot share the environment and doctrees with the others diff --git a/sphinx/templates/quickstart/make.bat_t b/sphinx/templates/quickstart/make.bat_t index 6e8665a49..cd96c0736 100644 --- a/sphinx/templates/quickstart/make.bat_t +++ b/sphinx/templates/quickstart/make.bat_t @@ -12,8 +12,8 @@ set SOURCEDIR={{ rsrcdir }} set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %SOURCEDIR% set I18NSPHINXOPTS=%SPHINXOPTS% %SOURCEDIR% if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_elements.papersize=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_elements.papersize=%PAPER% %I18NSPHINXOPTS% + set ALLSPHINXOPTS=-D latex_elements.papersize=%PAPER%paper %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_elements.papersize=%PAPER%paper %I18NSPHINXOPTS% ) if "%1" == "" goto help From 69f21c144c18a554a0123f14a9edd191e8377807 Mon Sep 17 00:00:00 2001 From: jfbu Date: Tue, 31 Jul 2018 19:11:04 +0200 Subject: [PATCH 2/4] Update CHANGES for PR #5235 --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index c22aefad5..d24322385 100644 --- a/CHANGES +++ b/CHANGES @@ -22,6 +22,8 @@ Bugs fixed console output (refs: #5236) * LaTeX: suppress "remreset Warning: The remreset package is obsolete" in latex console output with recent LaTeX (refs: #5237) +* #5234: PDF output: usage of PAPER environment variable is broken since Sphinx + 1.5 Testing -------- From 5a220d648ab7008ae845bc86026159f800089c29 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 2 Aug 2018 10:06:31 +0200 Subject: [PATCH 3/4] Fix LaTeX docs of Latin Modern font with XeLaTeX/LuaLaTeX refs: #5251 --- CHANGES | 2 ++ doc/config.rst | 36 +++++++++++++++++++++++++++--------- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/CHANGES b/CHANGES index d24322385..26d016677 100644 --- a/CHANGES +++ b/CHANGES @@ -24,6 +24,8 @@ Bugs fixed console output with recent LaTeX (refs: #5237) * #5234: PDF output: usage of PAPER environment variable is broken since Sphinx 1.5 +* LaTeX: fix the :confval:`latex_engine` documentation regarding Latin Modern + font with XeLaTeX/LuaLateX (refs: #5251) Testing -------- diff --git a/doc/config.rst b/doc/config.rst index d5c32ca4a..97c1a3df0 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -1632,15 +1632,33 @@ These options influence LaTeX output. See further :doc:`latex`. preamble. If your project uses such extra Unicode characters, switching the engine to - XeLaTeX or LuaLaTeX often provides a quick fix. They only work with UTF-8 - encoded sources and can (in fact, should) use OpenType fonts, either from - the system or the TeX install tree. Recent LaTeX releases will default with - these engines to the Latin Modern OpenType font, which has good coverage of - Latin and Cyrillic scripts (it is provided by standard LaTeX installation), - and Sphinx does not modify this default. Refer to the documentation of the - LaTeX ``polyglossia`` package to see how to instruct LaTeX to use some - other OpenType font if Unicode coverage proves insufficient (or use - directly ``\setmainfont`` et. al. as in :ref:`this example `.) + XeLaTeX or LuaLaTeX and setting up the document to use an OpenType font + with wide-enough glyph coverage is often easier than sticking with PDFLaTeX + and trying to get it to work with the Unicode characters. + + The :confval:`latex_elements` ``'fontpkg'`` key allows to set up the + document fonts, see :ref:`this example `. Currently, for + XeLaTeX and LuaLaTeX, Sphinx leaves this key empty and LaTeX then defaults + to the `Latin Modern`_ font family (from the TeX distribution fonts). This + font family provides good coverage of Latin scripts (European languages, + Vietnamese) but Cyrillic requires some other OpenType font; for example + Computer Modern Unicode (see `babel-russian`_ documentation on how to load + it in the LaTeX document). In future, it is planned Sphinx will provide + another default choice of OpenType font than `Latin Modern`_, perhaps + `Libertinus`_, which is included in recent TeX distributions and supports + Latin and Cyrillic and also has an accompanying math font. + + With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use + `polyglossia`_. For some languages the `babel`_ support appears + preferable; Sphinx uses currently `babel`_ for French and perhaps will also + for some more languages in future. One can use the + :confval:`latex_elements` ``'babel'`` key to override Sphinx's default. + + .. _`Latin Modern`: http://www.gust.org.pl/projects/e-foundry/latin-modern + .. _`polyglossia`: https://ctan.org/pkg/polyglossia + .. _`babel`: https://ctan.org/pkg/babel + .. _`babel-russian`: https://ctan.org/pkg/babel-russian + .. _`Libertinus`: https://ctan.org/pkg/libertinus .. confval:: latex_documents From 8a23ad1f44894afefe722fbf43b3ce05d3fa1de0 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 2 Aug 2018 12:46:33 +0200 Subject: [PATCH 4/4] Update LaTeX docs for a 1.7.6 change (refs #5178) --- doc/config.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/config.rst b/doc/config.rst index 97c1a3df0..ddce9a99b 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -1820,6 +1820,9 @@ These options influence LaTeX output. See further :doc:`latex`. is ``'\\usepackage{polyglossia}\n\\setmainlanguage{}'``. .. versionchanged:: 1.6 ``'lualatex'`` uses same default setting as ``'xelatex'`` + .. versionchanged:: 1.7.6 + For French, ``xelatex`` and ``lualatex`` default to using + ``babel``, not ``polyglossia``. ``'fontpkg'`` Font package inclusion, default ``'\\usepackage{times}'`` (which uses Times for text, Helvetica for sans serif and Courier for code-blocks).