new latex package environ (23sep07)

git-svn-id: svn://tug.org/texlive/trunk@5020 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 538 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/environ/environ.dtx b/Master/texmf-dist/source/latex/environ/environ.dtx
new file mode 100644
index 00000000000..f30120eb541
--- /dev/null
+++ b/Master/texmf-dist/source/latex/environ/environ.dtx
@@ -0,0 +1,476 @@
+% \iffalse 
+%<*internal>
+\iffalse
+%</internal>
+%<*readme>
+___________________
+The ENVIRON package
+v0.0
+
+______________
+Will Robertson
+wspr 81 [at] gmail [dot] com
+
+Copyright 2007
+Distributed under the LaTeX Project Public License
+%</readme>
+%<*internal>
+\fi
+\begingroup
+%</internal>
+%<*batchfile>
+\input docstrip.tex
+\keepsilent
+\preamble
+
+  __________________________________
+  Copyright (C) 2007  Will Robertson
+
+  License information appended.
+
+
+\endpreamble
+\postamble
+
+Copyright (C) 2007 by Will Robertson <wspr81@gmail.com>
+
+Distributable under the LaTeX Project Public License,
+version 1.3c or higher (your choice). The latest version of
+this license is at: http://www.latex-project.org/lppl.txt
+
+This work is "maintained" (as per LPPL maintenance status) 
+by Will Robertson.
+
+This work consists of the file  environ.dtx
+          and the derived files environ.pdf,
+                                environ.sty, and
+                                environ.ins.
+
+\endpostamble
+\askforoverwritefalse
+\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
+\generate{\file{\jobname.cfg}{\from{\jobname.dtx}{defaults}}}
+%</batchfile>
+%<batchfile>\endbatchfile
+%<*internal>
+\generate{\file{\jobname.ins}{\from{\jobname.dtx}{batchfile}}}
+\nopreamble\nopostamble
+\generate{\file{README.txt}{\from{\jobname.dtx}{readme}}}
+\generate{\file{prepare.sh}{\from{\jobname.dtx}{prepare}}}
+\generate{\file{dtx-style.sty}{\from{\jobname.dtx}{dtx-style}}}
+\endgroup
+\immediate\write18{makeindex -s gind.ist -o \jobname.ind  \jobname.idx}
+\immediate\write18{makeindex -s gglo.ist -o \jobname.gls  \jobname.glo}
+%</internal>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+%\OnlyDescription
+\usepackage{dtx-style}
+\begin{document}
+  \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+%
+%
+% \fi
+%
+% \GetFileInfo{\jobname.sty}
+% \CheckSum{0}
+% \makeatletter
+%
+% \title{A couple of things involving environments}
+% \author{Will Robertson}
+% \date{\filedate \qquad \fileversion}
+%
+% \maketitle
+%
+% \begin{abstract}
+% 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.
+% \end{abstract}
+%
+% \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 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,
+% \codeline \cmd\NewEnvironment\marg{name}\marg{macro code} ,\\
+% where \marg{macro code} has argument |#1| as everything inside the environment. \cmd\RenewEnvironment\ can be used to redefine a pre\"existing environment.
+%
+% As an example, consider putting a box around an environment. This requires more than a one-line solution without this package \note{And there're packages to do things much more nicely than I'm showing here anyway.}, but now we can write
+% \begin{example}{}
+% \NewEnvironment{test}{\fbox{\parbox{3cm}{#1}}}
+% \begin{test}
+%   par\par
+%   graf
+% \end{test}
+% \end{example}
+%
+% Now, this kind of environment definition makes collecting arguments a little cumbersome, but it's certainly possible. 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.
+%
+% Note that arguments to the environment have to be explicitly passed into the macro code defining what the environment actually does. This is a bit of a shame, and a more convenient syntax could be
+% \begin{Verbatim}[gobble=4]
+%   \NewEnv{test}[2][before]{\EnvBody\par---#1/#2---}
+% \end{Verbatim}
+% This is a probable future addition I'll make to the package.
+%
+% Oh, one last thing. These environments are defined to be ended by \cmd\ignorespacesafterend, which means that if they're used in a paragraph then the |\end{...}| command will gobble space after it. Let me know if this is a problem. It's kind of the way I like to do things but it might not fit everyone.
+%
+% \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:
+%
+% \begin{example}{}
+% \long\def\wrap#1{[#1]}
+% \newenvironment{test}{\Collect@Body\wrap}{}
+% \begin{test}
+%   hello
+%
+%   there
+% \end{test}
+% \end{example}
+%
+% And here's an example with environment arguments:
+%
+% \begin{example}{}
+% \long\def\wrap#1{[\arg#1]}
+% \def\arg#1{---#1---\par}
+% \newenvironment{test}{\Collect@Body\wrap}{}
+% \begin{test}{arg}
+%   hello
+%
+%   there
+% \end{test}
+% \end{example}
+%
+% \StopEventually{}
+%
+% \clearpage
+% \part{\pkg{\jobname} implementation}
+%\iffalse
+%<*package>
+%\fi
+%
+% This is the package.
+%    \begin{macrocode}
+\ProvidesPackage{environ}[2007/09/23 v0.1 A new environment syntax]
+%    \end{macrocode}
+%
+% \PrintChanges
+%
+% \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}%
+    \begingroup
+    \expandafter\let\csname\@currenvir\endcsname\collect@@body
+    \edef\process@envbody{\expandafter\noexpand\csname\@currenvir\endcsname}%
+    \process@envbody
+  }
+  \def\push@begins#1\begin#2{%
+    \ifx\end#2\else 
+      b\expandafter\push@begins
+    \fi}
+  \def\addto@envbody#1{%
+    \global\@envbody\expandafter{\the\@envbody#1}}
+  \def\collect@@body#1\end#2{%
+    \edef\begin@stack{%
+      \push@begins#1\begin\end \expandafter\@gobble\begin@stack}%
+    \ifx\@empty\begin@stack
+      \endgroup
+      \@checkend{#2}%
+      \addto@envbody{#1}%
+    \else
+      \addto@envbody{#1\end{#2}}%
+    \fi
+    \process@envbody}
+\fi
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\Collect@Body}
+% And now we define our own `long' version.
+%    \begin{macrocode}
+\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}%
+  \begingroup
+  \expandafter\let\csname\@currenvir\endcsname\Collect@@Body
+  \edef\process@envbody{\expandafter\noexpand\csname\@currenvir\endcsname}%
+  \process@envbody
+}
+\long\def\Push@Begins#1\begin#2{%
+  \ifx\end#2\else 
+    b\expandafter\Push@Begins
+  \fi}
+\long\def\Addto@Envbody#1{%
+  \global\@envbody\expandafter{\the\@envbody#1}}
+\long\def\Collect@@Body#1\end#2{%
+  \edef\begin@stack{%
+    \Push@Begins#1\begin\end\expandafter\@gobble\begin@stack}%
+  \ifx\@empty\begin@stack
+    \endgroup
+    \@checkend{#2}%
+    \Addto@Envbody{#1}%
+  \else
+    \Addto@Envbody{#1\end{#2}}%
+  \fi
+  \process@envbody}
+%    \end{macrocode}
+% \end{macro}
+%
+% \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}  
+  \expandafter\env@newcommand\csname env@@#1\endcsname[1]{%
+    \csname env@@@#1\endcsname{%
+      \csname env@args@\@currenvir\endcsname##1\unskip}}%
+%    \end{macrocode}
+% And then pass it all off to the environment macro (|#2|), 
+%    \begin{macrocode}  
+  \expandafter\env@newcommand\csname env@@@#1\endcsname[1]{#2}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\EnvironArgs}
+% \darg{Environment name}
+% \oarg{Number of arguments}
+% \oarg{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}
+% \end{macro}
+%
+%\iffalse
+%</package>
+%\fi
+%
+%
+%\iffalse
+%<*dtx-style>
+%    \begin{macrocode}
+\ProvidesPackage{dtx-style}
+
+\errorcontextlines=999
+
+\def\@dotsep{1000}
+\setcounter{tocdepth}{2}
+\setlength\columnseprule{0.1pt}
+\renewcommand\tableofcontents{\relax
+  \begin{multicols}{2}[\section*{\contentsname}]\small
+    \@starttoc{toc}\relax
+  \end{multicols}}
+
+\setcounter{IndexColumns}{2}
+\renewenvironment{theglossary}
+  {\small\list{}{}
+     \item\relax
+     \glossary@prologue\GlossaryParms 
+     \let\item\@idxitem \ignorespaces 
+     \def\pfill{\hspace*{\fill}}}
+  {\endlist}
+
+\usepackage{booktabs,calc,color,enumitem,fancyvrb,graphicx,ifthen,refstyle,subfig,varioref}
+\expandafter\usepackage\expandafter{\jobname}
+
+\usepackage{url}
+
+\usepackage[sc,osf]{mathpazo}
+
+\linespread{1.1}      % A bit more space between lines
+\frenchspacing         % Remove ugly extra space after punctuation
+  
+\definecolor{niceblue}{rgb}{0.2,0.4,0.8}
+\newenvironment{example}[1]
+  {\VerbatimEnvironment
+   \def\Options{#1}%
+   \begin{VerbatimOut}[gobble=2]{\examplefilename}}
+  {\end{VerbatimOut}\relax
+   \typesetexample}
+
+\fvset{formatcom=\color{niceblue}}
+\DefineShortVerb{\|}
+
+\def\theCodelineNo{\textcolor{niceblue}{\sffamily\tiny\arabic{CodelineNo}}}
+
+\let\examplesize\normalsize
+\let\auxwidth\relax
+
+\newlength\examplewidth\newlength\verbatimwidth
+\newlength\exoutdent   \newlength\exverbgap
+\setlength\exverbgap{1em}
+\setlength\exoutdent{-0.15\textwidth}
+\newsavebox\verbatimbox
+\edef\examplefilename{\jobname.example}
+
+\newcommand\typesetexample{\relax
+   \smallskip
+   \noindent
+   \begin{minipage}{\linewidth}
+   \color{niceblue}
+   \hrulefill\par
+   \edef\@tempa{[gobble=0,fontsize=\noexpand\small,\Options]}%
+   \begin{lrbox}{\verbatimbox}\relax
+     \expandafter\BVerbatimInput\@tempa{\examplefilename}%
+   \end{lrbox}
+   \begin{list}{}{\setlength\itemindent{0pt}
+                  \setlength\leftmargin\exoutdent
+                  \setlength\rightmargin{0pt}}\item
+   \ifx\auxwidth\relax
+     \setlength\verbatimwidth{\wd\verbatimbox}%
+   \else
+     \setlength\verbatimwidth{\auxwidth}%
+   \fi
+   \begin{minipage}[c]{\textwidth-\exoutdent-\verbatimwidth-\exverbgap}
+     \catcode`\%=14\centering\linespread{1.6}\input\examplefilename\relax
+   \end{minipage}\hfill
+   \begin{minipage}[c]{\verbatimwidth}
+     \usebox\verbatimbox
+   \end{minipage}
+   \end{list}
+   \par\noindent\hrulefill
+   \end{minipage}\par
+   \smallskip\noindent}
+
+\newcommand*\setverbwidth[1]{\def\auxwidth{#1}}
+
+\newcommand*\name[1]{{#1}}
+\newcommand*\pkg[1]{\textsf{#1}}
+\newcommand*\feat[1]{\texttt{#1}}
+\newcommand*\opt[1]{\texttt{#1}}
+
+\newcommand*\ltx[1]{%
+  \ifx3#1\relax
+    \textsc{ltx3}%
+  \else
+    \LaTeXe
+  \fi}
+
+\newcommand\note{\unskip\footnote}
+
+\let\latin\textit
+\def\eg{\latin{e.g.}}
+\def\Eg{\latin{E.g.}}
+\def\ie{\latin{i.e.}}
+\def\etc{\@ifnextchar.{\latin{etc}}{\latin{etc.}\@}}
+
+\def\STIX{\textsc{stix}}
+\def\MacOSX{Mac~OS~X}
+\def\ascii{\textsc{ascii}}
+\def\OMEGA{Omega}
+\def\CTAN{\textsc{ctan}}
+
+\newcounter{argument}
+\g@addto@macro\endmacro{\setcounter{argument}{0}}
+\newcommand*\darg[1]{%
+  \stepcounter{argument}%
+  {\ttfamily\char`\#\theargument~:~}#1\par\noindent\ignorespaces}
+\newcommand*\doarg[1]{%
+  \stepcounter{argument}%
+  {\ttfamily\makebox[0pt][r]{[}\char`\#\theargument]:~}#1\par\noindent\ignorespaces}
+
+\def\codeline{\par\hspace{\parindent}}% two \indents in total
+
+\newcommand\unichar[2]{\textsc{\MakeLowercase{u+#1: #2}}}
+
+\setlength\parindent{2em}
+
+%    \end{macrocode}
+%</dtx-style>
+%<*prepare>
+rm environ.zip
+latex environ.dtx
+mv README.txt README
+
+zip environ.zip environ.dtx environ.ins environ.pdf README
+%</prepare>
+%\fi
+%
+% \typeout{*************************************************************}
+% \typeout{*}
+% \typeout{* To finish the installation you have to move the following}
+% \typeout{* file into a directory searched by XeTeX:}
+% \typeout{*}
+% \typeout{* \space\space\space environ.sty}
+% \typeout{*}
+% \typeout{*************************************************************}
+%
+\endinput
diff --git a/Master/texmf-dist/source/latex/environ/environ.ins b/Master/texmf-dist/source/latex/environ/environ.ins
new file mode 100644
index 00000000000..644b366eee6
--- /dev/null
+++ b/Master/texmf-dist/source/latex/environ/environ.ins
@@ -0,0 +1,62 @@
+%%
+%% This is file `environ.ins',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% environ.dtx  (with options: `batchfile')
+%% 
+%%   __________________________________
+%%   Copyright (C) 2007  Will Robertson
+%% 
+%%   License information appended.
+%% 
+%% 
+\input docstrip.tex
+\keepsilent
+\preamble
+
+  __________________________________
+  Copyright (C) 2007  Will Robertson
+
+  License information appended.
+
+\endpreamble
+\postamble
+
+Copyright (C) 2007 by Will Robertson <wspr81@gmail.com>
+
+Distributable under the LaTeX Project Public License,
+version 1.3c or higher (your choice). The latest version of
+this license is at: http://www.latex-project.org/lppl.txt
+
+This work is "maintained" (as per LPPL maintenance status)
+by Will Robertson.
+
+This work consists of the file  environ.dtx
+          and the derived files environ.pdf,
+                                environ.sty, and
+                                environ.ins.
+
+\endpostamble
+\askforoverwritefalse
+\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
+\generate{\file{\jobname.cfg}{\from{\jobname.dtx}{defaults}}}
+\endbatchfile
+%% 
+%% Copyright (C) 2007 by Will Robertson <wspr81@gmail.com>
+%% 
+%% Distributable under the LaTeX Project Public License,
+%% version 1.3c or higher (your choice). The latest version of
+%% this license is at: http://www.latex-project.org/lppl.txt
+%% 
+%% This work is "maintained" (as per LPPL maintenance status)
+%% by Will Robertson.
+%% 
+%% This work consists of the file  environ.dtx
+%%           and the derived files environ.pdf,
+%%                                 environ.sty, and
+%%                                 environ.ins.
+%% 
+%%
+%% End of file `environ.ins'.