Merge pull request #3387 from jfbu/japanesetextlayout

Fix #3356 and #3394 latex text layout for Japanese document

CHANGES

@@ -21,6 +21,9 @@ Bugs fixed
 * since 1.5, PDF's TOC and bookmarks lack an entry for general Index
   (refs: #3383)
 * #3392: ``'releasename'`` in :confval:`latex_elements` is not working
+* #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,33 @@ 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 an additional ``[dvipdfm]`` for Japanese documents.
+        The Sphinx LaTeX style file executes:
+
+          ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}``
+
+        which can be customized via corresponding :ref:`'sphinxsetup' options
+        <latexsphinxsetup>`.
 
         .. 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 :ref:`'sphinxsetup' keys for the margins
+           <latexsphinxsetuphmargin>`.
+
+        .. versionchanged:: 1.5.3
+           The location in the LaTeX file has been moved to after
+           ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after
+           insertion of ``'fontpkg'`` key. 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. See the
+           :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
 
      ``'babel'``
         "babel" package inclusion, default ``'\\usepackage{babel}'`` (the

doc/latex.rst

@@ -14,13 +14,19 @@ The *latex* target does not benefit from pre-prepared themes like the
 .. raw:: latex
 
    \begingroup
-   \sphinxsetup{verbatimwithframe=false,%
-                VerbatimColor={named}{OldLace}, TitleColor={named}{DarkGoldenrod},%
-                hintBorderColor={named}{LightCoral}, attentionBgColor={named}{LightPink},%
-                attentionborder=3pt,  attentionBorderColor={named}{Crimson},%
-                noteBorderColor={named}{Olive}, noteborder=2pt,%
-                cautionBorderColor={named}{Cyan}, cautionBgColor={named}{LightCyan},%
-                cautionborder=3pt}
+   \sphinxsetup{%
+         verbatimwithframe=false,
+         VerbatimColor={named}{OldLace},
+         TitleColor={named}{DarkGoldenrod},
+         hintBorderColor={named}{LightCoral},
+         attentionborder=3pt,
+         attentionBorderColor={named}{Crimson},
+         attentionBgColor={named}{FloralWhite},
+         noteborder=2pt,
+         noteBorderColor={named}{Olive},
+         cautionborder=3pt,
+         cautionBorderColor={named}{Cyan},
+         cautionBgColor={named}{LightCyan}}
    \relax
 
 
@@ -75,6 +81,8 @@ configured, for example::
 
     latex_additional_files = ["mystyle.sty"]
 
+.. _latexsphinxsetup:
+
 The Sphinx LaTeX style package options
 --------------------------------------
 
@@ -109,13 +117,19 @@ If non-empty, it will be passed as argument to the ``\sphinxsetup`` command::
      dynamically the option values: this is actually what we did for the
      duration of this chapter for the PDF output, which is styled using::
 
+       \sphinxsetup{%
          verbatimwithframe=false,
-         VerbatimColor={named}{OldLace}, TitleColor={named}{DarkGoldenrod},
-         hintBorderColor={named}{LightCoral}, attentionBgColor={named}{LightPink},
-         attentionborder=3pt,  attentionBorderColor={named}{Crimson},
-         noteBorderColor={named}{Olive}, noteborder=2pt,
-         cautionBorderColor={named}{Cyan}, cautionBgColor={named}{LightCyan},
-         cautionborder=3pt
+         VerbatimColor={named}{OldLace},
+         TitleColor={named}{DarkGoldenrod},
+         hintBorderColor={named}{LightCoral},
+         attentionborder=3pt,
+         attentionBorderColor={named}{Crimson},
+         attentionBgColor={named}{FloralWhite},
+         noteborder=2pt,
+         noteBorderColor={named}{Olive},
+         cautionborder=3pt,
+         cautionBorderColor={named}{Cyan},
+         cautionBgColor={named}{LightCyan}}
 
      and with the ``svgnames`` option having been passed to "xcolor" package::
 
@@ -137,6 +151,62 @@ Here are the currently available options together with their default values.
    LaTeX requires for keys with Boolean values to use **lowercase** ``true`` or
    ``false``.
 
+.. _latexsphinxsetuphmargin:
+
+``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.
+
+    .. hint::
+
+       For a ``'manual'`` type document with :confval:`language` set to
+       ``'ja'``, which by default uses the ``jsbook`` LaTeX document class, the
+       dimension units, when the pointsize isn't ``10pt``, must be so-called TeX
+       "true" units::
+
+         'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
+
+       This is due to the way the LaTeX class ``jsbook`` handles the
+       pointsize.
+
+       Or, one uses regular units but with ``nomag`` as document class option.
+       This can be achieved for example via::
+
+         'pointsize': 'nomag,12pt',
+
+       in the :confval:`latex_elements` configuration variable.
+
+    .. 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/06 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,52 @@
   {\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-\tw@\dimexpr#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-\tw@\dimexpr#1\relax\relax/
+                 \baselineskip\relax}%
+ \ifx\@jsc@uplatextrue\undefined\else
+ % the way we found in order for the papersize special written by
+ % geometry in the dvi file to be correct in case of jsbook class
+   \ifnum\mag=\@m\else % do nothing special if nomag class option or 10pt
+     \PassOptionsToPackage{truedimen}{geometry}%
+   \fi
+ \fi
+ \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}}%
+ {}% <-- "false" clause of \@ifpackagewith
+
 \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}',
     },
 }