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

% \iffalse meta-comment
%
% File: clrstrip.dtx Copyright (C) 2018-2019 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-2019 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}
^^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{2019-06-03}
\ProvidesPackage{clrstrip}
  [\clrstrip@date\space place contents into a full width colour strip]
\RequirePackage{keyval}
%</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]
%\begin{verbatim}
% \begin{colorstrip}{red!5}
%   \blindduck
% \end{colorstrip}
%\end{verbatim}
% \end{colorstrip}
% \noindent
% with \pkg{xcolor} and \pkg{duckuments} loaded:
% \begin{colorstrip}{red!5}
%   \blindduck
% \end{colorstrip}
% \noindent
% The title of this documentation was typeset with
% \begin{colorstrip}{gray!15}[inner bot=0pt, inner top=2ex]
%\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}
%
% \noindent
% 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]|\\
%   |\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}. After this
%   environment starts a new paragraph with the document specific
%   \cs{parindent}. As always you can suppress this indent with \cs{noindent}.
%   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} 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 \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]
%     Ignores every value given to it. 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.
%   \item[noindent]
%     Ignores every value given to it. 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.
% \end{options}
%
% \subsection{Dependencies}
%
% \pkg{clrstrip} depends on the \pkg{keyval} package. In addition it 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@oarg}
%   Stores the first optional argument to \env{colorstrip} for later use.
%    \begin{macrocode}
\newcommand*\clrstrip@oarg{}
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\clrstrip@marg}
%   Stores the mandatory argument to \env{colorstrip} for later use.
%    \begin{macrocode}
\newcommand*\clrstrip@marg{}
%    \end{macrocode}
% \end{variable}
%
% \subsection{Internal Macros}
%
% \begin{macro}{\clrstrip@key}
%   Shortcut to define new keys with \pkg{keyval}.
%    \begin{macrocode}
\newcommand*\clrstrip@key{\define@key{clrstrip}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\clrstrip@strip}
%   Draws the colour strip using \cs{vrule}. \cs{clrstrip@strip} should be
%   called with the expanded \cs{clrstrip@marg} as its argument. It tests
%   whether the first optional argument is empty, sets the colour accordingly
%   and draws the \cs{vrule}. The arguments to \cs{color} need to be expanded as
%   \pkg{color} doesn't work with the unexpanded ones depending on the chosen
%   colour model.
%    \begin{macrocode}
\newcommand*\clrstrip@strip[1]
  {%
    \begingroup
      \ifx\clrstrip@oarg\@empty
        \color{#1}%
      \else
        \expandafter\color\expandafter[\clrstrip@oarg]{#1}%
      \fi
      \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}
% \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
      \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@key{afterheading}[]{\let\clrstrip@preventIndent\clrstrip@afterheading}
\clrstrip@key{noindent}[]{\let\clrstrip@preventIndent\clrstrip@noindent}
%    \end{macrocode}
%
% \subsection{User Level Macros}
%
% \begin{macro}{\colorstripSet}
%   Shortcut for \pkg{keyval}'s \cs{setkeys}.
%    \begin{macrocode}
\newcommand*\colorstripSet{\setkeys{clrstrip}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{colorstrip}
%    \begin{macrocode}
\newenvironment{colorstrip}[2][]
  {%
%    \end{macrocode}
% Save the arguments for the usage in |\end{colorstrip}|.
%    \begin{macrocode}
    \def\clrstrip@oarg{#1}%
    \def\clrstrip@marg{#2}%
%    \end{macrocode}
% Start grabbing the contents
%    \begin{macrocode}
    \clrstrip@start
  }
  {%
    \color@endgroup
    \egroup
    \par
    \vskip\clrstrip@outerT
    \noindent
    \expandafter\clrstrip@strip\expandafter{\clrstrip@marg}%
    \ifdim\clrstrip@left=1sp
      \advance\clrstrip@width-\linewidth
      \clrstrip@left-.5\clrstrip@width
    \fi
    \rlap{\hskip\clrstrip@left\copy\clrstrip@box}%
    \par
    \vskip\clrstrip@outerB
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
% \end{implementation}
%
%    \begin{macrocode}
%</pkg>
%    \end{macrocode}