Fix #3356 and #3394 (latex) text layout of Japanese documents

- make text width integer multiple of zenkaku width

- fix incompatibility of ``geometry`` package with ``jsbook`` LaTeX
  class (``'manual'`` docclass)

- fix issue with shortened text area height in ``'manual'`` docclass

CHANGES

@@ -20,6 +20,9 @@ Bugs fixed
 * #3364: sphinx-quickstart prompts overflow on Console with 80 chars width
 * since 1.5, PDF's TOC and bookmarks lack an entry for general Index
   (refs: #3383)
+* #3356: Page layout for Japanese ``'manual'`` docclass has a shorter text area
+* #3394: When ``'pointsize'`` is not ``10pt``, Japanese ``'manual'`` document
+  gets wrong PDF page dimensions
 
 Testing
 --------

doc/config.rst

@@ -1733,13 +1733,36 @@ These options influence LaTeX output. See further :doc:`latex`.
      ``'geometry'``
         "geometry" package inclusion, the default definition is:
 
-          ``'\\usepackage[margin=1in,marginparwidth=0.5in]{geometry}'``.
+          ``'\\usepackage{geometry}'`` (with ``[dvipdfm]`` for Japanese documents)
+
+        and :file:`sphinx.sty` executes a ``\PassOptionsToPackages`` with
+        ``hmargin=1in,vmargin=1in,marginparwidth=0.5in``. See :doc:`latex`
+        for the corresponding ``'sphinxsetup'`` options.
 
         .. versionadded:: 1.5
 
         .. versionchanged:: 1.5.2
-           For Japanese documents also ``dvipdfm`` option is passed to
-           ``geometry``.
+           ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.
+
+        .. versionadded:: 1.5.3
+           The ``'sphinxsetup'`` margin keys. See :doc:`latex`.
+
+        .. versionchanged:: 1.5.3
+           The key is executed after the  ``\sphinxsetup`` which follows
+           immediately the loading of :file:`sphinx.sty`. This is in order
+           to handle the paper layout options in a special way for Japanese
+           documents: the text width will be set to an integer multiple of the
+           *zenkaku* width, and the text height to an integer multiple
+           of the baseline.
+
+           Further, as the ``jsbook`` Japanese standard document class handles
+           pointsize other than ``10pt`` in a special manner, Sphinx uses then
+           as first document class option ``truedimen``: this will be received
+           by ``geometry`` package and help it interpret correctly further
+           class options such as ``letterpaper`` or ``a4paper``.
+
+           For ``jreport`` (Japanese ``'howto'`` documents), the situation is
+           otherwise, and the ``truedimen`` must not be used for ``geometry``.
 
      ``'babel'``
         "babel" package inclusion, default ``'\\usepackage{babel}'`` (the

doc/latex.rst

@@ -137,6 +137,55 @@ Here are the currently available options together with their default values.
    LaTeX requires for keys with Boolean values to use **lowercase** ``true`` or
    ``false``.
 
+``hmargin``
+    The dimensions of the horizontal margins. Legacy Sphinx default value is
+    ``1in`` (which stands for ``{1in,1in}``.) It is passed over as ``hmargin``
+    option to ``geometry`` package.
+
+    Here is an example for non-Japanese documents of use of this key::
+
+      'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
+
+    Japanese documents currently accept only the form with only one dimension.
+    This option is handled then in a special manner in order for ``geometry``
+    package to set the text width to an exact multiple of the *zenkaku* width
+    of the base document font.
+
+    .. attention::
+
+       For a ``'manual'`` type document, which by default uses the ``jsbook``
+       LaTeX document class, the dimension units must be so-called "true"
+       units:
+
+         'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=2zw'
+
+       This is due to ``jsbook`` LaTeX class way of handling the pointsize
+       when it is not ``10pt``.
+
+       To the contrary, the ``jreport`` class, which is used for ``'howto'``
+       document must be configured with "normal" units.
+
+    .. versionadded:: 1.5.3
+
+``vmargin``
+    The dimension of the vertical margins. Legacy Sphinx default value is
+    ``1in`` (or ``{1in,1in}``.) Passed over as ``vmargin`` option to
+    ``geometry``.
+
+    Japanese documents will arrange for the text height to be an integer
+    multiple of the baselineskip, taking the closest match suitable for the
+    asked-for vertical margin. It can then be only one dimension. See notice
+    above.
+
+    .. versionadded:: 1.5.3
+
+``marginpar``
+    The ``\marginparwidth`` LaTeX dimension, defaults to ``0.5in``. For Japanese
+    documents, the value is modified to be the closest integer multiple of the
+    *zenkaku* width.
+
+    .. versionadded:: 1.5.3
+
 ``verbatimwithframe``
     default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal
     includes are framed. Setting it to ``false`` does not deactivate use of

sphinx/templates/latex/content.tex_t

@@ -14,7 +14,6 @@
    \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
 \fi \sphinxpxdimen=<%= pxunit %>\relax
 <%= passoptionstopackages %>
-<%= geometry %>
 <%= inputenc %>
 <%= utf8extra %>
 <%= cmappkg %>
@@ -26,6 +25,7 @@
 <%= longtable %>
 \usepackage<%= sphinxpkgoptions %>{sphinx}
 <%= sphinxsetup %>
+<%= geometry %>
 \usepackage{multirow}
 \usepackage{eqparbox}
 <%= usepackages %>

sphinx/texinputs/sphinx.sty

@@ -6,7 +6,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2017/01/16 v1.5.2 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2017/02/03 v1.5.3 LaTeX package (Sphinx markup)]
 
 % we delay handling of options to after having loaded packages, because
 % of the need to use \definecolor.
@@ -61,6 +61,18 @@
 \RequirePackage{kvoptions}
 \SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix
 
+% Sphinx legacy text layout: 1in margins on all four sides
+\ifx\@jsc@uplatextrue\undefined
+\DeclareStringOption[1in]{hmargin}
+\DeclareStringOption[1in]{vmargin}
+\DeclareStringOption[.5in]{marginpar}
+\else
+% Japanese standard document classes handle \mag in a special way
+\DeclareStringOption[\inv@mag in]{hmargin}
+\DeclareStringOption[\inv@mag in]{vmargin}
+\DeclareStringOption[.5\dimexpr\inv@mag in\relax]{marginpar}
+\fi
+
 \DeclareBoolOption{dontkeepoldnames} % \ifspx@opt@dontkeepoldnames = \iffalse
 \DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0}
 
@@ -1052,13 +1064,44 @@
   {\endlist}
 \fi
 
-% adjust the margins for footer,
-% this works with the jsclasses only (Japanese standard document classes)
-% FIXME: rather, pass options to "geometry".
+\ifx\kanjiskip\undefined
+  \PassOptionsToPackage{%
+     hmargin={\unexpanded{\spx@opt@hmargin}},%
+     vmargin={\unexpanded{\spx@opt@vmargin}},%
+     marginpar=\unexpanded{\spx@opt@marginpar}}
+  {geometry}
+\else
+ % set text width for Japanese documents to be integer multiple of 1zw
+ % and text height to be integer multiple of \baselineskip
+ % the execution is delayed to \sphinxsetup then geometry.sty
+ \normalsize\normalfont
+ \newcommand*\sphinxtextwidthja[1]{%
+    \if@twocolumn\tw@\fi
+    \dimexpr
+       \numexpr\dimexpr\paperwidth-\dimexpr#1+#1\relax\relax/
+               \dimexpr\if@twocolumn\tw@\else\@ne\fi zw\relax
+    zw\relax}%
+ \newcommand*\sphinxmarginparwidthja[1]{%
+    \dimexpr\numexpr\dimexpr#1\relax/\dimexpr1zw\relax zw\relax}%
+ \newcommand*\sphinxtextlinesja[1]{%
+    \numexpr\@ne+\dimexpr\paperheight-\topskip-\dimexpr#1+#1\relax\relax/
+                 \baselineskip\relax}%
+ \PassOptionsToPackage{%
+    hmarginratio={1:1},%
+    textwidth=\unexpanded{\sphinxtextwidthja{\spx@opt@hmargin}},%
+    vmarginratio={1:1},%
+    lines=\unexpanded{\sphinxtextlinesja{\spx@opt@vmargin}},%
+    marginpar=\unexpanded{\sphinxmarginparwidthja{\spx@opt@marginpar}},%
+    footskip=2\baselineskip,%
+  }{geometry}%
+\fi
+
+% fix fncychap's bug which uses prematurely the \textwidth value
+\@ifpackagewith{fncychap}{Bjornstrup}
+               {\AtBeginDocument{\mylen\textwidth\advance\mylen-2\myhi}}%
+
 \ifx\@jsc@uplatextrue\undefined\else
   \PassOptionsToPackage{setpagesize=false}{hyperref}
-  \setlength\footskip{2\baselineskip}
-  \addtolength{\textheight}{-2\baselineskip}
 \fi
 
 % fix the double index and bibliography on the table of contents

sphinx/writers/latex.py

@@ -57,8 +57,7 @@ DEFAULT_SETTINGS = {
     'sphinxpkgoptions':     '',
     'sphinxsetup':     '',
     'passoptionstopackages': '',
-    'geometry':       ('\\usepackage[margin=1in,marginparwidth=0.5in]'
-                       '{geometry}'),
+    'geometry':        '\\usepackage{geometry}',
     'inputenc':        '',
     'utf8extra':       '',
     'cmappkg':         '\\usepackage{cmap}',
@@ -122,8 +121,7 @@ ADDITIONAL_SETTINGS = {
     },
     'platex': {
         'latex_engine': 'platex',
-        'geometry': ('\\usepackage[margin=1in,marginparwidth=0.5in,dvipdfm]'
-                     '{geometry}'),
+        'geometry':     '\\usepackage[dvipdfm]{geometry}',
     },
 }
 
@@ -438,6 +436,11 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
                 # pTeX (Japanese TeX) for support
                 if builder.config.language == 'ja':
+                    # if document uses Japanese standard document classes, then
+                    # geometry package needs truedimen as initial *class* option
+                    if docclass[:2] == 'js':
+                        self.elements['papersize'] = ('truedimen,' +
+                                                      self.elements['papersize'])
                     # use dvipdfmx as default class option in Japanese
                     self.elements['classoptions'] = ',dvipdfmx'
                     # disable babel which has not publishing quality in Japanese

tests/test_build_latex.py

@@ -423,7 +423,7 @@ def test_babel_with_language_ja(app, status, warning):
     print(result)
     print(status.getvalue())
     print(warning.getvalue())
-    assert '\\documentclass[letterpaper,10pt,dvipdfmx]{sphinxmanual}' in result
+    assert '\\documentclass[truedimen,letterpaper,10pt,dvipdfmx]{sphinxmanual}' in result
     assert '\\usepackage{babel}' not in result
     assert '\\usepackage{times}' in result
     assert '\\usepackage[Sonny]{fncychap}' not in result