summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/colorframed
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/colorframed')
-rw-r--r--macros/latex/contrib/colorframed/README.md55
-rw-r--r--macros/latex/contrib/colorframed/colorframed-doc.pdfbin0 -> 17300 bytes
-rw-r--r--macros/latex/contrib/colorframed/colorframed-doc.tex238
-rw-r--r--macros/latex/contrib/colorframed/colorframed.sty156
4 files changed, 449 insertions, 0 deletions
diff --git a/macros/latex/contrib/colorframed/README.md b/macros/latex/contrib/colorframed/README.md
new file mode 100644
index 0000000000..59bc8c094b
--- /dev/null
+++ b/macros/latex/contrib/colorframed/README.md
@@ -0,0 +1,55 @@
+% colorframed 0.9
+% Jean-François Burnol
+% 2022/09/22
+
+## Usage
+
+This is a LaTeX package. Use it with `\usepackage{colorframed}`.
+
+For reporting issues, use the
+[repository](https://github.com/jfbu/colorframed) issue tracker.
+
+## Purpose
+
+The initial release `0.9` of `2022/09/22` fixes colour leak issues
+which one encounters with the environments provided by the
+[framed](https://ctan.org/pkg/framed) package.
+
+It is planned to extend `colorframed` with one more environment,
+based upon [pict2e](https://ctan.org/pkg/pict2e), which will
+provide breakable boxes with possibly rounded corners, optional
+background colour, external or inset shadow, separate
+customizability of the padding separations and border widths in
+the four directions, ...
+
+## Copyright and License
+
+Copyright (c) 2022 Jean-François Burnol
+
+The colorframed [CTAN package](https://ctan.org/pkg/colorframed)
+is distributed under the
+[LPPL 1.3c](https://ctan.org/license/lppl1.3c).
+
+This Work may be distributed and/or modified under the conditions
+of the LaTeX Project Public License version 1.3c. This version of
+this license is in
+
+> <http://www.latex-project.org/lppl/lppl-1-3c.txt>
+
+and version 1.3 or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This Work has the LPPL maintenance status author-maintained.
+
+The Author of this Work is Jean-François Burnol
+
+This Work consists of the package files `colorframed.sty`, the
+documentation source `colorframed-doc.tex` and its conversion
+`colorframed-doc.pdf`, as well as this `README.md`.
+
+<!--
+%! Local variables:
+%! sentence-end-double-space: t
+%! fill-column: 72
+%! End:
+-->
diff --git a/macros/latex/contrib/colorframed/colorframed-doc.pdf b/macros/latex/contrib/colorframed/colorframed-doc.pdf
new file mode 100644
index 0000000000..16ee21cf33
--- /dev/null
+++ b/macros/latex/contrib/colorframed/colorframed-doc.pdf
Binary files differ
diff --git a/macros/latex/contrib/colorframed/colorframed-doc.tex b/macros/latex/contrib/colorframed/colorframed-doc.tex
new file mode 100644
index 0000000000..cc2b6fca39
--- /dev/null
+++ b/macros/latex/contrib/colorframed/colorframed-doc.tex
@@ -0,0 +1,238 @@
+\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} \ No newline at end of file
diff --git a/macros/latex/contrib/colorframed/colorframed.sty b/macros/latex/contrib/colorframed/colorframed.sty
new file mode 100644
index 0000000000..db6a5d5e2f
--- /dev/null
+++ b/macros/latex/contrib/colorframed/colorframed.sty
@@ -0,0 +1,156 @@
+% colorframed.sty v0.9 2022/09/22
+% Copyright (c) 2022 Jean-François Burnol
+% Distributed under the terms of the LPPL 1.3c, see README.md
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{colorframed}
+ [2022/09/22 v0.9 fix `framed' breakable boxes colour leaks (JFB)]
+\RequirePackage{framed}
+\RequirePackage{color}
+% First we must make \MakeFramed/\endMakeFramed colour safe.
+\expandafter\def\expandafter\MakeFramed\expandafter#\expandafter1\expandafter
+ {\MakeFramed{#1}\color@begingroup}
+\expandafter\def\expandafter\endMakeFramed\expandafter
+ {\expandafter\color@endgroup\endMakeFramed}
+%
+% `framed'
+\def\FrameCommand{%
+ \setlength\fboxrule{\FrameRule}\setlength\fboxsep{\FrameSep}%
+ \CustomFBox{}{}\fboxrule\fboxrule\fboxrule\fboxrule % replaces \fbox
+}
+% The frame colour can be set via modifying this macro.
+\def\colorframedbordercolorcommand{\normalcolor}
+%
+% `shaded', `shaded*', `snugshade', `snugshade*'
+% The \colorbox in \FrameCommand is replaced by \colorframedcolorbox
+\renewenvironment{shaded}{%
+ \def\FrameCommand{\fboxsep=\FrameSep
+ \colorframedcolorbox{shadecolor}}%<<<< MODIFIED
+ \MakeFramed {\FrameRestore}}%
+ {\endMakeFramed}
+\renewenvironment{shaded*}{%
+ \def\FrameCommand{\fboxsep=\FrameSep
+ \colorframedcolorbox{shadecolor}}%<<<< MODIFIED
+ \MakeFramed {\advance\hsize-\width \FrameRestore}}%
+ {\endMakeFramed}
+\renewenvironment{snugshade}{%
+ \def\FrameCommand##1{\hskip\@totalleftmargin \hskip-\fboxsep
+ \colorframedcolorbox{shadecolor}{##1}%<<<< MODIFIED
+ \hskip-\fboxsep
+ % There is no \@totalrightmargin, so:
+ \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
+ \MakeFramed {\advance\hsize-\width
+ \@totalleftmargin\z@ \linewidth\hsize
+ \@setminipage}%
+ }{\par\unskip\@minipagefalse\endMakeFramed}
+\renewenvironment{snugshade*}{%
+ \def\FrameCommand##1{\hskip\@totalleftmargin
+ \colorframedcolorbox{shadecolor}{##1}%<<<< MODIFIED
+ % There is no \@totalrightmargin, so:
+ \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
+ \MakeFramed {\advance\hsize-\width
+ \@totalleftmargin\z@ \linewidth\hsize
+ \advance\labelsep\fboxsep
+ \@setminipage}%
+ }{\par\unskip\@minipagefalse\endMakeFramed}
+% The \colorframedcolorbox was obtained via a process of trimming from some
+% far more capable box, hence some possibly strange looking or sub-optimal
+% code; but we did not want to keep extra capabilities and have to provide
+% interface for that...
+\def\colorframedcolorbox#1#2{%
+ % #1 is in our usage always "shadecolor" (which has to be defined by user)
+ % #2 is in our usage always a box or rule
+ \leavevmode% this is not needed in our usage
+ \hbox{%
+ \setbox\@tempboxa\hbox{\kern\fboxsep{#2}\kern\fboxsep}%
+ \ht\@tempboxa
+ \dimexpr\ht\@tempboxa+\fboxsep\relax
+ \dp\@tempboxa
+ \dimexpr\dp\@tempboxa+\fboxsep\relax
+ % BACKGROUND
+ % draw background and move back to reference point
+ {\color{#1}%
+ \vrule\@height\ht\@tempboxa
+ \@depth\dp\@tempboxa
+ \@width\wd\@tempboxa
+ \kern-\wd\@tempboxa
+ }%
+ % CONTENTS
+ \box\@tempboxa
+ }%
+}
+%
+% `oframed' and `titled-frame'
+% The \CustomFBox redefinition.
+% Refer to framed.sty for significance of the parameters.
+% We have not wrapped #3, #4, #5, #6 thicknesses in \dimexpr.
+% Generally speaking, no attempt here to make this macro more
+% versatile than is the original.
+% Our version tries to let #1 and #2 have same effect as in original
+% (where they are only used for titled-frame environment, and
+% it thus seems to be sort of a convention that #2 has no height.)
+\long\def\CustomFBox#1#2#3#4#5#6#7{%
+ \leavevmode\begingroup
+ \setbox\@tempboxa\hbox{%
+ \color@begingroup
+ \kern\fboxsep{#7}\kern\fboxsep
+ \color@endgroup}%
+ \hbox{%
+ \ht\@tempboxa
+ \dimexpr\ht\@tempboxa+\fboxsep+#3\relax % cf "overlap" remark below
+ \dp\@tempboxa
+ \dimexpr\dp\@tempboxa+\fboxsep+#4\relax
+ \setbox\z@\hbox
+ {\vrule\@width#5\relax
+ \kern\wd\@tempboxa
+ \vrule\@width#6\relax
+ }%
+ \ht\z@\ht\@tempboxa
+ \dp\z@\dp\@tempboxa
+ \vbox{%
+ \colorframedbordercolorcommand % defaults to \normalcolor
+ \hrule\@height#3\relax
+ \kern-#3\relax
+ #1%
+ \copy\z@ % deliberate overlap hrules+vrules to avoid anti-aliasing artefacts
+ \kern-#4\relax
+ #2%
+ \hrule\@height#4\relax
+ \kern-\dp\@tempboxa
+ }%
+ \kern-\wd\z@
+ \kern#5\relax
+ \box\@tempboxa
+ \kern#6\relax
+ }%
+ \endgroup
+}
+% The titled-frame environment depends in part on this macro,
+% whose original in framed.sty has various colour problems.
+% We have indicated the modifications, additionally to using
+% our modified \CustomFBox.
+% Original let the continuation label use same colour as frame.
+% Let make this customizable.
+\let\colorframedTFconlabcolorcommand\empty
+\renewcommand\TitleBarFrame[3][]{\begingroup
+ \ifx\delimiter#1\delimiter
+ \let\TF@conlab\@empty
+ \else
+ \def\TF@conlab{%
+ \nointerlineskip
+ \hbox{%<<<< ADDED (needed due to \smash doing \leavevmode nowadays)
+ \colorframedTFconlabcolorcommand%<<<< ADDED
+ \smash{\rlap{\kern\wd\@tempboxa\kern\fboxrule\kern\fboxsep #1}}}%
+ }%<<<< ADDED
+ \fi
+ %\let\TF@savecolor\current@color%<<<< REMOVED
+ %\textcolor{TFFrameColor}{% <<<< REMOVED
+ \def\colorframedbordercolorcommand{\color{TFFrameColor}}%<<<< ADDED
+ \CustomFBox
+ {\TF@Title{#2}}{\TF@conlab}%
+ \fboxrule\fboxrule\fboxrule\fboxrule
+ {%\let\current@color\TF@savecolor\set@color%<<<< REMOVED
+ #3}%
+ %}% <<<< REMOVED
+ \endgroup
+}
+\endinput