diff options
Diffstat (limited to 'macros/latex/contrib/colorframed/colorframed-doc.tex')
-rw-r--r-- | macros/latex/contrib/colorframed/colorframed-doc.tex | 238 |
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 |