path: root/macros/latex/contrib/multienv/multienv.dtx

% \iffalse meta-comment
%<=*COPYRIGHT>
%% Copyright (C) 2012 by Martin Scharrer <martin@scharrer-online.de>
%% --------------------------------------------------------------------
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
%%   http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Martin Scharrer.
%%
%% This work consists of the files multienv.dtx and multienv.ins
%% and the derived filebase multienv.sty.
%%
%<=/COPYRIGHT>
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{multienv.dtx}[%
%<=*DATE>
    2012/05/20
%<=/DATE>
%<=*VERSION>
    v1.0
%<=/VERSION>
    DTX file for multienv.sty]
\documentclass{ydoc}
\GetFileInfo{multienv.dtx}
\usepackage{multienv}[\filedate]
\providecommand\enquote[1]{``#1''}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\OnlyDescription
\optionaloff
\begin{document}
  \DocInput{\jobname.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{297}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1.0}{2012/05/20}{First release.}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \GetFileInfo{multienv.dtx}
% \author{Martin Scharrer}
% \email{martin@scharrer-scharrer.de}
% \ifdefined\repository
%   \repository{https://bitbucket.org/martin_scharrer/multienv}
% \fi
%
% \maketitle
%
% \begin{abstract}\noindent
% This package provides a \env{multienv} environment which allows to
% easily add multiple environments using a key=value syntax.
% Macros to define environments using this syntax are also provided.
% \end{abstract}
%
% \section{Introduction}
% It is sometimes required to add multiple environments around some text
% in order to achieve a specific format. This macro simplifies this task
% especially for larger number of environments by allowing the environments
% and their arguments to be specified using a key=value syntax.
% A special \Key{add code} key is also provided to allow arbitrary code being
% added before and after the environment content.
% Furthermore macros are provided to allow the definition of new environments
% which contain multiple other environments and code.
%
% \section{Usage}
% \vspace{-3ex}
% \DescribeEnv[<content>]{multienv}{<env=arg>','<key=value>,\ldots}
% This environment takes a comma separated list of key=values where the keys are usually environment
% names and the values the arguments to this environment.
% The environments are added around the content in the given order, i.e.\ the first environment
% is the most outer one and further environments are placed inside it.
%
% At the moment only the following key is defined. Any other key is taken as an environment name.
%
% \DescribeKey{add code}={<code before>}{<code after>}
% This adds the given code before and after the content.
% Any code is permitted including macro argument tokens like `|#1|'.
%
% \DescribeKey{\meta{environment}}
% \DescribeKey{\meta{environment}}=<arguments>
% Any unknown key is taken as environment name and the value as argument(s) to the environment.
% If the value does not start with a brace `|{|', bracket `|[|' or angle `|<|' it is taken
% as a single mandatory argument and is placed inside braces after the environment,
% otherwise it is placed unchanged after the environment:
% \par\medskip\par\noindent
% \begin{tabular}{@{}l@{ $\Rightarrow$ }l@{}}
%   \Key{\meta{env}}         & \Macro\begin{<env>}\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}=        & \Macro\begin{<env>}\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}=<arg>   & \Macro\begin{<env>}{<arg>}\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}={<arg>} & \Macro\begin{<env>}{<arg>}\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}={<arg1>}{<arg2>} & \Macro\begin{<env>}{<arg1>}{<arg2>}\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}=[<oarg>] & \Macro\begin{<env>}[<oarg>]\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}=[<oarg>]{<marg>} & \Macro\begin{<env>}[<oarg>]{<marg>}\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}=<< <aarg> >> & \Macro\begin{<env>}<< <aarg> >>\ldots\Macro\end{<env>} \\
%   \Key{\meta{env}}=<< <aarg> >>{<marg>} & \Macro\begin{<env>}<< <aarg> >>{<marg>}\ldots\Macro\end{<env>} \\
%   \multicolumn{2}{@{}l@{}}{etc.} \\
% \end{tabular}
% \par\bigskip\par
%
% \DescribeEnv[<content>]{multienv*}{<env=arg>','<key=value>,\ldots}
% This environment is identical to \env{multienv} but will apply the keys in the reverse order,
% i.e.\ every environment or code is added around the existing environments or code.
%
%
% \DescribeMacro\newmultienvironment{<env name>}[<number of args>][<default value>]{<env=arg>,\ldots}
% This macro defines a new environment like \Macro\newenvironment does but uses the \env{multienv}
% syntax. The resulting environment will contain all given environments and code.
% The environment can have arguments including one leading optional argument.
% The arguments can be used as part of the keys and values.
% It should be noted that it is not allowed to use arguments in the second argument of
% the \Key{add code} key, because that code will be part of \Macro\end{<env name>}.
%
% An error is raised if the environment already exists.
%
% \DescribeMacro\renewmultienvironment{<env name>}[<number of args>][<default value>]{<env=arg>,\ldots}
% Like \Macro\newmultienvironment but can be used to redefine existing environments.
% It is is not relevant \emph{how} the environment was defined previously.
% An error is raised if the environment does not already exist.
%
%
% \DescribeMacro\providemultienvironment{<env name>}[<number of args>][<default value>]{<env=arg>,\ldots}
% Like \Macro\newmultienvironment but the environment is only defined if it is not already defined.
% The environment is also not defined if there a macro with the same name exists.
%
% \section{Examples}
% \lstset{gobble=4,language=[latex]tex}
% The following \env{multienv} environment usage:
% \begin{lstlisting}
%   \begin{multienv}{enva,envb=arg,add code={code before}{code after},
%       envc=[oarg]{marg}}
%     content
%   \end{multienv}
% \end{lstlisting}
% \noindent is basically identical to:
% \begin{lstlisting}
%   \begin{enva}
%     \begin{envb}{arg}
%       code before
%       \begin{enc}[oarg]{marg}
%          content
%       \end{enc}
%       code after
%     \end{envb}
%   \end{enva}
% \end{lstlisting}
% \noindent Using \env{multienv*} the order the environments can be given in the opposite order:
% \begin{lstlisting}
%   \begin{multienv}{envc=[oarg]{marg},add code={code before}{code after},
%       envb=arg,enva}
%     content
%   \end{multienv}
% \end{lstlisting}
%
% \par\bigskip\par\noindent
% The following code defines a \env{centeredminipage} environment which content is placed
% in a centered \env{minipage} which inner content is also centered.
% \begin{lstlisting}
%   \newmultienvironment{centeredminipage}[1]
%     {center,minipage=#1,add code={\centering}{}}
% \end{lstlisting}
% \par\noindent
% This is basically identical to:\par
% \begin{lstlisting}
%   \newenvironment{centeredminipage}[1]
%     {\begin{center}\begin{minipage}{#1}\centering}
%     {\end{minipage}\end{center}}
% \end{lstlisting}
% \par\noindent
% However actually the \enquote{plain} form of the environment are used, because it is more efficient
% and will also produce a correct error message if an incorrect \cs{end} macro is found:\par
% \begin{lstlisting}
%   \newenvironment{centeredminipage}[1]
%     {\begingroup\center\begingroup\minipage{#1}\centering}
%     {\endminipage\endgroup\endcenter\endgroup}
% \end{lstlisting}
% \par\noindent
% The groups are added because some environments require to be placed in a group by themselves,
% which is normally done by |\begin| and |\end|.
%
% \StopEventually{}
% \clearpage
% \section{Implementation}
%
% \iffalse
%<*multienv.sty>
% \fi
%    \begin{macrocode}
%<!COPYRIGHT>
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{multienv}[%
%<!DATE>
%<!VERSION>
%<*DRIVER>
    2099/01/01 develop
%</DRIVER>
    Add multiple environments using a Key=value syntax]
%    \end{macrocode}
%
%
% \begin{macro}{\multienv}
%    \begin{macrocode}
\newcommand{\multienv}{%
    \begingroup
    \@ifstar{%
        \let\multienv@addcode\multienv@addcode@out
        \multienv@readkeys
    }{%
        \let\multienv@addcode\multienv@addcode@in
        \multienv@readkeys
    }%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\endmultienv}
%    \begin{macrocode}
\def\endmultienv{\end@multienv\endgroup}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{environment}{multienv*}
%    \begin{macrocode}
\newenvironment{multienv*}{%
    \begingroup
    \let\multienv@addcode\multienv@addcode@out
    \multienv@readkeys
}{%
    \end@multienv\endgroup
}
%    \end{macrocode}
% \end{environment}
%
%
% \begin{macro}{\newmultienvironment}
%    \begin{macrocode}
\newcommand\newmultienvironment{%
    \let\@multi@environment\newenvironment
    \@multienvironment
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\renewmultienvironment}
%    \begin{macrocode}
\newcommand\renewmultienvironment{%
    \let\@multi@environment\renewenvironment
    \@multienvironment
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\providemultienvironment}
%    \begin{macrocode}
\newcommand\providemultienvironment{%
    \@ifstar
        {\@providemultienvironment*}%
        {\@providemultienvironment{}}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@providemultienvironment}
%    \begin{macrocode}
\def\@providemultienvironment#1#2{%
    \@ifundefined{#2}%
        {\newmultienvironment#1{#2}}%
        {\begingroup\tracingall\renewcommand\@tempa[1][]{\renewcommand\@tempa[1][]{\expandafter\endgroup\@gobble}\@tempa}\@tempa}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@multienvironment}
%    \begin{macrocode}
\def\@multienvironment{%
    \@ifstar{%
        \let\multienv@addcode\multienv@addcode@out
        \newmultienvironment@marg
    }{%
        \let\multienv@addcode\multienv@addcode@in
        \newmultienvironment@marg
    }%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\newmultienvironment@marg}
%    \begin{macrocode}
\long\def\newmultienvironment@marg#1{%
    \@testopt{\newmultienvironment@oarg{#1}}{[0]}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\newmultienvironment@oarg}
%    \begin{macrocode}
\long\def\newmultienvironment@oarg#1[#2]{%
    \@ifnextchar[{%
        \newmultienvironment@oargb{#1}{#2}%
    }{%
        \newmultienvironment@def{#1}{[#2]}%
    }%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\newmultienvironment@oargb}
%    \begin{macrocode}
\long\def\newmultienvironment@oargb#1#2[#3]{%
    \newmultienvironment@def{#1}{[#2][#3]}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\newmultienvironment@def}
%    \begin{macrocode}
\long\def\newmultienvironment@def#1#2#3{%
    \begingroup
    \multienv@readkeys@{#3}%
    \def\@tempa{\@multi@environment*{#1}#2}%
    \@temptokena\expandafter\expandafter\expandafter{\expandafter\expandafter\expandafter{\expandafter\begin@multienv\expandafter}\expandafter{\end@multienv}}%
    \expandafter\expandafter\expandafter
    \endgroup
    \expandafter\@tempa\the\@temptokena
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@readkeys}
%    \begin{macrocode}
\long\def\multienv@readkeys#1{%
    \multienv@readkeys@{#1}%
    \begin@multienv
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@readkeys@}
%    \begin{macrocode}
\long\def\multienv@readkeys@#1{%
    \let\begin@multienv\@empty
    \let\end@multienv\@empty
    \multienv@readkeyval#1,\@nnil,\@nnil
}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\let\begin@multienv\@empty
\let\end@multienv\@empty
%    \end{macrocode}
%
% \begin{macro}{\multienv@readkeyval}
%    \begin{macrocode}
\long\def\multienv@readkeyval#1,{%
    \ifx\@nnil#1\relax
        \expandafter\@gobble
    \else
        \multienv@sepkeyval#1=\@nnil=\@nnil\relax
        \expandafter\multienv@readkeyval
    \fi
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@sepkeyval}
%    \begin{macrocode}
\long\def\multienv@sepkeyval#1=#2={%
    \ifx\@nnil#2\relax
        \multienv@handlekeyval{#1}{}%
        \expandafter\@gobble
    \else
        \multienv@handlekeyval{#1}{#2}%
        \expandafter
        \@gobblefour
    \fi
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@handlekeyval}
%    \begin{macrocode}
\long\def\multienv@handlekeyval#1#2{%
    \@ifundefined{multienv@key@#1}{%
        \multienv@addenv{#1}{#2}%
    }{%
        \@nameuse{multienv@key@#1}#2\@nnil
    }%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@addenv}
%    \begin{macrocode}
\long\def\multienv@addenv#1#2{%
    \@ifnextchar\bgroup{%
        \multienv@@addenv
    }{%
        \ifcase0%
            \expandafter\ifx\csname @let@token\endcsname\@nnil1\else
            \expandafter\ifx\csname @let@token\endcsname[1\else
            \expandafter\ifx\csname @let@token\endcsname<1\fi\fi\fi
        \relax
            \expandafter\multienv@@addenv@
        \else
            \expandafter\multienv@@addenv
        \fi
    }#2\@nnil{#1}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@@addenv@}
%    \begin{macrocode}
\long\def\multienv@@addenv@#1\@nnil{%
    \multienv@@addenv{{#1}}\@nnil
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@@addenv}
%    \begin{macrocode}
\long\def\multienv@@addenv#1\@nnil#2{%
     \multienv@addcode{\multi@env{#2}#1}{\endmulti@env{#2}}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multi@env}
%    \begin{macrocode}
\long\def\multi@env#1{%
  \begingroup
  \@ifundefined{#1}%
    {\@latex@error{Environment #1 undefined}\@eha}%
    {\csname #1\endcsname}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\endmulti@env}
%    \begin{macrocode}
\def\endmulti@env#1{\csname end#1\endcsname\endgroup}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@addcode@out}
%    \begin{macrocode}
\long\def\multienv@addcode@out#1#2{%
    \@temptokena{#1}%
    \@temptokena\expandafter\expandafter\expandafter{\expandafter\the\expandafter\@temptokena\begin@multienv}%
    \edef\begin@multienv{\the\@temptokena}%
    \@temptokena\expandafter{\end@multienv#2}%
    \edef\end@multienv{\the\@temptokena}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@addcode@in}
%    \begin{macrocode}
\long\def\multienv@addcode@in#1#2{%
    \@temptokena\expandafter{\begin@multienv#1}%
    \edef\begin@multienv{\the\@temptokena}%
    \@temptokena{#2}%
    \@temptokena\expandafter\expandafter\expandafter{\expandafter\the\expandafter\@temptokena\end@multienv}%
    \edef\end@multienv{\the\@temptokena}%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\multienv@key@add}
%    \begin{macrocode}
\long\@namedef{multienv@key@add code}#1\@nnil{%
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
    \multienv@addcode#1{}{}%
}
%    \end{macrocode}
%
% \begin{macro}{\multienv@key@adjustbox}
%    \begin{macrocode}
\long\@namedef{multienv@key@adjustbox}#1\@nnil{%
    \multienv@addcode{\csname adjustbox@noindent\endcsname\adjustbox{#1}\bgroup\ignorespaces}{\ifhmode\unskip\fi\egroup}%
}
%    \end{macrocode}
% \end{macro}
%
% \iffalse
%</multienv.sty>
% \fi
%
% \Finale
\endinput