summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/clrstrip/clrstrip.dtx
blob: a968ddf6095c9661f487311a6d58688ed737043e (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
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
% \iffalse meta-comment
%
% File: clrstrip.dtx Copyright (C) 2018-2020 Jonathan P. Spratte
%
% It may be distributed and/or modified under the conditions of the LaTeX
% Project Public License (LPPL), either version 1.3c of this license or (at your
% option) any later version.  The latest version of this license is in the file
%
%   https://www.latex-project.org/lppl.txt
%
% ------------------------------------------------------------------------------
%
%<*driver>
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
\input l3docstrip.tex
\askforoverwritefalse
\preamble

--------------------------------------------------------------
clrstrip -- place contents into a full width colour strip
E-mail: jspratte@yahoo.de
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
--------------------------------------------------------------

Copyright (C) 2018-2020 Jonathan P. Spratte

This  work may be  distributed and/or  modified under  the conditions  of the
LaTeX Project Public License (LPPL),  either version 1.3c  of this license or
(at your option) any later version.  The latest version of this license is in
the file:

  http://www.latex-project.org/lppl.txt

This work is "maintained" (as per LPPL maintenance status) by
  Jonathan P. Spratte.

This work consists of the file  clrstrip.dtx
and the derived files           clrstrip.pdf and
                                clrstrip.sty.

\endpreamble
% stop docstrip adding \endinput
\postamble
\endpostamble
\generate{\file{clrstrip.sty}{\from{clrstrip.dtx}{pkg}}}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</driver>
%
%<*driver>
\ProvidesFile{clrstrip.dtx}
  [%
    \csname clrstrip@date\endcsname\space
    place contents into a full width colour strip%
  ]
\documentclass{l3doc}
\usepackage{xcolor}
\usepackage{clrstrip}
\usepackage{duckuments}
\usepackage[oldstyle,notextcomp,nott]{kpfonts}
\input{glyphtounicode}
\pdfgentounicode=1
^^A fix \duckuments@enquote in latest released version
\makeatletter
\ExplSyntaxOn
\renewcommand*\duckuments@enquote[1]
  {%
    \cs_if_exist_use:NTF
      \enquote { { #1 } }
      { ``#1'' }
  }
\ExplSyntaxOff
\makeatother
\renewcommand*{\thefootnote}{\fnsymbol{footnote}}
\usepackage{enumitem}
\newenvironment{options}
  {\begin{description}[style=nextline,font=\normalfont\ttfamily]}
  {\end{description}}
\begin{document}
  \DocInput{clrstrip.dtx}
\end{document}
%</driver>
%<*pkg>
\newcommand*\clrstrip@date{2020-01-23}
\ProvidesPackage{clrstrip}
  [\clrstrip@date\space place contents into a full width colour strip]
\RequirePackage{expkv}
%</pkg>
% \fi
%
% \vspace*{-6cm}%
% \begin{colorstrip}{blue!15}
%   [%
%     inner bot=1cm, outer bot=\bigskipamount, width=\paperwidth,
%     inner top=6cm, left=-\dimexpr\marginparwidth+\marginparsep\relax
%   ]
%   \centering
%   \LARGE The \pkg{clrstrip} package\\[\bigskipamount]
%   \large
%   Jonathan P. Spratte\footnotemark\\[\medskipamount]
%   Released \csname clrstrip@date\endcsname
% \end{colorstrip}
% \footnotetext{E-mail: jspratte@yahoo.de}
% \tableofcontents
%
% \begin{documentation}
%
% \section{Introduction}
%
% This package provides the \env{colorstrip} environment, that places its
% contents into a full page width colour strip. It requires the macro \cs{color}
% to be defined and working, but doesn't load a package doing so on its own. So
% for everything to work out properly, you'd have to load a package like
% \pkg{color} or \pkg{xcolor} in your preamble, too.
%
% It is meant to be lightweight and fast. So while packages like \pkg{tcolorbox}
% provide very pretty output, this package has a simplistic look achieved with
% less than 100~lines of code.
%
% It is written as a docstrip file: executing |latex clrstrip.dtx| generates the
% \file{clrstrip.sty} file and typesets this documentation; execute
% |tex clrstrip.dtx| to only generate \file{clrstrip.sty}.
%
% \section{Examples}
%
% The following is an example showing the results of
% \begin{colorstrip}{gray!15}[inner bot=0pt, inner top=2ex, outer bot=2pt]
%\begin{verbatim}
% \begin{colorstrip}{red!5}
%   \blindduck
% \end{colorstrip}
%\end{verbatim}
% \end{colorstrip}
% with \pkg{xcolor} and \pkg{duckuments} loaded:
% \begin{colorstrip}{red!5}
%   \blindduck
% \end{colorstrip}
%
% The title of this documentation was typeset with
% \begin{colorstrip}{gray!15}[inner bot=0pt, inner top=2ex, outer bot=2pt]
%\begin{verbatim}
% \vspace*{-6cm}%
% \begin{colorstrip}{blue!15}
%   [%
%     inner bot=1cm, outer bot=\bigskipamount, width=\paperwidth,
%     inner top=6cm, left=-\dimexpr\marginparwidth+\marginparsep\relax
%   ]
%   \centering
%   \LARGE The \pkg{clrstrip} package\\[\bigskipamount]
%   \large
%   Jonathan P. Spratte\footnotemark\\[\medskipamount]
%   Released \csname clrstrip@date\endcsname
% \end{colorstrip}
% \footnotetext{E-mail: jspratte@yahoo.de}
%\end{verbatim}
% \end{colorstrip}
% and the code boxes in this section (except this one) are surrounded by
% \begin{colorstrip}{gray!15}[inner=2ex]
%   |\begin{colorstrip}{gray!15}[inner bot=0pt, inner top=2ex, outer bot=2pt]|\\
%   |\begin{verbatim}|\\
%   |\end{verbatim}  |\\
%   |\end{colorstrip}|
% \end{colorstrip}
%
% \section{Documentation}
%
% \subsection{Macros and Environments}
%
% \begin{function}{\colorstripSet}
%   \begin{syntax}
%     \cs{colorstripSet}\marg{key=value}
%   \end{syntax}
%   This macro can be used to set the options listed in \autoref{sec:opt}
%   outside of \env{colorstrip} (the package makes no global assignments).
% \end{function}
%
% \begin{function}{colorstrip}
%   \begin{syntax}
%     |\begin{colorstrip}|\oarg{color model}\marg{color}\oarg{key=value}
%   \end{syntax}
%   This environment typesets its contents inside a \cs{vbox} which gets
%   surrounded by a strip of the specified \meta{color} which reaches across the
%   full page width. \meta{color model} and \meta{color} are the arguments
%   passed to \cs{color}. In the second optional argument \meta{key=value} you
%   can specify any of the options listed in \autoref{sec:opt}. If you leave a
%   blank line after this environment the next paragraph will be indented, else
%   this indentation will be suppressed (this has been changed starting with
%   version 2019-11-03, in earlier versions you'd have to use \cs{noindent} to
%   suppress the paragraph indentation). The result is not page breakable.
% \end{function}
%
% \subsection{Options}\label{sec:opt}
%
% The package doesn't support load time options. The following options can be
% either set with \cs{colorstripSet} or inside of \env{colorstrip}.
%
% \begin{options}
%   \item[inner=\meta{skip}]
%     Sets both |inner top| and |inner bot| to \meta{skip}. Initially this is
%     set to \cs{medskipamount}.
%   \item[inner top=\meta{skip}]
%     Specifies additional padding between the upper border of the strip and its
%     contents.
%   \item[inner bot=\meta{skip}]
%     Specifies additional padding between the lower border of the strip and its
%     contents.
%   \item[outer=\meta{skip}]
%     Sets both |outer top| and |outer bot| to \meta{skip}. Initially this is
%     set to \cs{medskipamount}.
%   \item[outer top=\meta{skip}]
%     Specifies the vertical skip above the colour strip.
%   \item[outer bot=\meta{skip}]
%     Specifies the vertical skip below the colour strip.
%   \item[width=\meta{width}]
%     Sets the \cs{hsize} (and also \cs{linewidth} inside of the environment) of
%     the \cs{vbox} for the contents, resulting in the specified \meta{width}.
%     If \meta{width} is |0pt| (which is the initial value) the width is the
%     current surrounding \cs{linewidth}.
%   \item[left=\meta{skip}]
%     Specifies a horizontal skip from the left border of the text field for the
%     contents. If \meta{skip} is |1sp| (which is the initial value) the
%     \cs{vbox} is horizontally centred (not its contents).
%   \item[afterheading]
%     Doesn't accept any value. If used the indentation of the first line in a
%     \env{colorstrip} will be prevented using the \LaTeX\ macros
%     \cs{@afterindentfalse} and \cs{@afterheading}. This is the package default
%     since version 2018-09-25. There was another change to this key in version
%     2020-01-23, since which the key will throw an error if you provide a
%     value.
%   \item[noindent]
%     Doesn't accept any value. If used the indentation of the first line in a
%     \env{colorstrip} will be prevented using the \TeX\ primitives
%     \cs{noindent} and \cs{ignorespaces}. This was the package default before
%     version 2018-09-25. There was another change to this key in version
%     2020-01-23, since which the key will throw an error if you provide a
%     value.
% \end{options}
%
% \subsection{Dependencies}
%
% \pkg{clrstrip} depends on the \pkg{expkv} package. This has changed since
% version 2020-01-23, before that version \pkg{clrstrip} had been using
% \pkg{keyval}. Though \pkg{keyval} is faster than \pkg{expkv}, \pkg{expkv} is
% \emph{a lot} faster than \pkg{xkevyal} which replaces \pkg{keyval} and its
% performance as soon as any other package is loaded.
%
% In addition \pkg{clrstrip} needs a package defining \cs{color} such as
% \pkg{color} or \pkg{xcolor} but doesn't load one on its own.
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{Implementation}
%
%    \begin{macrocode}
%<*pkg>
%    \end{macrocode}
%
% \subsection{Initializing Variables}
%
% \begin{variable}{\clrstrip@box}
%   Stores the contents of \env{colorstrip}.
%    \begin{macrocode}
\newsavebox\clrstrip@box
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@innerT}
%   Stores the upper inner padding. Gets reused to store the overall height of
%   the colour strip locally.
%    \begin{macrocode}
\newlength\clrstrip@innerT
\clrstrip@innerT\medskipamount
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@innerB}
%   Stores the lower inner padding. Gets reused to store the overall depth of
%   the colour strip locally.
%    \begin{macrocode}
\newlength\clrstrip@innerB
\clrstrip@innerB\clrstrip@innerT
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@outerT}
%   Stores the upper outer padding.
%    \begin{macrocode}
\newlength\clrstrip@outerT
\clrstrip@outerT\clrstrip@innerT
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@outerB}
%   Stores the lower outer padding.
%    \begin{macrocode}
\newlength\clrstrip@outerB
\clrstrip@outerB\clrstrip@innerT
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@width}
%   Stores the width the text block inside of the colour strip should be wide.
%   Might be reused to calculate the skip to centre the text block locally.
%    \begin{macrocode}
\newlength\clrstrip@width
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@left}
%   Stores the left skip from the left border of the text field. Might be reused
%   to store the necessary left skip for centred alignment locally.
%    \begin{macrocode}
\newlength\clrstrip@left
\clrstrip@left1sp
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@arg}
%   Stores the first optional and the mandatory argument to \env{colorstrip} for
%   later use.
%    \begin{macrocode}
\newcommand*\clrstrip@arg{}
%    \end{macrocode}
% \end{variable}
%
% \subsection{Internal Macros}
%
% \begin{macro}{\clrstrip@key,\clrstrip@keyNV}
%   Shortcut to define new keys with \pkg{expkv}.
%    \begin{macrocode}
\newcommand*\clrstrip@key{\protected\ekvdef{clrstrip}}
\newcommand*\clrstrip@keyNV{\protected\ekvdefNoVal{clrstrip}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\clrstrip@start}
%   Used to grab the second optional argument to \env{colorstrip}. Sets the
%   specified keys and starts the grabbing of the contents inside the \cs{vbox}.
%    \begin{macrocode}
\newcommand\clrstrip@start[1][]
  {%
    \colorstripSet{#1}%
    \ifdim\clrstrip@width=\z@
      \clrstrip@width\linewidth
    \fi
    \setbox\clrstrip@box\vbox\bgroup
      \hsize\clrstrip@width
      \linewidth\hsize
      \color@setgroup
      \clrstrip@preventIndent
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\clrstrip@afterheading,\clrstrip@noindent}
%   These two macros are the two options to suppress the indentation in a
%   \env{colorstrip}.
%    \begin{macrocode}
\newcommand*\clrstrip@afterheading{\@afterindentfalse\@afterheading}
\newcommand*\clrstrip@noindent{\noindent\ignorespaces}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\clrstrip@preventIndent}
%   Used to prevent the indentation of the first line in a \env{colorstrip}. It
%   will be let to one of \cs{clrstrip@afterheading} or \cs{clrstrip@noindent}.
%    \begin{macrocode}
\newcommand*\clrstrip@preventIndent{}
\let\clrstrip@preventIndent\clrstrip@afterheading
%    \end{macrocode}
% \end{macro}
%
% \subsection{Initializing Keys}
%
%    \begin{macrocode}
\clrstrip@key{inner}{\clrstrip@innerT#1\relax\clrstrip@innerB#1\relax}
\clrstrip@key{outer}{\clrstrip@outerT#1\relax\clrstrip@outerB#1\relax}
\clrstrip@key{inner top}{\clrstrip@innerT#1\relax}
\clrstrip@key{inner bot}{\clrstrip@innerB#1\relax}
\clrstrip@key{outer top}{\clrstrip@outerB#1\relax}
\clrstrip@key{outer bot}{\clrstrip@outerB#1\relax}
\clrstrip@key{width}{\clrstrip@width#1\relax}
\clrstrip@key{left}{\clrstrip@left#1\relax}
\clrstrip@keyNV{afterheading}{\let\clrstrip@preventIndent\clrstrip@afterheading}
\clrstrip@keyNV{noindent}{\let\clrstrip@preventIndent\clrstrip@noindent}
%    \end{macrocode}
%
% \subsection{User Level Macros}
%
% \begin{macro}{\colorstripSet}
%   Shortcut for \pkg{expkv}'s \cs{ekvset}.
%    \begin{macrocode}
\protected\def\colorstripSet{\ekvset{clrstrip}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{colorstrip}
%    \begin{macrocode}
\newenvironment{colorstrip}[2][]
  {%
%    \end{macrocode}
% Save the arguments for the usage in |\end{colorstrip}|. If the first argument
% is empty \cs{color} won't get an optional argument, else store both the
% optional and the mandatory one in \cs{clrstrip@arg}.
%    \begin{macrocode}
    \def\clrstrip@arg{#1}%
    \ifx\clrstrip@arg\@empty
      \def\clrstrip@arg{{#2}}%
    \else
      \def\clrstrip@arg{[{#1}]{#2}}%
    \fi
%    \end{macrocode}
% Start grabbing the contents.
%    \begin{macrocode}
    \clrstrip@start
  }
  {%
%    \end{macrocode}
% End grabbing the contents.
%    \begin{macrocode}
    \color@endgroup
    \egroup
%    \end{macrocode}
% Start a new paragraph (if none was started yet) and add the upper outer
% padding.
%    \begin{macrocode}
    \par
    \vskip\clrstrip@outerT
    \noindent
%    \end{macrocode}
% Draw the colour strip using a coloured \cs{vrule}.
%    \begin{macrocode}
    \begingroup
      \expandafter\color\clrstrip@arg
      \advance\clrstrip@innerT\ht\clrstrip@box
      \advance\clrstrip@innerB\dp\clrstrip@box
      \rlap
        {%
          \hskip-\paperwidth
          \vrule
            width 2\paperwidth
            height \clrstrip@innerT
            depth \clrstrip@innerB
        }%
    \endgroup
%    \end{macrocode}
% Output the contents of the colour strip.
%    \begin{macrocode}
    \ifdim\clrstrip@left=1sp
      \advance\clrstrip@width-\linewidth
      \clrstrip@left-.5\clrstrip@width
    \fi
    \rlap{\hskip\clrstrip@left\copy\clrstrip@box}%
%    \end{macrocode}
% Start a new paragraph and add the lower outer padding. Also use \LaTeX's
% \cs{@endpetrue} mechanism to let the user control whether the text after this
% environment will be indented or not.
%    \begin{macrocode}
    \par
    \vskip\clrstrip@outerB
    \@endpetrue
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
% \end{implementation}
%
%    \begin{macrocode}
%</pkg>
%    \end{macrocode}