diff options
author | Karl Berry <karl@freefriends.org> | 2022-09-22 20:10:47 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-09-22 20:10:47 +0000 |
commit | 92e8e5b80a00790e3b5cc47dc7c8366798bb4e7e (patch) | |
tree | 8db65136c3843f2ac62bb1ba0fa9a17018fe8b0d /Master/texmf-dist/doc/latex/colorframed | |
parent | d30bc5664488185ab7cc29d83704505e8e939915 (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.md | 55 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/colorframed/colorframed-doc.pdf | bin | 0 -> 17300 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/colorframed/colorframed-doc.tex | 238 |
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 Binary files differnew file mode 100644 index 00000000000..16ee21cf33e --- /dev/null +++ b/Master/texmf-dist/doc/latex/colorframed/colorframed-doc.pdf 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 |