diff options
Diffstat (limited to 'sphinx/texinputs/sphinxlatexadmonitions.sty')
| -rw-r--r-- | sphinx/texinputs/sphinxlatexadmonitions.sty | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty new file mode 100644 index 0000000..a31ae4c --- /dev/null +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -0,0 +1,242 @@ +%% 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 |