Merge branch '1.7'

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

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
 

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 <latex-basic>`.)
+   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 <latex-basic>`.  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{<language>}'``.
         .. 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

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

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

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