summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/colorframed
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-09-22 20:10:47 +0000
committerKarl Berry <karl@freefriends.org>2022-09-22 20:10:47 +0000
commit92e8e5b80a00790e3b5cc47dc7c8366798bb4e7e (patch)
tree8db65136c3843f2ac62bb1ba0fa9a17018fe8b0d /Master/texmf-dist/doc/latex/colorframed
parentd30bc5664488185ab7cc29d83704505e8e939915 (diff)
colorframed (22sep22)
git-svn-id: svn://tug.org/texlive/trunk@64467 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/colorframed')
-rw-r--r--Master/texmf-dist/doc/latex/colorframed/README.md55
-rw-r--r--Master/texmf-dist/doc/latex/colorframed/colorframed-doc.pdfbin0 -> 17300 bytes
-rw-r--r--Master/texmf-dist/doc/latex/colorframed/colorframed-doc.tex238
3 files changed, 293 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/colorframed/README.md b/Master/texmf-dist/doc/latex/colorframed/README.md
new file mode 100644
index 00000000000..59bc8c094b4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/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/Master/texmf-dist/doc/latex/colorframed/colorframed-doc.pdf b/Master/texmf-dist/doc/latex/colorframed/colorframed-doc.pdf
new file mode 100644
index 00000000000..16ee21cf33e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/colorframed/colorframed-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/colorframed/colorframed-doc.tex b/Master/texmf-dist/doc/latex/colorframed/colorframed-doc.tex
new file mode 100644
index 00000000000..cc2b6fca39a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/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