diff --git a/CHANGES b/CHANGES index 2568168f2..ccede6ff7 100644 --- a/CHANGES +++ b/CHANGES @@ -238,6 +238,10 @@ 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 +* LaTeX: fix the :confval:`latex_engine` documentation regarding Latin Modern + font with XeLaTeX/LuaLateX (refs: #5251) Testing -------- diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index f7194a955..5ec53cf7f 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -280,7 +280,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/doc/usage/configuration.rst b/doc/usage/configuration.rst index 5d1022cc7..ba37ccdc1 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1785,15 +1785,33 @@ information. 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 @@ -2000,6 +2018,9 @@ information. 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 diff --git a/sphinx/cmd/make_mode.py b/sphinx/cmd/make_mode.py index 231e3af10..2a368e11a 100644 --- a/sphinx/cmd/make_mode.py +++ b/sphinx/cmd/make_mode.py @@ -141,7 +141,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