refactor the handling of latex options

previously, modifying a single option via ``\sphinxsetup`` redeclared
all dimensions and colours, even if they had not changed.

doc/latex.rst

@@ -63,14 +63,18 @@ configured, for example::
 The Sphinx LaTeX style package options
 --------------------------------------
 
+.. highlight:: latex
+
 The ``'sphinxpackageoptions'`` key to :confval:`latex_elements` provides a
 more convenient interface to various style parameters. It is a comma separated
-string of ``key=value`` instructions (if a key is repeated, it is its last
+string of ``key=value`` instructions::
-occurence which counts)::
 
     key1=value1,key2=value2, ...
 
-which will be used as argument to the ``\sphinxsetup`` command::
+- if a key is repeated, it is its last occurence which counts,
+- spaces around the commas and equal signs are ignored.
+
+If non-empty, it will be passed as argument to the ``\sphinxsetup`` command::
 
     \usepackage{sphinx}
     \sphinxsetup{key1=value1,key2=value2,...}
@@ -79,17 +83,19 @@ which will be used as argument to the ``\sphinxsetup`` command::
 
 .. note::
 
-   Almost all options described next could be positioned as :file:`sphinx.sty`
+   - Most options described next could also have been positioned as
-   package options. But when the key value contains some LaTeX code there are
+     :file:`sphinx.sty` package options. But for those where the key value
-   issues with LaTeX's processing and the use of ``\sphinxsetup`` is mandatory.
+     contains some LaTeX code the use of ``\sphinxsetup`` is mandatory. Hence
+     the whole ``'sphinxpackageoptions'`` string is passed as argument to
+     ``\sphinxsetup``.
 
-.. hint::
+   - As an alternative to the ``'sphinxpackageoptions'`` key, it is possibly
+     to insert explicitely the ``\\sphinxsetup{key=value,..}`` inside the
+     ``'preamble'`` key. It is even possible to use the ``\sphinxsetup`` in
+     the body of the document, via the :rst:dir:`raw` directive, to modify
+     dynamically the option values.
 
-   It is possible to use again ``\sphinxsetup`` in the preamble, via the
+Here are the currently available options together with their default values.
-   ``'preamble'`` key, or even in the body of the document, via the
-   :rst:dir:`raw` directive.
-
-Here is the list of currently available keys with their default values.
 
 ``verbatimwithframe``
     default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal
@@ -99,14 +105,16 @@ Here is the list of currently available keys with their default values.
 
     .. attention::
 
-       LaTeX requires ``=true`` or ``=false`` in *lowercase*.
+       LaTeX requires ``true`` or ``false`` to be specified in *lowercase*.
 
 ``verbatimwrapslines``
     default ``true``. Tells whether long lines in :rst:dir:`code-block`\ s
-    should be wrapped. It is theoretically possible to customize this even
+    should be wrapped.
-    more and decide at which characters a line-break can occur and whether
+
-    before or after, but this is accessible currently only by re-defining some
+    .. (comment) It is theoretically possible to customize this even
-    macros with complicated LaTeX syntax from :file:`sphinx.sty`.
+       more and decide at which characters a line-break can occur and whether
+       before or after, but this is accessible currently only by re-defining some
+       macros with complicated LaTeX syntax from :file:`sphinx.sty`.
 
 ``verbatimvisiblespace``
     default ``\\textcolor{red}{\\textvisiblespace}``. When a long code line is
@@ -114,25 +122,25 @@ Here is the list of currently available keys with their default values.
     displayed using this code.
 
 ``verbatimcontinued``
-    default
+    The default is::
-    ``\\makebox[2\\fontcharwd\\font`\\x][r]{\\textcolor{red}{\\tiny$\\hookrightarrow$}}``.
+
-    This is printed at start of continuation lines. This rather formidable
+      \\makebox[2\\fontcharwd\\font`\\x][r]{\\textcolor{red}{\\tiny$\\hookrightarrow$}}
-    expression has the effect of reserving twice the width of a typical
+
-    character in the current font and uses there a small red hook symbol pointing
+    It is printed at start of continuation lines. This rather formidable
-    to the right.
+    expression reserves twice the width of a typical character in the current
+    (monospaced) font and puts there a small red hook pointing to the right.
 
     .. versionchanged:: 1.5
        The breaking of long code lines was introduced at 1.4.2. The space
-       reserved to the continuation symbol (but not the symbol itself) was
+       reserved to the continuation symbol was changed at 1.5 to obey the
-       changed at 1.5 to obey the current font characteristics (this was needed
+       current font characteristics (this was needed as Sphinx 1.5 LaTeX
-       as Sphinx 1.5 LaTeX allows code-blocks in footnotes which use a smaller
+       allows code-blocks in footnotes which use a smaller font size).
-       font size).
 
        .. hint::
 
-          To recover exact same indent as earlier the
+          This specification gives the same spacing as before 1.5::
-          ``\\normalfont\\normalsize\\makebox[3ex][r]{...}`` specification
+
-          should be used.
+            \\normalfont\\normalsize\\makebox[3ex][r]{\\textcolor{red}{\\tiny$\\hookrightarrow$}
 
 ``TitleColor``
     default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured
@@ -177,6 +185,12 @@ Here is the list of currently available keys with their default values.
     Sphinx in LaTeX for styling a
     :dudir:`note` admonition. Defaults to black.
 
+    .. note::
+
+       The actual name of the colour as declared to "color" or "xcolor" is
+       ``sphinxnotebordercolor``. The same "sphinx" prefix applies to all
+       colours for notices and admonitions.
+
 ``hintbordercolor``
     default ``{rgb}{0,0,0}``. id.
 

sphinx/templates/latex/content.tex_t

@@ -16,7 +16,7 @@
 <%= fncychap %>
 <%= longtable %>
 \usepackage<%= sphinxpkgoptions %>{sphinx}
-\sphinxsetup{<%= sphinxpackageoptions %>}
+<%= sphinxsetup %>
 \usepackage{multirow}
 \usepackage{eqparbox}
 <%= usepackages %>

sphinx/texinputs/sphinx.sty

@@ -6,131 +6,10 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2016/10/27 v1.5 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2016/10/29 v1.5 LaTeX package (Sphinx markup)]
 
-% Handle package options via "kvoptions" (later loaded by hyperref anyhow)
+% we delay handling of options to after having loaded packages, because
-\RequirePackage{kvoptions}
+% of the need to use \definecolor.
-\SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix
-
-\DeclareBoolOption{dontkeepoldnames} % \ifspx@opt@dontkeepoldnames = \iffalse
-\DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0}
-
-% colour values must be given in format accepted by color's \definecolor
-\DeclareStringOption[{rgb}{0.126,0.263,0.361}]{TitleColor}
-% for hyperref
-\DeclareStringOption[{rgb}{0.208,0.374,0.486}]{InnerLinkColor}
-\DeclareStringOption[{rgb}{0.216,0.439,0.388}]{OuterLinkColor}
-% code-blocks and literal includes
-\DeclareStringOption[{rgb}{1,1,1}]{VerbatimColor}
-\DeclareStringOption[{rgb}{0,0,0}]{VerbatimBorderColor}
-\DeclareStringOption[\fboxsep]{verbatimsep}
-\DeclareStringOption[\fboxrule]{verbatimborder}
-\DeclareBoolOption[true]{verbatimwithframe}
-\DeclareBoolOption[true]{verbatimwrapslines}
-% \textvisiblespace for compatibility with fontspec+XeTeX/LuaTeX
-\DeclareStringOption[\textcolor{red}{\textvisiblespace}]{verbatimvisiblespace}
-\DeclareStringOption % must use braces to hide the brackets
-  [{\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\m@th\hookrightarrow$}}}]%
-  {verbatimcontinued}
-% topic boxes
-\DeclareStringOption[5pt]{shadowsep}
-\DeclareStringOption[4pt]{shadowsize}
-\DeclareStringOption[\fboxrule]{shadowrule}
-% admonition boxes, "light" style
-\DeclareStringOption[{rgb}{0,0,0}]{notebordercolor}
-\DeclareStringOption[{rgb}{0,0,0}]{hintbordercolor}
-\DeclareStringOption[{rgb}{0,0,0}]{importantbordercolor}
-\DeclareStringOption[{rgb}{0,0,0}]{tipbordercolor}
-\DeclareStringOption[0.5pt]{noteborder}
-\DeclareStringOption[0.5pt]{hintborder}
-\DeclareStringOption[0.5pt]{importantborder}
-\DeclareStringOption[0.5pt]{tipborder}
-% admonition boxes, "heavy" style
-\DeclareStringOption[{rgb}{0,0,0}]{warningbordercolor}
-\DeclareStringOption[{rgb}{0,0,0}]{cautionbordercolor}
-\DeclareStringOption[{rgb}{0,0,0}]{attentionbordercolor}
-\DeclareStringOption[{rgb}{0,0,0}]{dangerbordercolor}
-\DeclareStringOption[{rgb}{0,0,0}]{errorbordercolor}
-\DeclareStringOption[{rgb}{1,1,1}]{warningbgcolor}
-\DeclareStringOption[{rgb}{1,1,1}]{cautionbgcolor}
-\DeclareStringOption[{rgb}{1,1,1}]{attentionbgcolor}
-\DeclareStringOption[{rgb}{1,1,1}]{dangerbgcolor}
-\DeclareStringOption[{rgb}{1,1,1}]{errorbgcolor}
-\DeclareStringOption[1pt]{warningborder}
-\DeclareStringOption[1pt]{cautionborder}
-\DeclareStringOption[1pt]{attentionborder}
-\DeclareStringOption[1pt]{dangerborder}
-\DeclareStringOption[1pt]{errorborder}
-% Footnotes
-\DeclareStringOption[\mbox{ }]{AtStartFootnote}
-% we need a public macro name for direct use in latex file
-\newcommand*{\sphinxAtStartFootnote}{\spx@opt@AtStartFootnote}
-% no such need for this one, used inside other macros
-\DeclareStringOption[\leavevmode\unskip]{BeforeFootnote}
-% some font styling.
-\DeclareStringOption[\sffamily\bfseries]{HeaderFamily}
-
-\DeclareDefaultOption{\@unknownoptionerror}
-\ProcessKeyvalOptions*
-% don't allow use of maxlistdepth via \sphinxsetup.
-\DisableKeyvalOption{sphinx}{maxlistdepth}
-
-% We declare the \dimen registers here. Those are customizable via options.
-\newdimen\sphinxverbatimsep
-\newdimen\sphinxverbatimborder
-\newdimen\sphinxshadowsep
-\newdimen\sphinxshadowsize
-\newdimen\sphinxshadowrule
-% Other dimensions are set by the options and kept as \spx@opt@ prefix macros
-% They are assigned to \spx@notice@border at time of use (sphinxadmonition)
-\newdimen\spx@notice@border
-
-\newcommand*\sphinx@setup
-{%
- \sphinxverbatimsep   \dimexpr\spx@opt@verbatimsep   \relax
- \sphinxverbatimborder\dimexpr\spx@opt@verbatimborder\relax
- \sphinxshadowsep     \dimexpr\spx@opt@shadowsep     \relax
- \sphinxshadowsize    \dimexpr\spx@opt@shadowsize    \relax
- \sphinxshadowrule    \dimexpr\spx@opt@shadowrule    \relax
- \def\@tempa ##1##2##3{\edef\@tempb{\noexpand##1{##2}##3}\@tempb}%
- \@tempa\definecolor{TitleColor}                \spx@opt@TitleColor
- \@tempa\definecolor{InnerLinkColor}            \spx@opt@InnerLinkColor
- \@tempa\definecolor{OuterLinkColor}            \spx@opt@OuterLinkColor
- \@tempa\definecolor{VerbatimColor}             \spx@opt@VerbatimColor
- \@tempa\definecolor{VerbatimBorderColor}       \spx@opt@VerbatimBorderColor
- \@tempa\definecolor{sphinxnotebordercolor}     \spx@opt@notebordercolor
- \@tempa\definecolor{sphinxhintbordercolor}     \spx@opt@hintbordercolor
- \@tempa\definecolor{sphinximportantbordercolor}\spx@opt@importantbordercolor
- \@tempa\definecolor{sphinxtipbordercolor}      \spx@opt@tipbordercolor
- \@tempa\definecolor{sphinxwarningbordercolor}  \spx@opt@warningbordercolor
- \@tempa\definecolor{sphinxcautionbordercolor}  \spx@opt@cautionbordercolor
- \@tempa\definecolor{sphinxattentionbordercolor}\spx@opt@attentionbordercolor
- \@tempa\definecolor{sphinxdangerbordercolor}   \spx@opt@dangerbordercolor
- \@tempa\definecolor{sphinxerrorbordercolor}    \spx@opt@errorbordercolor
- \@tempa\definecolor{sphinxwarningbgcolor}      \spx@opt@warningbgcolor
- \@tempa\definecolor{sphinxcautionbgcolor}      \spx@opt@cautionbgcolor
- \@tempa\definecolor{sphinxattentionbgcolor}    \spx@opt@attentionbgcolor
- \@tempa\definecolor{sphinxdangerbgcolor}       \spx@opt@dangerbgcolor
- \@tempa\definecolor{sphinxerrorbgcolor}        \spx@opt@errorbgcolor
-}
-% additional user interface: options can be changed midway in a document!
-% the command will be executed only after package has finished loading.
-\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}\sphinx@setup}
-
-% this is the \ltx@ifundefined of ltxcmds.sty, which is loaded by
-% hyperref.sty, but we need it before, and the first release of
-% ltxcmds.sty as in TL2009/Debian has wrong definition.
-\newcommand{\spx@ifundefined}[1]{%
-    \ifcsname #1\endcsname
-      \expandafter\ifx\csname #1\endcsname\relax
-        \expandafter\expandafter\expandafter\@firstoftwo
-      \else
-        \expandafter\expandafter\expandafter\@secondoftwo
-      \fi
-    \else
-      \expandafter\@firstoftwo
-    \fi
-}
 
 \RequirePackage{graphicx}
 \@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
@@ -154,7 +33,7 @@
 \fvset{fontsize=\small}
 % For table captions.
 \RequirePackage{threeparttable}
-% For hyperlinked footnotes in tables; also for gathering footnotes from 
+% For hyperlinked footnotes in tables; also for gathering footnotes from
 % topic and warning blocks. Also to allow code-blocks in footnotes.
 \RequirePackage{footnotehyper-sphinx}
 \makesavenoteenv{tabulary}
@@ -173,6 +52,122 @@
 % Display "real" single quotes in literal blocks.
 \RequirePackage{upquote}
 
+% Handle options via "kvoptions" (later loaded by hyperref anyhow)
+\RequirePackage{kvoptions}
+\SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix
+
+\DeclareBoolOption{dontkeepoldnames} % \ifspx@opt@dontkeepoldnames = \iffalse
+\DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0}
+
+% dimensions, we declare the \dimen registers here.
+\newdimen\sphinxverbatimsep
+\newdimen\sphinxverbatimborder
+\newdimen\sphinxshadowsep
+\newdimen\sphinxshadowsize
+\newdimen\sphinxshadowrule
+% \DeclareStringOption is not convenient for the handling of these dimensions
+% because we want to assign the values to the corresponding registers. Even if
+% we added the code to the key handler it would be too late for the initial
+% set-up and we would need to do initial assignments explicitely. We end up
+% using \define@key directly.
+% verbatim
+\sphinxverbatimsep=\fboxsep
+  \define@key{sphinx}{verbatimsep}{\sphinxverbatimsep\dimexpr #1\relax}
+\sphinxverbatimborder=\fboxrule
+  \define@key{sphinx}{verbatimborder}{\sphinxverbatimborder\dimexpr #1\relax}
+% topic boxes
+\sphinxshadowsep =5pt
+  \define@key{sphinx}{shadowsep}{\sphinxshadowsep\dimexpr #1\relax}
+\sphinxshadowsize=4pt
+  \define@key{sphinx}{shadowsize}{\sphinxshadowsize\dimexpr #1\relax}
+\sphinxshadowrule=\fboxrule
+  \define@key{sphinx}{shadowrule}{\sphinxshadowrule\dimexpr #1\relax}
+% verbatim
+\DeclareBoolOption[true]{verbatimwithframe}
+\DeclareBoolOption[true]{verbatimwrapslines}
+% \textvisiblespace for compatibility with fontspec+XeTeX/LuaTeX
+\DeclareStringOption[\textcolor{red}{\textvisiblespace}]{verbatimvisiblespace}
+\DeclareStringOption % must use braces to hide the brackets
+  [{\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\m@th\hookrightarrow$}}}]%
+  {verbatimcontinued}
+% notices/admonitions
+% the dimensions for notices/admonitions are kept as macros and assigned to
+% \spx@notice@border at time of use, hence \DeclareStringOption is ok for this
+\newdimen\spx@notice@border
+\DeclareStringOption[0.5pt]{noteborder}
+\DeclareStringOption[0.5pt]{hintborder}
+\DeclareStringOption[0.5pt]{importantborder}
+\DeclareStringOption[0.5pt]{tipborder}
+\DeclareStringOption[1pt]{warningborder}
+\DeclareStringOption[1pt]{cautionborder}
+\DeclareStringOption[1pt]{attentionborder}
+\DeclareStringOption[1pt]{dangerborder}
+\DeclareStringOption[1pt]{errorborder}
+% footnotes
+\DeclareStringOption[\mbox{ }]{AtStartFootnote}
+% we need a public macro name for direct use in latex file
+\newcommand*{\sphinxAtStartFootnote}{\spx@opt@AtStartFootnote}
+% no such need for this one, as it is used inside other macros
+\DeclareStringOption[\leavevmode\unskip]{BeforeFootnote}
+% some font styling.
+\DeclareStringOption[\sffamily\bfseries]{HeaderFamily}
+% colours
+% same problems as for dimensions: we want the key handler to use \definecolor
+% first, some colours with no prefix, for backwards compatibility
+\newcommand*{\sphinxDeclareColorOption}[2]{%
+   \definecolor{#1}#2%
+   \define@key{sphinx}{#1}{\definecolor{#1}##1}%
+}%
+\sphinxDeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}}
+\sphinxDeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}}
+\sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}}
+\sphinxDeclareColorOption{VerbatimColor}{{rgb}{1,1,1}}
+\sphinxDeclareColorOption{VerbatimBorderColor}{{rgb}{0,0,0}}
+% now the colours defined with "sphinx" prefix in their names
+\newcommand*{\sphinxDeclareSphinxColorOption}[2]{%
+   % set the initial default
+   \definecolor{sphinx#1}#2%
+   % set the key handler. The "value" ##1 must be acceptable by \definecolor.
+   \define@key{sphinx}{#1}{\definecolor{sphinx#1}##1}%
+}%
+% admonition boxes, "light" style
+\sphinxDeclareSphinxColorOption{notebordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{hintbordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{importantbordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{tipbordercolor}{{rgb}{0,0,0}}
+% admonition boxes, "heavy" style
+\sphinxDeclareSphinxColorOption{warningbordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{cautionbordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{attentionbordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{dangerbordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{errorbordercolor}{{rgb}{0,0,0}}
+\sphinxDeclareSphinxColorOption{warningbgcolor}{{rgb}{1,1,1}}
+\sphinxDeclareSphinxColorOption{cautionbgcolor}{{rgb}{1,1,1}}
+\sphinxDeclareSphinxColorOption{attentionbgcolor}{{rgb}{1,1,1}}
+\sphinxDeclareSphinxColorOption{dangerbgcolor}{{rgb}{1,1,1}}
+\sphinxDeclareSphinxColorOption{errorbgcolor}{{rgb}{1,1,1}}
+
+\DeclareDefaultOption{\@unknownoptionerror}
+\ProcessKeyvalOptions*
+% don't allow use of maxlistdepth via \sphinxsetup.
+\DisableKeyvalOption{sphinx}{maxlistdepth}
+% user interface: options can be changed midway in a document!
+\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}}
+
+% this is the \ltx@ifundefined of ltxcmds.sty, which is loaded by
+% hyperref.sty, but we need it before, and the first release of
+% ltxcmds.sty as in TL2009/Debian has wrong definition.
+\newcommand{\spx@ifundefined}[1]{%
+    \ifcsname #1\endcsname
+      \expandafter\ifx\csname #1\endcsname\relax
+        \expandafter\expandafter\expandafter\@firstoftwo
+      \else
+        \expandafter\expandafter\expandafter\@secondoftwo
+      \fi
+    \else
+      \expandafter\@firstoftwo
+    \fi
+}
 % FIXME: the reasons might be obsolete (better color drivers now?)
 % use pdfoutput for pTeX and dvipdfmx
 % when pTeX (\kanjiskip is defined), set pdfoutput to evade \include{pdfcolor}

sphinx/writers/latex.py

@@ -52,8 +52,9 @@ DEFAULT_SETTINGS = {
     'classoptions':    '',
     'extraclassoptions': '',
     'maxlistdepth':    '',
-    'sphinxpkgoptions': '',
+    'sphinxpkgoptions':     '',
     'sphinxpackageoptions': '',
+    'sphinxsetup':     '',
     'passoptionstopackages': '',
     'geometry':        '\\usepackage[margin=1in,marginparwidth=0.5in]'
                        '{geometry}',
@@ -447,11 +448,15 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.check_latex_elements()
         self.elements.update(builder.config.latex_elements)
         if self.elements['maxlistdepth']:
-            self.elements['sphinxpkgoptions'] += (',maxlistdepth=%s' %
+            self.elements['sphinxpkgoptions'] = \
-                                                  self.elements['maxlistdepth'])
+                ','.join(self.elements['sphinxpkgoptions'], 'maxlistdepth=%s' %
+                         self.elements['maxlistdepth'])
         if self.elements['sphinxpkgoptions']:
             self.elements['sphinxpkgoptions'] = ('[%s]' %
                                                  self.elements['sphinxpkgoptions'])
+        if self.elements['sphinxpackageoptions']:
+            self.elements['sphinxsetup'] = ('\\sphinxsetup{%s}' %
+                                            self.elements['sphinxpackageoptions'])
         if self.elements['extraclassoptions']:
             self.elements['classoptions'] += ',' + \
                                              self.elements['extraclassoptions']