243 lines
11 KiB
TeX
243 lines
11 KiB
TeX
%% NOTICES AND ADMONITIONS
|
|
%
|
|
% change this info string if making any custom modification
|
|
\ProvidesFile{sphinxlatexadmonitions.sty}[2023/03/19 admonitions]
|
|
|
|
% Provides support for this output mark-up from Sphinx latex writer:
|
|
%
|
|
% - sphinxseealso environment added at 6.1.0
|
|
%
|
|
% - sphinxadmonition (environment)
|
|
% This is a dispatch supporting
|
|
%
|
|
% - note, hint, important, tip (via sphinxlightbox)
|
|
% (also optionally via sphinxheavybox since 6.2.0)
|
|
% - warning, caution, attention, danger, error (via sphinxheavybox)
|
|
%
|
|
% Each sphinx<notice name> environment can be redefined by user.
|
|
% The defaults are customizable via various colour and dimension
|
|
% settings, cf sphinx docs (latex customization).
|
|
%
|
|
% Requires:
|
|
\RequirePackage{sphinxpackageboxes}
|
|
\RequirePackage{framed}% used by sphinxheavybox
|
|
%
|
|
% Dependencies (they do not need to be defined at time of loading):
|
|
%
|
|
% - of course the various colour and dimension options handled via sphinx.sty
|
|
%
|
|
% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
|
|
%
|
|
% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
|
|
%
|
|
% - \sphinxstylenotetitle, ..., \sphinxstylewarningtitle, etc... which are used by
|
|
% default in the corresponding sphinx<notice> environments to replace at 6.2.0
|
|
% formerly hard-coded \sphinxstrong{#1}<space>
|
|
% Their definitions are in sphinxlatexstyletext.sty.
|
|
|
|
|
|
% Provides: (also in sphinxlatexliterals.sty)
|
|
\providecommand*\sphinxvspacefixafterfrenchlists{%
|
|
\ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
|
|
}
|
|
|
|
% Some are quite plain
|
|
\newenvironment{sphinxseealso}[1]{\sphinxstyleseealsotitle{#1}}{}
|
|
|
|
% This \dimen register is a legacy relic from Sphinx 1.5 which is used now
|
|
% only for sphinxlightbox. It is set in the sphinxadmonition environment.
|
|
\newdimen\spx@notice@border
|
|
|
|
\newenvironment{sphinxlightbox}{%
|
|
\par
|
|
\noindent{\color{spx@notice@bordercolor}%
|
|
\rule{\linewidth}{\spx@notice@border}}%
|
|
\par\nobreak
|
|
{\parskip\z@skip\noindent}%
|
|
}
|
|
{%
|
|
% counteract previous possible negative skip (French lists!):
|
|
% (we can't cancel that any earlier \vskip introduced a potential pagebreak)
|
|
\sphinxvspacefixafterfrenchlists
|
|
\nobreak\vbox{\noindent\kern\@totalleftmargin
|
|
{\color{spx@notice@bordercolor}%
|
|
\rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
|
|
{\linewidth}{\spx@notice@border}}\hss}\allowbreak
|
|
}% end of sphinxlightbox environment definition
|
|
|
|
% note/hint/important/tip notices
|
|
%
|
|
% Since 1.5 these environments are named individually to allow user to
|
|
% redefine them entirely.
|
|
%
|
|
% The Sphinx definitions were done like this, prior to 6.2.0:
|
|
%
|
|
% \newenvironment{sphinxhint}[1]
|
|
% {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
|
|
%
|
|
% The more complex definition below will branch to sphinxheavybox if a certain
|
|
% boolean associated to the notice type is true. This boolean is set to true
|
|
% whenever a CSS-named alike options for the notice type has been used in
|
|
% sphinxsetup. The old coding as above would still work, with the new options
|
|
% being then simply ignored. A user redefinition will probably either use
|
|
% directly sphinxlightbox or sphinxheavybox or something else, with no need to
|
|
% test the boolean.
|
|
%
|
|
% 6.2.0 also adds one layer of mark-up via \sphinxnotetitle etc..., because
|
|
% the former \sphinxstrong{#1}<space> used a too generic \sphinxstrong. But
|
|
% perhaps the #1 should be passed over to sphinx{light,heavy}box as parameter.
|
|
% Unfortunately replacing these environments with one-parameter environments
|
|
% would be potentially a breaking change. Anyway, sphinxpackageboxes.sty does not
|
|
% provide a "titled" box; the caption of code-blocks is handled by extra
|
|
% code in sphinxVerbatim.
|
|
\newenvironment{sphinxnote}[1]
|
|
{\edef\spx@env{sphinx\ifspx@opt@heavynote heavy\else light\fi box}%
|
|
\expandafter\begin\expandafter{\spx@env}\sphinxstylenotetitle{#1}}
|
|
{\expandafter\end\expandafter{\spx@env}}
|
|
\newenvironment{sphinxhint}[1]
|
|
{\edef\spx@env{sphinx\ifspx@opt@heavyhint heavy\else light\fi box}%
|
|
\expandafter\begin\expandafter{\spx@env}\sphinxstylehinttitle{#1}}
|
|
{\expandafter\end\expandafter{\spx@env}}
|
|
\newenvironment{sphinximportant}[1]
|
|
{\edef\spx@env{sphinx\ifspx@opt@heavyimportant heavy\else light\fi box}%
|
|
\expandafter\begin\expandafter{\spx@env}\sphinxstyleimportanttitle{#1}}
|
|
{\expandafter\end\expandafter{\spx@env}}
|
|
\newenvironment{sphinxtip}[1]
|
|
{\edef\spx@env{sphinx\ifspx@opt@heavytip heavy\else light\fi box}%
|
|
\expandafter\begin\expandafter{\spx@env}\sphinxstyletiptitle{#1}}
|
|
{\expandafter\end\expandafter{\spx@env}}
|
|
|
|
% warning/caution/attention/danger/error get more distinction
|
|
%
|
|
% Code adapted from framed.sty's "snugshade" environment.
|
|
% Nesting works (inner frames do not allow page breaks).
|
|
\newenvironment{sphinxheavybox}{\par
|
|
% 6.2.0 allows to not have to distinguish here between warning type notices
|
|
% which always use sphinxheavybox or note type notices which might use it.
|
|
% (MEMO: it is not a problem here if there is no sphinx<type>ShadowColor,
|
|
% as it used only if set)
|
|
\spx@boxes@fcolorbox@setup{\spx@noticetype}%
|
|
% Those are used by sphinxVerbatim if the \ifspx@inframed boolean is true
|
|
\setlength{\FrameRule}{0.5\dimexpr\spx@boxes@border@top+\spx@boxes@border@bottom\relax}%
|
|
% MEMO: prior to 5.1.0 \FrameSep was determined as 0.6\baselineskip -
|
|
% \FrameRule, and there was no possibility for user to adjust padding.
|
|
% Then \fcolorbox was used with \fboxrule set to \FrameRule and \fboxsep
|
|
% set to \FrameSep.
|
|
% The 5.1.0 default calculation of padding parameters maintains PDF output
|
|
% identical to legacy behaviour, as long as padding is not set by user.
|
|
\setlength{\FrameSep}{0.5\dimexpr\spx@boxes@padding@top+\spx@boxes@padding@bottom\relax}%
|
|
% "setup" macro has prepared the \spx@boxes@... dimen registers
|
|
\advance\spx@image@maxheight
|
|
-\dimexpr\spx@boxes@border@top+\spx@boxes@border@bottom
|
|
+\spx@boxes@padding@top+\spx@boxes@padding@bottom
|
|
+\baselineskip\relax % will happen again if nested, needed indeed!
|
|
% MEMO: the next comment is before boxing was extended to allow padding and
|
|
% multiple border-widths, not to mention shadows...
|
|
% 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.
|
|
\ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
|
|
\vspace{\FrameHeightAdjust}
|
|
% copied/adapted from framed.sty's snugshade
|
|
% but now using in place of \fcolorbox the Sphinx sophisticated own
|
|
\def\FrameCommand##1{%
|
|
\hskip\@totalleftmargin
|
|
% "setup" macro MUST have been called before
|
|
\spx@boxes@fcolorbox{##1}%
|
|
\hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth
|
|
}%
|
|
% 6.2.0 adds support for div.<notice type>_box-decoration-break=slice.
|
|
% (it is yet undecided if slice style should inhibit a bottom shadow)
|
|
\csname ifspx@\spx@noticetype @border@open\endcsname
|
|
\def\FirstFrameCommand
|
|
{\spx@boxes@fcolorbox@setup@openbottom\FrameCommand}%
|
|
\def\MidFrameCommand
|
|
{\spx@boxes@fcolorbox@setup@openboth \FrameCommand}%
|
|
\def\LastFrameCommand
|
|
{\spx@boxes@fcolorbox@setup@opentop \FrameCommand}%
|
|
\fi
|
|
\savenotes
|
|
% use a minipage if we are already inside a framed environment
|
|
\ifspx@inframed
|
|
\noindent\begin{minipage}{\linewidth}
|
|
\else
|
|
% handle case where notice is first thing in a list item (or is quoted)
|
|
\if@inlabel
|
|
\noindent\par\vspace{-\baselineskip}
|
|
\else
|
|
\vspace{\parskip}
|
|
\fi
|
|
\fi
|
|
\MakeFramed {\spx@inframedtrue
|
|
\advance\hsize-\width \@totalleftmargin\z@ \linewidth\hsize
|
|
% minipage initialization copied from LaTeX source code.
|
|
\@pboxswfalse
|
|
\let\@listdepth\@mplistdepth \@mplistdepth\z@
|
|
\@minipagerestore
|
|
\@setminipage }%
|
|
\color@begingroup % workaround to an upstream framed.sty bug
|
|
}
|
|
{%
|
|
\par\unskip
|
|
\color@endgroup % matches the \color@begingroup
|
|
\@minipagefalse
|
|
\endMakeFramed
|
|
\ifspx@inframed\end{minipage}\fi
|
|
% set footnotes at bottom of page
|
|
\spewnotes
|
|
% arrange for similar spacing below frame as for "light" boxes.
|
|
\vskip .4\baselineskip
|
|
}% end of sphinxheavybox environment definition
|
|
|
|
% - Since 1.5 these environments are named individually to allow user to
|
|
% redefine them entirely.
|
|
%
|
|
% - Since 5.1.0, sphinxheavybox is more versatile and four border widths, four
|
|
% padding widths, four corner radii, optional shadow, and three colors can all
|
|
% be modified via CSS-named alike options.
|
|
%
|
|
% - Since 6.2.0, also note/hint/important/tip notices can use these options
|
|
% and then they go automatically via sphinxheavybox. If only the legacy options
|
|
% are used, they keep using sphinxlightbox.
|
|
%
|
|
% - Since 6.2.0, \sphinxwarningtitle etc... add one level of mark-up (they
|
|
% expand to \sphinxstrong{#1}<space> which was former hard-coded mark-up).
|
|
% Example:
|
|
% \renewcommand{\sphinxwarningtitle}[1]{\textbf{#1}\par\smallskip
|
|
% {\color{sphinxwarningBorderColor}\hrule height1pt}\smallskip}
|
|
\newenvironment{sphinxwarning}[1]
|
|
{\begin{sphinxheavybox}\sphinxstylewarningtitle{#1}}{\end{sphinxheavybox}}
|
|
\newenvironment{sphinxcaution}[1]
|
|
{\begin{sphinxheavybox}\sphinxstylecautiontitle{#1}}{\end{sphinxheavybox}}
|
|
\newenvironment{sphinxattention}[1]
|
|
{\begin{sphinxheavybox}\sphinxstyleattentiontitle{#1}}{\end{sphinxheavybox}}
|
|
\newenvironment{sphinxdanger}[1]
|
|
{\begin{sphinxheavybox}\sphinxstyledangertitle{#1}}{\end{sphinxheavybox}}
|
|
\newenvironment{sphinxerror}[1]
|
|
{\begin{sphinxheavybox}\sphinxstyleerrortitle{#1}}{\end{sphinxheavybox}}
|
|
|
|
% the main dispatch for all types of notices
|
|
\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
|
|
% can't use #1 directly in definition of end part
|
|
\def\spx@noticetype {#1}%
|
|
% those next three are a remnant of legacy code; they are not used at
|
|
% all by sphinxheavybox, and their usage could be disposed of by sphinxlightbox
|
|
% but we keep for backward compatibility and also because it may be simpler
|
|
% for user redefinitions to employ for example "spx@notice@bgcolor" and not
|
|
% the more bulky "sphinx\spx@noticetype BgColor".
|
|
\sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
|
|
\sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
|
|
\spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
|
|
% trigger the sphinx<type> environment, #2=heading is passed as argument
|
|
\begin{sphinx#1}{#2}%
|
|
% 6.2.0 support of div.<type>_TeX{color,extras} options
|
|
\csname ifspx@\spx@noticetype @withtextcolor\endcsname
|
|
\color{sphinx\spx@noticetype TextColor}%
|
|
\fi
|
|
\csname spx@\spx@noticetype @TeXextras\endcsname
|
|
}
|
|
% workaround some LaTeX "feature" of \end command (can't use "sphinx#1" here)
|
|
{\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
|
|
|
|
\endinput
|