\ProvidesFile{commado.tex}[2015/11/16 documenting commado.sty]
\title{\pkg{\huge commado.sty} and \pkg{\huge filesdo.sty}\\---\\%
       Immediately Extend a One-Argument Macro\\
       to Comma-Separated Lists and Combinations\\ 
       of Filename Bases and Extensions\thanks{This document describes
       \textcolor{blue}{\UseVersionOf{\jobname.sty}} 
       of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}
       and version \textcolor{blue}{\UseVersionOf{filesdo.sty}} 
       as of \UseDateOf{filesdo.sty} of \pkg{filesdo.sty}..}}
% \RequirePackage[wrap]{nicefilelist} \listfiles
\RequirePackage{makedoc} \ProcessLineMessage{}
\renewcommand*{\mdSectionLevelOne}{\string\subsection}
\MakeJobDoc{19}{\SectionLevelOneParseInput}     %% 2012/11/26
\documentclass[fleqn]{article}%% TODO paper dimensions!?
% \documentclass{article} %% TODO paper dimensions!?
\usepackage{catchdq}    %% TODO earlier than `langcode'
\input{makedoc.cfg}     %% shared formatting settings
\ifpdf\else \errhelp{hyperref v6.83m option [draft] bad with \begin{equation}}
            \errmessage{run this with pdflatex only}\fi
\ReadPackageInfos{commado,filesdo}
% \usepackage{commado}
\MDkeywords{macro programming, programming structures, loops, lists}
\sloppy \catchdqs
\begin{document}
\maketitle
\begin{MDabstract}
'commado.sty' provides \[`\DoWithCSL{<cmd>}{<list>}'\] 
in order to apply an existing one-parameter macro <cmd> 
to each item in a list <list> in which items are 
\wikienref{comma-separated list}{separated by commas.} 
'filesdo.sty' provides \[`\DoWithBasesExts{<cmd>}{<bases>}{<exts>}'\]
in order to run `<cmd>{<base>.<ext>}' for some (at most) 
one-parameter macro <cmd>, each base filename <base> in the 
comma-separated list <bases> and each filename extension <ext> 
in the comma-separated list <exts>.
As opposed to \LaTeX's internal `\@for', no assignments are involved 
(unless <cmd> uses assignments---"expandability" in "\TeX's gullet").

Both packages are "generic," i.e., should work with Plain \TeX,
\LaTeX\ or even other formats, relying on the \ctanpkgref{plainpkg} 
package for some minimal \LaTeX-like behaviour.

\MDaddtoabstract{Related packages} \ctanpkgref{loops} and others 
mentioned in the \ctanpkgref{dowith} package documentation.
\end{MDabstract}
\newpage
\tableofcontents
% \newpage
\section{Installing and Calling}
The files 'commado.sty' and 'filesdo.sty' 
are provided ready, installation just requires
putting them somewhere where \TeX\ finds them
(which may need updating the filename data
 base).\urlfoot{ukfaqref}{inst-wlcf} 
However, installation of the package \ctanpkgdref{plainpkg} 
and the package 'stacklet.sty' (\ctanpkgdref{catcodes} bundle)
is required additionally.

As to calling (loading): 'commado.sty' and 'filesdo.sty' are 
"\pkg{plainpkg} packages" in the sense of the 'plainpkg'
documentation that you may consult for details.
So roughly, 
\begin{itemize}
  \item load it by \ |\usepackage{<pkg>}| \ if you can, 
  \item otherwise by \ |\RequirePackage{<pkg>}| \\
        (perhaps from within another "\pkg{plainpkg} package"), 
  \item or by \ |\input <pkg>.sty| 
  \item or even by \ |\input{<pkg>.sty}|~\dots
\end{itemize}
---where <pkg> is \qtdcode{commado} or \qtdcode{filesdo}.

% \pagebreak
\section{Syntax and Relation to the 'dowith' Package}
In <list> with |\DoWithCSL{<cmd>}{<list>}|, blank spaces %% boxed 2015/11/15
before entries or after commas as well as preceding the 
closing brace are ignored. So 
\[`\DoWithCSL{<cmd>}{ cfg, sty, tex }'\]
works like 
\[`\DoWithAllOf{<cmd>}{{cfg}{sty}{tex}}'\]      %% added `AllOf' 2015/11/15
from \ctanpkgstyref{dowith}.\urlfoot{CtanPkgRef}{dowith} %% foot 2012/11/30
With `\DoWithCSL' 
(at present), %% 2012/11/27
an item cannot be empty or consist of blank spaces only. 
Empty or blank items can be handled by `\DoWith'\-`AllOf'.
%% <- was not wrong without `AllOf', however ...                 2015/11/15
%%    ... hyphenation is a great compromise! without hyphen?
\par %% 2015/11/15
\begingroup \footnotesize
As to \strong{relevance}, the previous remark addresses those 
who want to understand what I am doing, such as me. 
The two commands provide a rather obvious ``link'' between the 'commado' 
and the 'dowith' bundle. But neither of them is a command that 
``you shouldn't miss.'' 'commado.sty' is mainly a programming tool 
(and I isolate it as an object of study).
%  similar to a chess diagram to demonstrate how to trap a lonely king 
%  with king and rook only, the actual task being expandability, 
%  in my case to generate \acro{HTML} with \TeX's `\write' primitive).
    \par\strong{Choosing between 'dowith' and 'commado'.}\quad What I 
\strong{really use} in the case of comma-separated lists is 
\strong{'filesdo.sty'} as described in the next section. %% TODO really?
It is great to keep certain files or file sections small (\strong{readability}), 
actually in describing package bundles, on \acro{CTAN} as well as 
with a complex book at which I am working. However, 
the comma feature is a little more complex than the 'dowith' way, 
and I like to avoid unnecessarily complex things. 
The real advantage of 'filesdo', as I feel it, 
is the readability of the code with combinations of file \emph{basenames}
and \emph{extensions}, similar to \emph{brace expansion} in the 
\Wikidisambref{Bash}{Unix shell} shell. 
The braces make obvious which are the basenames and which are the 
extensions, and the commas structure each of these two lists.

In applications of \strong{'dowith'}, saving \strong{tokens} and 
\strong{expansion} steps is more important to me (a kind of sports). 
\emph{Tokens} actually are saved with 'dowith' when <list> consists of 
single tokens rather than ``\strong{brace groups},'' 
and the former is the application of 'dowith' in my \ctanpkgdref{langcode} package 
(in the 'dowith' discussion, I compare this with the \ctanpkgdref{xspace} package).
On the other hand, a <list> of brace groups even needs more tokens than a comma-separated list.
% (Due to \TeX's tokenization, readability and parsimony are opposite and 
%  incompatible goals.)
The number of tokens or expansion steps is relevant when a list is stored
as a macro or in a token register. It is less relevant when a list 
is processed once only at the moment the input file is read 
and then is not stored any longer.

There is a situation where I prefer lists of \emph{brace groups} 
to comma-separated lists although the former need more tokens
and their readablility is worse: I use something like 
\begin{equation}
  `\autrefs{{apples}{oranges}{pears}}'
\end{equation}
to generate a list of internal links in a \acro{HTML} file. 
`\autrefs' this way rests on `\DoSeparateWith' from 'domore.sty'. 
`\DoSeparateWith' is based on `\DoWith'. Sometimes I use the former 
one directly as an \emph{author}. The alternative
\begin{equation}
  `\autrefs{apples,oranges,pears}'
\end{equation}
would need less tokens (which is absolutely irrelevant in this case 
because the line is in \TeX's memory for a moment only) 
and may be easier to read. However, often I want to change the order 
of the items. When I try this by cut\&paste in a comma-separated list, 
I always wonder whether I should cut/copy the right-hand comma 
of a list item or the left-hand comma; and at the next moment, 
I have forgotten whether I cut the right-hand comma 
or the other one. With the 'dowith' approach, I just cut\&paste
a brace group. A function key opens an empty brace group in my 
favorite editor.

\par \endgroup

\section{Example for 'filesdo.sty'}
In the file `srcfiles.tex' for the \ctanpkgdref{nicetext} bundle, 
there is a line 
\begin{quote}
`\DoWithBasesExts\ReadFileInfos{fifinddo,niceverb}{sty,tex}'\kern-10pt
\end{quote}
This works like 
\begin{quote}
`\ReadFileInfos{fifinddo.sty}'\\
`\ReadFileInfos{niceverb.sty}'\\
`\ReadFileInfos{fifinddo.tex}'\\
`\ReadFileInfos{niceverb.tex}'
\end{quote}
or actually 
(a special feature of \ctanpkgref{readprov}'s\urlfoot{CtanPkgRef}{readprov}
 %% <- foot 2012/11/30
 `\ReadFileInfos' is that its argument may be 
 a comma-separated list already)
\begin{quote}
`\ReadFileInfos{fifinddo.sty,niceverb.sty,'\\
\null\texttt{ ~ ~ ~ ~ ~ ~ ~ }`fifinddo.tex,niceverb.tex}'
\end{quote}
I ponder providing a shorthand `\ReadBaseExtInfos' for 
\begin{quote}
`\DoWithBasesExts\ReadFileInfos'
\end{quote}
and reimplementing `\ReadFileInfos' using `\DoWithCLS' in 'myfilist.sty'
(2012-11-27).

\pagebreak
\section{The File 'commado.sty'}
\subsection{Package File Header (Legalese and 'plainpkg')}
\input{commado.doc}

\newpage

\section{The File 'filesdo.sty'}
\subsection{Package File Header (Legalese and 'plainpkg')}
\ResetCodeLineNumbers
\renewcommand*{\mdJobName}{filesdo}
\MakeInputJobDoc{19}{\SectionLevelOneParseInput}
\end{document}

VERSION HISTORY

2012/11/24  for v0.1   very first
2012/11/30  for v0.11  \ctanpkgdref moves to `makedoc.cfg', 
                       2 more link footnotes
2015/11/15f.           `AllOf' was missing in the description of
                       the relation to the `dowith' bundle -- 
                       added an "essay"
2015/11/15             error message to deal with hyperref's
                       draft/equation problem as in dowith.tex