summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-05-20 23:58:05 +0000
committerKarl Berry <karl@freefriends.org>2012-05-20 23:58:05 +0000
commitd66f3e2f4f5c746daae0c2368b939be05b451781 (patch)
treefae34afcf6c57928bcc60dd604b2ba46250e93df /Master/texmf-dist/source/generic
parentcc16f0e908252ba50f1a8486afeaa021f551a1ad (diff)
dowith (18may12)
git-svn-id: svn://tug.org/texlive/trunk@26514 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/generic')
-rw-r--r--Master/texmf-dist/source/generic/dowith/SrcFILEs.txt9
-rw-r--r--Master/texmf-dist/source/generic/dowith/dowith.tex780
-rw-r--r--Master/texmf-dist/source/generic/dowith/srcfiles.tex3
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]