Debian Codegraph @

texmf-dist/source/latex/clrstrip/clrstrip.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: clrstrip.dtx Copyright (C) 2018-2021 Jonathan P. Spratte
4 %
5 % It may be distributed and/or modified under the conditions of the LaTeX
6 % Project Public License (LPPL), either version 1.3c of this license or (at your
7 % option) any later version. The latest version of this license is in the file
8 %
9 % https://www.latex-project.org/lppl.txt
10 %
11 % ------------------------------------------------------------------------------
12 %
13 %<*driver>
14 \def\nameofplainTeX{plain}
15 \ifx\fmtname\nameofplainTeX\else
16 \expandafter\begingroup
17 \fi
18 \input l3docstrip.tex
19 \askforoverwritefalse
20 \preamble
21
22 --------------------------------------------------------------
23 clrstrip -- place contents into a full width colour strip
24 E-mail: [email protected]
25 Released under the LaTeX Project Public License v1.3c or later
26 See http://www.latex-project.org/lppl.txt
27 --------------------------------------------------------------
28
29 Copyright (C) 2018-2021 Jonathan P. Spratte
30
31 This work may be distributed and/or modified under the conditions of the
32 LaTeX Project Public License (LPPL), either version 1.3c of this license or
33 (at your option) any later version. The latest version of this license is in
34 the file:
35
36 http://www.latex-project.org/lppl.txt
37
38 This work is "maintained" (as per LPPL maintenance status) by
39 Jonathan P. Spratte.
40
41 This work consists of the file clrstrip.dtx
42 and the derived files clrstrip.pdf and
43 clrstrip.sty.
44
45 \endpreamble
46 % stop docstrip adding \endinput
47 \postamble
48 \endpostamble
49 \generate{\file{clrstrip.sty}{\from{clrstrip.dtx}{pkg}}}
50 \ifx\fmtname\nameofplainTeX
51 \expandafter\endbatchfile
52 \else
53 \expandafter\endgroup
54 \fi
55 %</driver>
56 %
57 %<*driver>
58 \ProvidesFile{clrstrip.dtx}
59 [%
60 \csname clrstrip@date\endcsname\space
61 place contents into a full width colour strip%
62 ]
63 \documentclass{l3doc}
64 \usepackage{xcolor}
65 \usepackage{clrstrip}
66 \usepackage{duckuments}
67 \usepackage[oldstyle,notextcomp,nott]{kpfonts}
68 \input{glyphtounicode}
69 \pdfgentounicode=1
70 ^^A fix \duckuments@enquote in latest released version
71 \makeatletter
72 \ExplSyntaxOn
73 \renewcommand*\duckuments@enquote[1]
74 {%
75 \cs_if_exist_use:NTF
76 \enquote { { #1 } }
77 { ``#1'' }
78 }
79 \ExplSyntaxOff
80 \makeatother
81 \renewcommand*{\thefootnote}{\fnsymbol{footnote}}
82 \usepackage{enumitem}
83 \newenvironment{options}
84 {\begin{description}[style=nextline,font=\normalfont\ttfamily]}
85 {\end{description}}
86 \begin{document}
87 \DocInput{clrstrip.dtx}
88 \end{document}
89 %</driver>
90 %<*pkg>
91 \newcommand*\clrstrip@date{2021-08-28}
92 \ProvidesPackage{clrstrip}
93 [\clrstrip@date\space place contents into a full width colour strip]
94 \RequirePackage{expkv}
95 %</pkg>
96 % \fi
97 %
98 % \vspace*{-6cm}%
99 % \begin{colorstrip}{blue!15}
100 % [%
101 % inner bot=1cm, outer bot=\bigskipamount, width=\paperwidth,
102 % inner top=6cm, left=-\dimexpr\marginparwidth+\marginparsep\relax
103 % ]
104 % \centering
105 % \LARGE The \pkg{clrstrip} package\\[\bigskipamount]
106 % \large
107 % Jonathan P. Spratte\footnotemark\\[\medskipamount]
108 % Released \csname clrstrip@date\endcsname
109 % \end{colorstrip}
110 % \footnotetext{E-mail: [email protected]}
111 % \tableofcontents
112 %
113 % \begin{documentation}
114 %
115 % \section{Introduction}
116 %
117 % This package provides the \env{colorstrip} environment, that places its
118 % contents into a full page width colour strip. It requires the macro \cs{color}
119 % to be defined and working, but doesn't load a package doing so on its own. So
120 % for everything to work out properly, you'd have to load a package like
121 % \pkg{color} or \pkg{xcolor} in your preamble, too.
122 %
123 % It is meant to be lightweight and fast. So while packages like \pkg{tcolorbox}
124 % provide very pretty output, this package has a simplistic look achieved with
125 % less than 100~lines of code.
126 %
127 % It is written as a docstrip file: executing |latex clrstrip.dtx| generates the
128 % \file{clrstrip.sty} file and typesets this documentation; execute
129 % |tex clrstrip.dtx| to only generate \file{clrstrip.sty}.
130 %
131 % \section{Examples}
132 %
133 % The following is an example showing the results of
134 % \begin{colorstrip}{gray!15}[inner bot=0pt, inner top=2ex, outer bot=2pt]
135 %\begin{verbatim}
136 % \begin{colorstrip}{red!5}
137 % \blindduck
138 % \end{colorstrip}
139 %\end{verbatim}
140 % \end{colorstrip}
141 % with \pkg{xcolor} and \pkg{duckuments} loaded:
142 % \begin{colorstrip}{red!5}
143 % \blindduck
144 % \end{colorstrip}
145 %
146 % The title of this documentation was typeset with
147 % \begin{colorstrip}{gray!15}[inner bot=0pt, inner top=2ex, outer bot=2pt]
148 %\begin{verbatim}
149 % \vspace*{-6cm}%
150 % \begin{colorstrip}{blue!15}
151 % [%
152 % inner bot=1cm, outer bot=\bigskipamount, width=\paperwidth,
153 % inner top=6cm, left=-\dimexpr\marginparwidth+\marginparsep\relax
154 % ]
155 % \centering
156 % \LARGE The \pkg{clrstrip} package\\[\bigskipamount]
157 % \large
158 % Jonathan P. Spratte\footnotemark\\[\medskipamount]
159 % Released \csname clrstrip@date\endcsname
160 % \end{colorstrip}
161 % \footnotetext{E-mail: [email protected]}
162 %\end{verbatim}
163 % \end{colorstrip}
164 % and the code boxes in this section (except this one) are surrounded by
165 % \begin{colorstrip}{gray!15}[inner=2ex]
166 % |\begin{colorstrip}{gray!15}[inner bot=0pt, inner top=2ex, outer bot=2pt]|\\
167 % |\begin{verbatim}|\\
168 % |\end{verbatim} |\\
169 % |\end{colorstrip}|
170 % \end{colorstrip}
171 %
172 % \section{Documentation}
173 %
174 % \subsection{Macros and Environments}
175 %
176 % \begin{function}{\colorstripSet}
177 % \begin{syntax}
178 % \cs{colorstripSet}\marg{key=value}
179 % \end{syntax}
180 % This macro can be used to set the options listed in \autoref{sec:opt}
181 % outside of \env{colorstrip} (the package makes no global assignments).
182 % \end{function}
183 %
184 % \begin{function}{colorstrip}
185 % \begin{syntax}
186 % |\begin{colorstrip}|\oarg{color model}\marg{color}\oarg{key=value}
187 % \end{syntax}
188 % This environment typesets its contents inside a \cs{vbox} which gets
189 % surrounded by a strip of the specified \meta{color} which reaches across the
190 % full page width. \meta{color model} and \meta{color} are the arguments
191 % passed to \cs{color}. In the second optional argument \meta{key=value} you
192 % can specify any of the options listed in \autoref{sec:opt}. If you leave a
193 % blank line after this environment the next paragraph will be indented, else
194 % this indentation will be suppressed (this has been changed starting with
195 % version 2019-11-03, in earlier versions you'd have to use \cs{noindent} to
196 % suppress the paragraph indentation). The result is not page breakable.
197 % \end{function}
198 %
199 % \subsection{Options}\label{sec:opt}
200 %
201 % The package doesn't support load time options. The following options can be
202 % either set with \cs{colorstripSet} or inside of \env{colorstrip}.
203 %
204 % \begin{options}
205 % \item[inner=\meta{skip}]
206 % Sets both |inner top| and |inner bot| to \meta{skip}. Initially this is
207 % set to \cs{medskipamount}.
208 % \item[inner top=\meta{skip}]
209 % Specifies additional padding between the upper border of the strip and its
210 % contents.
211 % \item[inner bot=\meta{skip}]
212 % Specifies additional padding between the lower border of the strip and its
213 % contents.
214 % \item[outer=\meta{skip}]
215 % Sets both |outer top| and |outer bot| to \meta{skip}. Initially this is
216 % set to \cs{medskipamount}.
217 % \item[outer top=\meta{skip}]
218 % Specifies the vertical skip above the colour strip.
219 % \item[outer bot=\meta{skip}]
220 % Specifies the vertical skip below the colour strip.
221 % \item[width=\meta{width}]
222 % Sets the \cs{hsize} (and also \cs{linewidth} inside of the environment) of
223 % the \cs{vbox} for the contents, resulting in the specified \meta{width}.
224 % If \meta{width} is |0pt| (which is the initial value) the width is the
225 % current surrounding \cs{linewidth}.
226 % \item[left=\meta{skip}]
227 % Specifies a horizontal skip from the left border of the text field for the
228 % contents. If \meta{skip} is |1sp| (which is the initial value) the
229 % \cs{vbox} is horizontally centred (not its contents).
230 % \item[afterheading]
231 % Doesn't accept any value. If used the indentation of the first line in a
232 % \env{colorstrip} will be prevented using the \LaTeX\ macros
233 % \cs{@afterindentfalse} and \cs{@afterheading}. This is the package default
234 % since version 2018-09-25. There was another change to this key in version
235 % 2020-01-23, since which the key will throw an error if you provide a
236 % value.
237 % \item[noindent]
238 % Doesn't accept any value. If used the indentation of the first line in a
239 % \env{colorstrip} will be prevented using the \TeX\ primitives
240 % \cs{noindent} and \cs{ignorespaces}. This was the package default before
241 % version 2018-09-25. There was another change to this key in version
242 % 2020-01-23, since which the key will throw an error if you provide a
243 % value.
244 % \end{options}
245 %
246 % \subsection{Dependencies}
247 %
248 % \pkg{clrstrip} depends on the \pkg{expkv} package. This has changed since
249 % version 2020-01-23, before that version \pkg{clrstrip} had been using
250 % \pkg{keyval}. Though \pkg{keyval} is faster than \pkg{expkv}, \pkg{expkv} is
251 % \emph{a lot} faster than \pkg{xkevyal} which replaces \pkg{keyval} and its
252 % performance as soon as it's loaded.
253 %
254 % In addition \pkg{clrstrip} needs a package defining \cs{color} such as
255 % \pkg{color} or \pkg{xcolor} but doesn't load one on its own.
256 %
257 % \end{documentation}
258 %
259 % \begin{implementation}
260 %
261 % \section{Implementation}
262 %
263 % \begin{macrocode}
264 %<*pkg>
265 % \end{macrocode}
266 %
267 % \subsection{Initializing Variables}
268 %
269 % \begin{variable}[internal]{\clrstrip@box}
270 % Stores the contents of \env{colorstrip}.
271 % \begin{macrocode}
272 \newsavebox\clrstrip@box
273 % \end{macrocode}
274 % \end{variable}
275 %
276 % \begin{variable}[internal]{\clrstrip@innerT}
277 % Stores the upper inner padding. Gets reused to store the overall height of
278 % the colour strip locally.
279 % \begin{macrocode}
280 \newlength\clrstrip@innerT
281 \clrstrip@innerT=\medskipamount
282 % \end{macrocode}
283 % \end{variable}
284 %
285 % \begin{variable}[internal]{\clrstrip@innerB}
286 % Stores the lower inner padding. Gets reused to store the overall depth of
287 % the colour strip locally.
288 % \begin{macrocode}
289 \newlength\clrstrip@innerB
290 \clrstrip@innerB=\clrstrip@innerT
291 % \end{macrocode}
292 % \end{variable}
293 %
294 % \begin{variable}[internal]{\clrstrip@outerT}
295 % Stores the upper outer padding.
296 % \begin{macrocode}
297 \newlength\clrstrip@outerT
298 \clrstrip@outerT=\clrstrip@innerT
299 % \end{macrocode}
300 % \end{variable}
301 %
302 % \begin{variable}[internal]{\clrstrip@outerB}
303 % Stores the lower outer padding.
304 % \begin{macrocode}
305 \newlength\clrstrip@outerB
306 \clrstrip@outerB=\clrstrip@innerT
307 % \end{macrocode}
308 % \end{variable}
309 %
310 % \begin{variable}[internal]{\clrstrip@width}
311 % Stores the width the text block inside of the colour strip should be wide.
312 % Might be reused to calculate the skip to centre the text block locally.
313 % \begin{macrocode}
314 \newlength\clrstrip@width
315 % \end{macrocode}
316 % \end{variable}
317 %
318 % \begin{variable}[internal]{\clrstrip@left}
319 % Stores the left skip from the left border of the text field. Might be reused
320 % to store the necessary left skip for centred alignment locally.
321 % \begin{macrocode}
322 \newlength\clrstrip@left
323 \clrstrip@left=1sp
324 % \end{macrocode}
325 % \end{variable}
326 %
327 % \begin{variable}[internal]{\clrstrip@arg}
328 % Stores the first optional and the mandatory argument to \env{colorstrip} for
329 % later use.
330 % \begin{macrocode}
331 \newcommand*\clrstrip@arg{}
332 % \end{macrocode}
333 % \end{variable}
334 %
335 % \subsection{Internal Macros}
336 %
337 % \begin{macro}[internal]{\clrstrip@key,\clrstrip@keyNV}
338 % Shortcut to define new keys with \pkg{expkv}.
339 % \begin{macrocode}
340 \newcommand*\clrstrip@key{\protected\ekvdef{clrstrip}}
341 \newcommand*\clrstrip@keyNV{\protected\ekvdefNoVal{clrstrip}}
342 % \end{macrocode}
343 % \end{macro}
344 %
345 % \begin{macro}[internal]{\clrstrip@start}
346 % Used to grab the second optional argument to \env{colorstrip}. Sets the
347 % specified keys and starts the grabbing of the contents inside the \cs{vbox}.
348 % \begin{macrocode}
349 \newcommand\clrstrip@start[1][]
350 {%
351 \colorstripSet{#1}%
352 \ifdim\clrstrip@width=\z@
353 \clrstrip@width=\linewidth
354 \fi
355 \setbox\clrstrip@box\vbox\bgroup
356 \hsize=\clrstrip@width
357 \linewidth=\hsize
358 \color@setgroup
359 \clrstrip@preventIndent
360 }
361 % \end{macrocode}
362 % \end{macro}
363 %
364 % \begin{macro}[internal]{\clrstrip@afterheading,\clrstrip@noindent}
365 % These two macros are the two options to suppress the indentation in a
366 % \env{colorstrip}.
367 % \begin{macrocode}
368 \newcommand*\clrstrip@afterheading{\@afterindentfalse\@afterheading}
369 \newcommand*\clrstrip@noindent{\noindent\ignorespaces}
370 % \end{macrocode}
371 % \end{macro}
372 %
373 % \begin{macro}[internal]{\clrstrip@preventIndent}
374 % Used to prevent the indentation of the first line in a \env{colorstrip}. It
375 % will be let to one of \cs{clrstrip@afterheading} or \cs{clrstrip@noindent}.
376 % \begin{macrocode}
377 \newcommand*\clrstrip@preventIndent{}
378 \let\clrstrip@preventIndent\clrstrip@afterheading
379 % \end{macrocode}
380 % \end{macro}
381 %
382 % \subsection{Initializing Keys}
383 %
384 % \begin{macrocode}
385 \clrstrip@key{inner}{\clrstrip@innerT=#1\relax\clrstrip@innerB=\clrstrip@innerT}
386 \clrstrip@key{outer}{\clrstrip@outerT=#1\relax\clrstrip@outerB=\clrstrip@outerT}
387 \clrstrip@key{inner top}{\clrstrip@innerT=#1\relax}
388 \clrstrip@key{inner bot}{\clrstrip@innerB=#1\relax}
389 \clrstrip@key{outer top}{\clrstrip@outerB=#1\relax}
390 \clrstrip@key{outer bot}{\clrstrip@outerB=#1\relax}
391 \clrstrip@key{width}{\clrstrip@width=#1\relax}
392 \clrstrip@key{left}{\clrstrip@left=#1\relax}
393 \clrstrip@keyNV{afterheading}{\let\clrstrip@preventIndent\clrstrip@afterheading}
394 \clrstrip@keyNV{noindent}{\let\clrstrip@preventIndent\clrstrip@noindent}
395 % \end{macrocode}
396 %
397 % \subsection{User Level Macros}
398 %
399 % \begin{macro}{\colorstripSet}
400 % Shortcut for \pkg{expkv}'s \cs{ekvset}.
401 % \begin{macrocode}
402 \protected\ekvsetdef\colorstripSet{clrstrip}
403 % \end{macrocode}
404 % \end{macro}
405 %
406 % \begin{macro}{colorstrip}
407 % \begin{macrocode}
408 \newenvironment{colorstrip}[2][]
409 {%
410 % \end{macrocode}
411 % Save the arguments for the usage in |\end{colorstrip}|. If the first argument
412 % is empty \cs{color} won't get an optional argument, else store both the
413 % optional and the mandatory one in \cs{clrstrip@arg}.
414 % \begin{macrocode}
415 \def\clrstrip@arg{#1}%
416 \ifx\clrstrip@arg\@empty
417 \def\clrstrip@arg{{#2}}%
418 \else
419 \def\clrstrip@arg{[{#1}]{#2}}%
420 \fi
421 % \end{macrocode}
422 % Start grabbing the contents.
423 % \begin{macrocode}
424 \clrstrip@start
425 }
426 {%
427 % \end{macrocode}
428 % End grabbing the contents.
429 % \begin{macrocode}
430 \color@endgroup
431 \egroup
432 % \end{macrocode}
433 % Start a new paragraph (if none was started yet) and add the upper outer
434 % padding.
435 % \begin{macrocode}
436 \par
437 \vskip\clrstrip@outerT
438 \noindent
439 % \end{macrocode}
440 % Draw the colour strip using a coloured \cs{vrule}.
441 % \begin{macrocode}
442 \begingroup
443 \expandafter\color\clrstrip@arg
444 \advance\clrstrip@innerT\ht\clrstrip@box
445 \advance\clrstrip@innerB\dp\clrstrip@box
446 \rlap
447 {%
448 \hskip-\paperwidth
449 \vrule
450 width 2\paperwidth
451 height \clrstrip@innerT
452 depth \clrstrip@innerB
453 }%
454 \endgroup
455 % \end{macrocode}
456 % Output the contents of the colour strip.
457 % \begin{macrocode}
458 \ifdim\clrstrip@left=1sp
459 \advance\clrstrip@width-\linewidth
460 \clrstrip@left=-.5\clrstrip@width
461 \fi
462 \rlap{\hskip\clrstrip@left\copy\clrstrip@box}%
463 % \end{macrocode}
464 % Start a new paragraph and add the lower outer padding. Also use \LaTeX's
465 % \cs{@endpetrue} mechanism to let the user control whether the text after this
466 % environment will be indented or not.
467 % \begin{macrocode}
468 \par
469 \vskip\clrstrip@outerB
470 \@endpetrue
471 }
472 % \end{macrocode}
473 % \end{macro}
474 %
475 % \begin{macrocode}
476 \endinput
477 % \end{macrocode}
478 %
479 % \end{implementation}
480 %
481 % \begin{macrocode}
482 %</pkg>
483 % \end{macrocode}