Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %<=*COPYRIGHT>
3 %% Copyright (C) 2012 by Martin Scharrer <[email protected]>
4 %% --------------------------------------------------------------------
5 %% This work may be distributed and/or modified under the
6 %% conditions of the LaTeX Project Public License, either version 1.3
7 %% of this license or (at your option) any later version.
8 %% The latest version of this license is in
9 %% http://www.latex-project.org/lppl.txt
10 %% and version 1.3 or later is part of all distributions of LaTeX
11 %% version 2005/12/01 or later.
12 %%
13 %% This work has the LPPL maintenance status `maintained'.
14 %%
15 %% The Current Maintainer of this work is Martin Scharrer.
16 %%
17 %% This work consists of the files multienv.dtx and multienv.ins
18 %% and the derived filebase multienv.sty.
19 %%
20 %<=/COPYRIGHT>
21 % \fi
22 %
23 % \iffalse
24 %<*driver>
25 \ProvidesFile{multienv.dtx}[%
26 %<=*DATE>
27 2012/05/20
28 %<=/DATE>
29 %<=*VERSION>
30 v1.0
31 %<=/VERSION>
32 DTX file for multienv.sty]
33 \documentclass{ydoc}
34 \GetFileInfo{multienv.dtx}
35 \usepackage{multienv}[\filedate]
36 \providecommand\enquote[1]{``#1''}
37 \EnableCrossrefs
38 \CodelineIndex
39 \RecordChanges
40 \OnlyDescription
41 \optionaloff
42 \begin{document}
43 \DocInput{\jobname.dtx}
44 \PrintChanges
45 \PrintIndex
46 \end{document}
47 %</driver>
48 % \fi
49 %
50 % \CheckSum{297}
51 %
52 % \CharacterTable
53 % {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
54 % 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
55 % Digits \0\1\2\3\4\5\6\7\8\9
56 % Exclamation \! Double quote \" Hash (number) \#
57 % Dollar \$ Percent \% Ampersand \&
58 % Acute accent \' Left paren \( Right paren \)
59 % Asterisk \* Plus \+ Comma \,
60 % Minus \- Point \. Solidus \/
61 % Colon \: Semicolon \; Less than \<
62 % Equals \= Greater than \> Question mark \?
63 % Commercial at \@ Left bracket \[ Backslash \\
64 % Right bracket \] Circumflex \^ Underscore \_
65 % Grave accent \` Left brace \{ Vertical bar \|
66 % Right brace \} Tilde \~}
67 %
68 %
69 % \changes{v1.0}{2012/05/20}{First release.}
70 %
71 % \DoNotIndex{\newcommand,\newenvironment}
72 %
73 % \GetFileInfo{multienv.dtx}
74 % \author{Martin Scharrer}
75 % \email{[email protected]}
76 % \ifdefined\repository
77 % \repository{https://bitbucket.org/martin_scharrer/multienv}
78 % \fi
79 %
80 % \maketitle
81 %
82 % \begin{abstract}\noindent
83 % This package provides a \env{multienv} environment which allows to
84 % easily add multiple environments using a key=value syntax.
85 % Macros to define environments using this syntax are also provided.
86 % \end{abstract}
87 %
88 % \section{Introduction}
89 % It is sometimes required to add multiple environments around some text
90 % in order to achieve a specific format. This macro simplifies this task
91 % especially for larger number of environments by allowing the environments
92 % and their arguments to be specified using a key=value syntax.
93 % A special \Key{add code} key is also provided to allow arbitrary code being
94 % added before and after the environment content.
95 % Furthermore macros are provided to allow the definition of new environments
96 % which contain multiple other environments and code.
97 %
98 % \section{Usage}
99 % \vspace{-3ex}
100 % \DescribeEnv[<content>]{multienv}{<env=arg>','<key=value>,\ldots}
101 % This environment takes a comma separated list of key=values where the keys are usually environment
102 % names and the values the arguments to this environment.
103 % The environments are added around the content in the given order, i.e.\ the first environment
104 % is the most outer one and further environments are placed inside it.
105 %
106 % At the moment only the following key is defined. Any other key is taken as an environment name.
107 %
108 % \DescribeKey{add code}={<code before>}{<code after>}
109 % This adds the given code before and after the content.
110 % Any code is permitted including macro argument tokens like `|#1|'.
111 %
112 % \DescribeKey{\meta{environment}}
113 % \DescribeKey{\meta{environment}}=<arguments>
114 % Any unknown key is taken as environment name and the value as argument(s) to the environment.
115 % If the value does not start with a brace `|{|', bracket `|[|' or angle `|<|' it is taken
116 % as a single mandatory argument and is placed inside braces after the environment,
117 % otherwise it is placed unchanged after the environment:
118 % \par\medskip\par\noindent
119 % \begin{tabular}{@{}l@{ $\Rightarrow$ }l@{}}
120 % \Key{\meta{env}} & \Macro\begin{<env>}\ldots\Macro\end{<env>} \\
121 % \Key{\meta{env}}= & \Macro\begin{<env>}\ldots\Macro\end{<env>} \\
122 % \Key{\meta{env}}=<arg> & \Macro\begin{<env>}{<arg>}\ldots\Macro\end{<env>} \\
123 % \Key{\meta{env}}={<arg>} & \Macro\begin{<env>}{<arg>}\ldots\Macro\end{<env>} \\
124 % \Key{\meta{env}}={<arg1>}{<arg2>} & \Macro\begin{<env>}{<arg1>}{<arg2>}\ldots\Macro\end{<env>} \\
125 % \Key{\meta{env}}=[<oarg>] & \Macro\begin{<env>}[<oarg>]\ldots\Macro\end{<env>} \\
126 % \Key{\meta{env}}=[<oarg>]{<marg>} & \Macro\begin{<env>}[<oarg>]{<marg>}\ldots\Macro\end{<env>} \\
127 % \Key{\meta{env}}=<< <aarg> >> & \Macro\begin{<env>}<< <aarg> >>\ldots\Macro\end{<env>} \\
128 % \Key{\meta{env}}=<< <aarg> >>{<marg>} & \Macro\begin{<env>}<< <aarg> >>{<marg>}\ldots\Macro\end{<env>} \\
129 % \multicolumn{2}{@{}l@{}}{etc.} \\
130 % \end{tabular}
131 % \par\bigskip\par
132 %
133 % \DescribeEnv[<content>]{multienv*}{<env=arg>','<key=value>,\ldots}
134 % This environment is identical to \env{multienv} but will apply the keys in the reverse order,
135 % i.e.\ every environment or code is added around the existing environments or code.
136 %
137 %
138 % \DescribeMacro\newmultienvironment{<env name>}[<number of args>][<default value>]{<env=arg>,\ldots}
139 % This macro defines a new environment like \Macro\newenvironment does but uses the \env{multienv}
140 % syntax. The resulting environment will contain all given environments and code.
141 % The environment can have arguments including one leading optional argument.
142 % The arguments can be used as part of the keys and values.
143 % It should be noted that it is not allowed to use arguments in the second argument of
144 % the \Key{add code} key, because that code will be part of \Macro\end{<env name>}.
145 %
146 % An error is raised if the environment already exists.
147 %
148 % \DescribeMacro\renewmultienvironment{<env name>}[<number of args>][<default value>]{<env=arg>,\ldots}
149 % Like \Macro\newmultienvironment but can be used to redefine existing environments.
150 % It is is not relevant \emph{how} the environment was defined previously.
151 % An error is raised if the environment does not already exist.
152 %
153 %
154 % \DescribeMacro\providemultienvironment{<env name>}[<number of args>][<default value>]{<env=arg>,\ldots}
155 % Like \Macro\newmultienvironment but the environment is only defined if it is not already defined.
156 % The environment is also not defined if there a macro with the same name exists.
157 %
158 % \section{Examples}
159 % \lstset{gobble=4,language=[latex]tex}
160 % The following \env{multienv} environment usage:
161 % \begin{lstlisting}
162 % \begin{multienv}{enva,envb=arg,add code={code before}{code after},
163 % envc=[oarg]{marg}}
164 % content
165 % \end{multienv}
166 % \end{lstlisting}
167 % \noindent is basically identical to:
168 % \begin{lstlisting}
169 % \begin{enva}
170 % \begin{envb}{arg}
171 % code before
172 % \begin{enc}[oarg]{marg}
173 % content
174 % \end{enc}
175 % code after
176 % \end{envb}
177 % \end{enva}
178 % \end{lstlisting}
179 % \noindent Using \env{multienv*} the order the environments can be given in the opposite order:
180 % \begin{lstlisting}
181 % \begin{multienv}{envc=[oarg]{marg},add code={code before}{code after},
182 % envb=arg,enva}
183 % content
184 % \end{multienv}
185 % \end{lstlisting}
186 %
187 % \par\bigskip\par\noindent
188 % The following code defines a \env{centeredminipage} environment which content is placed
189 % in a centered \env{minipage} which inner content is also centered.
190 % \begin{lstlisting}
191 % \newmultienvironment{centeredminipage}[1]
192 % {center,minipage=#1,add code={\centering}{}}
193 % \end{lstlisting}
194 % \par\noindent
195 % This is basically identical to:\par
196 % \begin{lstlisting}
197 % \newenvironment{centeredminipage}[1]
198 % {\begin{center}\begin{minipage}{#1}\centering}
199 % {\end{minipage}\end{center}}
200 % \end{lstlisting}
201 % \par\noindent
202 % However actually the \enquote{plain} form of the environment are used, because it is more efficient
203 % and will also produce a correct error message if an incorrect \cs{end} macro is found:\par
204 % \begin{lstlisting}
205 % \newenvironment{centeredminipage}[1]
206 % {\begingroup\center\begingroup\minipage{#1}\centering}
207 % {\endminipage\endgroup\endcenter\endgroup}
208 % \end{lstlisting}
209 % \par\noindent
210 % The groups are added because some environments require to be placed in a group by themselves,
211 % which is normally done by |\begin| and |\end|.
212 %
213 % \StopEventually{}
214 % \clearpage
215 % \section{Implementation}
216 %
217 % \iffalse
218 %<*multienv.sty>
219 % \fi
220 % \begin{macrocode}
221 %<!COPYRIGHT>
222 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
223 \ProvidesPackage{multienv}[%
224 %<!DATE>
225 %<!VERSION>
226 %<*DRIVER>
227 2099/01/01 develop
228 %</DRIVER>
229 Add multiple environments using a Key=value syntax]
230 % \end{macrocode}
231 %
232 %
233 % \begin{macro}{\multienv}
234 % \begin{macrocode}
235 \newcommand{\multienv}{%
236 \begingroup
237 \@ifstar{%
238 \let\multienv@addcode\multienv@addcode@out
239 \multienv@readkeys
240 }{%
241 \let\multienv@addcode\multienv@addcode@in
242 \multienv@readkeys
243 }%
244 }
245 % \end{macrocode}
246 % \end{macro}
247 %
248 %
249 % \begin{macro}{\endmultienv}
250 % \begin{macrocode}
251 \def\endmultienv{\end@multienv\endgroup}
252 % \end{macrocode}
253 % \end{macro}
254 %
255 %
256 % \begin{environment}{multienv*}
257 % \begin{macrocode}
258 \newenvironment{multienv*}{%
259 \begingroup
260 \let\multienv@addcode\multienv@addcode@out
261 \multienv@readkeys
262 }{%
263 \end@multienv\endgroup
264 }
265 % \end{macrocode}
266 % \end{environment}
267 %
268 %
269 % \begin{macro}{\newmultienvironment}
270 % \begin{macrocode}
271 \newcommand\newmultienvironment{%
272 \let\@multi@environment\newenvironment
273 \@multienvironment
274 }
275 % \end{macrocode}
276 % \end{macro}
277 %
278 %
279 % \begin{macro}{\renewmultienvironment}
280 % \begin{macrocode}
281 \newcommand\renewmultienvironment{%
282 \let\@multi@environment\renewenvironment
283 \@multienvironment
284 }
285 % \end{macrocode}
286 % \end{macro}
287 %
288 %
289 % \begin{macro}{\providemultienvironment}
290 % \begin{macrocode}
291 \newcommand\providemultienvironment{%
292 \@ifstar
293 {\@providemultienvironment*}%
294 {\@providemultienvironment{}}%
295 }
296 % \end{macrocode}
297 % \end{macro}
298 %
299 %
300 % \begin{macro}{\@providemultienvironment}
301 % \begin{macrocode}
302 \def\@providemultienvironment#1#2{%
303 \@ifundefined{#2}%
304 {\newmultienvironment#1{#2}}%
305 {\begingroup\tracingall\renewcommand\@tempa[1][]{\renewcommand\@tempa[1][]{\expandafter\endgroup\@gobble}\@tempa}\@tempa}%
306 }
307 % \end{macrocode}
308 % \end{macro}
309 %
310 %
311 % \begin{macro}{\@multienvironment}
312 % \begin{macrocode}
313 \def\@multienvironment{%
314 \@ifstar{%
315 \let\multienv@addcode\multienv@addcode@out
316 \newmultienvironment@marg
317 }{%
318 \let\multienv@addcode\multienv@addcode@in
319 \newmultienvironment@marg
320 }%
321 }
322 % \end{macrocode}
323 % \end{macro}
324 %
325 %
326 % \begin{macro}{\newmultienvironment@marg}
327 % \begin{macrocode}
328 \long\def\newmultienvironment@marg#1{%
329 \@testopt{\newmultienvironment@oarg{#1}}{[0]}%
330 }
331 % \end{macrocode}
332 % \end{macro}
333 %
334 %
335 % \begin{macro}{\newmultienvironment@oarg}
336 % \begin{macrocode}
337 \long\def\newmultienvironment@oarg#1[#2]{%
338 \@ifnextchar[{%
339 \newmultienvironment@oargb{#1}{#2}%
340 }{%
341 \newmultienvironment@def{#1}{[#2]}%
342 }%
343 }
344 % \end{macrocode}
345 % \end{macro}
346 %
347 %
348 % \begin{macro}{\newmultienvironment@oargb}
349 % \begin{macrocode}
350 \long\def\newmultienvironment@oargb#1#2[#3]{%
351 \newmultienvironment@def{#1}{[#2][#3]}%
352 }
353 % \end{macrocode}
354 % \end{macro}
355 %
356 %
357 % \begin{macro}{\newmultienvironment@def}
358 % \begin{macrocode}
359 \long\def\newmultienvironment@def#1#2#3{%
360 \begingroup
361 \multienv@readkeys@{#3}%
362 \def\@tempa{\@multi@environment*{#1}#2}%
363 \@temptokena\expandafter\expandafter\expandafter{\expandafter\expandafter\expandafter{\expandafter\begin@multienv\expandafter}\expandafter{\end@multienv}}%
364 \expandafter\expandafter\expandafter
365 \endgroup
366 \expandafter\@tempa\the\@temptokena
367 }
368 % \end{macrocode}
369 % \end{macro}
370 %
371 %
372 % \begin{macro}{\multienv@readkeys}
373 % \begin{macrocode}
374 \long\def\multienv@readkeys#1{%
375 \multienv@readkeys@{#1}%
376 \begin@multienv
377 }
378 % \end{macrocode}
379 % \end{macro}
380 %
381 %
382 % \begin{macro}{\multienv@readkeys@}
383 % \begin{macrocode}
384 \long\def\multienv@readkeys@#1{%
385 \let\begin@multienv\@empty
386 \let\end@multienv\@empty
387 \multienv@readkeyval#1,\@nnil,\@nnil
388 }
389 % \end{macrocode}
390 % \end{macro}
391 %
392 % \begin{macrocode}
393 \let\begin@multienv\@empty
394 \let\end@multienv\@empty
395 % \end{macrocode}
396 %
397 % \begin{macro}{\multienv@readkeyval}
398 % \begin{macrocode}
399 \long\def\multienv@readkeyval#1,{%
400 \ifx\@nnil#1\relax
401 \expandafter\@gobble
402 \else
403 \multienv@sepkeyval#1=\@nnil=\@nnil\relax
404 \expandafter\multienv@readkeyval
405 \fi
406 }
407 % \end{macrocode}
408 % \end{macro}
409 %
410 %
411 % \begin{macro}{\multienv@sepkeyval}
412 % \begin{macrocode}
413 \long\def\multienv@sepkeyval#1=#2={%
414 \ifx\@nnil#2\relax
415 \multienv@handlekeyval{#1}{}%
416 \expandafter\@gobble
417 \else
418 \multienv@handlekeyval{#1}{#2}%
419 \expandafter
420 \@gobblefour
421 \fi
422 }
423 % \end{macrocode}
424 % \end{macro}
425 %
426 %
427 % \begin{macro}{\multienv@handlekeyval}
428 % \begin{macrocode}
429 \long\def\multienv@handlekeyval#1#2{%
430 \@ifundefined{multienv@key@#1}{%
431 \multienv@addenv{#1}{#2}%
432 }{%
433 \@nameuse{multienv@key@#1}#2\@nnil
434 }%
435 }
436 % \end{macrocode}
437 % \end{macro}
438 %
439 %
440 % \begin{macro}{\multienv@addenv}
441 % \begin{macrocode}
442 \long\def\multienv@addenv#1#2{%
443 \@ifnextchar\bgroup{%
444 \multienv@@addenv
445 }{%
446 \ifcase0%
447 \expandafter\ifx\csname @let@token\endcsname\@nnil1\else
448 \expandafter\ifx\csname @let@token\endcsname[1\else
449 \expandafter\ifx\csname @let@token\endcsname<1\fi\fi\fi
450 \relax
451 \expandafter\multienv@@addenv@
452 \else
453 \expandafter\multienv@@addenv
454 \fi
455 }#2\@nnil{#1}%
456 }
457 % \end{macrocode}
458 % \end{macro}
459 %
460 %
461 % \begin{macro}{\multienv@@addenv@}
462 % \begin{macrocode}
463 \long\def\multienv@@addenv@#1\@nnil{%
464 \multienv@@addenv{{#1}}\@nnil
465 }
466 % \end{macrocode}
467 % \end{macro}
468 %
469 %
470 % \begin{macro}{\multienv@@addenv}
471 % \begin{macrocode}
472 \long\def\multienv@@addenv#1\@nnil#2{%
473 \multienv@addcode{\multi@env{#2}#1}{\endmulti@env{#2}}%
474 }
475 % \end{macrocode}
476 % \end{macro}
477 %
478 %
479 % \begin{macro}{\multi@env}
480 % \begin{macrocode}
481 \long\def\multi@env#1{%
482 \begingroup
483 \@ifundefined{#1}%
484 {\@latex@error{Environment #1 undefined}\@eha}%
485 {\csname #1\endcsname}%
486 }
487 % \end{macrocode}
488 % \end{macro}
489 %
490 %
491 % \begin{macro}{\endmulti@env}
492 % \begin{macrocode}
493 \def\endmulti@env#1{\csname end#1\endcsname\endgroup}
494 % \end{macrocode}
495 % \end{macro}
496 %
497 %
498 % \begin{macro}{\multienv@addcode@out}
499 % \begin{macrocode}
500 \long\def\multienv@addcode@out#1#2{%
501 \@temptokena{#1}%
502 \@temptokena\expandafter\expandafter\expandafter{\expandafter\the\expandafter\@temptokena\begin@multienv}%
503 \edef\begin@multienv{\the\@temptokena}%
504 \@temptokena\expandafter{\end@multienv#2}%
505 \edef\end@multienv{\the\@temptokena}%
506 }
507 % \end{macrocode}
508 % \end{macro}
509 %
510 %
511 % \begin{macro}{\multienv@addcode@in}
512 % \begin{macrocode}
513 \long\def\multienv@addcode@in#1#2{%
514 \@temptokena\expandafter{\begin@multienv#1}%
515 \edef\begin@multienv{\the\@temptokena}%
516 \@temptokena{#2}%
517 \@temptokena\expandafter\expandafter\expandafter{\expandafter\the\expandafter\@temptokena\end@multienv}%
518 \edef\end@multienv{\the\@temptokena}%
519 }
520 % \end{macrocode}
521 % \end{macro}
522 %
523 %
524 % \begin{macro}{\multienv@key@add}
525 % \begin{macrocode}
526 \long\@namedef{multienv@key@add code}#1\@nnil{%
527 % \end{macrocode}
528 % \end{macro}
529 %
530 % \begin{macrocode}
531 \multienv@addcode#1{}{}%
532 }
533 % \end{macrocode}
534 %
535 % \begin{macro}{\multienv@key@adjustbox}
536 % \begin{macrocode}
537 \long\@namedef{multienv@key@adjustbox}#1\@nnil{%
538 \multienv@addcode{\csname adjustbox@noindent\endcsname\adjustbox{#1}\bgroup\ignorespaces}{\ifhmode\unskip\fi\egroup}%
539 }
540 % \end{macrocode}
541 % \end{macro}
542 %
543 % \iffalse
544 %</multienv.sty>
545 % \fi
546 %
547 % \Finale
548 \endinput