dowith (18may12)

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

3 files changed, 747 insertions, 45 deletions

diff --git a/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt b/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt
index 48f98f04414..98d2b808e05 100644
--- a/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt
+++ b/Master/texmf-dist/source/generic/dowith/SrcFILEs.txt
@@ -1,15 +1,16 @@
 
  *File List*
-  dowith.sty  2011/11/19  v0.2   simple list loop (UL)
-  dowith.tex  2012/05/10   --    documenting dowith.sty
+  dowith.sty  2012/05/14  v0.21  simple list loop (UL)
+  dowith.tex  2012/05/18   --    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/12/10   --    file infos -> SrcFILEs.txt
+srcfiles.tex  2012/05/14   --    file infos -> SrcFILEs.txt
+  dowith.RLS  2012/05/18  v0.21  r0.21c @ fix, new doc., .RLS
  ***********
 
- List made at 2012/05/10, 11:48
+ List made at 2012/05/18, 12:16
  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 de7b4c5aa7f..66b1dfca0ee 100644
--- a/Master/texmf-dist/source/generic/dowith/dowith.tex
+++ b/Master/texmf-dist/source/generic/dowith/dowith.tex
@@ -1,8 +1,10 @@
-\ProvidesFile{dowith.tex}[2012/05/10 documenting dowith.sty]
-\title{\kern-\baselineskip
-       \textsf{\huge dowith.sty}\\---\\Apply Command 
-       to Elements of Lists without Separators\,---\,
-       and without Iterator\thanks{This
+\ProvidesFile{dowith.tex}[2012/05/18 documenting dowith.sty]
+\title{%%%\kern-\baselineskip
+       \textsf{\huge dowith.sty}\\---\\Apply Command to
+%        Elements of Lists without Separators\,---\,%%% 2012/05/14
+%        and without Iterator\thanks{This
+       %% 2012/05/15, "in" 2012/05/18:
+       Each Item \\ in a List of Arguments in ``\TeX's Mouth"\thanks{This
        document describes version
        \textcolor{blue}{\UseVersionOf{\jobname.sty}}
        of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
@@ -13,27 +15,84 @@
   {\SectionLevelTwoParseInput}  }
 \documentclass[fleqn]{article}%% TODO paper dimensions!?
 \input{makedoc.cfg}    %% shared formatting settings
-\ReadPackageInfos{dowith}
-% \usepackage{dowith}
+% \ReadPackageInfos{dowith}
+\usepackage{dowith}                                         %% 2012/05/17b
 \sloppy
-\MDkeywords{macro programming, loops, list macros}
+\MDkeywords{programming structures;                         %% 2012/05/14b
+            macro programming, loops, list macros}
 \hypersetup{%
     pdftitle=dowith.sty handles lists without separators,
     pdfsubject=documenting dowith.sty
-}%% /2011/08/22
+}%% 2011/08/22 
+\usepackage{fixltx2e}                       %% \textsubscript 2012/05/17b
+\makeatletter                                   %% etc. 2012/05/17b
+  \newcommand*{\GetOtherChar}[2]{% 
+    \@ifdefinable#1{%
+        \edef#1{\expandafter\@gobble\string#2}}}
+\makeatother
+\GetOtherChar\codeLB\{ 
+\GetOtherChar\codeRB\} 
+% \GetOtherChar\codeSP\ %       %% ???
+{\MakeOther\ \xdef\codeSP{ }}
+\newcommand*{\codelb}{\code\codeLB}
+\newcommand*{\coderb}{\code\codeRB}
+\newcommand*{\codesp}{\code\codeSP}
+%% rm. 2012/05/17b:
+% \DeclareRobustCommand*{\code}[1]{%
+%   \texttt{%
+%     \let\{\codeLB \let\}\codeRB \let\ \codeSP
+%     #1}}
+% \newcommand*{\chtok}[2]{\ensuremath{\code{#1}\sb{#2}}}
+%% <- 2012/05/17b ->
+\newcommand*{\chtok}[2]{\code{#1}\textsubscript{#2}} 
+\newcommand*{\lbtok}{\chtok\codeLB{1}}
+\newcommand*{\rbtok}{\chtok\codeRB{2}}
+\newcommand*{\lttok}[1]{\chtok{#1}{11}}
+\newcommand*{\sptok}{\chtok\codeSP{10}}
+\providecommand*{\TTb}{\meta{The\nolinebreak[3] \TeX book}}
+\providecommand*{\TTbp}{\TTb\nolinebreak[3] p}
+\newenvironment*{smallpar}
+                {\medskip\par\begingroup\footnotesize}
+                {\par\endgroup\medskip}
+\newcommand*{\NTOK}[1]{\textsf{ntok}(\code{#1})}
+\newcommand*{\ntok}[1]{\textrm{?}\code{#1}}
+\newenvironment*{example}[1]
+                {\trivlist\item
+                 (\ulroman{#1})}
+                {\endtrivlist}
+\providecommand*{\ulroman}[1]{\meta{\romannumeral #1 }}
+\newcommand*{\inlineitem}[1]{\ (\ulroman{#1})\enspace
+             \ignorespaces}
+\newcommand*{\pdots}{~.\kern\fontdimen3\font
+                      .\kern\fontdimen3\font. }
+\providecommand*{\Chi}{\mathrm{X}}
 \begin{document}
 \maketitle
 \begin{MDabstract}\noindent
-This package provides macros for applying a command 
-to all elements of a list without separators, such as 
-`\DoWithAllIn{<cmd>}{<list-macro>}', and also for extending 
-and reducing macros storing such lists. Applications in mind belonged 
-to \LaTeX, but the package should work with other formats as well.
+This package provides macros for applying a 
+%% mod. 2012/05/15:
+% ``command" <cmd> to all items of a list $<arg-1><arg-2>\dots<arg-$n$>$
+``command" to all items in a ``list of possible macro arguments," %% v0.21a
+% in ``\TeX's mouth," 
+% such as `\DoWithAllIn{<cmd>}{<list-macro>}', 
+and also for extending and reducing macros storing such lists.
+``Brace groups" are single items of such lists, as opposed to 
+ token lists. 
+ %%% ---pleading for mathematical rigour in \TeX ology!)    %% rm. 2012/05/17b
+Applications in mind belonged to \LaTeX, but the package should work 
+with other formats as well.
 Loop and list macros in other packages are discussed.
-%% 2012/05/09:
-There is an emphasis on expandability 
-(no \Wikienref{iterator}),                                  %% 2012/05/10
-without relying on \CtanPkgRef{e-tex}{$\varepsilon$-\TeX}.
+% %% 2012/05/09:
+% There is an emphasis on expandability 
+% %% mod./add. 2012/05/15:
+% (no \wikienref{Iterator}{iterator;} 
+%  essential within \cs{write} as with \CtanPkgRef{morehype}{blog.sty}),
+% without relying on \CtanPkgRef{e-tex}{$\varepsilon$-\TeX}.
+%% 2012/05/18:
+Iteration is implemented within ``\TeX's mouth," so works within 
+`\write' as with \CtanPkgRef{morehype}{blog.sty}. There is no need for 
+\CtanPkgRef{e-tex}{$\varepsilon$-\TeX}.
+
 \MDaddtoabstract{Related packages}
 \pkg{etextools}, \pkg{etoolbox}, \pkg{forarray}, 
 \pkg{forloop}, \pkg{multido}, \pkg{moredefs}, \pkg{lmake}, 
@@ -42,10 +101,9 @@ without relying on \CtanPkgRef{e-tex}{$\varepsilon$-\TeX}.
 \tableofcontents
 
 %   \newpage
-% \section{Features and Usage}
-\section{Usage}
+\section{Usage and Features}                    %% restructured 2012/05/16
 
-% \subsection{Installing and Calling}
+\subsection{Installing and Calling}
 The file 'dowith.sty' is provided ready, installation only requires
 putting it somewhere where \TeX\ finds it
 (which may need updating the filename data
@@ -61,13 +119,606 @@ 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 below 
+The single commands that the package provides are described 
+\hyperref[sec:implement]{below}                             %% 2012/05/16
 together with their implementation.
 
 % \section{Example}
 
+% \section{Discussion}                                      %% 2012/05/16
+% \subsection{What It Seems to Do \dots}
+% The 'dowith' package provides tools to simplify \TeX\ macro programming. 
+% Understanding it \emph{really} may require understanding certain passages of 
+% \TTb, such as pp.~38f. It may even require overcoming 
+% terrible confusions in \TTb.
+% Let this be a last try at understanding the package without understanding \TeX: 
+% It allows you to abbreviate 
+% \[<cmd><arg-1><cmd><arg-2>\dots<cmd><arg-$n$>\]
+% by 
+% \[`\DoWith<cmd><arg-1><arg-2>\dots<arg-$n$>\StopDoing'\]
+% or by 
+% \[`\DoWithAllOf<cmd>{<arg-1><arg-2>\dots<arg-$n$>}'\]
+%
+\subsection{What It Does With What Lists}
+% \subsection{What It Actually Does \dots}
+\label{sec:lists-intuit}
+The term \qtd{list} may refer to various things and need clarification here. 
+
+First of all, we are not referring to \LaTeX\ `list' environments 
+such as `enumerate' or `itemize'; 
+neither to ``\acro{TODO}" lists of what needs to be done soon. 
+
+Rather, 'dowith' allows you to abbreviate 
+\[<cmd><arg-1><cmd><arg-2>\dots<cmd><arg-$n$>\]
+by 
+\[`\DoWith<cmd><arg-1><arg-2>'\dots<arg-$n$>`\StopDoing'\]
+or by 
+\[`\DoWithAllOf<cmd>{<arg-1><arg-2>'\dots<arg-$n$>`}'\]
+With small $n$, one may doubt whether this really is an abbreviation~\dots;
+anyway, 
+\[<arg-1><arg-2>\dots<arg-$n$>\]
+was an attempt to refer to the kind of lists we are dealing with. 
+\[<arg-1>, <art-2>, \dots, <arg-$n$>\]
+are the ``items" of the list. 
+The question is: what counts as an item?
+
+We might say that `aa' is a list of \emph{two} items, 
+<arg-1> being `a' and <arg-2> being `a', too.
+
+When we do \emph{three} keystrokes to get `a a' instead of `aa', 
+we still have \emph{two} items, 
+<arg-1> being `a' and <arg-2> being `a' too. 
+Strange, isn't it?
+
+Also, when in `aa' we replace the first `a' by a backslash, `\', 
+we get `\a', and this is a list of a \emph{single} item, 
+$<arg-1>=`\a'$~\dots
+
+You shouldn't believe these stories of mine entirely. 
+What I am alluding to is that the \emph{``items"} 'dowith' is about 
+are determined in terms of \emph{\TeX's tokens}, and the relation 
+between the ``characters you type" and \emph{\TeX's tokens} 
+is not entirely straightforward. 
+
+\subsection{The Notion of Arglists for \LaTeX\ Users}
+%% <- 2012/05/17b ->
+% \subsection{The Notion of Arglist}
+\label{sec:arglists-intuit}
+Still, it may suffice to clarify what counts as an <arg-$i$> 
+without speaking of \emph{tokens} explicitly: It is simply 
+what a \emph{one-parameter macro} 
+(where the parameter is \emph{not delimited} in terms of 
+ \TTbp p.~203f.)
+can take as an \emph{argument.}
+
+The lists 'dowith' is about then are lists \emph{of possible arguments}
+in the previous sense---let me call them \emph{``arglists."}\footnote{Not 
+    to be confused with German \httpref{de.wiktionary.org/wiki/Arglist}{Arglist.}}
+The single \emph{items} of such lists are those single possible arguments. 
+They become \emph{actual} arguments beginning from the leftmost \emph{possible} one 
+when 'dowith' presents them to that <cmd> mentioned earlier---where 
+<cmd> \emph{should} be a one-parameter macro (or some \TeX\ primitive 
+parsing arguments similarly).
+
+The reader perhaps has an \emph{intuitive} understanding of 
+what can be an argument of a one-parameter macro. 
+A \emph{strict \LaTeX} user may think that such an argument <arg-$i$>
+just has form `{'<ark-$i$>`}', i.e., $<arg-$i$>=`{'<ark-$i$>`}'$
+for some <ark-$i$>. Such arguments are also called \emph{``brace groups".}
+(\LaTeX's \emph{optional} arguments `[<extra>]' 
+ do not count as possible arguments here, they are not macro arguments 
+ in the sense of \TTb.)
+In this restricted \LaTeX\ sense, arglists consist of brace groups 
+\[`{<ark-1>}{<ark-2>}'\dots`{'<ark-$n$>`}',\]
+and each single brace group is an \emph{item} of it. 
+
+The \emph{\TeX\ macro writer}, by contrast, knows that a macro argument 
+doesn't need outer braces. In an intuitive sense, a single 
+``command" can be a macro argument, too. ``Command" may be understood 
+as ``control sequence" (starting with a backslash), 
+but some authors also have considered single \emph{characters} 
+(character \emph{tokens}?) ``commands." Blank spaces, by contrast, 
+are ignored when a macro looks for its argument.    %% 2012/05/17b
+
+%% useless, just name items 2012/05/17b:
+% We arrive at an ``intuitive recursive definition" of ``arglist:" \
+% (\meta{i})\enspace The empty list is an arglist; it doesn't have an item 
+% for 'dowith'. \ (\meta{ii})\enspace If <list> is an arglist, then 
+% (a)~`{<ark>}<list>' is an arglist whose first item for 'dowith' is `{<ark>}';
+% (b)~`<cs><list>' with a ``control sequence" <cs>
+%     is an arglist whose first item is `<cs>' 
+%     (for the command <cmd> to which 'dowith' presents <cs>); and
+% (c)~`<char><list>' with a non-blank character <char>
+%     is an arglist whose first item is `<char>'. \
+% (\meta{iii})\enspace Nothing else is an arglist.
+% 
+% But keep in mind that this ``intuitive" understanding essentially is wrong.
+
+\subsection{\TeX's Tokens}
+\label{sec:toks}
+
+% The \emph{\TeX\ macro writer} understanding \TeX\ properly 
+% does not really think of arglists. \TeX perts instead think of 
+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), 
+    \urlhttpref{tug.org/TUGboat/tb11-2/tb28jeffrey.pdf}.}
+or somewhere deeper. 
+The 'dowith' package is a tool to control those events
+(and actually, it is confined to \TeX's mouth). 
+
+\begin{smallpar}
+The ``characters you type" are somewhere in front of ``\TeX's mouth", 
+while \emph{in} \TeX's mouth, there are \emph{tokens}. 
+Before \TeX\ \emph{swallows} them, it often manipulates them 
+in some ways, after they got \emph{into} its mouth.
+
+More formally, \TeX\ has a \emph{character buffer.}
+It forms a single token from an initial segment of the buffer content---unless 
+there is a special situation with blank spaces or something pathological.
+When an \emph{escape character}, as the backslash usually is one, 
+has been noticed recently (that isn't followed by another one immediately), 
+the character buffer may need to be feeded from more outside, 
+until it contains enough material to form a token from. 
+The character(s) \emph{after} the escape character until 
+some delimiting character form a \emph{string} that is the 
+\emph{name} of the token that is formed.
+What has been used to form a token is removed from the character buffer.
+
+There are \emph{two kinds of tokens} here: \emph{named} tokens 
+and \emph{character} tokens. ``Named" tokens usually are referred
+to as ``control sequence tokens" or just ``control sequences"---I~really 
+want to avoid those horrible confusions from \TTb.
+There never are any ``parameter tokens" in \TeX's mouth 
+(perhaps unless one considers a one-step macro expansion 
+ a two-or-more-step procedure).
+
+For every \emph{string of characters}, there is exactly one 
+(possible) \emph{named token} whose name the string is.\footnote{``Possible" 
+    refers to the fact that \TeX\ does not store named tokens anywhere 
+    before they appear in its mouth, maybe apart from ``primitive" 
+    tokens that have a ``pre-assigned meaning" when a \TeX run 
+    starts.---What is more bad with my claim is that 
+    the \TeX\ program by design cannot extend its memory arbitrarily---even 
+    not using the ``cloud''---, so it doesn't support tokens 
+    whose name lengths are above a certain limit.}
+It is so common (starting from \TTb) to denote the token whose name 
+is <string> by \lq\verb+\+<string>\rq. For instance, the token whose 
+name is `input' is denoted by \qtd{&\input}. On the other hand, 
+on page~7 of \TTb\ \qtd{&\input} is a ``string of characters."
+With this notation, it is already difficult to explain what 
+the \LaTeX\ command `\DeclareRobustCommand' does or what the difference 
+between a starred \LaTeX\ command and a starred \LaTeX\ environment is.\footnote{%
+    A reader knowing \LaTeX\ only thinks that \qtd{\code{&\\\codesp}} 
+    is the result of typing a double backslash and a space 
+    and that \qtd{\cs{equation*}} is the ``command" \cs{equation} 
+    followed by a `*'.} 
+\TTb\ makes it worse by saying on page~39: 
+\meta{``A control sequence is considered to be a single object 
+        that is no longer composed of a sequence of symbols."}
+So ``it depends" whether \qtd{&\input} is a string of characters or not---it \emph{is 
+before} tokenization, but \emph{no longer} afterwards. 
+So if you have two computers and start a \TeX\ run on each of them 
+with a little difference in time, there will be a moment where 
+\qtd{&\input} is a string on the one computer but not on the other? 
+This is like saying \meta{``When we apply the square root function to 
+the number 4, the number 4 will no longer be the number 4, 
+it will be the number 2 instead."}
+\end{smallpar}
+
+\TTb\ does offer an alternative notation for named tokens: ``boxing;" 
+so the token whose name is `input' can be denoted by the rather 
+``graphical" notation \qtd{|input|} (used only exceptionally).\footnote{%
+    The box notation is introduced on page~38 without explanation, 
+    as if it explained something.} 
+\emph{I}~would suggest something like 
+\qtd{\NTOK{input}} for clarity and \qtd{\ntok{input}} 
+for brevity.\footnote{I am suggesting the question mark for named tokens 
+ since \TeX\ ``must look up the current definition" of a named token 
+ according to \TTbp.~39, while the meaning of character tokens rather 
+ is ``fixed," at least according to \TTbp.~39. However, 
+    \emph{active}-character such as .&~ are in the same situation 
+    as named tokens as to this respect. The dot notation may be fine for them, 
+    though.}
+
+\begin{smallpar}
+\emph{Character tokens} get into \TeX's mouth by tokenization 
+when characters begin the buffer content while \emph{not} scanning 
+a name for a named token. A single character then is removed from the 
+character buffer, and a token storing its character code and current 
+category code is pushed into \TeX's mouth.
+
+Named tokens may get into \TeX's mouth by ``tokenization" as described above, 
+i.e., they are drawn from the character buffer. But they also can 
+appear in \TeX's mouth ``from within," 
+by the manipulation inside \TeX's mouth. 
+
+More formally, those manipulations are called ``expansion,"
+and \TeX's mouth can be conceived of as a \emph{token buffer} 
+that is feeded to the right (or end) by tokenization from the character buffer. 
+Expansion means that certain tokens in the token buffer are substituted 
+by other ones. This way tokens may get into \TeX's mouth that 
+emerged from tokenization a ``long time ago", maybe in a previous 
+run that created the \emph{format} (\TeX's variant \code{INITEX}); 
+or tokens may appear by some hardwired expansion function. 
+
+However, \emph{named tokens} may get into \TeX's mouth 
+also by \emph{expansion}, never having been drawn by tokenization 
+and not being hardwired. This happens by the `\csname' name construct. 
+The input \emph{code} may contain 
+\[`\csname tupni\endcsname'\]
+This may be converted into 7 tokens entering \TeX's mouth, 
+the first one being \NTOK{csname}, the last one 
+\NTOK{endcsname}, and five character tokens in between. 
+Due to some \emph{function} (which I would denote as *\code{csname})
+originally associated with the token \NTOK{csname}, 
+those seven tokens then are replaced by \NTOK{tupni}, 
+the named token whose name is `tupni'. It is not required that 
+the \TeX\ program knows about a token \NTOK{tupni}, 
+neither anybody must type \qtd{&\tupni} in any file.\footnote{These 
+    considerations may not be essential here, 
+    rather a draft for a paper. Using 'dowith', 
+    one better just thinks of the arglist items one actually lists.}
+\end{smallpar}
+
+\subsection{Arglists vs.\ Lists of Tokens---Example}
+% \subsection{Arglists and 'dowith' \TeX nically}
+% In the \TeX nical sense, I think of arglists \emph{and their items}
+% as follows. Arglists are lists (or sequences) of tokens. 
+% What is somewhat difficult is that the \emph{items} of a token list 
+% usually are \emph{tokens.} Especially, the curly braces in the code 
+% you type usually are converted into certain \emph{character tokens}
+% that are single items of the resulting token list.\footnote{I discover 
+%     this conceptual puzzle 2012-05-16.} 
+% 
+% The conceptual trap here may have resulted from denoting lists 
+% in a \emph{\Wikienref{juxtaposition}} notation. 
+% In Section~\ref{sec:lists-intuit}, I have written `aa' for a 
+% ``list" of \emph{two} items. ``List" is rather a \emph{computer science} 
+% term, its mathematical counterpart rather is the notion of (finite) 
+% \emph{sequences.} The usual \emph{mathematical} notation for a finite sequence 
+% writes list items surrounded by \emph{\wikienref{bracket}{brackets}}
+% (round---\emph{\Wikienref{parentheses}}---seems to be more common than square, 
+%  also \wikienref{angle brackets}{chevrons} are used).
+% 
+% So the \emph{string} `aa' can be written more clearly---mathematically---as 
+% $(`a',`a')$. The trap with `\a' is that it could be \emph{either} the \emph{string} 
+% $(`\',`a')$ \emph{or} the one-item list $(`\a')$ of strings. 
+% But even in the latter case, I urge not to consider it a \emph{\TeX\ token}. 
+% Rather, I consider `\a' a mistaken way of referring to the 
+% named token \NTOK{a} whose name is the string `a' (or $(`a')$).
+% (Section~\ref{sec:toks}). 
+% 
+% However, the conceptual trap about arglists and token lists 
+% (there must have been some ``Arglist"!\@) lurks on another level, 
+% as follows. Recall \TTb's notation of \chtok{<char>}{<cat>}
+% for the \emph{character token} that \TeX's tokenizer forms 
+% from <char> in the character buffer when <char>'s category code is <cat>.
+% Usually, the \emph{character} `a' is converted into the 
+% \emph{character token} \lttok{a}, `{' is converted into \lbtok, 
+% and `}' is converted into \rbtok. 
+% 
+% We are turning to some \strong{examples} and \strong{counterexamples}. 
+% Let us see what confusions occurred in the ``intuitive" view on 
+% arglists in Section~\ref{sec:arglists-intuit}.
+% 
+% % \begin{example}{1} It 
+% First, it was bad in Section~\ref{sec:arglists-intuit}
+% to think that `aa' is a two-item arglist. It was confused with something 
+% like $\lttok{a}\lttok{a}$. The latter looks like a token list---or is it an arglist? 
+% Both? Anyway, it is juxtaposition notation applied to tokens, 
+% mathematically it is $(\lttok{a},\lttok{a})$, so~\dots
+% % \end{example}
+% 
+% Now let us reconsider the ``intuitive recursive definition" of arglist. 
+% Or let us look at a recursive definition of \emph{token} list.
+% \inlineitem{1} There is nothing wrong with saying the the empty list is 
+% a token list, the same holds for arglists. 
+% \inlineitem{2} a.~When we attach an arbitrary token to a \emph{token} list 
+% (at the left), the result is another token list---fine. 
+% There are only certain difficulties with ``handling" special token lists 
+% such as $\lbtok\lttok{a} = (\lbtok,\lttok{a})$. 
+% And the latter is \emph{not} an \emph{arglist!} \
+% b.~When we attach a \emph{named} token to an arglist (at the left), 
+% the result \emph{is} an \emph{arglist}.\footnote{This is 
+%     a \emph{conjecture} only right now---2012-05-16---in which I strongly believe. 
+%     Likewise later.} 
+% c.~When we attach a \emph{letter} token \lttok{<char>} to an arglist 
+% (at the left), the result \emph{is} an \emph{arglist}.
+% d.~When we talked about ``brace groups," they seemed to be \emph{strings} 
+% of characters. Instead, I would like to suggest that a brace group 
+% is an \emph{arglist}\pdots
+% When \lbtok\ is attached to the left of an arglist and \rbtok\ to the right, 
+% the result is an arglist---this is what I would call a ``brace group"!
+% e.~The \Wikienref{concatenation} of two arglists is an arglist. 
+% 
+% \begin{smallpar}
+% The above notion of ``attaching" a token to a token list or an arglist 
+% % should be clarified, but instead of a general definition in terms of 
+% % ``words" of formal languages, examples may suffice here and now.\footnote{2012-05-16.}
+% should be clarified. Attaching an item $j$ at the left of a list $\lambda$ 
+% is the same as concatenating the one-item list $(j)$ with $\lambda$\pdots 
+% but the English \wikienref{append}{Wikipedia} seems to explain concatenation by 
+% \emph{appending}. As we \emph{remove} items one-by-one from the \emph{left} 
+% (beginning) of a list, I prefer the inverse \emph{prepending} items as basic operation 
+% for building lists---cf.\ \Wikienref{CAR and CDR}.
+% \end{smallpar}
+% 
+% We won't complete a formal (recursive) definition of arglist here and 
+% now.\footnote{2012-05-16.} Just observe that ``brace groups" 
+% make the difference between token lists and arglists. 
+% Recall that an ``item" of an arglist ``operationally" is defined 
+% as something that a one-parameter macro removes. 
+% Such a macro removes certain single tokens 
+% (space tokens not among them)---and entire ``brace groups"! 
+% Especially, consider \[\lbtok\rbtok\]%%%.
+% Actually, this is another ambiguous notation. 
+% If it refers to $(\lbtok,\rbtok)$, it is a \emph{token} list, 
+% not an arglist. If it refers to $(\lbtok\rbtok)$---it should 
+% better refer to $((\lbtok,\rbtok))$, which is a 
+% \emph{one-item arglist} whose only item is the former two-item token list!
+% 
+%% <- 2012/05/17b ->
+Let us reconsider the examples from Sections~\ref{sec:lists-intuit}
+and~\ref{sec:arglists-intuit}, and pack them into a single example. 
+If you type a file line
+\begin{equation}
+  `a a\a{a}'
+\end{equation}
+(\emph{eight} keystrokes),
+it should usually be converted into this \emph{seven}-item list 
+of (five) tokens:
+\begin{equation}
+  \label{eq:toks}
+  \lttok{a}\;\sptok\;\lttok{a}\;\NTOK{a}\;\lbtok\;\lttok{a}\;\rbtok
+\end{equation}
+---with notation from Section~\ref{sec:toks} and
+\TTb's notation \chtok{<char>}{<cat>} 
+for the \emph{character token} that \TeX's tokenizer forms 
+from <char> in the character buffer when <char>'s category code is <cat>.
+
+It turns out that the token list in \ref{eq:toks} 
+provides an arglist of \emph{four} items: The token \lttok{a}
+at the first and third place, the named token \NTOK{a}, and the entire 
+token list $\lbtok\lttok{a}\rbtok$ as a single item---a ``brace group."
+The space token is ignored.\footnote{\TTbp.~201: ``\TeX\ doesn't use 
+single spaces as undelimited arguments."}
+
+You can try this after `\renewcommand{\a}{A}'\footnote{Otherwise 
+    \cs{a} is a one-parameter macro that breaks 'dowith''s control.}
+with 'dowith':
+\begin{equation}
+  \label{eq:sample-code}
+  `\DoWith\typein a a\a{a}\StopDoing'
+\end{equation}
+Then \LaTeX\ shows `a', `a', `A' from `\a', and another `a' from within 
+the braces---`\typein' (as any macro with arguments) removes them.
+
+% \show\a
+% \a{a}
+\renewcommand*{\a}{A}
+% {\MakeNormalHere\# \newcommand*{\TypeOut}[1]{\typein{#1}}
+%  \global\let\TypeOut\TypeOut}
+% \let\TypeOut\typein
+% \let\TypeOut\typeout
+% \DoWith\TypeOut a a\a{a}\StopDoing
+% \DoWith\typein a a\a{a}\StopDoing
+% { %%% \tracingmacros=1 \tracingonline=1
+%  \MakeNormalHere\# \AssignCatCodeTo{2}\]
+%  \DoWith\typein #a\a{a]\StopDoing}
+
+I have avoided saying \ref{eq:toks} \emph{were} an arglist of 4 items. 
+The mathematical basic way of writing lists---understood as finite
+\emph{\wikienref{sequence}{sequences}}---as ``commma-separated lists" 
+within \wikienref{bracket}{brackets} may clarify the difference 
+(that the \Wikienref{juxtaposition} notation tends to conceal). 
+The \emph{token} list is 
+\begin{equation}
+  \label{eq:toks,}
+  (\lttok{a}, \sptok, \lttok{a}, \NTOK{a}, \lbtok, \lttok{a}, \rbtok)
+\end{equation}
+while the list of macro arguments is
+\begin{equation}
+  \label{eq:args}
+  (\lttok{a}, \lttok{a}, \NTOK{a}, (\lbtok, \lttok{a}, \rbtok)).
+\end{equation}
+\ref{eq:toks} or \ref{eq:toks,} simply is \emph{not} an arglist 
+(since neither \lbtok\ nor \rbtok\ can be a macro argument), 
+and the arglist \ref{eq:args} ``provided" by the list of tokens 
+is \emph{not} a list of \emph{tokens}---its final item is a 
+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}
+\begin{smallpar}
+To write token lists easier and hopefully easier to read, 
+I would suggest writing \qtd{.<char>} for the character token 
+that the tokenizer ``usually" forms from character <char>, i.e., 
+adding the \emph{standard} category code as in \TTb\ (page~37).
+Then \ref{eq:toks} would read\footnote{See Section~\ref{sec:toks} for the question mark.}
+\begin{equation}
+  .&a\,.\codesp\,.&a\,\ntok{a}\,.\codelb\,.&a\,.\coderb
+\end{equation}
+and the corresponding arglist is
+\begin{equation}
+  (.&a,.&a,\ntok{a},(.\codelb\,.&a\,.\coderb))
+\end{equation}
+In ``retrospect," the result of tokenizing \ref{eq:toks} should be
+\begin{equation}
+  \label{eq:retro}
+  \ntok{DoWith}\,\ntok{typein}\,
+  .&a\,.\codesp\,.&a\,\ntok{a}\,.\codelb\,.&a\,.\coderb\,
+  \ntok{StopDoing}
+\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
+\end{equation}
+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 
+required by our definition of `\DoWith'. A few moments later, 
+the token buffer's content will just be\footnote{If you use 
+    \cs{DoWithAllOf&\typein\codeLB a\codeSP a&\a\codeLB a\codeRB\codeRB} 
+    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{expandafter}\,\ntok{typein}\,\ntok{fi}
+\end{equation}
+Next $\ntok{typein}.&a$ 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, 
+the remaining \ntok{expandafter} tokens and the \ntok{fi} will be 
+removed from the character buffer, and it contains only
+\begin{equation}
+  \ntok{DoWith}\,\ntok{typein}
+\end{equation}
+Another token is ordered from the tokenizer to provide a second 
+argument for expanding \ntok{DoWith}. The token .\codesp\ comes in, 
+but that doesn't serve as a macro argument. It is removed, and the 
+next token is .&a. The same story as before happens, until the 
+named token \ntok{a} is found\pdots
+\end{smallpar}
+
+\subsection{Summary of Possible Arglist Items}
+\begin{smallpar}
+For $0\leq i\leq 15$, let $\Chi_i$ be the set of character tokens 
+of category code $i$. $\Chi_1$ is the set of tokens working like 
+$\lbtok$, and $\Chi_2$ is the set of tokens working like $\rbtok$.
+
+Let $E$ be the set $\{3,4,6,7,8,11,12,13\}$. 
+These numbers are the category codes for 
+\meta{math},   \meta{align}, \meta{parameter}, \meta{super}, \meta{sub}, 
+\meta{letter}, \meta{other}, \meta{active} respectively. 
+Let $\Chi_E$ be the set of character tokens of category code in $E$
+(so $\Chi_E=\bigcup_{i\in E}\Chi_i$).
+
+Let $\circ$ be the \emph{concatenation} operation among token lists.\footnote{%
+    %% 2012/05/18
+    TODO: Define for representations by maps, or:
+    ``Concatenation is about as basic as natural numbers and is 
+      understood in terms of axioms rather than by a definition.''---See 
+        notes from 2011 (even with attempts with \Wikienref{Category theory})
+%         the \wikienref{Sequence}{English} 
+        the English Wikipedia for 
+        \wikienref{Sequence}{sequences}---\wikideref{Folge (Mathematik)}{German} 
+        article too much restricted to maps.}
+
+The following kinds of token lists form a single arglist item, 
+i.e., can serve as an argument for an undelimited parameter:
+\begin{enumerate}
+  \item a \emph{named} token, or the single-token list consisting of it, 
+        if you prefer that;
+  \item a \emph{character} token from $\Chi_E$ or the list consisting of it; 
+  \item a \emph{brace group.} 
+        That is a token list meeting the following conditions:
+        \inlineitem{1} its \emph{first} token is in $\Chi_1$,
+        \inlineitem{2} its \emph{last} token is in $\Chi_2$,
+        \inlineitem{3} it has as many occurrences of tokens from $\Chi_1$ as from $\Chi_2$,
+        \inlineitem{4} if it is split as $\lambda\circ\rho$, there are not 
+            more $\Chi_2$ occurrences in $\lambda$ than $\Chi_1$ occurrences in $\rho$
+            (``don't close before opening").
+\end{enumerate}
+The second claim can be checked with
+\begin{equation}
+  `\DoWith\typein$#^_a1~\StopDoing'
+\end{equation}
+%  \begingroup
+%   \def\a{A}\MakeNormalHere\# 
+%   \DoWith\typein$# ^_a1~\StopDoing
+%   \DoWith\typein#1\StopDoing
+%  \endgroup
+as to what works. 
+(The claim is not affected by one or two surprises.)\footnote{Moreover, 
+    \cs{DoWith&\typein&#1&\StopDoing} tells something about 
+    ``parameter tokens."} 
+Characters with different category codes 
+either are not converted into a character token\footnote{\TTbp.~47.} 
+or are not accepted as macro arguments. The latter applies to ``brace" tokens 
+in $\Chi_1$, $\Chi_2$ and to the single space token \sptok.
+
+As to \emph{``brace groups"}, the third and fourth condition above 
+are intended to say that what is between the two outer tokens 
+is $\langle$balanced text$\rangle$ in the sense of \TTbp p.~275f. and~385;
+i.e., for two tokens $a$, $b$ and a token list $\beta$, 
+$(a)\circ\beta\circ(b)$ is a brace group exactly if $a$ is from $\Chi_1$,
+$b$ is from $\Chi_2$, and $\beta$ is $\langle$balanced text$\rangle$. 
+The conditions are more formal than what I can find in \TTb, 
+but still they don't give me an idea of all possibities. 
+This should be improved by the following recursive definition:
+
+\begin{trivlist}\item 
+B1.~The empty list is balanced text. 
+B2.~For any token $t$ not in $\Chi_1$ or $\Chi_2$, 
+    the single-item token list $(t)$ is balanced text. 
+    (Such a token is either a \emph{named} token or a 
+     \emph{character} token from $\Chi_E$ or \emph{the space token}~\sptok.)
+B3.~If $\alpha$ and $\beta$ are balanced texts, 
+    then $\alpha\circ\beta$ is balanced text.
+B4.~If $\beta$ is balanced text, 
+    $a$ is from $\Chi_1$, and $b$ is from $\Chi_2$, 
+    then $(a)\circ\beta\circ(b)$ is balanced text.
+    (This is a brace group, and the only way of getting a brace group.)
+B5.~Nothing else is balanced text.
+\end{trivlist}
+
+In other words, a token list is a brace group if and only if 
+it is balanced text and starts with a token from $\Chi_1$
+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}
+
+% 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.
+% 
+% Especially, we have (\meta{i})~lists of \emph{characters} that 
+% the \emph{\TeX} program recieves from files and 
+% (\meta{ii})~lists of so-called \emph{tokens} 
+% that the \TeX\ program forms from the incoming list of characters 
+% and that it works on.
+% 
+% There are \emph{more} kinds of lists that \TeX\ works on. 
+% Here we are dealing with ``\TeX's mouth."\footnote{Cf.\ documentation 
+%     of the \ctanpkgref{bitelist} package.}
+% \TeX's mouth processes tokens formed from character input. 
+% It may turn a list `<toks-a><toks_b><toks-c>' of tokens 
+% into a list `<toks-a><toks-B><toks-c>', i.e., 
+% replace <toks-b> by <toks-B>---by so-called ``expansion". 
+% The result may be subject to expansion as well. 
+% When nothing is left to be expanded, results are passed to another, 
+% more interior subprocessor of \TeX. This one is deeper than \TeX's mouth, 
+% we are not concerned with that here.
+% 
+% Not \emph{all} of those tokens in ``\TeX's mouth" are formed 
+% (``directly") from input characters. 
+% Rather, some \cs{csname} function may form \emph{new} tokens 
+% from other tokens in \TeX's mouth---and place them there again. 
+% This way characters `\csname a\endcsname' you type may just work like 
+% `\a'.
+% 
+% It is difficult to tell on the \emph{character level} what the 
+% present package does. The relation between incoming characters 
+% and resulting tokens can hardly be explained by a single sentence or so.
+% However, <cmd> here refers to a command <macro> with a single 
+% undelimited macro. More precisely, a certain character sequence 
+% (``string") in the code you type, will be converted into a TODO
+% 
+% \subsection{Separators}
+% TODO
+% 
+% \subsection{Iterators and \TeX's Mouth}
+% TODO
+% 
 \section{Similar Commands in other Packages}
-The \CtanPkgRef{etex}{$\varepsilon$-TeX}-related                %% e->... 2012/05/09
+%% <- section again 2012/05/17b
+\subsection{``Heavy" Packages}                      %% add. heading 2012/05/17b
+The \CtanPkgRef{etex}{$\varepsilon$-TeX}-related    %% e->... 2012/05/09
 packages \ctanpkgref{etextools} 
 (Florent Chervet), \ctanpkgref{etoolbox} (Philipp Lehman), 
 and \ctanpkgref{texapi} (Paul Isambert) seem to include and 
@@ -80,11 +731,32 @@ like the few that are here.\footnote{\ctanpkgref{arrayjobx}
     provides somewhat ``exotic" handling of ``lists".}          %% 2012/05/10
 (I~do not want to load that much.)
 
+\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 
-comma-separated lists (such as lists of options). 
+\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. 
+However, when \LaTeX\ analyzes such lists (in ``\TeX's mouth"), 
+it uses representations by \emph{character tokens} of them.
+
+%% moved here 2012/05/17b:
+% %% 2011/11/10:
+% Also Heiko Oberdiek's \ctanpkgref{zref} deals with ``lists" of 
+% ``properties" of ``entities," 
+%% 2011/11/11: comma separated!
 
+%% 2012/05/09f.:
+The more recent \ctanpkgref{lmake} 
+(Shengjun Pan)                                      %% 2012/05/18
+provides a key-value syntax for printing lists of 
+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{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 
@@ -95,8 +767,18 @@ 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). 
 
+``Expandability" 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.
+Assignments happen somewhere \emph{behind} ``\TeX's mouth." 
+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 Niepraksch, Herbert 
+\ctanpkgref{multido} (Timothy Van Zandt, Rolf Nie\-praksch, Herbert 
 Vo\ss), and \ctanpkgref{xfor} (Nicola Talbot)? 
 
 'xfor' is just a reimplementation of `\@for'. 
@@ -111,10 +793,14 @@ This is essentially not needed when a list literally is
 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 and a macro parameter may have been 
-a good reason.
+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.
 
-Commands like `\DoWith' also save tokens thinking of list macros 
+\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} 
 which may be used as a \emph{command} to be applied to the list 
 elements. One example is 
@@ -137,6 +823,7 @@ and then
 \[`\DoWithAllIn\@makeother\specials'\]
 `latex.ltx' uses `\@elt' instead of `\do' for its own list macros.
 
+\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 
@@ -160,24 +847,26 @@ that (allegedly) is behind your enumeration. \ \meta{Example:}
 ---\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:
 In \LaTeX's \ctanpkgref{tools} bundle, \ctanpkgref{xspace}
-has a list macro `\@xpspace@exceptions@tlp' without separators. 
+%% add. 2012/05/18:
+was developed in the nineties by David Carlisle. 
+It had a rather fixed exception list implemented by a deeply
+nested conditional. In 2004 Morton H\o gholm joined, 
+and now 'xspace' has a list macro 
+`\@xspace@exceptions@tlp'                           %% was xpspace 2012/05/17b
+without separators. 
 It is handled like here, except that it ``breaks" the loop 
 when an item is found that applies.
-% %% 2011/11/10:
-% Also Heiko Oberdiek's \ctanpkgref{zref} deals with ``lists" of 
-% ``properties" of ``entities," 
-%% 2011/11/11: comma separated!
-
-%% 2012/05/09f.:
-The more recent \ctanpkgref{lmake} provides a key-value syntax
-for printing lists of complex mathematical expressions easily 
-(using some assignments) 
-as well as defining commands according to a pattern from a list.
+%% add. 2012/05/17bf.:
+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                                                %% 2011/11/03
+  \pagebreak                                                %% 2012/05/17b
 \section{Implementation}                                    %% 2012/05/10
+\label{sec:implement}
 \subsection{Package File Header (Legalese)}                 %% sub 2012/05/10
 \input{dowith.doc}
 \end{document}
@@ -192,3 +881,14 @@ VERSION HISTORY
 2012/05/10              "iterator", \MDkeywords, \hypersetup,
                         Legalize -> Legalese, "Related packages", 
                         tighter sectioning
+2012/05/14  for v0.21   spurious space in title fixed
+2012/05/14b     r0.21a  another keyword
+2012/05/15              abstract: why expandable
+2012/05/16              discussion much extended; 
+                        stored separately before reworking
+2012/05/16b     r0.21b  reworking ... many mistakes!
+2012/05/17              updating date, was 2012/05/14 before!
+                        and from 2012/05/14b onwards it should 
+                        have been r0.21a; storing again, 
+                        renaming dir.s ...
+2012/05/17bf.   r0.21c  reducing text ...
diff --git a/Master/texmf-dist/source/generic/dowith/srcfiles.tex b/Master/texmf-dist/source/generic/dowith/srcfiles.tex
index 0db90229e0a..6e2649ba5c6 100644
--- a/Master/texmf-dist/source/generic/dowith/srcfiles.tex
+++ b/Master/texmf-dist/source/generic/dowith/srcfiles.tex
@@ -1,7 +1,7 @@
+\ProvidesFile{srcfiles.tex}[2012/05/14 file infos -> SrcFILEs.txt]
 \RequirePackage{nicefilelist}
 \MFfieldtemplate{f-base}{dowithxx}
 \RequirePackage{myfilist}
-\ProvidesFile{srcfiles.tex}[2012/12/10 file infos -> SrcFILEs.txt]
 \EmptyFileList %%% [readprov.sty,myfilist.sty]
 %% packages:
 \ReadPackageInfos{dowith}
@@ -11,4 +11,5 @@
 \ReadPackageInfos{fifinddo,makedoc,niceverb}
 \ReadFileInfos{makedoc.cfg,mdoccorr.cfg}
 \ReadFileInfos{srcfiles}
+\ReadFileInfos{dowith.RLS}
 \ListInfos[SrcFILEs.txt]