From e6bf1654e9dcecdb03d8172c7493d45fc245783d Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 1 Apr 2013 22:50:52 +0000 Subject: environ (1apr13) git-svn-id: svn://tug.org/texlive/trunk@29600 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/environ/environ.dtx | 164 ++++----------------- Master/texmf-dist/source/latex/environ/environ.ins | 4 +- 2 files changed, 33 insertions(+), 135 deletions(-) (limited to 'Master/texmf-dist/source/latex/environ') diff --git a/Master/texmf-dist/source/latex/environ/environ.dtx b/Master/texmf-dist/source/latex/environ/environ.dtx index 020e3ef87fc..40a2d44e144 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.2 +v0.3 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 +Copyright 2007-2008, 2013 Distributed under the LaTeX Project Public License % %<*internal> @@ -48,7 +48,7 @@ Distributed under the LaTeX Project Public License \endpreamble \postamble -Copyright (C) 2007 by Will Robertson +Copyright (C) 2007-2008, 2013 by Will Robertson 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 % % %<*driver> -\documentclass{ltxdoc} +\documentclass[12pt]{ltxdoc} \EnableCrossrefs \CodelineIndex \RecordChanges @@ -109,6 +109,7 @@ This work consists of the file environ.dtx % \section{Introduction} % % This packages provides new commands for defining environments. Here's a trivial example: +% % \begin{example}{} % \NewEnviron{test}{% % \fbox{\parbox{1.5cm}{\BODY}} @@ -121,7 +122,7 @@ This work consists of the file environ.dtx % \end{test} % \end{example} % -% \cmd\RenewEnviron\ can be used with the same syntax to redefine a pre\"existing environment. +% \cmd\RenewEnviron\ can be used with the same syntax to redefine a pre-existing environment. % % \section{For the document author} % @@ -137,8 +138,11 @@ This work consists of the file environ.dtx % \subsection{Environment arguments} % % If you want to use arguments to the environment, these are specified in the usual way: -% \codeline \cmd\NewEnviron\marg{name}\oarg{N.\,args}\oarg{opt.\,arg.}\marg{macro code}\oarg{final code} ,\\ +% \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|): +% % \begin{example}{} % \NewEnviron{test}[2][\today]{% % \fbox{\parbox{3cm}{% @@ -160,9 +164,10 @@ 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 default is to define each new environment postfixed by \cmd\ignorespacesafterend, like this: +% 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}| .\\ % Here's a silly example: +% % \begin{example}{} % \environfinalcode{((finish))} % \NewEnviron{test}{\fbox{\parbox{3cm}{\BODY}}} @@ -181,6 +186,7 @@ This work consists of the file environ.dtx % \section{Test} % % Here's an example to ensure everything that you'd think should work, in fact, does: +% % \begin{example}{} % \NewEnviron{test}{% % \fbox{\parbox{\linewidth- @@ -200,48 +206,6 @@ This work consists of the file environ.dtx % \end{test} % \end{example} % -% -% \section{Backwards compatibility} -% -% In v0.1 of this package, the \cmd\NewEnvironment\ macro was -% used instead (described below). There were a number of limitations with the different -% approach that it used, the main ones being: -% \begin{itemize} -% \item Option processing occured with \emph{every} instance of |#1| -% (which represented the environment body), -% \item Environment options were only available \emph{after} the first instance of |#1|. -% \end{itemize} -% Please, please, don't use \cmd\NewEnvironment. -% -% The code for this syntax is still loaded by this package for -% backwards compatibility, but in the next major release it will -% be moved to a conditional package option. Eventually, I'll -% probably delete it from the package altogether. -% -% \subsection{Previous code documentation} -% -% Just in case you need the documentation for the old syntax, here it is: -% \codeline \cmd\NewEnvironment\marg{name}\marg{macro code} ,\\ -% where \marg{macro code} has argument |#1| as everything inside the environment. -% -% Now, this kind of environment definition makes collecting arguments a little cumbersome. Arguments are defined with a separate macro that `gobbles up' the arguments inside the environment before the body is passed to \marg{macro code}. -% \codeline \cmd\EnvironArgs\marg{name}\oarg{N.\ args}\oarg{opt. arg.}\marg{arg. macro code} \\ -% This follows the same syntax of defining a macro with several arguments and a possible optional argument at the beginning. Here's an example: -% \begin{example}{} -% \NewEnvironment{test}{(#1)\tmp} -% \EnvironArgs{test}[2][before]{\def\tmp{\par---#1/#2---}} -% \begin{test}{after} -% par -% -% graf -% \end{test} -% \end{example} -% -% I've tried to ensure that whitespace is ignored at the appropriate places; without this additional code, there would be a space before `par' and after `graf' in the examples above. -% -% Environments created with \cmd\NewEnvironment\ are ended by the command \cmd\ignorespacesafterend, which means that if they're used in a paragraph then the |\end{...}| command will gobble space after it. (If the environment is a paragraph on its own, there will be no difference.) -% -% \newpage % \section{For the macro author} % % The \pkg{amsmath} package contains a macro that facilitates the functionality in the previous section, which package writers may wish to use directly. The canonical command is \cmd\collect@body, which I've also defined in \cmd\long\ form to be useable for multi-paragraph environments (\cmd\Collect@Body). Here's how it's used: @@ -279,13 +243,18 @@ This work consists of the file environ.dtx % % This is the package. % \begin{macrocode} -\ProvidesPackage{environ}[2008/06/18 v0.2 A new way to define environments] +\ProvidesPackage{environ}[2013/04/01 v0.3 A new environment syntax] % \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! @@ -313,31 +282,18 @@ This work consists of the file environ.dtx % \end{macrocode} % \end{macro} % -% \begin{macro}{\trim@spaces} -% \darg{tokens} Removes leading and trailing spaces from the (arbitrary) input. -% Thanks to Morten H\o gholm. -% \begin{macrocode} -\catcode`\Q=3 -\long\def\trim@spaces#1{\romannumeral-`\q\trim@trim@\noexpand#1Q Q} -\long\def\trim@trim@#1 Q{\trim@trim@@#1Q} -\long\def\trim@trim@@#1Q#2{#1} -\catcode`\Q=11 -% \end{macrocode} -% \changes{v0.2}{2008/06/16}{Added.} -% \end{macro} -% % \section{\cs{collect@body}-related code} % % \begin{macro}{\collect@body} % Now, \pkg{amsmath} defines \cmd\collect@body\ for us. But that package may not be loaded, and we don't want to have to load the whole thing just for this one macro. % \begin{macrocode} \unless\ifdefined\collect@body - \newtoks\@emptytoks \newtoks\@envbody \def\collect@body#1{% \@envbody{\expandafter#1\expandafter{\the\@envbody}}% \edef\process@envbody{\the\@envbody\noexpand\end{\@currenvir}}% - \@envbody\@emptytoks \def\begin@stack{b}% + \@envbody={}% + \def\begin@stack{b}% \begingroup \expandafter\let\csname\@currenvir\endcsname\collect@@body \edef\process@envbody{% @@ -371,7 +327,8 @@ This work consists of the file environ.dtx \long\def\Collect@Body#1{% \@envbody{\expandafter#1\expandafter{\the\@envbody}}% \edef\process@envbody{\the\@envbody\noexpand\end{\@currenvir}}% - \@envbody\@emptytoks \def\begin@stack{b}% + \@envbody={}% + \def\begin@stack{b}% \begingroup \expandafter\let\csname\@currenvir\endcsname\Collect@@Body \edef\process@envbody{% @@ -401,6 +358,7 @@ This work consists of the file environ.dtx % \section{User-level syntax} % \begin{macro}{\NewEnviron} % This is the new one. +% \paragraph{Input argument parsing} % \begin{macrocode} \def\NewEnviron{% \let\env@newcommand\newcommand @@ -455,7 +413,7 @@ This work consists of the file environ.dtx % \begin{macrocode} \env@newenvironment{#1}{% \expandafter\Collect@Body\csname env@#1@parse\endcsname - }{#4} + }{#4}% % \end{macrocode} % |env@#1@parse| executes the body twice: the first time to save the body while ignoring the arguments; and the second time to process the environment definition itself while ignoring the environment body: % \begin{macrocode} @@ -488,79 +446,19 @@ This work consists of the file environ.dtx % \changes{v0.2}{2008/06/16}{Added.} % \end{macro} % -% \section{Backwards compatibility} +% \section{Old code} % \begin{macro}{\NewEnvironment} % \darg{Environment name} % \darg{Macro definition applied to env.\ body} -% Here's our new environment definition macro. First of all wrap it up appropriately for new- or renew- -% \begin{macrocode} -\newcommand\NewEnvironment{% - \let\env@newenvironment\newenvironment - \let\env@newcommand\newcommand - \Make@Environment} -\newcommand\RenewEnvironment{% - \let\env@newenvironment\renewenvironment - \let\env@newcommand\renewcommand - \Make@Environment} -% \end{macrocode} -% And here we go: -% \begin{macrocode} -\newcommand\Make@Environment[2]{% -% \end{macrocode} -% Initial `argument' parser, does nothing but remove leading space: -% \begin{macrocode} - \expandafter\let\csname env@args@#1\endcsname\ignorespaces -% \end{macrocode} -% We use \cmd\Collect@Body\ to grab the argument (always \cmd\long) -% \begin{macrocode} - \env@newenvironment{#1}{% - \expandafter\Collect@Body\csname env@@#1\endcsname}{\ignorespacesafterend}% -% \end{macrocode} -% Now precede the env.\ body by the argument parsing command, which may or may not be defined in \cmd\EnvironArgs\ (and \cmd\unskip\ removes trailing space) -% \begin{macrocode} - \longdef@c{env@@#1}##1{% - \csname env@@@#1\endcsname{% - \csname env@args@#1\endcsname##1\unskip}}% -% \end{macrocode} -% And then pass it all off to the environment macro (|#2|), -% \begin{macrocode} - \longdef@c{env@@@#1}##1{#2}} -% \end{macrocode} -% \changes{v0.2}{2008/06/11}{Changed \cs{@currenv} to \texttt{\#1} to allow nesting.} +% 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} -% \darg{Environment name} -% \doarg{Number of arguments} -% \doarg{Optional argument} -% \darg{Argument macro code} -% Tedious argument parsing: -% \begin{macrocode} -\newcommand\EnvironArgs[1]{% - \@ifnextchar[ - {\Env@Args{#1}} - {\Env@Args{#1}[0]}} -% \end{macrocode} -% Tedious argument parsing: -% \begin{macrocode} -\long\def\Env@Args#1[#2]{% - \@ifnextchar[ - {\Env@@@Args{#1}[#2]} - {\Env@@Args{#1}[#2]}} -% \end{macrocode} -% This is when there is no optional argument. In this case and the next, we simply define a command that is inserted when the argument body is processed (see \cmd\NewEnvironment). \cmd\ignorespaces\ removes leading space after the arguments. -% \begin{macrocode} -\long\def\Env@@Args#1[#2]#3{% - \expandafter\renewcommand\csname env@args@#1\endcsname[#2]{% - #3\ignorespaces}} -% \end{macrocode} -% Same as above when there is an optional argument: -% \begin{macrocode} -\long\def\Env@@@Args#1[#2][#3]#4{% - \expandafter\renewcommand\csname env@args@#1\endcsname[#2][#3]{% - #4\ignorespaces}} -% \end{macrocode} +% Deprecated. +% \changes{v0.3}{2013/04/01}{Deleted.} % \end{macro} % %\iffalse diff --git a/Master/texmf-dist/source/latex/environ/environ.ins b/Master/texmf-dist/source/latex/environ/environ.ins index 135c6a9cebd..67dd1de1c08 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 by Will Robertson +Copyright (C) 2007-2008, 2013 by Will Robertson Distributable under the LaTeX Project Public License, version 1.3c or higher (your choice). The latest version of @@ -43,7 +43,7 @@ This work consists of the file environ.dtx \generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}} \endbatchfile %% -%% Copyright (C) 2007 by Will Robertson +%% Copyright (C) 2007-2008, 2013 by Will Robertson %% %% Distributable under the LaTeX Project Public License, %% version 1.3c or higher (your choice). The latest version of -- cgit v1.2.3