diff options
Diffstat (limited to 'sphinx/texinputs/sphinx.sty')
| -rw-r--r-- | sphinx/texinputs/sphinx.sty | 189 |
1 files changed, 106 insertions, 83 deletions
diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index aaf2f548f..cbc465c1e 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -6,28 +6,19 @@ % \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2017/03/12 v1.5.4 LaTeX package (Sphinx markup)] - -% this is the \ltx@ifundefined of ltxcmds.sty, which is loaded by -% kvoptions (and later by hyperref), but 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 -} +\ProvidesPackage{sphinx}[2017/03/12 v1.6 LaTeX package (Sphinx markup)] + +% provides \ltx@ifundefined +% (many packages load ltxcmds: graphicx does for pdftex and lualatex but +% not xelatex, and anyhow kvoptions does, but it may be needed in future to +% use \sphinxdeprecationwarning earlier, and it needs \ltx@ifundefined) +\RequirePackage{ltxcmds} %% for deprecation warnings \newcommand\sphinxdeprecationwarning[4]{% #1 the deprecated macro or name, % #2 = version when deprecated, #3 = version when removed, #4 = message \edef\spx@tempa{\detokenize{#1}}% - \spx@ifundefined{sphinx_depr_\spx@tempa}{% + \ltx@ifundefined{sphinx_depr_\spx@tempa}{% \global\expandafter\let\csname sphinx_depr_\spx@tempa\endcsname\spx@tempa \expandafter\AtEndDocument\expandafter{\expandafter\let\expandafter \sphinxdeprecatedmacro\csname sphinx_depr_\spx@tempa\endcsname @@ -55,6 +46,64 @@ ******** ERROR !! PLEASE UPDATE titlesec.sty !!********^^J% ******** THIS VERSION SWALLOWS SECTION NUMBERS.********}}}}{} \RequirePackage{tabulary} +% tabulary has a bug with its re-definition of \multicolumn in its first pass +% which is not \long. But now Sphinx does not use LaTeX's \multicolumn but its +% own macro. Hence we don't even need to patch tabulary. See sphinxmulticell.sty +% X or S (Sphinx) may have meanings if some table package is loaded hence +% \X was chosen to avoid possibility of conflict +\newcolumntype{\X}[2]{p{\dimexpr + (\linewidth-\arrayrulewidth)*#1/#2-\tw@\tabcolsep-\arrayrulewidth\relax}} +\newcolumntype{\Y}[1]{p{\dimexpr + #1\dimexpr\linewidth-\arrayrulewidth\relax-\tw@\tabcolsep-\arrayrulewidth\relax}} +% using here T (for Tabulary) feels less of a problem than the X could be +\newcolumntype{T}{J}% +\RequirePackage{longtable} +% For table captions. +\RequirePackage{threeparttable} +% fixing the LaTeX mess of vertical spaces with threeparttable and longtable +% The user interface: +\newcommand*\sphinxtablepre {0pt}% +\newcommand*\sphinxtablepost{\medskipamount}% +% as one can not use \baselineskip from inside longtable (it is zero there) +% we need \sphinxbaselineskip, which defaults to \baselineskip +\newcommand*\sphinxbelowcaptionspace{.5\sphinxbaselineskip}% +\def\sphinxbaselineskip{\baselineskip}% +% Helper macros, not a priori for user customization +\def\sphinxatlongtablestart + {\par + \vskip\parskip + \vskip\dimexpr\sphinxtablepre\relax % adjust vertical position + \vbox{}% get correct baseline from above + \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips + \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}}% +\def\sphinxatlongtableend{\prevdepth\z@\vskip\sphinxtablepost\relax}% +% the longtable template inserts a \strut at caption's end +\def\sphinxlongtablecapskipadjust + {\dimexpr-\dp\strutbox-\sphinxbaselineskip + +\sphinxbelowcaptionspace\relax}% +% tabular(y) with or without threeparttable +\def\sphinxattablestart + {\par + \vskip\dimexpr\sphinxtablepre\relax + \belowcaptionskip\sphinx@TPTbelowcaptionskip}% +\let\sphinxattableend\sphinxatlongtableend +% the tabular(y) templates use [t] vertical placement parameter +\def\sphinx@TPTbelowcaptionskip + {\dimexpr-1.2\baselineskip % .2\baselineskip hardcoded in threeparttable + +\sphinxbelowcaptionspace\relax }% +% varwidth is crucial for our handling of general contents in merged cells +\RequirePackage{varwidth} +% but addition of a compatibility patch with hyperref is needed +% (tested with varwidth v 0.92 Mar 2009) +\AtBeginDocument {% + \let\@@vwid@Hy@raisedlink\Hy@raisedlink + \long\def\@vwid@Hy@raisedlink#1{\@vwid@wrap{\@@vwid@Hy@raisedlink{#1}}}% + \edef\@vwid@setup{% + \let\noexpand\Hy@raisedlink\noexpand\@vwid@Hy@raisedlink % HYPERREF ! + \unexpanded\expandafter{\@vwid@setup}}% +}% +% Homemade package to handle merged cells +\RequirePackage{sphinxmulticell} \RequirePackage{makeidx} % For framing code-blocks and warning type notices, and shadowing topics \RequirePackage{framed} @@ -67,15 +116,9 @@ % For highlighted code. \RequirePackage{fancyvrb} \fvset{fontsize=\small} -% For table captions. -\RequirePackage{threeparttable} % 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} -\makesavenoteenv{tabular} -\makesavenoteenv{threeparttable} -% (longtable is hyperref compatible and needs no special treatment here.) % For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code % for allowing figures in tables. \RequirePackage{float} @@ -267,7 +310,7 @@ % define all missing \@list... macros \count@\@ne \loop - \spx@ifundefined{@list\romannumeral\the\count@} + \ltx@ifundefined{@list\romannumeral\the\count@} {\iffalse}{\iftrue\advance\count@\@ne}% \repeat \loop @@ -276,7 +319,7 @@ \csname @list\romannumeral\the\count@\expandafter\endcsname \csname @list\romannumeral\the\numexpr\count@-\@ne\endcsname % work around 2.6--3.2d babel-french issue (fixed in 3.2e; no change needed) - \spx@ifundefined{leftmargin\romannumeral\the\count@} + \ltx@ifundefined{leftmargin\romannumeral\the\count@} {\expandafter\let \csname leftmargin\romannumeral\the\count@\expandafter\endcsname \csname leftmargin\romannumeral\the\numexpr\count@-\@ne\endcsname}{}% @@ -285,7 +328,7 @@ % define all missing enum... counters and \labelenum... macros and \p@enum.. \count@\@ne \loop - \spx@ifundefined{c@enum\romannumeral\the\count@} + \ltx@ifundefined{c@enum\romannumeral\the\count@} {\iffalse}{\iftrue\advance\count@\@ne}% \repeat \loop @@ -305,7 +348,7 @@ % define all missing labelitem... macros \count@\@ne \loop - \spx@ifundefined{labelitem\romannumeral\the\count@} + \ltx@ifundefined{labelitem\romannumeral\the\count@} {\iffalse}{\iftrue\advance\count@\@ne}% \repeat \loop @@ -331,7 +374,7 @@ {\end{theindex}} \renewenvironment{sphinxthebibliography}[1] - {\cleardoublepage\phantomsection + {\cleardoublepage% \phantomsection % not needed here since TeXLive 2010's hyperref \begin{thebibliography}{1}} {\end{thebibliography}} \fi @@ -347,45 +390,27 @@ % make commands known to non-Sphinx document classes \providecommand*{\sphinxtableofcontents}{\tableofcontents} -\spx@ifundefined{sphinxthebibliography} +\ltx@ifundefined{sphinxthebibliography} {\newenvironment {sphinxthebibliography}{\begin{thebibliography}}{\end{thebibliography}}% } {}% else clause of ifundefined -\spx@ifundefined{sphinxtheindex} +\ltx@ifundefined{sphinxtheindex} {\newenvironment{sphinxtheindex}{\begin{theindex}}{\end{theindex}}}% {}% else clause of ifundefined %% COLOR (general) % -% 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} -\ifx\kanjiskip\undefined\else - \newcount\pdfoutput\pdfoutput=0 -\fi - -% for PDF output, use colors and maximal compression -\newif\ifsphinxpdfoutput % used in \maketitle -\ifx\pdfoutput\undefined\else - \ifnum\pdfoutput=\z@ - \let\py@NormalColor\relax - \let\py@TitleColor\relax - \else - \sphinxpdfoutputtrue - \input{pdfcolor} - \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} - \def\py@TitleColor{\color{TitleColor}} - \pdfcompresslevel=9 - \fi -\fi - -% XeLaTeX can do colors, too -\ifx\XeTeXrevision\undefined\else - \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} - \def\py@TitleColor{\color{TitleColor}} -\fi +% FIXME: \normalcolor should probably be used in place of \py@NormalColor +% elsewhere, and \py@NormalColor should never be defined. \normalcolor +% switches to the colour from last \color call in preamble. +\def\py@NormalColor{\color{black}} +% FIXME: it is probably better to use \color{TitleColor}, as TitleColor +% can be customized from 'sphinxsetup', and drop usage of \py@TitleColor +\def\py@TitleColor{\color{TitleColor}} +% FIXME: this line should be dropped, as "9" is default anyhow. +\ifdefined\pdfcompresslevel\pdfcompresslevel = 9 \fi %% PAGE STYLING @@ -399,7 +424,7 @@ % Redefine the 'normal' header/footer style when using "fancyhdr" package: % Note: this presupposes "twoside". If "oneside" class option, there will be warnings. -\spx@ifundefined{fancyhf}{}{ +\ltx@ifundefined{fancyhf}{}{ % Use \pagestyle{normal} as the primary pagestyle for text. \fancypagestyle{normal}{ \fancyhf{} @@ -411,7 +436,7 @@ \renewcommand{\headrulewidth}{0.4pt} \renewcommand{\footrulewidth}{0.4pt} % define chaptermark with \@chappos when \@chappos is available for Japanese - \spx@ifundefined{@chappos}{} + \ltx@ifundefined{@chappos}{} {\def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}} } % Update the plain style so we get the page number & footer line, @@ -528,33 +553,25 @@ %% GRAPHICS % -% Redefine \includegraphics to resize images larger than the line width, +% \sphinxincludegraphics defined to resize images larger than the line width, % except if height or width option present. % % If scale is present, rescale before fitting to line width. (since 1.5) -% -% Warning: future version of Sphinx will not modify original \includegraphics, -% below code will be definition only of \sphinxincludegraphics. -\let\py@Oldincludegraphics\includegraphics \newbox\spx@image@box -\renewcommand*{\includegraphics}[2][]{% +\newcommand*{\sphinxincludegraphics}[2][]{% \in@{height}{#1}\ifin@\else\in@{width}{#1}\fi \ifin@ % height or width present - \py@Oldincludegraphics[#1]{#2}% + \includegraphics[#1]{#2}% \else % no height nor width (but #1 may be "scale=...") - \setbox\spx@image@box\hbox{\py@Oldincludegraphics[#1,draft]{#2}}% + \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}% \ifdim \wd\spx@image@box>\linewidth \setbox\spx@image@box\box\voidb@x % clear memory - \py@Oldincludegraphics[#1,width=\linewidth]{#2}% + \includegraphics[#1,width=\linewidth]{#2}% \else - \py@Oldincludegraphics[#1]{#2}% + \includegraphics[#1]{#2}% \fi \fi } -% Writer will put \sphinxincludegraphics in LaTeX source, and with this, -% documents which used their own modified \includegraphics will compile -% as before. But see warning above. -\newcommand*{\sphinxincludegraphics}{\includegraphics} %% FIGURE IN TABLE @@ -600,7 +617,7 @@ % for captions of literal blocks % also define `\theH...` macros for hyperref \newcounter{literalblock} -\spx@ifundefined{c@chapter} +\ltx@ifundefined{c@chapter} {\@addtoreset{literalblock}{section} \def\theliteralblock {\ifnum\c@section>\z@ \thesection.\fi\arabic{literalblock}} \def\theHliteralblock {\theHsection.\arabic{literalblock}}} @@ -971,7 +988,7 @@ \newenvironment{sphinxShadowBox} {\def\FrameCommand {\spx@ShadowFBox }% % configure framed.sty not to add extra vertical spacing - \spx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}% + \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}% % the \trivlist will add the vertical spacing on top and bottom which is % typical of center environment as used in Sphinx <= 1.4.1 % the \noindent has the effet of an extra blank line on top, to @@ -1056,7 +1073,7 @@ % configure framed.sty's parameters to obtain same vertical spacing % as for "light" boxes. We need for this to manually insert parskip glue and % revert a skip done by framed before the frame. - \spx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}% + \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}% \vspace{\FrameHeightAdjust} % copied/adapted from framed.sty's snugshade \def\FrameCommand##1{\hskip\@totalleftmargin @@ -1112,10 +1129,7 @@ \csname\@backslashchar color@#2\endcsname } % the main dispatch for all types of notices -\newenvironment{sphinxadmonition}{\begin{notice}}{\end{notice}} -% use of ``notice'' is for backwards compatibility and will be removed in -% future release; sphinxadmonition environment will be defined directly. -\newenvironment{notice}[2]{% #1=type, #2=heading +\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading % can't use #1 directly in definition of end part \def\spx@noticetype {#1}% % set parameters of heavybox/lightbox @@ -1126,6 +1140,14 @@ \begin{sphinx#1}{#2}} % in end part, need to go around a LaTeX's "feature" {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp} +% use of ``notice'' is for backwards compatibility and will be removed in +% Sphinx 1.7. +\newenvironment{notice} + {\sphinxdeprecationwarning {notice}{1.6}{1.7}{% + This document was probably built with a Sphinx extension using ``notice''^^J + environment. At Sphinx 1.7, ``notice'' environment will be removed. Please^^J + report to extension author to use ``sphinxadmonition'' instead.^^J% + ****}\begin{sphinxadmonition}}{\end{sphinxadmonition}} %% PYTHON DOCS MACROS AND ENVIRONMENTS @@ -1328,12 +1350,12 @@ \ifspx@opt@dontkeepoldnames\else \let\spx@alreadydefinedlist\@empty \typeout{** (sphinx) defining (legacy) text style macros without \string\sphinx\space prefix} - \typeout{** if clashes with packages, set latex_keep_old_macro_names=False + \typeout{** if clashes with packages, do not set latex_keep_old_macro_names=True in conf.py} \@for\@tempa:=code,strong,bfcode,email,tablecontinued,titleref,% menuselection,accelerator,crossref,termref,optional\do {% first, check if command with no prefix already exists - \spx@ifundefined{\@tempa}{% + \ltx@ifundefined{\@tempa}{% % give it the meaning defined so far with \sphinx prefix \expandafter\let\csname\@tempa\expandafter\endcsname \csname sphinx\@tempa\endcsname @@ -1353,6 +1375,7 @@ Sphinx mark-up uses only \string\sphinx\expandafter\@gobble\sphinxdeprecatedmacro.}% }% \fi + \sphinxdeprecationwarning{latex_keep_old_macro_names=True}{1.6}{1.7}{}% \fi % additional customizable styling @@ -1378,4 +1401,4 @@ % Tell TeX about pathological hyphenation cases: \hyphenation{Base-HTTP-Re-quest-Hand-ler} - +\endinput |