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']