path: root/Master/texmf-dist/source/latex/clrstrip/clrstrip.dtx

% \iffalse meta-comment
%
% File: clrstrip.dtx Copyright (C) 2018-2021 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-2021 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{2021-08-28}
\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 it's 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}[internal]{\clrstrip@box}
%   Stores the contents of \env{colorstrip}.
%    \begin{macrocode}
\newsavebox\clrstrip@box
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}[internal]{\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}[internal]{\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}[internal]{\clrstrip@outerT}
%   Stores the upper outer padding.
%    \begin{macrocode}
\newlength\clrstrip@outerT
\clrstrip@outerT=\clrstrip@innerT
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}[internal]{\clrstrip@outerB}
%   Stores the lower outer padding.
%    \begin{macrocode}
\newlength\clrstrip@outerB
\clrstrip@outerB=\clrstrip@innerT
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}[internal]{\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}[internal]{\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@left=1sp
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}[internal]{\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}[internal]{\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}[internal]{\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}[internal]{\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}[internal]{\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=\clrstrip@innerT}
\clrstrip@key{outer}{\clrstrip@outerT=#1\relax\clrstrip@outerB=\clrstrip@outerT}
\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\ekvsetdef\colorstripSet{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}