summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/colorframed/colorframed-doc.tex
blob: cc2b6fca39ab24880f2bb7b420e591726d9c1702 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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}