summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/colorframed/colorframed-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/colorframed/colorframed-doc.tex')
-rw-r--r--macros/latex/contrib/colorframed/colorframed-doc.tex238
1 files changed, 238 insertions, 0 deletions
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