From b6695ad7fc8d0b78cbb40530c368c9b68f63bea4 Mon Sep 17 00:00:00 2001 From: jfbu Date: Fri, 28 Oct 2016 21:45:44 +0200 Subject: [PATCH] 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 | 84 ++++++++++++++++++++-------- sphinx/templates/latex/content.tex_t | 3 +- sphinx/texinputs/sphinx.sty | 26 ++++----- sphinx/writers/latex.py | 12 ++-- 4 files changed, 80 insertions(+), 45 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 555b04483..df2e26ac0 100644 --- a/doc/latex.rst +++ b/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 -:ref:`latex-options` as described in :doc:`config`. For example:: +Basic customization +------------------- + +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 -future by advanced users for wider use. +The Sphinx LaTeX style package options +-------------------------------------- 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[]{sphinx} - -It is possible to modify later the options (even midway in the -document using a ``.. raw:: latex`` directive) via use of the command -``\sphinxsetup{}``, with the same option ``key=value`` syntax. + \usepackage{sphinx} + \sphinxsetup{key1=value1,key2=value2,...} .. 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 - :rst:dir:`code-block`\ s and literal includes. Setting it to ``false`` - does not deactivate use of package "framed", because it is still in use - for the optional background colour (see below). + 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 + package "framed", because it is still in use for the optional background + 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 diff --git a/sphinx/templates/latex/content.tex_t b/sphinx/templates/latex/content.tex_t index f63fac6d1..ae642119e 100644 --- a/sphinx/templates/latex/content.tex_t +++ b/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 %> diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index ee186e211..9a21383e6 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/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. -% 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} +\newcommand*\sphinxafterbreak {\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}% - \sbox\sphinxvisiblespacebox {\FV@SetupFont\sphinxvisiblespace}% + \expandafter\def\expandafter\FV@SetupFont\expandafter + {\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@ diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 4ffafc66e..9f29e466e 100644 --- a/sphinx/writers/latex.py +++ b/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'] - if sphinxpkgoptions: - self.elements['sphinxpackageoptions'] += sphinxpkgoptions + self.elements['sphinxpkgoptions'] += (',maxlistdepth=%s' % + self.elements['maxlistdepth']) + if self.elements['sphinxpkgoptions']: + self.elements['sphinxpkgoptions'] = ('[%s]' % + self.elements['sphinxpkgoptions']) if self.elements['extraclassoptions']: self.elements['classoptions'] += ',' + \ self.elements['extraclassoptions']