summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/colorframed/colorframed-doc.tex
blob: 3f00ea270615f4363f8e72e2134d17857c74af5d (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
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
\documentclass[a4paper,dvipdfmx,11pt,english]{article}
\usepackage{babel}
\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}{purple}
\def\colorframedTFconlabcolorcommand{\color{purple}}
% shaded
\colorlet{shadecolor}{orange!10}
% framed
\FrameRule5pt\relax
\FrameSep9pt\relax % this is framed.sty default anyhow, 3\fboxsep
% attention that \FrameSep influences framed but also shaded, shaded* and
% oframed, which is not so clear from reading only framed documentation
\def\colorframedbordercolorcommand{\color{red!20}}

\title{The \colorframed package%
\vadjust{\vtop to 0pt{\hbox
    to\linewidth{\strut\footnotesize Release 0.9a of
      2022/09/23\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| (at top level) 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|, which \colorframed overwrites)
but also to some \LaTeX2e internals, as some environments of
\ctanpackage{framed}.sty rely on usage of |\fbox| or |\colorbox|.
Rather than overwriting internal \LaTeX2e macros such as
|\@frameb@x| or |\color@b@x|, \colorframed simply replaces |\fbox|
and |\colorbox| in the \ctanpackage{framed}.sty environments by
appropriate substitutes.

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.

\section{The environments from \ctanpackage{framed}}

\begin{titled-frame}{A list of the environments from package \ctanpackage{framed}}
  This list indicates which boxing macros are
  used in the original, and their replacement.
% (investigate later why something such as shortverb |#| in
% preamble does not work)
\halign{\bfseries#\hfil&(#\unskip)~\hfil&#\hfil\cr
%
  framed & |\fbox| & Replaced by specialization of own \rlap{\string\CustomFBox.}\cr
%
  oframed & |\CustomFBox| & \colorframed uses a redefined |\CustomFBox|.\cr
%
  titled-frame & |\CustomFBox| & \emph{id.}\cr
%
  shaded & |\colorbox| & Replaced by |\colorframedcolorbox|.\cr
%
  shaded* & |\colorbox| & \emph{id.}\cr
%
  snugshade & |\colorbox| & \emph{id.}\cr
%
  snugshade* & |\colorbox| & \emph{id.}\cr
%
  leftbar & none & This one does not use any boxing macro.\cr
}
\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 inside \ctanpackage{framed}.sty: (code and comments by Donald Arseneau)\par
\begin{footnotesize}
\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...
\normalcolor
Side note: this `titled-frame' environment was in effect
broken in recent \LaTeX\ which has modified how |\smash|
behaves; \colorframed fixes this infelicity in passing.\par

\emph{(the current box is an example of \emph{`shaded*'} environment, next one is with
\emph{`snugshade*'}, both use a \emph{shadecolor} which must be defined by user)}
\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*}
\leavevmode\color{OliveGreen}
  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 |$\blacktriangleright$|
  (which produces $\blacktriangleright$ and acquires thus a colour
  despite its name) requires to
  the best of my knowledge loading \ctanpackage{amssymb} or
  some other math symbols package and it is up to user to do it, if
  its usage is kept.
%
  The original environment gives to this continuation label the
  same colour as the frame.  \colorframed adds the
  possibility to customize this colour via suitably defining a
  macro, like this for example:% le % pour éviter un bug lorsqu'un caractère
                               % espace est à la fin d'une ligne quasi-pleine,
                               % je soupçonne bug de TeX que j'ai déjà
                               % rencontré plusieurs fois, ou peut-être ici un
                               % problème du \trivlist de verbatim
\begin{verbatim}
\renewcommand\colorframedTFconlabcolorcommand{\color{purple}}
\end{verbatim}
\end{snugshade*}

\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|.

\footnotesize (|\color{blue}| in source)
\normalsize
\color{blue}
  So the current frame was configured using:
\begin{verbatim}
\setlength{\FrameRule}{5pt}
\setlength{\FrameSep}{9pt}
\renewcommand\colorframedbordercolorcommand{\color{red!20}}
\end{verbatim}
\begin{footnotesize}\normalcolor
  The length |\FrameSep| influences also `oframed', `shaded', and `shaded*',
  but `snugshade' and `snugshade*' employ |\fboxsep| rather.

  As per |\FrameRule|, it influences `framed' and `oframed' but not
  `titled-frame' which simply uses |\fboxrule| for its border width.\par
\end{footnotesize}
  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}

The aim of \colorframed regarding \ctanpackage{framed} existing
code base is strictly limited to fixing the colour leak issues,
there is not intent to extend the existing environments of
\ctanpackage{framed} with additional capabilities and
customizability: we have mentioned already the two sole
customization additions.

\section{TODO}

The author has developed based upon usage of \ctanpackage{pict2e}
breakable boxes with round corners, background colour, optional
shadow (possibly inset), 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.

\thispagestyle{empty}
\enlargethispage{2\baselineskip}

\colorlet{shadecolor}{lightgray!50}
\footnotesize
\begin{snugshade}
  After initial release made it to CTAN on
  2022/09/22 I became aware of \ctanpackage{longfbox} which
  provides already such \ctanpackage{pict2e} breakable boxes with
  rounded corners (even elliptical arcs), and furthermore with a
  CSS-like interface which is exactly what I had done on my side
  too... I need to check more \ctanpackage{longfbox} before a
  decision is made here!  Perhaps it will be better to keep
  \colorframed as it is currently and produce another package for
  extras such as \ctanpackage{pict2e}-based boxes or a key-value
  interface to `inline' or `display' box macros and environments.
\end{snugshade}
\centerline{\hrulefill documentation ends here\hrulefill}
\end{document}