diff --git a/CHANGES b/CHANGES index 535444241e0..09e166fe5de 100644 --- a/CHANGES +++ b/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 -------- diff --git a/doc/config.rst b/doc/config.rst index 62e6f8fe3fc..9631a0478fd 100644 --- a/doc/config.rst +++ b/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 + `. .. 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 + `. + + .. 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 ` documentation for more. ``'babel'`` "babel" package inclusion, default ``'\\usepackage{babel}'`` (the diff --git a/doc/latex.rst b/doc/latex.rst index 355948c4dcb..3d322337c44 100644 --- a/doc/latex.rst +++ b/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 diff --git a/sphinx/templates/latex/content.tex_t b/sphinx/templates/latex/content.tex_t index e35c83648be..b3a77ca4296 100644 --- a/sphinx/templates/latex/content.tex_t +++ b/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 %> diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 05a1f8b5e7d..ac0250838d2 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/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 diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 0b698fa0a68..b11bd570a76 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -57,8 +57,7 @@ 'sphinxpkgoptions': '', 'sphinxsetup': '', 'passoptionstopackages': '', - 'geometry': ('\\usepackage[margin=1in,marginparwidth=0.5in]' - '{geometry}'), + 'geometry': '\\usepackage{geometry}', 'inputenc': '', 'utf8extra': '', 'cmappkg': '\\usepackage{cmap}', @@ -122,8 +121,7 @@ }, 'platex': { 'latex_engine': 'platex', - 'geometry': ('\\usepackage[margin=1in,marginparwidth=0.5in,dvipdfm]' - '{geometry}'), + 'geometry': '\\usepackage[dvipdfm]{geometry}', }, }