\documentclass[a4paper,dvipdfmx,11pt]{article} \usepackage[T1]{fontenc} \usepackage{geometry} \usepackage[straightquotes,ttzdefault]{newtxtt} \usepackage{framed} \usepackage[dvipsnames]{xcolor} \usepackage{colorframed} % we put this here but it does not have to be in preamble of % course % titled-frame \colorlet{TFFrameColor}{teal!20} \colorlet{TFTitleColor}{orange} \def\colorframedTFconlabcolorcommand{\color{red}} % shaded \colorlet{shadecolor}{orange!20} % framed \FrameRule5pt\relax \FrameSep9pt\relax \def\colorframedbordercolorcommand{\color{red!20}} \title{The \colorframed package% \vadjust{\vtop to 0pt{\hbox to\linewidth{\strut\footnotesize Release 0.9 of 2022/09/22\hss report issues at \url{https://github.com/jfbu/colorframed}}\vss}}% } \author{Jean-François Burnol} \date{} \usepackage{shortvrb}\MakeShortVerb\| %\usepackage{url}\urlstyle{same} \usepackage{hyperref} \def\ctanpackage#1{\href{https://ctan.org/pkg/#1}{#1}} \usepackage{amssymb} \usepackage{parskip} \usepackage{xspace} \definecolor{joli}{RGB}{225,95,0} \definecolor{JOLI}{RGB}{225,95,0} \newcommand\colorframed{% \texorpdfstring{{\color{joli}\bfseries colorframed}}{colorframed}\xspace} {\makeatletter\sbox0{\color{RawSienna}\xdef\foo{\current@color}}} \edef\verbatimpushcolor{\special{color push \foo}} \def\verbatimpopcolor{\special{color pop}} \AddToHook{env/verbatim/before}{\verbatimpushcolor} \AddToHook{env/verbatim/end}{\verbatimpopcolor} \begin{document} \maketitle \section{Description} This package fixes various colour leaks one encounters with the environments from Donald Arseneau's package \ctanpackage{framed}. Typically, colour leaks occur if using |\color| inside the environments, or more subtly also when using |\textcolor| with an argument ending up being split at a page break. This latter type of colour leak (or colour disappearance) is the more challenging one as the fix requires modifications or replacements not only of some of the \ctanpackage{framed}.sty macros (such as its |\CustomFBox|) but also to some \LaTeX2e internals, as some environments of \ctanpackage{framed}.sty rely on usage of |\fbox| or |\colorbox|. However, rather than overwriting such internal \LaTeX2e macros as |\@frameb@x| or |\color@b@x|, the \ctanpackage{framed}.sty environments are modified by \colorframed to make use of custom replacements to |\fbox|, |\colorbox|, and |\CustomFBox|. I am aware \ctanpackage{tcolorbox} package documentation explains at least one colour issue which looks similar to those fixed here in \ctanpackage{framed} context, and that the fix overthere uses an extra colour stack, hence is not xelatex compatible currently. The problems are solved here without involving an extra colour stack, hence the fixes work also with xelatex. % The analysis and original workarounds for using framed.sty % with colours were developed by me in some contributions I made % to the Sphinx project (\url{https://github.com/sphinx-doc/sphinx}) % and I am transferring here the general idea. % The key thing is that the boxes handled by framed.sty may % contain isolated colour push or colour pop. We must make % sure an isolated colour push, if followed by colour changes, % is always followed by paired ones, and never by a colour pop % from a colour command originated "prior". % TODO: transfer also the breakable box environment based on pict2e % and allowing rounded corners and shadows developped overthere. \section{The environments from \ctanpackage{framed}} \begin{titled-frame}{A list of the environments from package \ctanpackage{framed}} This indicates the boxing macros they are based upon originally, and what this package does as replacement: \begin{description} \item[framed] (|\fbox|) The \colorframed variant uses own |\CustomFBox| rather. \item[oframed] (|\CustomFBox|) \colorframed replaces it with own version. \item[titled-frame] (|\CustomFbox|) Replaced by own version. \item[shaded] (|\colorbox|) Replaced by |\colorframedcolorbox|. \item[shaded*] (|\colorbox|) Idem. \item[snugshade] (|\colorbox|) Idem. \item[snugshade*] (|\colorbox|) Idem. \item[leftbar] This one does not use any boxing macro. \end{description} \end{titled-frame} \begin{shaded*} We refer the reader to \ctanpackage{framed} documentation and provide here only a few additional details, particularly regarding the `titled-frame' environment as it is described in \ctanpackage{framed} documentation more as being a template than a user-level finalized environment. The above box gives an example of its use. It is an environment with one mandatory argument which provides the title of the frame, which is repeated after a page break with |(cont)| appended. The colours |TFFrameColor| and |TFTitleColor| must be defined by user. To customize further one will need to renew the environment definition, which is left untouched by \colorframed (which modifies rather |\TitleBarFrame| and |\CustomFBox|). Here is how this environment is defined: \begin{verbatim} % A particular type of titled frame with continuation marks. % Parameter #1 is the title, repeated on each page. \newenvironment{titled-frame}[1]{% \def\FrameCommand{\fboxsep8pt\fboxrule2pt \TitleBarFrame{\textbf{#1}}}% \def\FirstFrameCommand{\fboxsep8pt\fboxrule2pt \TitleBarFrame[$\blacktriangleright$]{\textbf{#1}}}% \def\MidFrameCommand{\fboxsep8pt\fboxrule2pt \TitleBarFrame[$\blacktriangleright$]{\textbf{#1\ (cont)}}}% \def\LastFrameCommand{\fboxsep8pt\fboxrule2pt \TitleBarFrame{\textbf{#1\ (cont)}}}% \MakeFramed{\advance\hsize-20pt \FrameRestore}}% % note: 8 + 2 + 8 + 2 = 20. Don't use \width because the frame title % could interfere with the width measurement. {\endMakeFramed} \end{verbatim} % pas de \footnote dans les environnements de framed... \begin{footnotesize}\normalcolor As a side note, this `titled-frame' environment was partly broken in recent \LaTeX\ which has modified how |\smash| behaves; \colorframed fixes it in passing.\par \end{footnotesize} \end{shaded*} % jeudi 22 septembre 2022 à 14:37:08 % Il se passe des choses très bizarres avec snugshade* ou % framed en premier après un \item qui me semblent être des % bugs de framed. Dans Sphinx, je n'ai pas eu ces problèmes, % au contraire je suis sûr que ça fonctionne avec les % environnements que j'y ai définis reposant sur framed (et un % \trivlist en général), j'ai testé plusieurs fois. % Ce n'est pas induit par colorframed j'ai vérifié sans lui. %\begin{enumerate} %\item\relax% {\footnotesize Now testing the `snugshade*' environment.} \begin{snugshade*}\textcolor{ForestGreen}{% using textcolor to % avoid extra vspace from \color One does not need to dive into the details of the macros used above to understand intuitively how they are supposed to influence the final output. To modify this output, simply redefine this environment with suitable changes. Notice in particular that \expandafter|\string\blacktriangleright| requires to the best of my knowledge loading of \ctanpackage{amssymb} or other math symbols package and it is up to user to do it, if its usage is kept.} %\end{snugshade*} %\item\relax% {\footnotesize It appears to have a bug of not being % usable directly after |\item|.\par} %\begin{snugshade*} The original environment gives to the continuation label at bottom right of the first part of a broken box the same colour as the frame. The \colorframed variant adds the possibility to customize this colour via suitably defining a macro, in the example above we did: \begin{verbatim} \renewcommand\colorframedTFconlabcolorcommand{\color{red}} \end{verbatim} \end{snugshade*} %\end{enumerate} \begin{framed} This is an example of usage of the environment `framed'. This environment allows customization of the border width and of the separation with contents, via |\FrameRule| and |\FrameSep|, but not of the colour of the border. The \colorframed version adds this possibility: it is simply a matter of redefining the |\colorframedbordercolorcommand| macro, which defaults to |\normalcolor|. \color{blue} So the current frame was configured using: \begin{verbatim} \setlength{\FrameRule}{5pt} \setlength{\FrameSep}{9pt} \renewcommand\colorframedbordercolorcommand{\color{red!20}} \end{verbatim} The text colour induced from a |\color{blue}| will not leak out to the frame or to the text following this environment, even in case of a pagebreak. \end{framed} As indicated the aim of \colorframed is not to modify the existing environments of \ctanpackage{framed}.sty into acquiring more capabilities and customizability, and we have indicated already the two sole customization additions. The aim was strictly to fix the colour leak issues. \section{TODO} The author has developed based upon usage of \ctanpackage{pict2e} breakable boxes with round corners, background colour, optional shadow, and other goodies and is planning on incorporating this environment into the package. Of course, it will remain limited in comparison to the fully customizable boxes provided by package \ctanpackage{tcolorbox} but our testing showed significant speed-up in build time, which may matter for long documents. Hopefully this addition will be done when time will permit. \end{document}