From 66c819ee217018f3590ceb87b5052b662df2c16c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 13 Mar 2023 17:19:58 +0100 Subject: [PATCH] LaTeX: refactoring of some internals from box-decoration-break support --- sphinx/texinputs/sphinxlatexliterals.sty | 26 ++---- sphinx/texinputs/sphinxpackageboxes.sty | 108 +++++++++++++++++------ 2 files changed, 87 insertions(+), 47 deletions(-) diff --git a/sphinx/texinputs/sphinxlatexliterals.sty b/sphinx/texinputs/sphinxlatexliterals.sty index c4902ff2f..c16bea530 100644 --- a/sphinx/texinputs/sphinxlatexliterals.sty +++ b/sphinx/texinputs/sphinxlatexliterals.sty @@ -190,19 +190,19 @@ }% \def\sphinxVerbatim@FirstFrameCommand{% \ifspx@pre@border@open - \let\spx@boxes@fcolorbox@setuphook\spx@verb@boxes@fcolorbox@setuphook@openbottom + \spx@boxes@fcolorbox@setup@openbottom \fi \spx@verb@FrameCommand\sphinxVerbatim@Before\sphinxVerbatim@Continues }% \def\sphinxVerbatim@MidFrameCommand{% \ifspx@pre@border@open - \let\spx@boxes@fcolorbox@setuphook\spx@verb@boxes@fcolorbox@setuphook@openboth + \spx@boxes@fcolorbox@setup@openboth \fi \spx@verb@FrameCommand\sphinxVerbatim@Continued\sphinxVerbatim@Continues }% \def\sphinxVerbatim@LastFrameCommand{% \ifspx@pre@border@open - \let\spx@boxes@fcolorbox@setuphook\spx@verb@boxes@fcolorbox@setuphook@opentop + \spx@boxes@fcolorbox@setup@opentop \fi \spx@verb@FrameCommand\sphinxVerbatim@Continued\sphinxVerbatim@After }% @@ -218,26 +218,10 @@ \spx@boxes@border@bottom\z@ \spx@boxes@border@left\z@ \spx@boxes@border\z@ + % MEMO: rounded corners still make sense in presence of a background + % color, so we do not force the fcolorbox@rectangle here \fi }% -\def\spx@verb@boxes@fcolorbox@setuphook@openbottom{% - \spx@boxes@border@bottom \z@ - \spx@boxes@radius@bottomright\z@ - \spx@boxes@radius@bottomleft \z@ -}% -\def\spx@verb@boxes@fcolorbox@setuphook@opentop{% - \spx@boxes@border@top \z@ - \spx@boxes@radius@topright\z@ - \spx@boxes@radius@topleft \z@ -}% -\def\spx@verb@boxes@fcolorbox@setuphook@openboth{% - \spx@boxes@border@top \z@ - \spx@boxes@border@bottom \z@ - \spx@boxes@radius@topright\z@ - \spx@boxes@radius@topleft \z@ - \spx@boxes@radius@bottomright\z@ - \spx@boxes@radius@bottomleft \z@ -}% % For linebreaks inside Verbatim environment from package fancyvrb. \newbox\sphinxcontinuationbox diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index 9bd80b16c..f1efbc4c0 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -156,11 +156,11 @@ % As this conditional is a priori false and should only be changed locally % (by \sphinxbox), this line is actually superfluous. \spx@boxes@shadowinbboxfalse - \spx@boxes@fcolorbox@setup@b + \spx@boxes@fcolorbox@setup@fcolorbox } \@ifpackageloaded{pict2e} {% pict2e is available and loaded - \def\spx@boxes@fcolorbox@setup@b{% + \def\spx@boxes@fcolorbox@setup@fcolorbox{% \if1% use rounded boxes only if needed and no inset shadow \ifdim\spx@boxes@radius@topleft >\z@0\fi \ifdim\spx@boxes@radius@topright >\z@0\fi @@ -174,14 +174,46 @@ \def\spx@boxes@fcolorbox{\spx@boxes@fcolorbox@rounded}% \fi \fi - }% end of definition of setup@b in case of presence of pict2e + }% end of definition of setup@fcolorbox in case of presence of pict2e }% {% pict2e could not be loaded, we must always use fcolorbox@rectangle - \def\spx@boxes@fcolorbox@setup@b{% + \def\spx@boxes@fcolorbox@setup@fcolorbox{% \def\spx@boxes@fcolorbox{\spx@boxes@fcolorbox@rectangle}% - }% end of definition of setup@b in case of absence of pict2e + }% end of definition of setup@fcolorbox in case of absence of pict2e }% end of "no pict2e" branch +%%%%%%%%%%%%%%%% +% Support of box-decoration-break +% +% 6.2.0 has renamed and moved this here from sphinxlatexliterals.sty. +% It also modified when these post actions are executed, in order +% for openboth to be able to trigger usage of fcolorbox@rectangle. +% So now openbottom and opentop also take advantage of this possible +% optimization. +% +% Currently only used by sphinxVerbatim, i.e. code-block directive. +\def\spx@boxes@fcolorbox@setup@openbottom{% + \spx@boxes@border@bottom \z@ + \spx@boxes@radius@bottomright\z@ + \spx@boxes@radius@bottomleft \z@ + \spx@boxes@fcolorbox@setup@fcolorbox +}% +\def\spx@boxes@fcolorbox@setup@opentop{% + \spx@boxes@border@top \z@ + \spx@boxes@radius@topright\z@ + \spx@boxes@radius@topleft \z@ + \spx@boxes@fcolorbox@setup@fcolorbox +}% +\def\spx@boxes@fcolorbox@setup@openboth{% + \spx@boxes@border@top \z@ + \spx@boxes@border@bottom \z@ + \spx@boxes@radius@topright\z@ + \spx@boxes@radius@topleft \z@ + \spx@boxes@radius@bottomright\z@ + \spx@boxes@radius@bottomleft \z@ + \def\spx@boxes@fcolorbox{\spx@boxes@fcolorbox@rectangle}% +}% + %%%%%%%%%%%%%%%% % \sphinxbox (added at 6.2.0) % @@ -249,12 +281,20 @@ % % \spx@boxes@fcolorbox expands either to \spx@boxes@fcolorbox@rectangle % or \spx@boxes@fcolorbox@rounded depending on preliminary set-up. -% Let's give it some default fall-back: -% (but preliminary "setup" of \spx@boxes@fcolorbox@rectangle parameters -% is mandatory requirement for it to work) +% +% This is decided by the "setup" which must have been executed by the caller. +% Let's give it some (thus unneeded) default fall-back for clarity. \def\spx@boxes@fcolorbox{\spx@boxes@fcolorbox@rectangle} - -% Then: +% +% A macro \spx@boxes@fcolorbox@setuphook used to be executed at start of the +% \hbox constructs (rectangle or rounded). This was used until 6.2.0 for the +% support of pre_box-decoration-break option, hence was really an internal +% non-public macro. As it is not needed anymore, with some hesitation it got +% entirely removed at 6.2.0 on the occasion of a refactoring of interactions of +% this file with sphinxlatexliterals.sty. Besides its name should have been +% rather something such as \spx@boxes@fcolorbox@atstartofhbox. +% +% After "setup", \spx@boxes@fcolorbox expands to one of: % % - \spx@boxes@fcolorbox@rectangle (4 padding parameters, 4 border widths, 2 shadow widths, % and three colours: background, border and shadow; same as in CSS styling) @@ -282,27 +322,30 @@ % if nothing else is changed (perhaps in future the title itself could be also % rendered in a rounded box?) +%%%%%%%% %//// \spx@boxes@fcolorbox@rectangle +% % This box will have the same baseline as its argument (which is typeset in % horizontal mode). It takes into account four border widths parameters, four % padding parameters, two shadow widths (each possibly negative), and three % colors: background, border and shadow. Its boundary box takes into account -% all of shadow, border and padding. It is up to the caller to take steps for -% the shadow (and perhaps also border, and padding) to go into margin or stay -% inside the text area, in collaboration with framed.sty. In usage as a -% "FrameCommand" with framed.sty, the argument will already be a collection -% of TeX boxes (and interline glues). +% border and padding. Width of shadow is taken into account if the boolean +% \ifspx@boxes@shadowinbbox is \iftrue. The "setup" sets it to \iffalse. +% Prior to 6.2.0, shadow size was included in bbox but the callers manually +% removed it by extra steps. The \sphinxbox command sets it to \iftrue after +% the "setup". % -% The customization of the various parameters are under responsability of -% the caller, before expansion of \spx@boxes@fcolorbox. -% An extra hook is provided which is used by \sphinxVerbatim@FirstFrameCommand -% from sphinxlatexliterals.sty and others. -\let\spx@boxes@fcolorbox@setuphook\@empty +% It is up to the caller to take extra steps if the border and padding must go +% into margin as well (see sphinxlatexliterals.sty for how this is done in +% \spx@verb@FrameCommand). +% +% In usage as a "FrameCommand" with framed.sty, the argument will already be a +% collection of TeX boxes (and interline glues). % -% The parameters are interpreted as they would as CSS properties. +% This was designed so that the parameters configured by "setup" are +% interpreted as they would be as CSS properties in an HTML context. \long\def\spx@boxes@fcolorbox@rectangle#1{% \hbox\bgroup - \spx@boxes@fcolorbox@setuphook \setbox\spx@tempboxa \hbox{\kern\dimexpr\spx@boxes@border@left+\spx@boxes@padding@left\relax {#1}% @@ -318,6 +361,7 @@ \fi } +% external shadow \def\spx@boxes@fcolorbox@externalshadow{% % reserve space to external shadow if on left \ifspx@boxes@withshadow @@ -414,8 +458,9 @@ \egroup } -%//// \spx@boxes@fcolorbox@insetshadow -% The parameters are interpreted as in CSS styling. +% inset shadow +% +% The parameters signs are interpreted as in CSS styling. \def\spx@boxes@fcolorbox@insetshadow{% % BACKGROUND % draw background and move back to reference point @@ -511,7 +556,7 @@ % swallowed all the coming definitions even if pict2e % had in fact not been loaded... but we aborted the input above) %%%%%%%% -% \spx@boxes@fcolorbox@rounded +%//// \spx@boxes@fcolorbox@rounded % % Various radii but only one border-width parameter. % Shadow too. @@ -580,6 +625,13 @@ {\spx@boxes@radius@topleft}{90}{180}% \spx@lineto(\z@,\z@)% }% end of definition of \spx@boxes@borderpath@openbottom +% MEMO: at 6.2.0, this is still needed. If the user has set some corner radius +% to be positive and also both bottom and top border widths to be zero, this +% will be executed (and thus ignore the radii). But in the specific case of +% the MidFrameCommand of sphinxVerbatim under pre_box-decoration-break=slice +% (code-block is the only directive supporting it so far) the +% \spx@boxes@fcolorbox@setup@openboth will have triggered usage of +% fcolorbox@rectangle, not fcolorbox@rounded, so this is not executed then. \def\spx@boxes@borderpath@openboth{% \spx@moveto(\wd\spx@tempboxa-\spx@boxes@border,\z@)% \spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,% @@ -588,9 +640,13 @@ \spx@lineto(\z@,\z@)% }% end of definition of \spx@boxes@borderpath@openboth +% The customization of the various parameters must have been done via an +% appropriate call to \spx@boxes@fcolorbox@setup, which will have set up +% \spx@boxes@fcolorbox to expand to \spx@boxes@fcolorbox@rounded, and will +% have set its various parameters. +% \long\def\spx@boxes@fcolorbox@rounded #1{% \hbox{% - \spx@boxes@fcolorbox@setuphook % reserve space to external shadow if on left \ifspx@boxes@withshadow \ifspx@boxes@shadowinbbox