summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/environ
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-05-04 21:43:33 +0000
committerKarl Berry <karl@freefriends.org>2014-05-04 21:43:33 +0000
commitce474d87225a325bc73c84890b079a2a1b8a635c (patch)
treeddc5cfbd999829028662a8d8f804d5c5c6d6a80e /Master/texmf-dist/source/latex/environ
parentc5ab811ed86fca6665ac80b83b72a714e7d93397 (diff)
environ (4may14)
git-svn-id: svn://tug.org/texlive/trunk@33821 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/environ')
-rw-r--r--Master/texmf-dist/source/latex/environ/environ.dtx160
-rw-r--r--Master/texmf-dist/source/latex/environ/environ.ins5
2 files changed, 89 insertions, 76 deletions
diff --git a/Master/texmf-dist/source/latex/environ/environ.dtx b/Master/texmf-dist/source/latex/environ/environ.dtx
index 40a2d44e144..b6a047ca1a0 100644
--- a/Master/texmf-dist/source/latex/environ/environ.dtx
+++ b/Master/texmf-dist/source/latex/environ/environ.dtx
@@ -5,7 +5,7 @@
%<*readme>
___________________
The ENVIRON package
-v0.3
+v0.2
Provides two things: a new way of defining
environments that read their contents before
@@ -27,7 +27,7 @@ ______________
Will Robertson
wspr 81 [at] gmail [dot] com
-Copyright 2007-2008, 2013
+Copyright 2007-2014
Distributed under the LaTeX Project Public License
%</readme>
%<*internal>
@@ -48,7 +48,7 @@ Distributed under the LaTeX Project Public License
\endpreamble
\postamble
-Copyright (C) 2007-2008, 2013 by Will Robertson <wspr81@gmail.com>
+Copyright (C) 2007-2014 by Will Robertson <wspr81@gmail.com>
Distributable under the LaTeX Project Public License,
version 1.3c or higher (your choice). The latest version of
@@ -78,7 +78,7 @@ This work consists of the file environ.dtx
%</internal>
%
%<*driver>
-\documentclass[12pt]{ltxdoc}
+\documentclass[a4paper]{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
@@ -103,45 +103,41 @@ This work consists of the file environ.dtx
% \maketitle
%
% \begin{abstract}
-% \noindent This package provides two things, one for document authors and one for macro authors. For the document authors, a new method of defining environments that might be more convenient on occassion. And for the package writers, \pkg{amsmath}'s \cmd\collect@body\ command, and a long version of the same, \cmd\Collect@Body.
+% \noindent This package provides two things, one for document authors and one for macro authors. For the document authors, a new method, \cs{NewEnviron}, fo defining environments that might be more convenient on occasion. And for the package writers, \pkg{amsmath}'s \cmd\collect@body\ command, and a long version of the same, \cmd\Collect@Body.
% \end{abstract}
%
% \section{Introduction}
%
-% This packages provides new commands for defining environments. Here's a trivial example:
+% This packages provides new commands for defining environments:
%
% \begin{example}{}
% \NewEnviron{test}{%
-% \fbox{\parbox{1.5cm}{\BODY}}
-% \color{red}
+% \fbox{\parbox{1.5cm}{\BODY}}\color{red}
% \fbox{\parbox{1.5cm}{\BODY}}}
-%
% \begin{test}
-% par\par
-% graf
+% par\par graf
% \end{test}
% \end{example}
-%
-% \cmd\RenewEnviron\ can be used with the same syntax to redefine a pre-existing environment.
+% \cmd\RenewEnviron\ has the same syntax to redefine a pre-existing environment.
%
% \section{For the document author}
%
% \LaTeX's standard method of defining environments looks like this (ignoring arguments for now):
% \codeline \cmd\newenvironment\marg{name}\marg{pre code}\marg{post code} .
%
-% The advantage to using environments is that their contents is not treated as a macro argument, so there are less restrictions on what can exist inside, and the processing can be more efficient for long pieces of document text.
+% The advantage to using environments is that their contents are not treated as a macro argument, so there are fewer restrictions on what can exist inside, and the processing can be more efficient for long pieces of document text.
%
-% The disadvantage of environments is that sometimes you really do want to collect up its body and apply some sort of command to the whole thing. This package provides a way to define such environments, and v0.2 of this package brings a new syntax:
+% The disadvantage of environments is that sometimes you really do want to collect up their body and apply some sort of command to the whole thing. This package provides a way to define such environments:
% \codeline \cmd\NewEnviron\marg{name}\marg{macro code}\oarg{final code} .\\
% You saw an example in the introduction; the body of the environment is contained within the macro |\BODY|, and \oarg{final code} is the code executed at |\end|\marg{name} (more on this later).
%
% \subsection{Environment arguments}
%
-% If you want to use arguments to the environment, these are specified in the usual way:
-% \begin{center}
-% \makebox[0pt][c]{\cmd\NewEnviron\marg{name}\oarg{N.\,args}\oarg{opt.\,arg.}\marg{macro code}\oarg{final code}}
-% \end{center}
-% where \marg{macro code} has arguments |#1|, |#2|, \dots, as per traditional \LaTeX\ environment mandatory and optional arguments. Here's an example with two arguments; one optional argument (|#1|, which is |\today| if omitted) and one mandatory argument (|#2|):
+% If you want to use arguments to the environment, these are specified as usual:
+% \codeline \cmd\NewEnviron\marg{name}\oarg{N.\,args}\oarg{opt.\,arg.}\marg{macro code}\oarg{final code} \\
+% where \marg{macro code} has arguments |#1|, |#2|, \dots, as per traditional \LaTeX\ environment mandatory and optional arguments.
+%
+% Here's an example with two arguments; one optional argument (|#1|, which is |\today| if omitted) and one mandatory argument (|#2|):
%
% \begin{example}{}
% \NewEnviron{test}[2][\today]{%
@@ -164,12 +160,12 @@ This work consists of the file environ.dtx
% For the purposes of this package it is only designed (but is very useful indeed) for cleanup code such as space gobbling in the input text.
%
% \DescribeMacro{\environfinalcode}
-% This macro sets a default value for the \oarg{final code} (unless manually specified) in each subsequent environment created with \cmd\NewEnviron. The \pkg{environ} package defaults to defining each new environment to be postfixed by \cmd\ignorespacesafterend, like this:
-% \codeline |\environfinalcode{\ignorespacesafterend}| .\\
+% This macro sets a default value for the \oarg{final code} (unless manually specified) in each subsequent environment created with \cmd\NewEnviron. The default is to define each new environment postfixed by \cmd\ignorespacesafterend, like this:
+% \codeline |\environfinalcode{\ignorespacesafterend}| \\
% Here's a silly example:
%
% \begin{example}{}
-% \environfinalcode{((finish))}
+% \environfinalcode{(finish)}
% \NewEnviron{test}{\fbox{\parbox{3cm}{\BODY}}}
% \begin{test}
% par\par
@@ -178,32 +174,27 @@ This work consists of the file environ.dtx
% \end{example}
%
% Careful, \cmd\environfinalcode\ cannot contain square brackets without first protecting them with braces (\eg,
-% \codeline |\environfinalcode{[end]}| \\
+% |\environfinalcode{[end]}|
% will not work but
-% \codeline |\environfinalcode{{[end]}}| \\
+% |\environfinalcode{{[end]}}|
% will). This is because the optional argument to \cmd\NewEnviron\ itself uses square brackets as argument delimiters.
%
-% \section{Test}
+% \subsection{The \cs{BODY} command}
%
-% Here's an example to ensure everything that you'd think should work, in fact, does:
+% \DescribeMacro{\environbodyname}
+% Using \cs{BODY} as the body of the environment might clash with a command defined by another package.
+% To overcome such conflicts, rename this command with
+% \codeline |\environbodyname|\cs{\meta{command}}\\
+% at which point \cs{NewEnviron} will use \cs{\meta{command}} instead of \cs{BODY}.
+% Here's an example:
%
% \begin{example}{}
-% \NewEnviron{test}{%
-% \fbox{\parbox{\linewidth-
-% 0.1cm*\currentgrouplevel}{\BODY}}
-% \setlength\fboxrule{2\fboxrule}
-% \fbox{\parbox{\linewidth-
-% 0.1cm*\currentgrouplevel}{``\BODY''}}}
-%
-% \begin{test}
-% outer\par
-% \def\tmp#1{*#1*}%
-% \tmp{aa}\par
-% \begin{test}
-% inner\par
-% \def\tmp#1{(#1)}\tmp{bb}
-% \end{test}
-% \end{test}
+% \NewEnviron{FOO}{\fbox{\BODY}}
+% \environbodyname\envbody
+% \NewEnviron{foo}{\fbox{\envbody}}
+%
+% \begin{FOO}FOO\end{FOO}
+% \begin{foo}foo\end{foo}
% \end{example}
%
% \section{For the macro author}
@@ -233,6 +224,36 @@ This work consists of the file environ.dtx
% \end{test}
% \end{example}
%
+% \newpage
+% \section{Test}
+%
+% Here's an example or two to ensure everything that you'd think should work, in fact, does:
+%
+% \begin{example}{}
+% \NewEnviron{test}{%
+% \fbox{\parbox{\linewidth-
+% 0.1cm*\currentgrouplevel}{\BODY}}
+% \setlength\fboxrule{2\fboxrule}
+% \fbox{\parbox{\linewidth-
+% 0.1cm*\currentgrouplevel}{``\BODY''}}}
+%
+% \begin{test}
+% outer\par
+% \def\tmp#1{*#1*}%
+% \tmp{aa}\par
+% \begin{test}
+% inner\par
+% \def\tmp#1{(#1)}\tmp{bb}
+% \end{test}
+% \end{test}
+% \end{example}
+%
+%
+%% ^^A Test that \RenewEnvironment works correctly:
+% \newenvironment{foobar}{}{}
+% \RenewEnviron{foobar}{\BODY}
+%
+%
% \StopEventually{}
%
% \clearpage
@@ -243,18 +264,14 @@ This work consists of the file environ.dtx
%
% This is the package.
% \begin{macrocode}
-\ProvidesPackage{environ}[2013/04/01 v0.3 A new environment syntax]
+\ProvidesPackage{environ}[2014/05/04 v0.3 A new way to define environments]
+\RequirePackage{trimspaces}
% \end{macrocode}
%
-% \changes{v0.3}{2013/04/01}{Use trimspaces package, remove eTeX requirement.}
% \PrintChanges
%
% \section{Begin}
%
-% \begin{macrocode}
-\RequirePackage{trimspaces}
-% \end{macrocode}
-%
% \begin{macro}{\environbodyname}
% \darg{control sequence}
% Changes the control sequence used to represent the environment body in its definition. Not to be used as a user command; but maybe one day it will be. Don't change this after defining any |\NewEnviron| environments!
@@ -262,6 +279,7 @@ This work consists of the file environ.dtx
\def\environbodyname#1{\def\env@BODY{#1}}
\environbodyname\BODY
% \end{macrocode}
+% \changes{v0.3}{2015/05/04}{Works properly and now documented.}
% \end{macro}
%
% \begin{macro}{\environfinalcode}
@@ -356,16 +374,15 @@ This work consists of the file environ.dtx
% \end{macro}
%
% \section{User-level syntax}
+% \begin{macro}{\RenewEnviron}
+% \changes{v0.3}{2015/05/04}{Fixed for non-environ commands.}
% \begin{macro}{\NewEnviron}
% This is the new one.
-% \paragraph{Input argument parsing}
% \begin{macrocode}
\def\NewEnviron{%
- \let\env@newcommand\newcommand
\let\env@newenvironment\newenvironment
\env@NewEnviron}
\def\RenewEnviron{%
- \let\env@newcommand\renewcommand
\let\env@newenvironment\renewenvironment
\env@NewEnviron}
% \end{macrocode}
@@ -409,6 +426,10 @@ This work consists of the file environ.dtx
% \begin{macrocode}
\long\def\env@new#1#2#3[#4]{%
% \end{macrocode}
+% Save the definition of \cs{env@BODY} so we know what to look for.
+% \begin{macrocode}
+ \longdef@c{env@#1@BODY\expandafter}\expandafter{\env@BODY}%
+% \end{macrocode}
% Define the new environment to Collect its body and execute |env@#1@parse| on it.
% \begin{macrocode}
\env@newenvironment{#1}{%
@@ -423,20 +444,25 @@ This work consists of the file environ.dtx
% \end{macrocode}
% These must be defined on a per-environment basis in order to get the argument gobbling right: (because there are a variable number of arguments)
% \begin{macrocode}
- \expandafter\env@newcommand
- \csname env@#1@save@env\endcsname#2{\env@save}%
- \expandafter\env@newcommand
- \csname env@#1@process\endcsname#2{#3\env@ignore}}
+ \expandafter\let\csname env@#1@save@env\endcsname\relax
+ \expandafter\let\csname env@#1@process\endcsname\relax
+ \expandafter\newcommand
+ \csname env@#1@save@env\endcsname#2{%
+ \expandafter\expandafter\expandafter
+ \env@save\csname env@#1@BODY\endcsname}%
+ \expandafter\newcommand
+ \csname env@#1@process\endcsname#2{#3\env@ignore}%
+}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\env@save}
% If \cmd{\env@BODY} were variable, this macro would have to be saved for every environment definition individually; at the moment we just use a global definition.
% Use \cmd\trim@spaces\ to remove surrounding space:
% \begin{macrocode}
-\long\def\env@save#1\env@nil{%
- \expandafter\edef\env@BODY{%
+\long\def\env@save#1#2\env@nil{%
+ \edef#1{%
\unexpanded\expandafter
- \expandafter\expandafter{\trim@spaces{#1}}}}
+ \expandafter\expandafter{\trim@spaces{#2}}}}
% \end{macrocode}
% \end{macro}
% This is the same as a \cmd\@gobblenil\ but long and less likely to exist in the environment body:
@@ -445,20 +471,6 @@ This work consists of the file environ.dtx
% \end{macrocode}
% \changes{v0.2}{2008/06/16}{Added.}
% \end{macro}
-%
-% \section{Old code}
-% \begin{macro}{\NewEnvironment}
-% \darg{Environment name}
-% \darg{Macro definition applied to env.\ body}
-% Deprecated.
-% \changes{v0.1a}{2008/06/11}{Changed \cs{@currenv} to \texttt{\#1} to allow nesting.}
-% \changes{v0.2}{2008/06/16}{Deprecated.}
-% \changes{v0.3}{2013/04/01}{Deleted.}
-% \end{macro}
-%
-% \begin{macro}{\EnvironArgs}
-% Deprecated.
-% \changes{v0.3}{2013/04/01}{Deleted.}
% \end{macro}
%
%\iffalse
@@ -602,7 +614,7 @@ This work consists of the file environ.dtx
% \typeout{*************************************************************}
% \typeout{*}
% \typeout{* To finish the installation you have to move the following}
-% \typeout{* file into a directory searched by XeTeX:}
+% \typeout{* file into a directory searched by TeX:}
% \typeout{*}
% \typeout{* \space\space\space environ.sty}
% \typeout{*}
diff --git a/Master/texmf-dist/source/latex/environ/environ.ins b/Master/texmf-dist/source/latex/environ/environ.ins
index 67dd1de1c08..e40cfa18119 100644
--- a/Master/texmf-dist/source/latex/environ/environ.ins
+++ b/Master/texmf-dist/source/latex/environ/environ.ins
@@ -24,7 +24,7 @@
\endpreamble
\postamble
-Copyright (C) 2007-2008, 2013 by Will Robertson <wspr81@gmail.com>
+Copyright (C) 2007-2014 by Will Robertson <wspr81@gmail.com>
Distributable under the LaTeX Project Public License,
version 1.3c or higher (your choice). The latest version of
@@ -42,8 +42,9 @@ This work consists of the file environ.dtx
\askforoverwritefalse
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
\endbatchfile
+%% ^^A Test that \RenewEnvironment works correctly:
%%
-%% Copyright (C) 2007-2008, 2013 by Will Robertson <wspr81@gmail.com>
+%% Copyright (C) 2007-2014 by Will Robertson <wspr81@gmail.com>
%%
%% Distributable under the LaTeX Project Public License,
%% version 1.3c or higher (your choice). The latest version of