LaTeX: some code and comments clean-up for readability

sphinx-doc · Jul 8, 2022 · fd03665 · fd03665
1 parent 9528ebf
commit fd03665
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 47 deletions.
diff --git a/sphinx/texinputs/sphinxlatexliterals.sty b/sphinx/texinputs/sphinxlatexliterals.sty
@@ -148,12 +148,15 @@
   \edef\spx@verb@fcolorbox@width@sp
       {\number\dimexpr\wd\z@+2\sphinxverbatimsep+2\sphinxverbatimborder sp}%
   \vbox{#1% continuation hint attached above frame, uses \spx@verb@fcolorbox@width@sp
+        % no \expandafter here for code lisibility
+        % the boxes@fcolorbox constructs an \hbox with bbox containing the border
         \ifdim\sphinxverbatimradius>\z@
-          \expandafter\spx@boxes@fcolorbox@rounded
+          \spx@boxes@fcolorbox@rounded{\box\z@}%
         \else
-          \expandafter\spx@boxes@fcolorbox
+          \spx@boxes@fcolorbox{\box\z@}%
         \fi
-        {\box\z@}% the macro constructs an \hbox with bbox containing the border
+        % This \nointerlineskip to maintain legacy spacing when a \hrule was
+        % formerly last prior item in vertical list.  TODO: remove this at 6.0.0 ?
         \nointerlineskip
         #2% continuation hint attached below frame, uses \spx@verb@fcolorbox@width@sp
        }% end of \vbox
@@ -169,22 +172,26 @@
     \moveright\dimexpr\sphinxverbatimborder+\sphinxverbatimsep\hb@xt@\z@{#1\hss}%
 }%
 %
-\def\sphinxVerbatim@Continued
-   {\csname spx@verb@fcolorbox@put@\spx@opt@verbatimcontinuedalign\endcsname
-    {{\normalcolor\sphinxstylecodecontinued\literalblockcontinuedname}}}%
-\def\sphinxVerbatim@Continues
-   {\csname spx@verb@fcolorbox@put@\spx@opt@verbatimcontinuesalign\endcsname
-    {{\normalcolor\sphinxstylecodecontinues\literalblockcontinuesname}}}%
-\def\sphinxVerbatim@Title
-   {\spx@verb@fcolorbox@put@c{\unhcopy\sphinxVerbatim@TitleBox}}%
+\def\sphinxVerbatim@Continued{%
+    \csname spx@verb@fcolorbox@put@\spx@opt@verbatimcontinuedalign\endcsname
+    {{\normalcolor\sphinxstylecodecontinued\literalblockcontinuedname}}%
+}%
+\def\sphinxVerbatim@Continues{%
+    \csname spx@verb@fcolorbox@put@\spx@opt@verbatimcontinuesalign\endcsname
+    {{\normalcolor\sphinxstylecodecontinues\literalblockcontinuesname}}%
+}%
+\def\sphinxVerbatim@Title{%
+    \spx@verb@fcolorbox@put@c{\unhcopy\sphinxVerbatim@TitleBox}%
+}%
 \let\sphinxVerbatim@Before\@empty
 \let\sphinxVerbatim@After\@empty
 % Defaults are redefined in document preamble according to language
 \newcommand*\literalblockcontinuedname{continued from previous page}%
 \newcommand*\literalblockcontinuesname{continues on next page}%
 %
-\def\sphinxVerbatim@FrameCommand
-   {\spx@verb@FrameCommand\sphinxVerbatim@Before\sphinxVerbatim@After}%
+\def\sphinxVerbatim@FrameCommand{%
+    \spx@verb@FrameCommand\sphinxVerbatim@Before\sphinxVerbatim@After
+}%
 \def\sphinxVerbatim@FirstFrameCommand{%
     \ifspx@opt@verbatimopenframe
       \let\spx@boxes@fcolorbox@init\spx@verb@boxes@fcolorbox@init@openbottom
@@ -194,7 +201,7 @@
 \def\sphinxVerbatim@MidFrameCommand{%
     \ifspx@opt@verbatimopenframe
       \let\spx@boxes@fcolorbox@init\spx@verb@boxes@fcolorbox@init@openboth
-      \sphinxverbatimradius=\z@
+      \sphinxverbatimradius=\z@ % will trigger usage of "rectangular" boxes@fcolorbox
     \fi
     \spx@verb@FrameCommand\sphinxVerbatim@Continued\sphinxVerbatim@Continues
 }%
@@ -717,15 +724,20 @@
   \fi
   \global\let\sphinxLiteralBlockLabel\empty
   \global\let\sphinxVerbatimTitle\empty
+  % the "FrameCommand"'s will check status of verbatimwithframe option
+  % to decide if to stroke the borders ; ultimately they are also
+  % responsible to attach the "Title".
   \let\FrameCommand     \sphinxVerbatim@FrameCommand
-  % they will check status of verbatimopenframe option
+  % those will also check status of the verbatimopenframe option
   \let\FirstFrameCommand\sphinxVerbatim@FirstFrameCommand
   \let\MidFrameCommand  \sphinxVerbatim@MidFrameCommand
   \let\LastFrameCommand \sphinxVerbatim@LastFrameCommand
+  %
   \ifspx@opt@verbatimhintsturnover\else
       \let\sphinxVerbatim@Continued\@empty
       \let\sphinxVerbatim@Continues\@empty
   \fi
+  % initialization for sphinxpackageboxes provided \spx@boxes@fcolorbox
   \def\spx@boxes@fcolorbox@init{\spx@verb@boxes@fcolorbox@init}%
   \ifspx@opt@verbatimwrapslines
     % deep hack into fancyvrb's internal processing of input lines
@@ -787,7 +799,7 @@
      \color@begingroup % protect against color leaks (upstream framed.sty bug)
      % will fetch its optional arguments if any
      \OriginalVerbatim
-}
+}%
 {%
   \endOriginalVerbatim
   \color@endgroup % matches the \color@begingroup

diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty
@@ -18,36 +18,38 @@
 \RequirePackage{framed}
 \RequirePackage{sphinxpackageboxes}
 
+\def\spx@shadowbox@boxes@fcolorbox@init{%
+  \spx@boxes@border@top   \sphinxshadowrule
+  \spx@boxes@border@right \sphinxshadowrule
+  \spx@boxes@border@bottom\sphinxshadowrule
+  \spx@boxes@border@left  \sphinxshadowrule
+  %
+  \spx@boxes@padding@top   \sphinxshadowsep
+  \spx@boxes@padding@right \sphinxshadowsep
+  \spx@boxes@padding@bottom\sphinxshadowsep
+  \spx@boxes@padding@left  \sphinxshadowsep
+  %
+  \spx@boxes@shadow@xoffset\sphinxshadowsize
+  \spx@boxes@shadow@yoffset\sphinxshadowsize
+  %
+  \spx@boxes@noshadowfalse
+  \spx@boxes@nobackgroundcolortrue
+  \spx@boxes@noshadowcolorfalse
+  \sphinxcolorlet{spx@boxes@shadowcolor}{sphinxshadowShadowColor}%
+  \spx@boxes@nobordercolorfalse
+  \sphinxcolorlet{spx@boxes@bordercolor}{sphinxshadowBorderColor}%
+}%
+
+% At 5.1.0 the code formerly here has been refactored and incorporated
+% into more powerful \spx@boxes@fcolorbox from sphinxpackageboxes.sty
 \long\def\spx@ShadowFBox#1{%
-  \leavevmode\begingroup
-  \def\spx@boxes@fcolorbox@init{%
-    \spx@boxes@border@top   \sphinxshadowrule
-    \spx@boxes@border@right \sphinxshadowrule
-    \spx@boxes@border@bottom\sphinxshadowrule
-    \spx@boxes@border@left  \sphinxshadowrule
-    %
-    \spx@boxes@padding@top   \sphinxshadowsep
-    \spx@boxes@padding@right \sphinxshadowsep
-    \spx@boxes@padding@bottom\sphinxshadowsep
-    \spx@boxes@padding@left  \sphinxshadowsep
-    %
-    \spx@boxes@shadow@xoffset\sphinxshadowsize
-    \spx@boxes@shadow@yoffset\sphinxshadowsize
-    %
-    \spx@boxes@noshadowfalse
-    \spx@boxes@nobackgroundcolortrue
-    \spx@boxes@noshadowcolorfalse
-    \sphinxcolorlet{spx@boxes@shadowcolor}{sphinxshadowShadowColor}%
-    \spx@boxes@nobordercolorfalse
-    \sphinxcolorlet{spx@boxes@bordercolor}{sphinxshadowBorderColor}%
-  }%
+  \leavevmode
   % we hide the shadow width
   \ifdim\sphinxshadowsize>\z@
-    \hbox{\spx@boxes@fcolorbox{#1}\kern-\sphinxshadowsize}%
+    \spx@boxes@fcolorbox{#1}\kern-\sphinxshadowsize
   \else
-    \hbox{\kern\sphinxshadowsize\spx@boxes@fcolorbox{#1}}%
+    \kern\sphinxshadowsize\spx@boxes@fcolorbox{#1}%
   \fi
-  \endgroup
 }
 
 % Use framed.sty \MakeFramed/\endMakeFramed to allow page breaks for topic
@@ -69,7 +71,9 @@
 %   more sophisticated way on usage of \MakeFramed/\endMakeFramed, and
 %   adjusting to current text indentation.
 \newenvironment{sphinxShadowBox}
-  {\def\FrameCommand {\spx@ShadowFBox }%
+  {%
+   \let\spx@boxes@fcolorbox@init\spx@shadowbox@boxes@fcolorbox@init
+   \def\FrameCommand {\spx@ShadowFBox }%
    \advance\spx@image@maxheight
    -\dimexpr2\sphinxshadowrule
            +2\sphinxshadowsep

diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty
@@ -8,13 +8,13 @@
 %   allows dimensional arguments to its \moveto, \lineto, etc...  but we add
 %   ourselves some wrappers equivalent to its v0.4a 2020/08/16 version.
 
-
-% WIP
-% Currently provides
-% - box registers \spx@tempboxa, \spx@tempboxb usable in other places
+% Provides box registers \spx@tempboxa, \spx@tempboxb usable in other places
 \newbox\spx@tempboxa
 \newbox\spx@tempboxb
-% - Internal dimens, conditionals, and color parameters
+
+% WIP
+% Internal dimens, conditionals, and color parameters involved
+% in \spx@boxes@fcolorbox@init which is to be set by callers
 \newif\ifspx@boxes@nobackgroundcolor\spx@boxes@nobackgroundcolortrue
 \newif\ifspx@boxes@noshadow         \spx@boxes@noshadowtrue
 \newif\ifspx@boxes@noshadowcolor    \spx@boxes@noshadowcolortrue