1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
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
|
