use 'sphinxpackageoptions' as argument to `\sphinxsetup`

Indeed, LaTeX's handling of package options is not robust when options
contain LaTeX macros; thus we pass all the user customization to
``\sphinxsetup``, not as package options to "sphinx.sty".

Also, make parameters for long code line breaking (ref #2343, 1.4.2)
accessible as sub-keys of 'sphinxpackageoptions'. The space reserved for
the continuation character has been modified for coherence and
compatibility with use in footnotes. In fact it did not use the correct
font for the dimension computation. The documentation explains how to
recover former value.

doc/latex.rst

@@ -11,8 +11,12 @@ LaTeX customization
 The *latex* target does not benefit from pre-prepared themes like the
 *html* target does (see :doc:`theming`).
 
-Basic customization is available from ``conf.py`` via usage of the
+Basic customization
-:ref:`latex-options` as described in :doc:`config`. For example::
+-------------------
+
+It is available from ``conf.py`` via usage of the
+:ref:`latex-options` as described in :doc:`config` (backslashes must be doubled
+in Python string literals to reach latex.) For example::
 
     # inside conf.py
     latex_engine = 'xelatex'
@@ -56,36 +60,46 @@ configured, for example::
 
     latex_additional_files = ["mystyle.sty"]
 
-Such *LaTeX Sphinx theme* files could possibly be contributed in the
+The Sphinx LaTeX style package options
-future by advanced users for wider use.
+--------------------------------------
 
 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::
+string of ``key=value`` instructions (if a key is repeated, it is its last
+occurence which counts)::
 
     key1=value1,key2=value2, ...
 
-which will be passed as the optional parameter to the Sphinx LaTeX style \file::
+which will be used as argument to the ``\sphinxsetup`` command::
 
-    \usepackage[<sphinxpackageoptions>]{sphinx}
+    \usepackage{sphinx}
-
+    \sphinxsetup{key1=value1,key2=value2,...}
-It is possible to modify later the options (even midway in the
-document using a ``.. raw:: latex`` directive) via use of the command
-``\sphinxsetup{<options>}``, with the same option ``key=value`` syntax.
 
 .. versionadded:: 1.5
 
-Here is the current list:
+.. note::
+
+   Almost all options described next could be positioned as :file:`sphinx.sty`
+   package options. But when the key value contains some LaTeX code there are
+   issues with LaTeX's processing and the use of ``\sphinxsetup`` is mandatory.
+
+.. hint::
+
+   It is possible to use again ``\sphinxsetup`` in the preamble, via the
+   ``'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 use or not frames around
+    default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal
-    :rst:dir:`code-block`\ s and literal includes. Setting it to ``false``
+    includes are framed. Setting it to ``false`` does not deactivate use of
-    does not deactivate use of package "framed", because it is still in use
+    package "framed", because it is still in use for the optional background
-    for the optional background colour (see below).
+    colour (see below).
 
     .. attention::
 
-       LaTeX wants *lowercase* ``=true`` or  ``=false`` here.
+       LaTeX requires ``=true`` or ``=false`` in *lowercase*.
 
 ``verbatimwrapslines``
     default ``true``. Tells whether long lines in :rst:dir:`code-block`\ s
@@ -94,6 +108,32 @@ Here is the current list:
     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
+    split, space characters located at end of the line before the break are
+    displayed using this code.
+
+``verbatimcontinued``
+    default
+    ``\\makebox[2\\fontcharwd\\font`\\x][r]{\\textcolor{red}{\\tiny$\\hookrightarrow$}}``.
+    This is printed at start of continuation lines. This rather formidable
+    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
+    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
+       changed at 1.5 to obey the current font characteristics (this was needed
+       as Sphinx 1.5 LaTeX allows code-blocks in footnotes which use a smaller
+       font size).
+
+       .. hint::
+
+          To recover exact same indent as earlier the
+          ``\\normalfont\\normalsize\\makebox[3ex][r]{...}`` specification
+          should be used.
+
 ``TitleColor``
     default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured
     via use of package "titlesec".) It must obey the syntax of the
@@ -229,6 +269,9 @@ Here is the current list:
 In the future, possibly more keys will be made available. As seen above, they
 may even be used for LaTeX commands.
 
+The LaTeX environments defined by Sphinx
+----------------------------------------
+
 Let us now list some macros from the package file
 :file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
 :file:`sphinxmanual.cls`, which can be entirely redefined, if desired.
@@ -326,13 +369,6 @@ Let us now list some macros from the package file
   .. versionchanged:: 1.5
      formerly, the original environments were modified by Sphinx.
 
-.. note::
-
-   It is impossible to revert or prevent the loading of a package that results
-   from a ``\usepackage`` executed from inside the :file:`sphinx.sty` style
-   file. Sphinx aims at loading as few packages as are really needed for its
-   default design.
-
 .. hint::
 
    As an experimental feature, Sphinx can use user-defined template file for

sphinx/templates/latex/content.tex_t

@@ -15,7 +15,8 @@
 <%= fontpkg %>
 <%= fncychap %>
 <%= longtable %>
-\usepackage[<%= sphinxpackageoptions %>]{sphinx}
+\usepackage<%= sphinxpkgoptions %>{sphinx}
+\sphinxsetup{<%= sphinxpackageoptions %>}
 \usepackage{multirow}
 \usepackage{eqparbox}
 <%= usepackages %>

sphinx/texinputs/sphinx.sty

@@ -27,6 +27,11 @@
 \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}
@@ -56,16 +61,15 @@
 \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.
@@ -81,7 +85,6 @@
 % They are assigned to \spx@notice@border at time of use (sphinxadmonition)
 \newdimen\spx@notice@border
 
-% The \sphinx@setup execution is delayed to after having loaded color/xcolor
 \newcommand*\sphinx@setup
 {%
  \sphinxverbatimsep   \dimexpr\spx@opt@verbatimsep   \relax
@@ -111,6 +114,7 @@
  \@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
@@ -169,9 +173,6 @@
 % Display "real" single quotes in literal blocks.
 \RequirePackage{upquote}
 
-% Initialize style parameters
-\sphinx@setup
-
 % 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}
@@ -350,13 +351,7 @@
 % For linebreaks inside Verbatim environment from package fancyvrb.
 \newbox\sphinxcontinuationbox
 \newbox\sphinxvisiblespacebox
-% Customize this via 'preamble' key if desired.
+\newcommand*\sphinxafterbreak {\copy\sphinxcontinuationbox}
-% Use of \textvisiblespace for compatibility with XeTeX/LuaTeX/fontspec.
-% FIXME: convert this to package options
-\newcommand*\sphinxvisiblespace {\textcolor{red}{\textvisiblespace}}
-\newcommand*\sphinxcontinuationsymbol {\textcolor{red}{\llap{\tiny$\m@th\hookrightarrow$}}}
-\newcommand*\sphinxcontinuationindent {3ex }
-\newcommand*\sphinxafterbreak {\kern\sphinxcontinuationindent\copy\sphinxcontinuationbox}
 
 % Take advantage of the already applied Pygments mark-up to insert
 % potential linebreaks for TeX processing.
@@ -447,8 +442,9 @@
   %       to achieve this without extensive rewrite of fancyvrb.
   %     - The (not used in sphinx) obeytabs option to Verbatim is
   %       broken by this change (showtabs and tabspace work).
-  \sbox\sphinxcontinuationbox {\sphinxcontinuationsymbol}%
+  \expandafter\def\expandafter\FV@SetupFont\expandafter
-  \sbox\sphinxvisiblespacebox {\FV@SetupFont\sphinxvisiblespace}%
+    {\FV@SetupFont\sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
+                  \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}}%
   \def\FancyVerbFormatLine ##1{\hsize\linewidth
           \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
                 \doublehyphendemerits\z@\finalhyphendemerits\z@

sphinx/writers/latex.py

@@ -52,6 +52,7 @@ DEFAULT_SETTINGS = {
     'classoptions':    '',
     'extraclassoptions': '',
     'maxlistdepth':    '',
+    'sphinxpkgoptions': '',
     'sphinxpackageoptions': '',
     'passoptionstopackages': '',
     'geometry':        '\\usepackage[margin=1in,marginparwidth=0.5in]'
@@ -370,9 +371,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
             'releasename':  _('Release'),
             'indexname':    _('Index'),
         })
-        sphinxpkgoptions = ''
         if not builder.config.latex_keep_old_macro_names:
-            sphinxpkgoptions = ',dontkeepoldnames'
+            self.elements['sphinxpkgoptions'] = 'dontkeepoldnames'
         if document.settings.docclass == 'howto':
             docclass = builder.config.latex_docclass.get('howto', 'article')
         else:
@@ -447,9 +447,11 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.check_latex_elements()
         self.elements.update(builder.config.latex_elements)
         if self.elements['maxlistdepth']:
-            sphinxpkgoptions += ',maxlistdepth=%s' % self.elements['maxlistdepth']
+            self.elements['sphinxpkgoptions'] += (',maxlistdepth=%s' %
-        if sphinxpkgoptions:
+                                                  self.elements['maxlistdepth'])
-            self.elements['sphinxpackageoptions'] += sphinxpkgoptions
+        if self.elements['sphinxpkgoptions']:
+            self.elements['sphinxpkgoptions'] = ('[%s]' %
+                                                 self.elements['sphinxpkgoptions'])
         if self.elements['extraclassoptions']:
             self.elements['classoptions'] += ',' + \
                                              self.elements['extraclassoptions']