This repository provides User Manual for setting up a Docker environment tailored for testing DGTD code.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

424 lines
18 KiB

8 months ago
%% COLOURED BOXES
%
% change this info string if making any custom modification
\ProvidesPackage{sphinxpackageboxes}[2022/07/04 v5.1.0 advanced colored boxes]
% Optionally executes \RequirePackage for:
%
% - pict2e. Ideally we would like to use the v0.4a 2020/08/16 release of this
% package as it allows dimensional arguments to its \moveto, \lineto, etc...
% Or we could use extra package "picture". We opt for custom wrappers
% \spx@moveto, \spx@lineto, ..., working with old versions.
% Provides box registers \spx@tempboxa, \spx@tempboxb usable in other places
\newbox\spx@tempboxa
\newbox\spx@tempboxb
% Internal dimens, conditionals, and colour parameters to be configured
% by callers in "setup" macros
\newif\ifspx@boxes@withshadow
\newif\ifspx@boxes@insetshadow
\newif\ifspx@boxes@withbackgroundcolor
\newif\ifspx@boxes@withshadowcolor
\newif\ifspx@boxes@withbordercolor
%
\newdimen\spx@boxes@border
\newdimen\spx@boxes@border@top
\newdimen\spx@boxes@border@right
\newdimen\spx@boxes@border@bottom
\newdimen\spx@boxes@border@left
%
\newdimen\spx@boxes@padding@top
\newdimen\spx@boxes@padding@right
\newdimen\spx@boxes@padding@bottom
\newdimen\spx@boxes@padding@left
%
\newdimen\spx@boxes@shadow@xoffset
\newdimen\spx@boxes@shadow@yoffset
%
\newdimen\spx@boxes@radius@topleft % only circular arcs, x-radius same as y-radius
\newdimen\spx@boxes@radius@topright
\newdimen\spx@boxes@radius@bottomright
\newdimen\spx@boxes@radius@bottomleft
%
% These colours have to be defined appropriately by the callers:
% spx@boxes@bordercolor
% spx@boxes@backgroundcolor
% spx@boxes@shadowcolor
%%%%%%%%%%%%%%%%
% MACROS
%
% - \spx@boxes@fcolorbox (4 padding parameters, 4 border widths, 2 shadow widths,
% and three colours: background, border and shadow; same as in CSS styling)
%
% - \spx@boxes@fcolorbox@insetshadow (same as in CSS styling)
%
% - \spx@boxes@fcolorbox@rounded: rounded corners using the picture environment
% and pict2e package for its low-weight interface to PDF graphics operations
% MEMO: we have also successfully tested usage of tcolorbox.sty (its \tcbox) but
% decided to use pict2e.sty for the following reasons:
% 1- PDF build was observed to be an order of magnitude faster,
% 2- the boxes we can do with pict2e appear to be fancy enough,
% almost matching what one can see in HTML renderings,
% 2- orders of magnitude smaller dependency (tcolorbox uses the pgf TeX
% framework), although on Ubuntu it seems texlive-pictures is
% needed which also contains the whole of pgf/TikZ... so this point
% is a bit moot...
% For code-blocks, attachements of caption and continuation hints are done
% exactly as prior to extension of Sphinx via this package, whether the box
% has straight or rounded corners. The vertical space occupied is the same,
% if nothing else is changed (perhaps in future the title itself could be also
% rendered in a rounded box?)
%//// \spx@boxes@fcolorbox
% 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).
%
% The customization of the various parameters are under responsability of
% the caller, before exapnsion of \spx@boxes@fcolorbox.
% An extra hook is provided:
\let\spx@boxes@fcolorbox@setuphook\@empty
%
% The parameters are interpreted as they would as CSS properties.
% For inset shadows see separate \spx@boxes@fcolorbox@insetshadow.
\long\def\spx@boxes@fcolorbox#1{%
\hbox\bgroup
\spx@boxes@fcolorbox@setuphook
\setbox\spx@tempboxa
\hbox{\kern\dimexpr\spx@boxes@border@left+\spx@boxes@padding@left\relax
{#1}%
\kern\dimexpr\spx@boxes@padding@right+\spx@boxes@border@right\relax}%
\ht\spx@tempboxa
\dimexpr\ht\spx@tempboxa+\spx@boxes@border@top+\spx@boxes@padding@top\relax
\dp\spx@tempboxa
\dimexpr\dp\spx@tempboxa+\spx@boxes@padding@bottom+\spx@boxes@border@bottom\relax
\ifspx@boxes@insetshadow
\expandafter\spx@boxes@fcolorbox@insetshadow
\else
\expandafter\spx@boxes@fcolorbox@externalshadow
\fi
}
\def\spx@boxes@fcolorbox@externalshadow{%
% reserve space to shadow if on left
\ifspx@boxes@withshadow
\ifdim\spx@boxes@shadow@xoffset<\z@\kern-\spx@boxes@shadow@xoffset\fi
\fi
% BACKGROUND
% draw background and move back to reference point
\ifspx@boxes@withbackgroundcolor
{\color{spx@boxes@backgroundcolor}%
\vrule\@height\ht\spx@tempboxa
\@depth\dp\spx@tempboxa
\@width\wd\spx@tempboxa
\kern-\wd\spx@tempboxa
}%
\fi
% BOX SHADOW
% draw shadow and move back to reference point
\ifspx@boxes@withshadow
\vbox{%
\moveright\spx@boxes@shadow@xoffset
\hbox{\lower\spx@boxes@shadow@yoffset
\vbox{\ifspx@boxes@withshadowcolor\color{spx@boxes@shadowcolor}\fi
\ifdim\spx@boxes@shadow@yoffset<\z@
\hrule\@height-\spx@boxes@shadow@yoffset
\kern\spx@boxes@shadow@yoffset
\fi
\setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa{%
\ifdim\spx@boxes@shadow@xoffset<\z@\vrule\@width-\spx@boxes@shadow@xoffset\fi
\hss
\ifdim\spx@boxes@shadow@xoffset>\z@\vrule\@width\spx@boxes@shadow@xoffset\fi
}%
\ht\spx@tempboxb\ht\spx@tempboxa
\dp\spx@tempboxb\dp\spx@tempboxa
\box\spx@tempboxb
\ifdim\spx@boxes@shadow@yoffset>\z@
\kern-\spx@boxes@shadow@yoffset
\hrule\@height\spx@boxes@shadow@yoffset
\fi
\kern-\dp\spx@tempboxa
}% end of \vbox, attention it will have zero depth if yoffset>0
\kern-\wd\spx@tempboxa
\ifdim\spx@boxes@shadow@xoffset>\z@
\kern-\spx@boxes@shadow@xoffset
\fi
}% end of \hbox, attention its depth is only yoffset if yoffset>0
}% end of \vbox
\fi % end of shadow drawing, and we are back to horizontal reference point
% BOX BORDER
\vbox{\ifspx@boxes@withbordercolor\color{spx@boxes@bordercolor}\fi
\hrule\@height\spx@boxes@border@top
\kern-\spx@boxes@border@top
\setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa
{\vrule\@width\spx@boxes@border@left
\hss\vrule\@width\spx@boxes@border@right
}%
\ht\spx@tempboxb\ht\spx@tempboxa
\dp\spx@tempboxb\dp\spx@tempboxa
\box\spx@tempboxb
\kern-\spx@boxes@border@bottom
\hrule\@height\spx@boxes@border@bottom
\kern-\dp\spx@tempboxa
}% attention this box has zero depth due to \hrule at bottom
% step back to horizontal reference point
\kern-\wd\spx@tempboxa
% end of border drawing
% CONTENTS
% adjust the total depth to include the bottom shadow
\ifspx@boxes@withshadow
\ifdim\spx@boxes@shadow@yoffset>\z@
\dp\spx@tempboxa\dimexpr\dp\spx@tempboxa+\spx@boxes@shadow@yoffset\relax
\fi
\fi
\box\spx@tempboxa
% include lateral shadow in total width
\ifspx@boxes@withshadow
\ifdim\spx@boxes@shadow@xoffset>\z@\kern\spx@boxes@shadow@xoffset\fi
\fi
\egroup
}
%//// \spx@boxes@fcolorbox@insetshadow
% The parameters are interpreted as in CSS styling.
\def\spx@boxes@fcolorbox@insetshadow{%
% BACKGROUND
% draw background and move back to reference point
\ifspx@boxes@withbackgroundcolor
{\color{spx@boxes@backgroundcolor}%
\vrule\@height\ht\spx@tempboxa
\@depth\dp\spx@tempboxa
\@width\wd\spx@tempboxa
\kern-\wd\spx@tempboxa
}%
\fi
% BOX SHADOW
% draw shadow and move back to reference point
\ifspx@boxes@withshadow
\hbox{\vbox{\ifspx@boxes@withshadowcolor\color{spx@boxes@shadowcolor}\fi
% NOTA BENE
% We deliberately draw shadow partially under an area later covered by frame
% with the idea to avoid anti-aliasing problems but in fact this may be a bad
% idea with border is thin.
% This may need some extra testing with PDF viewers... reports welcome!
\ifdim\spx@boxes@shadow@yoffset>\z@
\hrule\@height\dimexpr\spx@boxes@border@top+\spx@boxes@shadow@yoffset\relax
\kern-\spx@boxes@shadow@yoffset
\kern-\spx@boxes@border@top
\fi
\setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa{%
\ifdim\spx@boxes@shadow@xoffset>\z@
\vrule\@width\dimexpr\spx@boxes@border@left+\spx@boxes@shadow@xoffset\relax\fi
\hss
\ifdim\spx@boxes@shadow@xoffset<\z@
\vrule\@width\dimexpr-\spx@boxes@shadow@xoffset+\spx@boxes@border@right\relax\fi
}%
\ht\spx@tempboxb\ht\spx@tempboxa
\dp\spx@tempboxb\dp\spx@tempboxa
\box\spx@tempboxb
\ifdim\spx@boxes@shadow@yoffset<\z@
\kern\spx@boxes@shadow@yoffset
\kern-\spx@boxes@border@bottom
\hrule\@height\dimexpr-\spx@boxes@shadow@yoffset+\spx@boxes@border@bottom\relax
\fi
\kern-\dp\spx@tempboxa
}% end of \vbox, attention it will have zero depth if yoffset<0
\kern-\wd\spx@tempboxa
}% end of \hbox, attention its depth is only |yoffset| if yoffset<0
\fi % end of inset shadow drawing, and we are back to horizontal reference point
% BOX BORDER
\vbox{\ifspx@boxes@withbordercolor\color{spx@boxes@bordercolor}\fi
\hrule\@height\spx@boxes@border@top
\kern-\spx@boxes@border@top
\setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa
{\vrule\@width\spx@boxes@border@left
\hss\vrule\@width\spx@boxes@border@right
}%
\ht\spx@tempboxb\ht\spx@tempboxa
\dp\spx@tempboxb\dp\spx@tempboxa
\box\spx@tempboxb
\kern-\spx@boxes@border@bottom
\hrule\@height\spx@boxes@border@bottom
\kern-\dp\spx@tempboxa
}% attention this box has zero depth due to \hrule at bottom
% step back to horizontal reference point
\kern-\wd\spx@tempboxa
% end of border drawing
% CONTENTS
\box\spx@tempboxa
\egroup
}
%%%%%%%%
% \spx@boxes@fcolorbox@rounded
%
% Various radii but only one border-width parameter.
% Shadow too.
% wrappers for pict2e usage if old
% Better not to copy over 2020 pict2e definitions in case
% something internal changes
% However our wrappers will work ONLY with dimensional inputs
% No need to pre-expand the arguments
% Braces in case the expression uses parentheses
\def\spx@moveto(#1,#2){\moveto({\strip@pt\dimexpr#1\relax},{\strip@pt\dimexpr#2\relax})}
\def\spx@lineto(#1,#2){\lineto({\strip@pt\dimexpr#1\relax},{\strip@pt\dimexpr#2\relax})}
% attention here the [N] becomes mandatory
\def\spx@circlearc[#1]#2#3#4%#5#6
{\circlearc[#1]{\strip@pt\dimexpr#2\relax}%
{\strip@pt\dimexpr#3\relax}%
{\strip@pt\dimexpr#4\relax}}
% This macro will when executed in a picture environment prepare a path which
% is both used for filling backround color and stroking border
% The coordinate origin in the LaTeX picture environment will be at half the
% border width (d/2, d/2), d = constant border width
\def\spx@boxes@borderpath{%
\spx@moveto(\spx@boxes@radius@bottomleft,\z@)% \z@ not 0 as our \spx@moveto is quite dumb
\spx@lineto(\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright,\z@)%
\spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright}%
{\spx@boxes@radius@bottomright}%
{\spx@boxes@radius@bottomright}{-90}{0}%
\spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,%
\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright)%
\spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}
{\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}%
{\spx@boxes@radius@topright}{0}{90}%
\spx@lineto(\spx@boxes@radius@topleft,\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
\spx@circlearc[2]{\spx@boxes@radius@topleft}%
{\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topleft}%
{\spx@boxes@radius@topleft}{90}{180}%
\spx@lineto(\z@,\spx@boxes@radius@bottomleft)%
\spx@circlearc[2]{\spx@boxes@radius@bottomleft}%
{\spx@boxes@radius@bottomleft}%
{\spx@boxes@radius@bottomleft}{180}{270}%
}% end of definition of \spx@boxes@borderpath
\def\spx@boxes@borderpath@opentop{%
\spx@moveto(\z@,\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
\spx@lineto(\z@,\spx@boxes@radius@bottomleft)%
\spx@circlearc[2]{\spx@boxes@radius@bottomleft}%
{\spx@boxes@radius@bottomleft}%
{\spx@boxes@radius@bottomleft}{180}{270}%
\spx@lineto(\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright,\z@)%
\spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright}%
{\spx@boxes@radius@bottomright}%
{\spx@boxes@radius@bottomright}{-90}{0}%
\spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,%
\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
}% end of definition of \spx@boxes@borderpath@opentop
\def\spx@boxes@borderpath@openbottom{%
\spx@moveto(\wd\spx@tempboxa-\spx@boxes@border,\z@)%
\spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,%
\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright)%
\spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}
{\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}%
{\spx@boxes@radius@topright}{0}{90}%
\spx@lineto(\spx@boxes@radius@topleft,\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
\spx@circlearc[2]{\spx@boxes@radius@topleft}%
{\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topleft}%
{\spx@boxes@radius@topleft}{90}{180}%
\spx@lineto(\z@,\z@)%
}% end of definition of \spx@boxes@borderpath@openbottom
\def\spx@boxes@borderpath@openboth{%
\spx@moveto(\wd\spx@tempboxa-\spx@boxes@border,\z@)%
\spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,%
\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
\spx@moveto(\z@,\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
\spx@lineto(\z@,\z@)%
}% end of definition of \spx@boxes@borderpath@openboth
\long\def\spx@boxes@fcolorbox@rounded #1{%
\hbox{%
\spx@boxes@fcolorbox@setuphook
% reserve space to shadow if on left
\ifspx@boxes@withshadow
\ifdim\spx@boxes@shadow@xoffset<\z@\kern-\spx@boxes@shadow@xoffset\fi
\fi
\vbox{%
% adjust vertical bbox
\ifspx@boxes@withshadow
\ifdim\spx@boxes@shadow@yoffset<\z@
\kern-\spx@boxes@shadow@yoffset
\fi
\fi
\setlength{\unitlength}{1pt}%
\setbox\spx@tempboxa
\hbox{\kern\dimexpr\spx@boxes@border+\spx@boxes@padding@left\relax
{#1}%
\kern\dimexpr\spx@boxes@padding@right+\spx@boxes@border\relax}%
\ht\spx@tempboxa
\dimexpr\ht\spx@tempboxa+\spx@boxes@border+\spx@boxes@padding@top\relax
\dp\spx@tempboxa
\dimexpr\dp\spx@tempboxa+\spx@boxes@padding@bottom+\spx@boxes@border\relax
\hbox{%
\begin{picture}%
% \strip@pt\dimexpr to work around "old" LaTeX picture limitation
% (we could use the "picture" package, this would add another dependency)
(\strip@pt\wd\spx@tempboxa,\strip@pt\dimexpr\ht\spx@tempboxa+\dp\spx@tempboxa\relax)%
(\strip@pt\dimexpr-.5\spx@boxes@border\relax,\strip@pt\dimexpr-.5\spx@boxes@border\relax)%
\ifspx@boxes@withshadow
\color{spx@boxes@shadowcolor}%
\put(\strip@pt\dimexpr\ifdim\spx@boxes@shadow@xoffset<\z@-\fi
0.5\spx@boxes@border+\spx@boxes@shadow@xoffset\relax,%
\strip@pt\dimexpr\ifdim\spx@boxes@shadow@yoffset<\z@\else-\fi
0.5\spx@boxes@border-\spx@boxes@shadow@yoffset\relax)
{\spx@boxes@borderpath\fillpath}%
{\ifspx@boxes@withbackgroundcolor\else
\color{white}% or rather try to use page color?
\spx@boxes@borderpath\fillpath
\fi}%
\fi
{\ifspx@boxes@withbackgroundcolor
\color{spx@boxes@backgroundcolor}%
\spx@boxes@borderpath\fillpath
\fi}%
\ifdim\spx@boxes@border>\z@
% even with \spx@boxes@border set to 0pt as done if verbatimwithframe=false
% stroke will produce a visible contour, so we exclude doing it in that case
\ifspx@boxes@withbordercolor
\color{spx@boxes@bordercolor}%
\fi
\linethickness{\spx@boxes@border}%
\ifdim\spx@boxes@border@top=\z@
\ifdim\spx@boxes@border@bottom=\z@
\spx@boxes@borderpath@openboth
\else \spx@boxes@borderpath@opentop
\fi
\else
\ifdim\spx@boxes@border@bottom=\z@
\spx@boxes@borderpath@openbottom
\else\spx@boxes@borderpath\strokepath
\fi\fi
\strokepath
\fi
\end{picture}}% end of picture \hbox in \vbox
% back-up vertically for outputting the contents
\kern-\dimexpr\ht\spx@tempboxa+\dp\spx@tempboxa\relax
% adjust vertical bbox
\ifspx@boxes@withshadow
\ifdim\spx@boxes@shadow@yoffset>\z@
\dp\spx@tempboxa\dimexpr\dp\spx@tempboxa+\spx@boxes@shadow@yoffset\relax
\fi
\fi
\box\spx@tempboxa
}% end of \vbox
% include lateral shadow in total width
\ifspx@boxes@withshadow
\ifdim\spx@boxes@shadow@xoffset>\z@\kern\spx@boxes@shadow@xoffset\fi
\fi
}% end of \hbox
}%
\endinput