\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
       document describes version
       \textcolor{blue}{\UseVersionOf{\jobname.sty}}
       of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
{ \RequirePackage{makedoc} \ProcessLineMessage{}
  \renewcommand*\mdSectionLevelOne{\string\subsection}
  \renewcommand*\mdSectionLevelTwo{\string\subsubsection}
  \MakeJobDoc{16}%% 2011/09/06
  {\SectionLevelTwoParseInput}  }
\documentclass[fleqn]{article}%% TODO paper dimensions!?
\input{makedoc.cfg}    %% shared formatting settings
\ReadPackageInfos{dowith}
% \usepackage{dowith}
\sloppy
\MDkeywords{macro programming, loops, list macros}
\hypersetup{%
    pdftitle=dowith.sty handles lists without separators,
    pdfsubject=documenting dowith.sty
}%% /2011/08/22
\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.
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}.
\MDaddtoabstract{Related packages}
\pkg{etextools}, \pkg{etoolbox}, \pkg{forarray}, 
\pkg{forloop}, \pkg{multido}, \pkg{moredefs}, \pkg{lmake}, 
\pkg{texapi}, \pkg{xfor}, \pkg{xspace}
\end{MDabstract}
\tableofcontents

%   \newpage
% \section{Features and Usage}
\section{Usage}

% \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
 base).\urlfoot{ukfaqref}{inst-wlcf}           %% corr. 2011/02/08

With \LaTeX, 
you load 'dowith.sty' (as usually) by
\begin{verbatim}
  \usepackage{dowith}
\end{verbatim}
below the `\documentclass' line(s) and above `\begin{document}'.
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 
together with their implementation.

% \section{Example}

\section{Similar Commands in other Packages}
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 
(very much) extend the functionality of 'dowith'. 
Also the `\ForEach'\texttt{\dots\unkern} macros of 
\ctanpkgref{forarray} (Christian Schr\"oppel) seem to extend 
the present `\DoWith'\texttt{\dots\unkern} commands. 
\ctanpkgref{moredefs} (Matt Swift) provides list handling commands 
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.)

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). 

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 
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). 

What about \ctanpkgref{forloop} (Nick Setzer), 
\ctanpkgref{multido} (Timothy Van Zandt, Rolf Niepraksch, 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 and a macro parameter may have been 
a good reason.

Commands like `\DoWith' also 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 
`\dospecials' that already is in Plain \TeX\ and expands to 
\[`\do\ \do\\\do\{\do\}\do\$\do\&\do\#\do\^\do\_\do\%\do\~'\]
% \begin{verbatim}
% `\do\ \do\\\do\{\do\}\do\$\do\&\do\#\do\^\do\_\do\%\do\~'
% \end{verbatim}
An important application of `\dospecials' is temporarily 
switching off the ``special" functionality of the ``elements" 
in `\dospecials'. With \LaTeX, this may happen thus:
\[`\let\do\@makeother\dospecials'\]
% \begin{verbatim}
% `\let\do\@makeother
% \end{verbatim}
With 'dowith', you can do the same with a shorter variant 
`\specials' of `\dospecials', defined by 
\[`\def\specials{\ \\\{\}\$\&\#\^\_\%\~}'\]
and then 
\[`\DoWithAllIn\@makeother\specials'\]
`latex.ltx' uses `\@elt' instead of `\do' for its own list macros.

%% 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 
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'?

%% 2011/11/07:
In \LaTeX's \ctanpkgref{tools} bundle, \ctanpkgref{xspace}
has a list macro `\@xpspace@exceptions@tlp' 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.

  \pagebreak                                                %% 2011/11/03
\section{Implementation}                                    %% 2012/05/10
\subsection{Package File Header (Legalese)}                 %% sub 2012/05/10
\input{dowith.doc}
\end{document}

VERSION HISTORY

2011/11/02  for v0.1    very first
2011/11/03              discussing \loop; \pagebreak
2011/11/07              xspace
2011/11/10f.            zref added/removed
2012/05/09  for v0.2    $\varepsilon$-\TeX
2012/05/10              "iterator", \MDkeywords, \hypersetup,
                        Legalize -> Legalese, "Related packages", 
                        tighter sectioning
