dowith (21may12)

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

3 files changed, 217 insertions, 66 deletions

diff --git a/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt b/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt
index 98d2b808e05..04dfe2f6d69 100644
--- a/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt
+++ b/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt
@@ -1,16 +1,16 @@
 
  *File List*
-  dowith.sty  2012/05/14  v0.21  simple list loop (UL)
-  dowith.tex  2012/05/18   --    documenting dowith.sty
+  dowith.sty  2012/05/19  v0.21a simple list loop (UL)
+  dowith.tex  2012/05/20   --    documenting dowith.sty
 fifinddo.sty  2012/01/20  v0.51  filtering TeX(t) files by TeX (UL)
  makedoc.sty  2011/11/19  v0.42  TeX input from *.sty (UL)
 niceverb.sty  2011/12/05  v0.44  minimize doc markup (UL)
  makedoc.cfg  2012/05/10   --    documentation settings
 mdoccorr.cfg  2011/12/03   --    makedoc local typographical corrections
-srcfiles.tex  2012/05/14   --    file infos -> SrcFILEs.txt
-  dowith.RLS  2012/05/18  v0.21  r0.21c @ fix, new doc., .RLS
+srcfiles.tex  2012/05/20   --    file infos -> SrcFILEs.txt
+  dowith.RLS  2012/05/20  r0.21d v0.21a discussing other cmds 
  ***********
 
- List made at 2012/05/18, 12:16
+ List made at 2012/05/20, 21:55
  from script file srcfiles.tex
 
diff --git a/Master/texmf-dist/source/generic/dowith/dowith.tex b/Master/texmf-dist/source/generic/dowith/dowith.tex
index 66b1dfca0ee..f3c173b5287 100644
--- a/Master/texmf-dist/source/generic/dowith/dowith.tex
+++ b/Master/texmf-dist/source/generic/dowith/dowith.tex
@@ -1,4 +1,4 @@
-\ProvidesFile{dowith.tex}[2012/05/18 documenting dowith.sty]
+\ProvidesFile{dowith.tex}[2012/05/20 documenting dowith.sty]
 \title{%%%\kern-\baselineskip
        \textsf{\huge dowith.sty}\\---\\Apply Command to
 %        Elements of Lists without Separators\,---\,%%% 2012/05/14
@@ -37,6 +37,7 @@
 \newcommand*{\codelb}{\code\codeLB}
 \newcommand*{\coderb}{\code\codeRB}
 \newcommand*{\codesp}{\code\codeSP}
+\newcommand*{\codebd}[1]{\code{\codeLB#1\codeRB}}       %% 2012/05/19
 %% rm. 2012/05/17b:
 % \DeclareRobustCommand*{\code}[1]{%
 %   \texttt{%
@@ -119,9 +120,6 @@ However, the package can also be used with other formats, just
 \begin{verbatim}
   \input dowith.sty
 \end{verbatim}
-The single commands that the package provides are described 
-\hyperref[sec:implement]{below}                             %% 2012/05/16
-together with their implementation.
 
 % \section{Example}
 
@@ -139,9 +137,17 @@ together with their implementation.
 % or by 
 % \[`\DoWithAllOf<cmd>{<arg-1><arg-2>\dots<arg-$n$>}'\]
 %
+%   \pagebreak                                                %% 2012/05/19
 \subsection{What It Does With What Lists}
 % \subsection{What It Actually Does \dots}
 \label{sec:lists-intuit}
+
+The single commands that the package provides are described 
+in the \hyperref[sec:implement]{implementation section} below. 
+What follows here is some general background about how the 
+commands work.
+%% <- moved down from previous section, mod. 2012/05/19
+
 The term \qtd{list} may refer to various things and need clarification here. 
 
 First of all, we are not referring to \LaTeX\ `list' environments 
@@ -243,7 +249,7 @@ What \TeX nically matters is
 what happens in ``\TeX's mouth,"\footnote{Cf.~\TTbp.~46.} 
 as some authors have suggested a metaphor,\footnote{%
     Alan Jeffrey: \tugbartref{tb11-2/tb28jeffrey}{``Lists in \TeX's Mouth,"} 
-    TUGboat Volume~11 No.~2 (1990), pp.~237--245), 
+    TUGboat Vol.~11 (1990), No.~2, pp.~237--245), 
     \urlhttpref{tug.org/TUGboat/tb11-2/tb28jeffrey.pdf}.}
 or somewhere deeper. 
 The 'dowith' package is a tool to control those events
@@ -532,6 +538,7 @@ three-item list of tokens, and a token cannot be a list of
 two or more tokens itself(\emph{!?}).
 
 \subsection{Another Notation and the Example's Steps}
+\label{sec:steps}                                           %% 2012/05/20
 \begin{smallpar}
 To write token lists easier and hopefully easier to read, 
 I would suggest writing \qtd{.<char>} for the character token 
@@ -554,9 +561,13 @@ In ``retrospect," the result of tokenizing \ref{eq:toks} should be
 \end{equation}
 and the intention is that it works like 
 \begin{equation}
-  \ntok{typein}.&a\,\ntok{typein}.&a\,\ntok{typein}\ntok{a}\,
+  \ntok{typein}.\codelb.&a.\coderb\,
+  \ntok{typein}.\codelb.&a.\coderb\,
+  \ntok{typein}.\codelb \ntok{a}.\coderb\,
   \ntok{typein}.\codelb.&a.\coderb
 \end{equation}
+(The definition of `\DoWith' in Section~\ref{sec:core} indeed adds surrounding braces, 
+ if missing.)
 However, \TeX\ rather tries to work with as few tokens ahead as possible.
 When it finds \ntok{DoWith} and the latter's meaning is the one intended 
 by 'dowith', it first looks for nothing more than the two arguments 
@@ -566,10 +577,10 @@ the token buffer's content will just be\footnote{If you use
     instead, the entire token sequence \ref{eq:retro} will appear in the 
     token buffer ``at once."}
 \begin{equation}
-  \ntok{typein}.&a\,\ntok{expandafter}\,\ntok{DoWith}\,
+  \ntok{typein}.\codelb.&a.\coderb\,\ntok{expandafter}\,\ntok{DoWith}\,
   \ntok{expandafter}\,\ntok{typein}\,\ntok{fi}
 \end{equation}
-Next $\ntok{typein}.&a$ is expanded according to the code for 
+Next $\ntok{typein}.\codelb.&a.\coderb$ is expanded according to the code for 
 `\typein' in \file{latex.ltx}. Some unexpandable tokens will emerge 
 and be moved into the ``command buffer," and you should get a screen
 message with `a' and a prompt. When you have entered something, 
@@ -673,6 +684,45 @@ and ends with a token from $\Chi_2$.\footnote{Again, this may be  more
     of a draft for a paper, or notes for it, than package documentation.}
 \end{smallpar}
 
+\subsection{Summary: ``Commands" Usable with 'dowith'}
+In the \hyperref[sec:apply]{implementation section,} 
+you learn about 
+\[`\DoWith<cmd>',\quad `\DoWithAllOf<cmd>',\quad 
+    \mbox{and}\quad  `\DoWithAllIn<cmd>'.\] 
+(\LaTeX\ users may type `{<cmd>}' instead.)
+What <cmd>s are allowed?
+
+\begin{enumerate}
+  \item All \strong{one-parameter macros} <cmd> work this way, 
+        unless there are programming mistakes outside 'dowith' 
+        (also thinking of arguments that take over control 
+         from 'dowith' commands before the argument list is finished). 
+  \item \strong{Other one-parameter} ``commands" <cmd> such as
+        \TeX\ \strong{primitives} may work---you must think of 
+        the fact that surrounding \emph{braces} are added.\footnote{TODO: 
+            in the future, variants not adding braces could be added.}
+        So the \strong{primitives} `\hbox' and `\vbox' work, 
+        for instance. `\show' is an example that doesn't work at all, 
+        it takes the single starting brace token and then confuses 
+        `\DoWith'.
+  \item Some <cmd>s taking \strong{no argument} may make sense, e.g., 
+        for getting 
+          \begin{enumerate}
+            \DoWithAllOf{\item}{{apples,}{pears,}{peaches}}
+          \end{enumerate}
+        from 
+        \begin{quote}
+          &\begin{enumerate}\\
+          \null\code{~~}&\DoWithAllOf{&\item}{%
+            \codebd{apples,}\codebd{pears,}\codebd{peaches}}\\
+          &\end{enumerate}
+        \end{quote}
+        Recall that `\item' at most takes an \emph{optional} argument.
+  \item <cmd> must \strong{not take more than one} parameter. 
+        %% see def. \DoWith
+        A different package will support multi-parameter macros.
+\end{enumerate}
+
 % Rather, ``list" is a term from \Wikienref{computer science} here. 
 % It corresponds to the notion of ``sequence" in mathematics 
 % and to ``word" with formal languages.
@@ -733,12 +783,12 @@ like the few that are here.\footnote{\ctanpkgref{arrayjobx}
 
 \subsection{Separators}                             %% add. heading 2012/05/17b
 Regarding \LaTeX\ macros in `latex.ltx', the basic macro `\DoWith' of 
-the present package resembles `\@tfor' very much, which likewise deals 
-with lists without separators. By contrast, \LaTeX's `\@for' deals with 
+the present package resembles |\@tfor| very much, which likewise deals 
+with lists without separators. By contrast, \LaTeX's |\@for| deals with 
 \emph{comma-separated} lists (such as lists of package options). 
 With comma-separated lists, a ``string" of characters counts as 
 an item when it is delimited by commas, or by a comma and the 
-list ``border", or spaces may be used as separators additionally. 
+list ``border," or spaces may be used as separators additionally. 
 However, when \LaTeX\ analyzes such lists (in ``\TeX's mouth"), 
 it uses representations by \emph{character tokens} of them.
 
@@ -756,18 +806,104 @@ complex mathematical expressions easily (using some assignments)
 as well as defining commands according to a pattern from a list.
 Those lists are comma-separated.
 
+\subsection{``For" Loops vs.\ ``Foreach" Loops}     %% mv. up 2012/05/20
+What about \ctanpkgref{forloop} (Nick Setzer), 
+\ctanpkgref{multido} (Timothy Van Zandt, Rolf Nie\-praksch, Herbert 
+Vo\ss), and \ctanpkgref{xfor} (Nicola Talbot)? 
+
+'xfor' is just a reimplementation of `\@for'. 
+'forloop' and 'multido' are more close to ``real \qtd{for} loops"
+(cf.\ \wikienref{for loop}{\meta{Wikipedia}}).
+Loops of the latter kind go through a certain set as well, 
+but such sets rather consist of \emph{numbers} and are exhausted 
+by incrementing (or also decrementing) variables 
+\wikienref{Loop counter}{(counters).}
+This is essentially not needed 
+(neither helpful)                                       %% 2012/05/20
+when a list literally is 
+\emph{enumerated}---such loops are distinguished as 
+\wikienref{Foreach loop}{``foreach loops."}             %% 2012/05/19
+
 \subsection{Iterators}                              %% add. heading 2012/05/17b
-A major difference between `\DoWith' and `\@tfor' is that the latter 
-uses a ``loop variable" or rather ``\Wikienref{iterator}" 
-to which the elements of the list are 
-assigned. `\DoWith<cmd>' does not use such a loop variable 
+So `\DoWith' and |\@tfor| rather provide ``foreach" loops. 
+A major difference between them is that the latter uses a 
+\wikienref{For loop}{``loop variable"} or 
+%%% rather                                              %% rm. 2012/05/20
+\wikienref{Iterator}{``iterator"} to which the elements 
+of the list are assigned. 
+`\DoWith<cmd>' does not use such a loop variable 
 or such assignments and thus is ``expandable" at least when <cmd> 
 (and the elements, depending on <cmd>) are expandable.
 On the other hand, `\@tfor' applies some procedure to the list 
 elements without needing a \emph{name} for the procedure 
 (or a \emph{macro} storing the procedure). 
+%
+I wondered whether behind \LaTeX's 
+`\@tfor' (and `\@for') there was an ``ideological" consideration 
+such as ``A loop must have a loop variable!"\pdots
+% However, avoiding usage of a macro name 
+% (to store the ``loop body" code)                        %% 2012/05/18
+% and a macro parameter 
+% (to incorporate the list item into the body code)       %% 2012/05/18
+% may have been a good reason.
+%% <- 2012/05/19
 
-``Expandability" is essential especially within \cs{write}. 
+%% 2012/05/20:
+Hopefully more clearly on ``loop variable" vs.\ our approach: 
+In order to run
+\[<code-before><item><code-after>\]
+on each <item> of a <list>, \emph{we here}
+% \[
+\begin{equation}
+  \mbox{define} \quad `\do' \quad \mbox{as} \quad 
+  `#1'\;\to\;`<code-before>#1<code-after>'
+\end{equation}
+% \]
+and then run `\do{<item>}' for each <item> in <list>,\footnote{Cf.~description 
+    of procedure in terms of tokens in Section~\ref{sec:steps}.} 
+\begin{equation}
+  \mbox{always replacing}\quad  `\do{<item>}'\quad \mbox{by}\quad  `\do{<item>}\do'. 
+\end{equation}
+(`\do' is only an example command that 'dowith' supports especially.)
+% The ``received" approach from ``usual" programming languages, 
+% \file{latex.ltx}, and its followers is
+In \file{latex.ltx} instead, we find things like
+% \[
+\begin{equation}
+  \label{eq:tfor}
+  `\@tfor\@tmp:=<list>\do{<code-before>\@tmp<code-after>}'
+\end{equation}
+% \]
+where `\@tmp' is a \emph{macro} that is set to be <item> at each 
+iteration of the loop, by 
+\begin{equation}
+  `\def\@tmp{<item>}'
+\end{equation}
+within `\@tforloop'. After that,
+\begin{equation}
+  \label{eq:code-tmp-code}
+  `<code-before>\@tmp<code-after>'
+\end{equation}
+from \ref{eq:tfor} is run.---\ref{eq:code-tmp-code} like 
+\ref{eq:tfor} is stored in a larger macro. `\do' in \ref{eq:tfor}
+does not act as a macro, it just delimits a macro parameter 
+in order give a feeling of some familiar programming structure. 
+This organisation of macros is fine when the loop body code 
+is only used by the containing macro, while the 'dowith' approach 
+to store the ``loop body" in an own macro has been useful when 
+the loop body code also is used for different purposes 
+or when it has been introduced before I thought of using it 
+in a loop.
+% \[\mbox{defining}\;`\@tmp'\;\mbox{as}\;<item>\quad \mbox{and run} \quad 
+%   `<code-before>\@tmp<code-after>'\]
+% for each <item> in <list>.
+
+Note that this only was an example. In general, <item> may appear 
+more than once in the ``loop body."
+
+``Expandability" by \emph{avoiding} something iterating `\def\@tmp{<item>}'
+and doing iteration in \TeX's mouth (`\do' or so must have been defined earlier)
+is essential especially within \cs{write}. 
 Assignments do not work there. A major motivation for developing 
 'dowith' developed with the \ctanpkgref{blog} package 
 that \cs{write}s \acro{HTML} code.
@@ -776,29 +912,6 @@ That place might be called the ``command buffer" to which
 the ``expansion processor" moves items from the incoming token buffer 
 that cannot be expanded (any more).
 
-\subsection{``For" Loops vs.\ ``Foreach" Loops}
-What about \ctanpkgref{forloop} (Nick Setzer), 
-\ctanpkgref{multido} (Timothy Van Zandt, Rolf Nie\-praksch, Herbert 
-Vo\ss), and \ctanpkgref{xfor} (Nicola Talbot)? 
-
-'xfor' is just a reimplementation of `\@for'. 
-'forloop' and 'multido' are more close to ``real \qtd{for} loops"
-(cf.\ \wikienref{for loop}{\meta{Wikipedia}}).
-Loops of the latter kind go through a certain set as well, 
-but such sets rather consist of \emph{numbers} and are exhausted 
-by incrementing (or also decrementing) variables (counters). 
-This is essentially not needed when a list literally is 
-\emph{enumerated}---such loops are distinguished as 
-``\wikienref{Foreach loop}{foreach loops}."             %% W -> w 2012/05/10
-I wondered whether behind \LaTeX's 
-`\@tfor' (and `\@for') there was an ``ideological" consideration 
-such as ``A loop must have a loop variable!" However, 
-avoiding usage of a macro name 
-(to store the ``loop body" code)                        %% 2012/05/18
-and a macro parameter 
-(to incorporate the list item into the body code)       %% 2012/05/18
-may have been a good reason.
-
 \subsection{Separator Macros}                       %% add. heading 2012/05/17b
 Commands like `\DoWith' also could save tokens thinking of list macros 
 (in \LaTeX/`latex.ltx') that use a \emph{separator macro} 
@@ -826,26 +939,36 @@ and then
 \subsection{Ye Olde \cs{loop}}                      %% add. heading 2012/05/17b
 %% added 2011/11/03:
 There also is |\loop<loop-body>\repeat| in Plain \TeX\ and a 
-refined version of it in `latex.ltx'. It is \emph{not} expandable 
+refined\footnote{Using Kabelschacht's suggestion, cf.\ Section~\ref{sec:kabel}} 
+version of it in `latex.ltx'. It is \emph{not} expandable 
 since it starts with an assignment for `\body' (Plain \TeX) or 
-`\iterate' (`latex.ltx'). As to the programming structure, 
-it is so simple and general that you cannot immediately see 
-what kind of loops it addresses. However, the applications 
-I have seen have been ``for" or (rather) ``while" loops. 
-``While" loops can ``emulate" ``for" and ``foreach" loops 
-by having the ``incrementation" method or the ``enumeration" method in 
-their body. This is quite obvious for ``for" loops, not quite so for 
-``foreach" loops; which for practical application (in my view) means 
-that neither \LaTeX/\TeX's `\loop' macro nor in general ``while" loops 
-is/are very helpful for implementing ``foreach" loops, 
-as rather `\DoWith' and similar constructions are.
-The reason for this is (as it seems to me) is that you 
-(a human being) can much more easily enumerate (``list") 
-the items of a list (you have in mind) than define the \emph{method} 
-that (allegedly) is behind your enumeration. \ \meta{Example:} 
-\[`\DoWithAllOf{\printsamplearea}{\red\green\blue}'\]
----\emph{how} (according to what ``method"?) did you ``proceed" from 
-`\red' to `\green' and from `\green' to `\blue'?
+`\iterate' (`latex.ltx'), 
+%% add. 2012/05/20:
+and then some assignments are needed to stop the loop, 
+such as incrementing or decrementing a \emph{counter.} 
+As to the programming structure, it is very simple and general, 
+I think any kind of loop can be implemented by this
+(apart from nested loops). E.g., I realize\footnote{2012-05-20}
+that even a ``foreach" loop could be implemented by managing 
+a list macro, e.g., using \LaTeX's internal `\@next'.
+%% rm. 2012/05/20:
+% that you cannot probably
+% what kind of loops it addresses. However, the applications 
+% I have seen have been ``for" or (rather) ``while" loops. 
+% ``While" loops can ``emulate" ``for" and ``foreach" loops 
+% by having the ``incrementation" method or the ``enumeration" method in 
+% their body. This is quite obvious for ``for" loops, not quite so for 
+% ``foreach" loops; which for practical application (in my view) means 
+% that neither \LaTeX/\TeX's `\loop' macro nor in general ``while" loops 
+% is/are very helpful for implementing ``foreach" loops, 
+% as rather `\DoWith' and similar constructions are.
+% The reason for this is (as it seems to me) is that you 
+% (a human being) can much more easily enumerate (``list") 
+% the items of a list (you have in mind) than define the \emph{method} 
+% that (allegedly) is behind your enumeration. \ \meta{Example:} 
+% \[`\DoWithAllOf{\printsamplearea}{\red\green\blue}'\]
+% ---\emph{how} (according to what ``method"?) did you ``proceed" from 
+% `\red' to `\green' and from `\green' to `\blue'?
 
 \subsection{Without Iterator and Separators}        %% add. heading 2012/05/17b
 %% 2011/11/07:
@@ -864,11 +987,33 @@ After the ``next" token is stored by the usual \cs{futurelet},
 the exception list is searched without using an iterator. 
 Addition and removal commands are provided as well. 
 
-  \pagebreak                                                %% 2012/05/17b
+%   \pagebreak                                                %% 2012/05/17b
+% \newpage                                                    %% 2012/05/19
 \section{Implementation}                                    %% 2012/05/10
 \label{sec:implement}
 \subsection{Package File Header (Legalese)}                 %% sub 2012/05/10
 \input{dowith.doc}
+
+\section{Ack.: 25 Years of Kabel\-schacht's Method}  %% 2012/05/20
+\label{sec:kabel}
+The essential idea of 'dowith' and `\DoWith' is 
+\[`\if<code>\expandafter<one-token>\fi'\]
+%     Alan Jeffrey: \tugbartref{tb11-2/tb28jeffrey}{``Lists in \TeX's Mouth,"} 
+%     TUGboat Vol.~11 (1990), No.~2, pp.~237--245), 
+%     \urlhttpref{tug.org/TUGboat/tb11-2/tb28jeffrey.pdf}.}
+It was described by \textsc{Alois Kabelschacht} as 
+\tugbartref{tb08-2/tb18kabel}{``&\expandafter\ vs. &\let\ and &\def\ 
+    in Conditionals and a Generalization of PLAIN's &\loop"}
+in TUGboat Vol.~8 (1987), No.~2, pp.~184f.\
+(a little more than one column).\foothttpurlref{tug.org/TUGboat/%
+    tb08-2/tb18kabel.pdf}
+See some German biographical notes on Kabelschacht in the 
+\wikideref{Benutzer:RolteVolte/Alois_Kabelschacht}{German Wikipedia.}\foothttpurlref{%% 
+    de.wikipedia.org/wiki/Benutzer:RolteVolte/Alois\string_Kabelschacht}
+It seems to me that Knuth didn't note this application of `\expandafter' 
+in \TTb. It was then applied in many macros of \file{latex.ltx}, 
+cf.~\file{source2e.pdf}.
+
 \end{document}
 
 VERSION HISTORY
@@ -892,3 +1037,8 @@ VERSION HISTORY
                         have been r0.21a; storing again, 
                         renaming dir.s ...
 2012/05/17bf.   r0.21c  reducing text ...
+2012/05/19      r0.21d  braces and commands applicable
+2012/05/20              corrections, clarifications, reorder; 
+                        especially examples for `dowith' vs. 
+                        `\@tfor'; remarks about `\loop' corr.:
+                        how to `foreach' ...; Kabelschacht
diff --git a/Master/texmf-dist/source/generic/dowith/srcfiles.tex b/Master/texmf-dist/source/generic/dowith/srcfiles.tex
index 6e2649ba5c6..182905e4c3f 100644
--- a/Master/texmf-dist/source/generic/dowith/srcfiles.tex
+++ b/Master/texmf-dist/source/generic/dowith/srcfiles.tex
@@ -1,5 +1,6 @@
-\ProvidesFile{srcfiles.tex}[2012/05/14 file infos -> SrcFILEs.txt]
-\RequirePackage{nicefilelist}
+\ProvidesFile{srcfiles.tex}[2012/05/20 file infos -> SrcFILEs.txt]
+\RequirePackage[r]{nicefilelist}[2012/05/20]
+%% <- [r] 2012/05/20
 \MFfieldtemplate{f-base}{dowithxx}
 \RequirePackage{myfilist}
 \EmptyFileList %%% [readprov.sty,myfilist.sty]