LaTeX: refactoring of some internals from box-decoration-break support

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,15 +174,47 @@
         \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)
 %
 % For an inline box, possibly rounded.
@@ -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