diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/generic/dowith |
Initial commit
Diffstat (limited to 'macros/generic/dowith')
-rw-r--r-- | macros/generic/dowith/README | 64 | ||||
-rw-r--r-- | macros/generic/dowith/doc/Announce.txt | 79 | ||||
-rw-r--r-- | macros/generic/dowith/doc/SrcFILEs.txt | 21 | ||||
-rw-r--r-- | macros/generic/dowith/doc/domore.pdf | bin | 0 -> 524474 bytes | |||
-rw-r--r-- | macros/generic/dowith/doc/dowith.RLS | 19 | ||||
-rw-r--r-- | macros/generic/dowith/doc/dowith.pdf | bin | 0 -> 694501 bytes | |||
-rw-r--r-- | macros/generic/dowith/docsrc/domore.tex | 166 | ||||
-rw-r--r-- | macros/generic/dowith/docsrc/dowith.tex | 1168 | ||||
-rw-r--r-- | macros/generic/dowith/docsrc/fdatechk.tex | 12 | ||||
-rw-r--r-- | macros/generic/dowith/docsrc/srcfiles.tex | 23 | ||||
-rw-r--r-- | macros/generic/dowith/domore.sty | 164 | ||||
-rw-r--r-- | macros/generic/dowith/dowith.sty | 204 |
12 files changed, 1920 insertions, 0 deletions
diff --git a/macros/generic/dowith/README b/macros/generic/dowith/README new file mode 100644 index 0000000000..8f7664cbe3 --- /dev/null +++ b/macros/generic/dowith/README @@ -0,0 +1,64 @@ + + README for the `dowith' package + + Apply Command to Each Item in a List of Arguments + in TeX's Macro Expansion Buffer + + (C) Uwe Lueck 2012/11/19 + + +`dowith.sty' provides macros for applying a command to all items +in a list of macro arguments, and also for extending and reducing +macros storing such lists. "Brace groups" are single items of +such lists, as opposed to token lists. Iteration is implemented +within TeX's expansion processor, so works within \write as with +`blog.sty'. Loop and list macros in other packages are discussed +in the documentation. There is no need for e-TeX to which some +of them refer. + +`domore.sty' extends `dowith.sty' in order to apply multi- +parameter macros to a list and to insert "separator material" +between resulting items. One application has been generating +inline lists of links that are separated by ` | '. + +The packages are "generic", i.e., should also work with Plain TeX, +relying on the `plainpkg' package for some minimal LaTeX-like +behaviour. + +KEYWORDS: programming structures; + macro programming, loops, list macros + +RELATED PACKAGES: catoptions, etextools, etoolbox, forarray, +forloop, loops, multido, moredefs, lmake, texapi, xfor, xspace + +LICENSE: + +The package file `dowith.sty', `domore.sty' and the +documentation files `dowith.pdf', `domore.pdf', `dowith.tex', +and `domore.tex' can be redistributed and/or modified under the +terms of the LaTeX Project Public License; either version 1.3c +of the License, or any later version, see + + http://www.latex-project.org/lppl.txt + +We did our best to help you, but there is NO WARRANTY. + +The `dowith' package is author-maintained in the sense of +this license. + +The latest public version of the package is available at + + http://mirror.ctan.org/macros/generic/dowith/ + +A TDS version of the package is available as + + http://mirror.ctan.org/install/macros/generic/dowith.tds.zip + +The file `dowith.RLS' provides RELEASE info accessible by LaTeX +FILE info packages, see + + http://ctan.org/pkg/latexfileinfo-pkgs + +Please report bugs, problems, and suggestions via + + http://www.contact-ednotes.sty.de.vu diff --git a/macros/generic/dowith/doc/Announce.txt b/macros/generic/dowith/doc/Announce.txt new file mode 100644 index 0000000000..c705fca031 --- /dev/null +++ b/macros/generic/dowith/doc/Announce.txt @@ -0,0 +1,79 @@ + +`dowith' -- iterate on separator-less arglists in TeX's gullet + +________________________________________________________________ + +r0.32 2015/11/14 + + * `domore.sty' v0.32 fixes: + * finally works without LaTeX indeed + * \StopDoing without `dowith.sty', + e.g., vital with recent `texlinks.sty' + * documentation fix \DoWithMore + + * `dowith.pdf' has two documentation modifications + (`dowith.tex' r0.3a, strange word removed from explanation + of "arglist") and has been typeset with recent + documentation packages + +________________________________________________________________ + +r0.31a 2013/03/23 + publishes fdatechk.tex needed for proper compilation of + documentation, created for r0.31, enhanced for r0.31a + +________________________________________________________________ + +Iterate stuff on argument list (no separators) expandably + +r0.31 2013/03/22 + +domore.sty v0.3 only enhanced dowith.sty's \DoWith{<do>} so that +<do> can be complex. domore v0.31 enhances dowith.sty's +\DoWithAllOf{<do>}{<args>} and \DoWithAllIn{<do>}{<macro>} +in the same respect. + +________________________________________________________________ + +r0.3a corrects TDS -- "generic", not "latex" +________________________________________________________________ + +Iterate stuff on argument list in TeX's gullet (no separators) + +r0.3 2012/11/19 + + * new `domore.sty' enhances `dowith.sty', allowing iterated + application of multi-parameter macros and inserting + "separator material". + + * `dowith.sty' documentation correction: according to Knuth, + this is TeX's "gullet", while some authors have called it + "TeX's mouth", see quotations in section 1.4 of `dowith.pdf'. + + * `dowith.sty' (v0.3) "generic" now by `plainpkg' + (instead of imitating `german.sty'). + + * `dowith.sty' documentation `dowith.pdf' furthermore reworked. + +________________________________________________________________ + +Iterate command on argument list in TeX's mouth (no separators) + +r0.22 2012/06/03 + +Documentation + (i) discusses what <cmd> in \DoWith<cmd>... can be + (ii) extends comparison with \@tfor +(iii) has some contentual corrections + (iv) celebrates 25 years of Alois Kabelschacht's idea +________________________________________________________________ + +Iterate macro on argument list in TeX's mouth – no separators + +r0.21c 2012/05/18 + + (i) @ fix for "generic" and `typeoutfileinfo' + (ii) documentation much extended to clarify kind of "items," + distinguishing tokens from code +(iii) `dowith.RLS' provides release info as LaTeX file info + diff --git a/macros/generic/dowith/doc/SrcFILEs.txt b/macros/generic/dowith/doc/SrcFILEs.txt new file mode 100644 index 0000000000..0152ec5c9a --- /dev/null +++ b/macros/generic/dowith/doc/SrcFILEs.txt @@ -0,0 +1,21 @@ + + *File List* + dowith.RLS 2015/11/14 r0.32 domore v0.32: fix w/o LaTeX/dowith & doc. + dowith.sty 2012/11/05 v0.3 simple list loop (UL) + domore.sty 2015/09/17 v0.32 dowith extended (UL) + dowith.tex 2015/11/14 -- documenting dowith.sty + domore.tex 2015/11/14 -- documenting domore files +srcfiles.tex 2015/11/14 -- file infos -> SrcFILEs.txt +fdatechk.tex 2015/11/14 -- dowith filedate checks + ---USED.--- -- -- -- -- -- + catchdq.sty 2015/05/22 v0.21 typographic dqs (UL) +fifinddo.sty 2012/11/17 v0.61 filtering TeX(t) files by TeX (UL) + makedoc.sty 2012/08/28 v0.52 TeX input from *.sty (UL) +niceverb.sty 2015/11/09 v0.61 minimize doc markup (UL) + makedoc.cfg 2013/03/25 -- documentation settings +mdoccorr.cfg 2012/11/13 -- `makedoc' local typographical corrections + *********** + + List made at 2015/11/14, 20:03 + from script file srcfiles.tex + diff --git a/macros/generic/dowith/doc/domore.pdf b/macros/generic/dowith/doc/domore.pdf Binary files differnew file mode 100644 index 0000000000..a476a09dbd --- /dev/null +++ b/macros/generic/dowith/doc/domore.pdf diff --git a/macros/generic/dowith/doc/dowith.RLS b/macros/generic/dowith/doc/dowith.RLS new file mode 100644 index 0000000000..d9929af280 --- /dev/null +++ b/macros/generic/dowith/doc/dowith.RLS @@ -0,0 +1,19 @@ +\ProvidesFile{dowith.RLS} %% >RELEASE INFO< + [2015/11/14 r0.32 domore v0.32: fix w/o LaTeX/dowith & doc.] + [2013/03/23 r0.31a publishing fdatechk.tex] + [2013/03/22 r0.31 domore AllIn AllOf] + [2012/11/27 r0.3b `domore.sty'; doc. mouth -> gullet,^^J + rm. `pdfstartview'] + [2012/11/20 r0.3a doc. mouth -> gullet, `domore.sty'; + TDS corr.] + [2012/11/19 r0.3 doc. mouth -> gullet, `domore.sty'] + [2012/06/03 r0.22 v0.22 arg. {}; doc.: catoptions] + [2012/06/03 r0.21f v0.21a; doc.: catoptions] + [2012/05/22 r0.21e v0.21a; doc.: Kabelschacht vs. TeXbook] + [2012/05/20 r0.21d v0.21a discussing other cmds ] + [2012/05/18 v0.21 r0.21c @ fix, new doc., .RLS] + [2012/05/14 r0.21 @ fix, .RLS, README/title typo...] + %% <- FAILED + [2012/05/10 r0.2a corr. generic dir.] + [2012/05/10 r0.2 first on CTAN] + diff --git a/macros/generic/dowith/doc/dowith.pdf b/macros/generic/dowith/doc/dowith.pdf Binary files differnew file mode 100644 index 0000000000..7da251a37b --- /dev/null +++ b/macros/generic/dowith/doc/dowith.pdf diff --git a/macros/generic/dowith/docsrc/domore.tex b/macros/generic/dowith/docsrc/domore.tex new file mode 100644 index 0000000000..f134780fd0 --- /dev/null +++ b/macros/generic/dowith/docsrc/domore.tex @@ -0,0 +1,166 @@ +\ProvidesFile{domore.tex}[2015/11/14 documenting domore files] +\title{\pkg{domore}\\---\\Some More Commands for Lists of Tokens} +% \listfiles +{ \RequirePackage{makedoc} \ProcessLineMessage{} + \renewcommand\mdSectionLevelOne {\string\subsection} + \renewcommand\mdSectionLevelTwo {\string\subsubsection} + \MainDocParser{\SectionLevelTwoParseInput} + \HeaderLines{17} + \MakeSingleDoc{domore.sty} + \MakeSingleDoc{reversdo.sty} + \MakeSingleDoc{domodes.sty} +} +\documentclass[fleqn]{article}%% TODO paper dimensions!? +\input{makedoc.cfg} %% shared formatting settings +\MDkeywords{Macro programming, programming structures, + loops, list macros} +\newcommand*{\headersec}{% + \subsection{Package File Header---\pkg{plainpkg} and Legalese}} +\usepackage{catchdq} \catchdqs %% 2012/11/19 +\AddToMacro{\mdStartPackageCode}{\MakeOther\"} %% 2012/11/19 + %% something moved to makedoc.cfg from here 2013/03/21 +\newif\ifmultmore %% 2012/11/19 +%%% \multmoretrue %% 2015/11/14 TODO domodes/revers... with plainpkg! +\MDfinaldatechecks +\sloppy +\begin{document} +\maketitle +\begin{MDabstract} +\ifmultmore + This document describes packages that do similar things + as the 'dowith' package or extend it. +\else + 'domore.sty' is a package that enhances 'dowith.sty''s + `\DoWith' (without assignments) + and `\setdo' commands for applying something + (e.g., `\do') to each item of an "arglist". + Each item may consist of two or more arguments for a macro, + and some "separator" material may be inserted between the + applications to items. A practiced application has been + generating inline lists of links that are separated + by \qtdcode{~\string|~}. + 'domore.sty' is (to some extent) format-independent + by means of the \ctanpkgref{plainpkg} and 'stacklet' packages. +\fi +% \MDaddtoabstract{Required Packages} +% \ctanpkgref{plainpkg}, 'stacklet' +\MDaddtoabstract{Related Packages} cf. `dowith.pdf'. +\end{MDabstract} +\tableofcontents + +\edef\domore{\ifmultmore\noexpand\MetaVar domore>\else domore\fi} +% \section{Shared Features of Usage} +\ifmultmore + \section{Shared Features of Usage} + All the packages described in this document + are "\pkg{plainpkg} packages" +\else + \section{Making 'domore.sty' Available} + The 'domore' package is a "\pkg{plainpkg} package" +\fi +in the sense of the +\ctanpkgdref{plainpkg} +documentation that exhibits details of what is summarized here. +Therefore: +\begin{itemize} + \item \ifmultmore All of them require \else It is required \fi + that \TeX\ finds `plainpkg.tex' + as well as `stackrel.sty' from the + \ctanpkgdref{catcodes} bundle. + \item In order to load \file{\domore.sty}%%% + \ifmultmore\ (where \domore\ is `domore', `domodes', or `reversdo')\fi, + type + \begin{description} + \ifmultmore\cmdboxitem|\usepackage{<domore>}| + \else\cmdboxitem|\usepackage{domore}| \fi + \ within a \LaTeX\ document + preamble, \ + \ifmultmore\cmdboxitem|\RequirePackage{<domore>}| + \else\cmdboxitem|\RequirePackage{domore}| \fi + \ in a "\pkg{plainpkg} package", or \ + \ifmultmore\cmdboxitem|\input <domore>.sty| + \else\cmdboxitem|\input domore.sty| \fi + \end{description} + $\dots$ \ or perhaps `\input{<domore>.sty}'? +\end{itemize} + +\section{Remark on the Style of Code Documentation} +In `dowith.pdf', the documentation of the 'dowith' package, +in the section about "\TeX's tokens," I have tried to explain +the difference between \TeX\ input code and the tokens that +arise from it. In order to really understand what packages +in the 'dowith' bundle do, one should think of the behaviour +of the \emph{tokens}. For convenience however, I may rather +fall back into the usual confusion here. After reading the +documentation `dowith.pdf' of `dowith.sty', you may be able +to guess successfully what is meant below. + +% \section{Overview of Packages Described in \file{\jobname.pdf}} +\ifmultmore + \section{Overview of Packages Described in \file{\jobname.pdf}} + \label{sec:over} + The present document describes the packages provided by the + \ctanpkgref{dowith} bundle apart from 'dowith.sty' itself + for applying something to each item from some list. + \begin{enumerate} + \item +\else + \section{Overview of Commands} +\fi + \strong{\pkg{domore.sty}} provides a more powerful version + of 'dowith.sty''s + \[|\DoWith{<repeat>}<args>\StopDoing|\] + acting on an "arglist" <args> + where <repeat> may be more complex than with 'dowith.sty'. + Based on this, another variant |\DoWithMore| of `\DoWith' + is provided where <repeat> may be a macro with more than + one argument. With \LaTeX\ e.g., <repeat> may be |\do| + defined by \[|\setdo[<digit>]<opt>{<replace>}|\] + an extension of 'dowith.sty''s `\setdo'. + Further, + \[|\DoSeparateWith{<repeat>}{<sep>}<args>\StopDoing|\] + inserts "separator material" <sep> between the applications + of <repeat> to the items in <args>. Another + |\DoSeparateWithMore| combines the features of the two + previous macros. I have used this with 'blog.sty' from + the \ctanpkgref{morehype} bundle for generating inline + lists of links, separated by something like \qtdcode{~\string|~}, + in \acro{HTML} documents. + + As auxiliaries, variants |\@firstsecondoftwo| and + |\@secondfirstoftwo| of \LaTeX's `\@firstofone' are introduced. +\ifmultmore + \end{enumerate} + + \section{'domore.sty'} + An overview of what 'domore.sty' provides has been given in + Section~\ref{sec:over}. + For details, see the comments to the package's code below. +\else + + For details, see the comments to the package's code below. + \section{Contents of 'domore.sty'} +\fi +\headersec +\input{domore.doc} + +\MakeOther\" +\ifmultmore +\section{'domodes.sty'} +See Section~\ref{sec:domodes-cmds} for the commands provided. +\headersec +\input{domodes.doc} + +\section{'reversdo.sty'} +See Section~\ref{sec:reversdo-cmds} for the commands provided. +\headersec +\input{reversdo.doc} + +\fi +\end{document} + +VERSION HISTORY + +2012/10/23 for v0.2 started +2012/11/05ff. for v0.3 +2013/03/21f. for v0.31 \MDfinaldatecheck diff --git a/macros/generic/dowith/docsrc/dowith.tex b/macros/generic/dowith/docsrc/dowith.tex new file mode 100644 index 0000000000..edd167ae26 --- /dev/null +++ b/macros/generic/dowith/docsrc/dowith.tex @@ -0,0 +1,1168 @@ +\ProvidesFile{dowith.tex}[2015/11/14 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 Gullet"\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{18}%% 2012/11/05 for v0.3 + {\SectionLevelTwoParseInput} } +% \RequirePackage[ir]{inputtrc} +\documentclass[fleqn]{article}%% TODO paper dimensions!? +\input{makedoc.cfg} %% shared formatting settings +\ifpdf\else \errhelp{hyperref draft bad with {equation}} + \errmessage{run this with pdflatex only}\fi +% \ReadPackageInfos{dowith} +\usepackage{dowith} %% 2012/05/17b +\sloppy +\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 +\usepackage{fixltx2e} %% \textsubscript 2012/05/17b +%% <- TODO with `lmodern'? +% \newcommand*{\ctanpkgdref}[1]{% %% 2012/11/19 +% \ctanpkgref{#1}\,\foothttpurlref{ctan.org/pkg/#1}} +%% <- in `makedoc.cfg' 2015/11/14 +\makeatletter %% etc. 2012/05/17b +%% TODO `actcodes'!? 2012/11/02 + \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} +\newcommand*{\codebd}[1]{\code{\codeLB#1\codeRB}} %% 2012/05/19 +%% 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}} +\renewcommand*{\httpprefix}{\theHTTPprefix} +\begin{document} +\maketitle +\begin{MDabstract} +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. Iteration is implemented within \TeX's expansion +processor, so works within `\write' as with 'blog.sty'. + %%% ---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 in the documentation. +% %% 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} to which +some of them refer. + +The package is ``generic," i.e., should also work with Plain \TeX\ +or even other formats, relying on the \ctanpkgref{plainpkg} package +for some minimal \LaTeX-like behaviour. %% \ 2012/11/27 + +\MDaddtoabstract{Related packages} +\let\pkg\ctanpkgref \pkg{catoptions}, +\pkg{etextools}, \pkg{etoolbox}, \pkg{forarray}, \pkg{forloop}, +\pkg{loops}, \pkg{multido}, \pkg{moredefs}, \pkg{lmake}, +\pkg{texapi}, \pkg{xfor}, \pkg{xspace} +\end{MDabstract} +\tableofcontents + +% \newpage +\section{Usage and Features} %% restructured 2012/05/16 + +\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 +The packages \ctanpkgdref{plainpkg} +and 'stacklet' (\ctanpkgref{catcodes})\urlfoot{ctanpkgref}{catcodes} +must be installed as well. + +As to calling (loading): 'dowith' is a ``\pkg{plainpkg} package" +in the sense of the \ctanpkgref{plainpkg} +documentation that you may consult for details. +So roughly, +\begin{itemize} + \item load it by \ |\usepackage{dowith}| \ if you can, + \item otherwise by \ |\RequirePackage{dowith}| \\ + (perhaps from within another ``\pkg{plainpkg} package"), + \item or by \ |\input dowith.sty| + \item or even by \ |\input{dowith.sty}|~\dots +\end{itemize} + +% \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$>}'\] +% +% \pagebreak %% 2012/05/19 +\subsection{What It Does With What Lists} +% \subsection{What It Actually Does \dots} +\label{sec:lists-intuit} + +The single commands that the package provides are described +in the \hyperref[sec:implement]{implementation section} below. +What follows here is some general background about how the +commands work. +%% <- moved down from previous section, mod. 2012/05/19 + +The term \qtd{list} may refer to various things and need clarification here. + +First of all, we are not referring to \LaTeX\ `list' environments +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{Anatomy of \TeX} +The documentation of v0.22 as of 2012-06-04 said that the package +is about ``lists in \TeX's mouth." However, this was very wrong. +I believed it following Alan Jeffrey's paper ``Lists in \TeX's Mouth",\footnote{% + Alan Jeffrey: \tugbartref{tb11-2/tb28jeffrey}{``Lists in \TeX's Mouth,"} + \acro{TUG}boat Vol.~11 (1990), No.~2, pp.~237--245), + \urlhttpref{tug.org/TUGboat/tb11-2/tb28jeffrey.pdf}.} +in whose Section~2 you read: +\begin{quote}\it + \TeX's programming facilities come in two forms---there + are \TeX's \emph{macros} which are expanded in its + mouth, and some additional \emph{assignment} operations + like \cs{def} which take place in the stomach. +\end{quote} +The macros that Jeffrey lists and describes in that article can be +obtained as a \acro{CTAN} package +\ctanpkgref{lambda-lists}.\footnote{\urlhttpref{ctan.org/pkg/lambda-lists}} +If you follow the link given here (in the footnote), +you currently (2012-11-03) read about this package: +\begin{quote}\it + These list-processing macros avoid the reassignments + employed in the macros shown in Appendix D of the TeXbook: + all the manipulations take place in what Knuth is pleased to + call ``TeX's mouth". +\end{quote} +But Knuth doesn't. On page 267 of \TTb, you read: +\begin{quote}\it + Chapter 7 has described the process by which input files + are converted to lists of tokens in \TeX's ``mouth," + and Chapter 20 explained how expandable tokens are converted + to unexpandable ones in \TeX's ``gullet" by a process + similar to regurgitation. +\end{quote} +I.e., the ``mouth" is \TeX's ``tokenizer," the inner part of what +van Eijkhout calls \TeX's ``input processor" on, e.g., p.~15 of his +\meta{\TeX~by Topic}.\footnote{It is available as a \acro{CTAN} package + \ctanpkgref{texbytopic} at \urlhttpref{ctan.org/pkg/texbytopic}.} +The exact rules the tokenizer follows are described on pp.~46f.\ +(Chapter~8!) of \TTb. +\emph{Macro expansion} takes place in \TeX's \emph{``gullet"}, +which van Eijkhout calls \TeX's ``expansion processor" (p.~16). +Abrahams, Hargreaves, and Berry follow Knuth's terminology on +pp.~16 and 46f.\ of their \meta{\TeX~for the Impatient}.\footnote{It + is available as \acro{CTAN} package \ctanpkgref{impatient}, + \urlhttpref{ctan.org/pkg/impatient}.} +% Only Jeffreys and my wrong old documentation say this were +% ``\TeX's mouth"---and I made the same mistake with the +% \ctanpkgref{bitelist} package. +%% <- 2012/11/19 -> + +\TeX's gullet has been called ``\TeX's mouth" also +in the documentation of my \ctanpkgdref{bitelist} package and +in the documentation of the package \ctanpkgdref{bibleref-mouth}. + +Moreover, I should have clarified that Jeffrey's paper deals with +``lists" in some general, rather abstract sense, different from +the kind of lists the present documentation tries to characterize +as the objects for 'dowith'. + +\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{% +The 'dowith' package is a tool that affects the order of tokens in +\TeX's gullet. + +\begin{smallpar} +The ``characters you type" enter ``\TeX's mouth" line by line, +in a slightly modified appearance. Each line forms a \emph{string}. +\TeX\ takes initial substrings away from it and turns them +into \emph{tokens} that are appended to the right of \TeX's +\emph{expansion buffer} (``gullet"). + +%% Removing 2012/11/04: +% 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, +%% <- especially wrong, 2012/11/04 +% until it contains enough material to form a token from. + +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 gullet +(perhaps unless one considers a one-step macro expansion + a two-or-more-step procedure). +% merged 2012/11/04 +%% Moving down 2012/11/04 +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---a \emph{named} +token, as I am saying. +% What has been used to form a token is removed from the character buffer. +%% 2012/11/04: +\emph{Character} tokens are formed by removing a character from the +beginning of the character buffer and appending it to the token buffer +paired with its \emph{category} code. + +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 gullet, maybe apart from ``primitive" + tokens that have a ``pre-assigned meaning" when a \TeX\ run %% \ 2012/11/04 + 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 +appears to me %%% is %% 2012/11/04 +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} +%% rm. 2012/11/04, cf. above +% \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 gullet by ``tokenization" as described above, +i.e., they are drawn from the character buffer. But they also can +appear in \TeX's gullet ``from within," +by the manipulation inside \TeX's gullet. + +More formally, those manipulations are called ``expansion," +and \TeX's gullet 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 gullet 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 gullet +also by \emph{expansion}, never having been drawn by tokenization +and not being hardwired. This happens by the `\csname' +% name %% rm. 2012/07/25 +construct. +The input \emph{code} may contain +\[`\csname tupni\endcsname'\] +This may be converted into 7 tokens entering \TeX's gullet, +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) %% rm. 2015/11/14 -- ??? +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} +\label{sec:steps} %% 2012/05/20 +\begin{smallpar} +To write token lists easier and hopefully easier to read, +I would suggest writing \qtd{.<char>} for the character token +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} + %% added \,s 2012/06/07: + \ntok{typein}\,.\codelb\,.&a\,.\coderb\, + \ntok{typein}\,.\codelb\,.&a\,.\coderb\, + \ntok{typein}\,.\codelb \ntok{a}\,.\coderb\, + \ntok{typein}\,.\codelb\,.&a\,.\coderb +\end{equation} +(The definition of `\DoWith' in Section~\ref{sec:core} indeed adds surrounding braces, + if missing.) +However, \TeX\ rather tries to work with as few tokens ahead as possible. +When it finds \ntok{DoWith} and the latter's meaning is the one intended +by 'dowith', it first looks for nothing more than the two arguments +required by our definition of `\DoWith'. A few moments later, +the token buffer's content will just be\footnote{If you use + `&\DoWithAllOf&\typein\codeLB a\codeSP a&\a\codeLB a\codeRB\codeRB' + %% <- \cs bad 2015/11/14 + instead, the entire token sequence \ref{eq:retro} will appear in the + token buffer ``at once."} +\begin{equation} + \ntok{typein}.\codelb.&a.\coderb\,\ntok{expandafter}\,\ntok{DoWith}\, + \ntok{expandafter}\,\ntok{typein}\,\ntok{fi} +\end{equation} +Next $\ntok{typein}.\codelb.&a.\coderb$ is expanded according to the code for +`\typein' in \file{latex.ltx}. Some unexpandable tokens will emerge +and be moved into the ``instruction buffer," %% cmd -> instr 2012/11/04 +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: %% \ 2012/11/05 + ``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, + `&\DoWith&\typein&\StopDoing' %% \cs bad 2015/11/14 + 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} + +\subsection{Summary: ``Commands" Usable with 'dowith'} +In the \hyperref[sec:apply]{implementation section,} +you learn about +\[`\DoWith<cmd>',\quad `\DoWithAllOf<cmd>',\quad + \mbox{and}\quad `\DoWithAllIn<cmd>'.\] +(\LaTeX\ users may type `{<cmd>}' instead.) +What <cmd>s are allowed? + +\begin{enumerate} + \item All \strong{one-parameter macros} <cmd> work this way, + unless there are programming mistakes outside 'dowith' + (also thinking of arguments that take over control + from 'dowith' commands before the argument list is finished). + \item \strong{Other one-parameter} ``commands" <cmd> such as + \TeX\ \strong{primitives} may work---you must think of + the fact that surrounding \emph{braces} are added.\footnote{\TODO: %% \ 2012/11/05 + in the future, variants not adding braces could be added.} + So the \strong{primitives} `\hbox' and `\vbox' work, + for instance. `\show' is an example that doesn't work at all, + it takes the single starting brace token and then confuses + `\DoWith'. + \item Some <cmd>s taking \strong{no argument} may make sense, e.g., + for getting + \begin{enumerate} + \DoWithAllOf{\item}{{apples,}{pears,}{peaches}} + \end{enumerate} + from + \begin{quote} + &\begin{enumerate}\\ + \null\code{~~}&\DoWithAllOf{&\item}{% + \codebd{apples,}\codebd{pears,}\codebd{peaches}}\\ + &\end{enumerate} + \end{quote} + Recall that `\item' at most takes an \emph{optional} argument. + \item <cmd> must \strong{not take more than one} parameter. + %% see def. \DoWith + A different package will support multi-parameter macros. +\end{enumerate} + +% Rather, ``list" is a term from \Wikienref{computer science} here. +% It corresponds to the notion of ``sequence" in mathematics +% and to ``word" with formal languages. +% +% 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 gullet."\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} +%% <- 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 +(very much) extend the functionality of 'dowith'. +Also the `\ForEach'\texttt{\dots\unkern\@} macros of %% \@ 2012/06/03 +\ctanpkgref{forarray} (Christian Schr\"oppel) seem to extend +the present `\DoWith'\texttt{\dots\unkern\@} commands. %% \@ 2012/06/03 +Moreover, Ahmed Musa describes such commands as %% 2012/06/03 +``Parsing \qtd{tsv} lists" in documenting his +\ctanpkgref{catoptions} package. +\ctanpkgref{moredefs} (Matt Swift) provides list handling commands +like the few that are here.\footnote{\ctanpkgref{arrayjobx}% %% % 2012/11/05 + provides somewhat ``exotic" handling of ``lists".} %% 2012/05/10 +%% 2012/11/05: +---In October 2012, Ahmed Musa's \ctanpkgref{loops} appeared on +\acro{CTAN}, offering loops of several ``categories" about as those +that are listed below, very elaborate.% +%% /2012/11/05 +% (I~do not want to load that much.) +%% <- 2012/11/04 -> +---I do not want to load that much. I need and only need something +excessively simple, very few lines of code, as presented in +Section~\ref{sec:implement}. The next sections somewhat point +out single features of loop constructs that I do not want to have. + +\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 +\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 gullet"), +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{``For" Loops vs.\ ``Foreach" Loops} %% mv. up 2012/05/20 +What about \ctanpkgref{forloop} (Nick Setzer), +\ctanpkgref{multido} (Timothy Van Zandt, Rolf Nie\-praksch, Herbert +Vo\ss), and \ctanpkgref{xfor} (Nicola Talbot)? + +'xfor' is just a reimplementation of `\@for'. +'forloop' and 'multido' are more close to ``real \qtd{for} loops" +(cf.\ \wikienref{for loop}{\meta{Wikipedia}}). +Loops of the latter kind go through a certain set as well, +but such sets rather consist of \emph{numbers} and are exhausted +by incrementing (or also decrementing) variables +\wikienref{Loop counter}{(counters).} +This is essentially not needed +(neither helpful) %% 2012/05/20 +when a list literally is +\emph{enumerated}---such loops are distinguished as +\wikienref{Foreach loop}{``foreach loops."} %% 2012/05/19 + +\subsection{Iterators} %% add. heading 2012/05/17b +So `\DoWith' and |\@tfor| rather provide ``foreach" loops. +A major difference between them is that the latter uses a +\wikienref{For loop}{``loop variable"} or +%%% rather %% rm. 2012/05/20 +\wikienref{Iterator}{``iterator"} to which the elements +of the list are assigned. +`\DoWith<cmd>' does not use such a loop variable +or such assignments and thus is ``expandable" at least when <cmd> +(and the elements, depending on <cmd>) are expandable. +On the other hand, `\@tfor' applies some procedure to the list +elements without needing a \emph{name} for the procedure +(or a \emph{macro} storing the procedure). +% +I wondered whether behind \LaTeX's +`\@tfor' (and `\@for') there was an ``ideological" consideration +such as ``A loop must have a loop variable!"\pdots +% However, avoiding usage of a macro name +% (to store the ``loop body" code) %% 2012/05/18 +% and a macro parameter +% (to incorporate the list item into the body code) %% 2012/05/18 +% may have been a good reason. +%% <- 2012/05/19 + +%% 2012/05/20: +Hopefully more clearly on ``loop variable" vs.\ our approach: +In order to run +\[<code-before><item><code-after>\] +on each <item> of a <list>, \emph{we here} +% \[ +\begin{equation} + \mbox{define} \quad `\do' \quad \mbox{as} \quad + `#1'\;\to\;`<code-before>#1<code-after>' +\end{equation} +% \] +and then run `\do{<item>}' for each <item> in <list>,\footnote{Cf.~description + of procedure in terms of tokens in Section~\ref{sec:steps}.} +\begin{equation} + \mbox{always replacing}\quad `\do{<item>}'\quad \mbox{by}\quad `\do{<item>}\do'. +\end{equation} +(`\do' is only an example command that 'dowith' supports especially.) +% The ``received" approach from ``usual" programming languages, +% \file{latex.ltx}, and its followers is +In \file{latex.ltx} instead, we find things like +% \[ +\begin{equation} + \label{eq:tfor} + `\@tfor\@tmp:=<list>\do{<code-before>\@tmp<code-after>}' +\end{equation} +% \] +where `\@tmp' is a \emph{macro} that is set to be <item> at each +iteration of the loop, by +\begin{equation} + `\def\@tmp{<item>}' +\end{equation} +within `\@tforloop'. After that, +\begin{equation} + \label{eq:code-tmp-code} + `<code-before>\@tmp<code-after>' +\end{equation} +from \ref{eq:tfor} is run.---\ref{eq:code-tmp-code} like +\ref{eq:tfor} is stored in a larger macro. `\do' in \ref{eq:tfor} +does not act as a macro, it just delimits a macro parameter +in order give a feeling of some familiar programming structure. +This organisation of macros is fine when the loop body code +is only used by the containing macro, while the 'dowith' approach +to store the ``loop body" in an own macro has been useful when +the loop body code also is used for different purposes +or when it has been introduced before I thought of using it +in a loop. +% \[\mbox{defining}\;`\@tmp'\;\mbox{as}\;<item>\quad \mbox{and run} \quad +% `<code-before>\@tmp<code-after>'\] +% for each <item> in <list>. + +Note that this only was an example. In general, <item> may appear +more than once in the ``loop body." + +``Expandability" by \emph{avoiding} something iterating `\def\@tmp{<item>}' +and doing iteration in \TeX's gullet (`\do' or so must have been defined earlier) +is essential especially within \cs{write}. +Assignments do not work there. A major motivation for developing +'dowith' developed with the \ctanpkgref{blog} package +that \cs{write}s \acro{HTML} code. +Assignments happen in ``\TeX's stomach." %% 2012/11/04 +That place might be called the +``instruction buffer" to which %% cmd -> instr 2012/11/04 +the ``expansion processor" moves items from the incoming token buffer +that cannot be expanded (any more). + +\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 +`\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. + +\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\footnote{Using Kabelschacht's suggestion, cf.\ Section~\ref{sec:kabel}} +version of it in `latex.ltx'. It is \emph{not} expandable +since it starts with an assignment for `\body' (Plain \TeX) or +`\iterate' (`latex.ltx'), +%% add. 2012/05/20: +and then some assignments are needed to stop the loop, +such as incrementing or decrementing a \emph{counter.} +As to the programming structure, it is very simple and general, +I think any kind of loop can be implemented by this +(apart from nested loops). E.g., I realize\footnote{2012-05-20} +that even a ``foreach" loop could be implemented by managing +a list macro, e.g., using \LaTeX's internal `\@next'. +%% rm. 2012/05/20: +% that you cannot probably +% what kind of loops it addresses. However, the applications +% I have seen have been ``for" or (rather) ``while" loops. +% ``While" loops can ``emulate" ``for" and ``foreach" loops +% by having the ``incrementation" method or the ``enumeration" method in +% their body. This is quite obvious for ``for" loops, not quite so for +% ``foreach" loops; which for practical application (in my view) means +% that neither \LaTeX/\TeX's `\loop' macro nor in general ``while" loops +% is/are very helpful for implementing ``foreach" loops, +% as rather `\DoWith' and similar constructions are. +% The reason for this is (as it seems to me) is that you +% (a human being) can much more easily enumerate (``list") +% the items of a list (you have in mind) than define the \emph{method} +% that (allegedly) is behind your enumeration. \ \meta{Example:} +% \[`\DoWithAllOf{\printsamplearea}{\red\green\blue}'\] +% ---\emph{how} (according to what ``method"?) did you ``proceed" from +% `\red' to `\green' and from `\green' to `\blue'? + +\subsection{Without Iterator and Separators} %% add. heading 2012/05/17b +%% 2011/11/07: +In \LaTeX's \ctanpkgref{tools} bundle, \ctanpkgref{xspace} +%% 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. +%% 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 %% 2012/05/17b +% \newpage %% 2012/05/19 +\section{Implementation} %% 2012/05/10 +\label{sec:implement} +\subsection{Package File Header (Legalese)} %% sub 2012/05/10 +\input{dowith.doc} + +\newpage %% 2012/06/04 +\section{Ack.: 25 Years of Kabel\-schacht's \cs{expandafter}} %% 2012/05/20 +\label{sec:kabel} +The essential idea of 'dowith' and `\DoWith' is +\[`\if<code>\expandafter<one-token>\fi'\] +% Alan Jeffrey: \tugbartref{tb11-2/tb28jeffrey}{``Lists in \TeX's Mouth,"} +% \acro{TUG}boat Vol.~11 (1990), No.~2, pp.~237--245), +% \urlhttpref{tug.org/TUGboat/tb11-2/tb28jeffrey.pdf}.} +It was described by \textsc{Alois Kabelschacht} as +\tugbartref{tb08-2/tb18kabel}{``&\expandafter\ vs.\ &\let\ and &\def\ + in Conditionals and a Generalization of PLAIN's &\loop"} +in \acro{TUG}boat Vol.~8 (1987), No.~2, pp.~184f.\ +(a little more than one column).\foothttpurlref{tug.org/TUGboat/% + tb08-2/tb18kabel.pdf} +See some German biographical notes on Kabelschacht in the +\wikideref{Benutzer:RolteVolte/Alois_Kabelschacht}{German Wikipedia.}\foothttpurlref{%% + de.wikipedia.org/wiki/Benutzer:RolteVolte/Alois\string_Kabelschacht} +It seems to me that Knuth didn't note this application of `\expandafter' +in \TTb.\footnote{% %% 2012/05/22 + However, the paper \meta{\qtd{uses the fact that the expansion of both + \cs{else ... }\cs{fi} and \cs{fi} is empty.}} In \TTb\ I only find + %% &\else and &\fi failed + \meta{\qtd{The ``expansion" of a conditional is empty}} on page~213.} +It was then applied in many macros of \file{latex.ltx}, +cf.~\file{source2e.pdf}. + +\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 +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 ... +2012/05/19 r0.21d braces and commands applicable +2012/05/20 corrections, clarifications, reorder; + especially examples for `dowith' vs. + `\@tfor'; remarks about `\loop' corr.: + how to `foreach' ...; Kabelschacht +2012/05/22 r0.21e Kabelschacht vs. TeXbook +2012/06/03 r0.21f cf. `catoptions'; \dots\unkern\@, vs.\ +2012/06/07 r0.22a added \,s in "?typein ..." +2012/07/25 r0.3 "\csname name construct"? +2012/11/02ff. gullet, plainpkg, more modifications +2012/11/19 mod. on "mouth" (bibleref-mouth) +2012/11/27 r0.3a plainpkg +2015/11/14 rm. "(five)" & \ctanpkgdref, code in two + footnotes, don't use hyperref draft diff --git a/macros/generic/dowith/docsrc/fdatechk.tex b/macros/generic/dowith/docsrc/fdatechk.tex new file mode 100644 index 0000000000..afae09a988 --- /dev/null +++ b/macros/generic/dowith/docsrc/fdatechk.tex @@ -0,0 +1,12 @@ +\ProvidesFile{fdatechk.tex}[2015/11/14 dowith filedate checks] +%% load earlier: +%\RequirePackage{filedate,filesdo} +%\UseReferenceDate{\thepdfmoddate} +\ModDates +\DatesDiffErrors +\FileDateAutoChecks %% 2012/12/20 +\DoWithBasesExts\ReadFileInfos{ + dowith,domore}{sty,tex} +\ReadFileInfos{dowith.RLS,fdatechk.tex} +\DatesDiffWarnings %% 2015/11/14 +\CheckDateOfToday{dowith.RLS} %% corr. 2015/05/22 diff --git a/macros/generic/dowith/docsrc/srcfiles.tex b/macros/generic/dowith/docsrc/srcfiles.tex new file mode 100644 index 0000000000..512b8bda8c --- /dev/null +++ b/macros/generic/dowith/docsrc/srcfiles.tex @@ -0,0 +1,23 @@ +\ProvidesFile{srcfiles.tex}[2015/11/14 file infos -> SrcFILEs.txt] +\RequirePackage[r,wrap]{nicefilelist}[2012/05/20] +\RequirePackage{filedate,filesdo} +\input{plainpkg} +\MaxBaseEmptyList* +%\FileDateAutoChecks +\ReadFileInfos{dowith.RLS} +%% packages: +\ReadPackageInfos{dowith,domore} +%% documentation: +\ReadFileInfos{dowith,domore} +\ReadFileInfos{srcfiles,fdatechk} %% adding fdatechk 2013/03/23 +%% documentation settings and auxiliaries: +%\NoFileDateAutoChecks +\FileListRemark[ --]{---USED.---} +\ReadPackageInfos{catchdq,fifinddo,makedoc,niceverb} + %% ^^^^^^^^ 2015/11/14 +\ReadFileInfos{makedoc.cfg,mdoccorr.cfg} +\NoStopListInfos[SrcFILEs.txt] +%\DatesDiffWarnings +%\CheckDateOfToday{dowith.RLS} +\input{fdatechk} +\stop diff --git a/macros/generic/dowith/domore.sty b/macros/generic/dowith/domore.sty new file mode 100644 index 0000000000..176bf4a2c8 --- /dev/null +++ b/macros/generic/dowith/domore.sty @@ -0,0 +1,164 @@ + \input plainpkg +\ProvidesPackage{domore}[2015/09/17 v0.32 dowith extended (UL)] +%% Copyright (C) 2012 2013 2015 Uwe Lueck, +%% http://www.contact-ednotes.sty.de.vu +%% -- author-maintained in the sense of LPPL below -- +%% +%% This file can be redistributed and/or modified under +%% the terms of the LaTeX Project Public License; either +%% version 1.3c of the License, or any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% We did our best to help you, but there is NO WARRANTY. +%% +%% Please report bugs, problems, and suggestions via +%% +%% http://www.contact-ednotes.sty.de.vu +%% +\PushCatMakeLetterAt %% 2015/09/17 +%% == With \LaTeX, extend 'dowith''s \cs{setdo} == +%% %% mod. 2012/11/06: +%% The original 'dowith' offers |\setdo{<do>}| +%% for defining a one-parameter macro `\do' expanding to <do>. +%% The present package allows applying a <digit>-parameter macro +%% (maybe `\do', <digit> being 2, 3, or ...) +%% to a list of "brace groups" where each brace group +%% contains <digit> arguments. If \LaTeX\ is present ... +\ifltx +%% ... the following extension +%% \[|\setdo[<digit>]{<do>}]|\] +%% of the basic 'dowith' version +%% can be used to define a <digit>-parameter macro `\do'. +%% You also can equip `\do' with an initial optional argument by +%% \[|\setdo[<digit>][<default>]{<do>}]|\] +%% The next two moves allow loading the package +%% independently of 'dowith' (overriding its definition of `\setdo') +%% as well as using the package +%% with a format that has not defined `\do' before. +%% The first parameter of `\do' may even be \emph{optional.} + \let\setdo\relax \let\do\empty + \newcommand*{\setdo}[1][1]{\renewcommand\do[#1]} +\fi +%% +%% == Auxiliaries == +%% |\@firstsecondoftwo{<balanced-1>}{<balanced-2>}| \ +%% is a variant of \LaTeX's `\@firstofone{<balanced>}' for +%% \emph{two} arguments. It just removes outer braces +%% from each of the two arguments (provided it has outer braces), +%% resulting in \[<balanced-1><balanced-2>\] +\long\def\@firstsecondoftwo#1#2{#1#2} +%% % |\@secondfirstoftwo<arg-1><arg-2>| results in <ark-2><ark-1> +%% % where <ark-1> is ... +%% % [TODO declare "meta-function removing braces"---in 'dowith' documentation] +%% % (<arg-1>, <arg-2> must not contain `\par' tokens so far---TODO): +%% |\@secondfirstoftwo{<balanced-1>}{<balanced-2>}| +%% \emph{additionally} interchanges the two arguments +%% (after removing braces): +\long\def\@secondfirstoftwo#1#2{#2#1} +%% Our main application is using it as an extended `\expandafter' +%% before `\fi': +%% \[`\@secondfirstoftwo{<do>}\fi'\] +%% will expand to +%% \[`\fi<do>'\] +%% This won't work with `\else' in place of `\fi'. +%% +%% == Enhanced \cs{DoWith} == +%% Here comes a more powerful variant of 'dowith''s `\DoWith'. +%% Instead of iterating a single "command" <cmd> +%% on an arglist <args> by +%% \[`\DoWith{<cmd>}<args>\StopDoing'\] +%% (cf. `dowith.pdf'), the present `\DoWith' can have a +%% more complex first argument. If <args> consists +%% of some brace groups the first of which is {<farg>} +%% so that <args> is +%% \[`{<farg>}<rgs>'\] +%% ---<rgs> being the remaining arglist--- +%% \[|\DoWith{<repeat>}<args>\StopDoing|\] +%% works like +%% \[`<repeat>{<farg>}\DoWith{<repeat>}<rgs>\StopDoing'\] +%% and so on---a recursive explanation. Or if <args> is +%% \[`{<arg-1>}{<arg-2>}'\dots`{<arg-n>}'\] +%% ($n$ items), the result is like +%% \[`<repeat>{<arg-1>}<repeat>{<arg-2>}'\dots`<repeat>{<arg-n>}'\] +%% The actual definition is: +\def\DoWith#1#2{% + \ifx\StopDoing#2\empty %% not \@empty for Plain 2012/11/05 + \else\@secondfirstoftwo{#1{#2}\DoWith{#1}}\fi} +%% In order to \strong{use} the remaining definitions from \strong{'dowith' +%% together with the present package}, %% \strong 2012/11/06 +%% load `dowith.sty' before `domore.sty'. +%% +%% (v0.32:) |\StopDoing| must be provided in case 'dowith' +%% is not loaded at all. Being "undefined" is very +%% bad when `\DoWithMore' is used for a list of \emph{assignments.} +%% As in 'dowith', we assume that no argument starts with something +%% that has the same meaning as `\DoWith' itself: +\let\StopDoing\DoWith +%% +%% == Applications of \cs{DoWith} == +%% `\DoWith' still is somewhat auxiliary. What I have used in practice, +%% are the following definitions. +%% +%% |\DoWithMore{<repeat>}<args>\StopDoing| %% was \DoMore 2015/05/22 +%% with <args> as above +%% "unpacks" each arglist item so that <repeat> may be a macro +%% with more than one argument---say, <digit> arguments. +%% Then <f-arg> or <arg-1>, as well as <arg-2> $\dots$ <arg-n>, +%% should provide an arglist consisting of <digit> items. +\def\DoWithMore#1{\DoWith{\@firstsecondoftwo{#1}}} +%% Now I use metavariable <do> instead of <repeat>. +%% We consider some "separator" material <sep> to be inserted +%% between instances of applying <do> to an item of <args>. +%% We want to get +%% \[`<do>{<arg-1>}<sep><do>{<arg-2>}<sep>'\dots`<sep><do>{<arg-n>}'\] +%% This is achieved simply by starting with +%% \[`<do>{<farg>}'\] +%% and then proceeding as with +%% \[`\DoWith{<sep><do>}<rgs>\StopDoing'\] +%% And that's what |\DoSeparateWith{<do>}{<sep>}<args>\StopDoing| does: +\def\DoSeparateWith#1#2#3{#1{#3}\DoWith{#2#1}} +%% |\DoSeparateWithMore{<do>}{<sep>}<args>\StopDoing| combines +%% the two previous things, inserting separator material <sep> +%% and unpacking the nested arg\-lists: +\def\DoSeparateWithMore#1#2{% %% wieder 2012/06/05 + \DoSeparateWith{\@firstsecondoftwo{#1}}{#2}} +%% My main application is that <do> is a link macro with arguments +%% <target> and <text> and that <sep> is \qtdcode{~\string|~} +%% (or some tie variant) to get a horizontal list of links like +%% \[\def|{$\vert$}\mbox{<text-1> | <text-2> | \dots | <text-n>}\] +%% +%% == Without \cs{StopDoing} == %% 2013/03/20, mv. 2013/03/22 +%% The following enhancements of 'dowith' are provided by %% 2013/03/22 +%% v0.31. +%% +%% |\DoWithAllOf{<repeat>}{<list>}| works like +%% \[`\DoWith{<repeat>}<list>\StopDoing'\] +%% as in 'dowith', but now with a more general first argument: +\def\DoWithAllOf#1#2{\DoWith{#1}#2\StopDoing} +%% |\DoWithAllIn{<repeat>}{<list-macro>}| works as in 'dowith' too +%% and needs the <repeat> enhancement too: %% 2013/03/21 +\def\DoWithAllIn#1#2{% + \expandafter \@secondfirstoftwo \expandafter {#2}{\DoWith{#1}}% + \StopDoing} +%% +%% == Leaving and History == +\PopLetterCatAt +\endinput + +VERSION HISTORY +v0.1 2012/01/17 developed in `texblog.fdf' + (using \[re]newcommand*) +v0.2 2012/08/07 own file `domore.sty', \def's only + 2012/08/08 dealing with "more" \setdo +v0.3 2012/11/05 using `plainpkg'; removing old % code + (see stored v0.2); auxiliaries \long + 2012/11/06 doc.: more on \setdo (<digit>, opt. arg.), + usage with `dowith' \strong + 2012/11/18 doc.: adjusted for `catchdq'; reworking for + \DoWith; \DoWithMore, \DoSeparateWith + 2012/11/19 doc.: \DoSeparateWithMore +v0.31 2013/03/20 \DoWithAllOf + 2013/03/21 \DoWithAllIn + 2013/03/22 moving down new section, mod. doc. +v0.32 2015/05/22 doc. fix \DoWithMore; providing \StopDoing + 2015/09/17 \PushCatMakeLetterAt! diff --git a/macros/generic/dowith/dowith.sty b/macros/generic/dowith/dowith.sty new file mode 100644 index 0000000000..a4625aade3 --- /dev/null +++ b/macros/generic/dowith/dowith.sty @@ -0,0 +1,204 @@ +\def\filename{dowith} \def\fileinfo{simple list loop (UL)} +\def\filedate{2012/11/05} \def\fileversion{v0.3} +%% +%% Copyright (C) 2011 2012 Uwe Lueck, +%% http://www.contact-ednotes.sty.de.vu +%% -- author-maintained in the sense of LPPL below -- +%% +%% This file can be redistributed and/or modified under +%% the terms of the LaTeX Project Public License; either +%% version 1.3c of the License, or any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% We did our best to help you, but there is NO WARRANTY. +%% +%% Please report bugs, problems, and suggestions via +%% +%% http://www.contact-ednotes.sty.de.vu +%% +%% == Proceeding without \LaTeX == +%% v0.3 mainly replaces imitating the +%% \CtanPkgRef{german}{german.sty} approach to genericity +%% by \ctanpkgref{plainpkg}: +\input plainpkg +\ProvidesPackage{\filename}[\filedate\space + \fileversion\space \fileinfo] +\PushCatMakeLetterAt +%% If \LaTeX\ is not present ... +\ifltx \else +%% ... an old version of its `\in@' is introduced. +%% It is bad as a subword test +%% (false positive cases, cf. \CtanPkgRef{nicetext}{fifinddo} +%% documentation), but 'dowith' will check for single tokens only. +%% If \LaTeX\ \emph{is} present, +%% on the other hand, `\ifin@' is recognized while skipping +%% `false' parts of conditionals, without being matched +%% by some `\fi' before the next `\else', so I hide it by `\csname': + \expandafter\newif\csname ifin@\endcsname + \def\in@#1#2{% + \def\in@@##1#1##2##3\in@@{% + \ifx\in@##2\in@false\else\in@true\fi}% + \in@@#2#1\in@\in@@} +\fi +%% +%% == Applying a Command == %% 2011/11/07 +%% \label{sec:apply} +%% === Core === +%% \label{sec:core} +%% |\DoWith{<cmd>}<list>\StopDoing| applies <cmd> to all elements +%% of <list>. An element of <list> (after tokenizing) +%% may be either a single token or a group `{<balanced>}'. +\def\DoWith#1#2{% + \ifx\StopDoing#2\empty +%% The previous `\empty' (replacing `%') is a bug fix as of v0.22 +%% (June 2012), %% 2012/11/05 +%% while in my extension draft I already had it in January 2012. +%% It allows ``empty" arglist items \qtd{\lbtok\rbtok}. +%% Before v0.22, such an empty brace group would have resulted +%% in comparing `\StopDoing' with `\else', so \qtd{\lbtok\rbtok} +%% would have had the same effect as `\StopDoing', the token text +%% after `\else' until `\fi' would have been skipped. +%% Instead, the user may have a reason to allow empty arguments\slash +%% brace groups. + \else#1{#2}\expandafter\DoWith\expandafter#1\fi} +%% |\StopDoing| delimits the list: +\let\StopDoing\DoWith +%% ... something arbitrary that is not expected to occur in a list. +%% With \[`\let\StopDoing*'\] instead, the star would end lists. +%% +%% |\DoWithAllOf{<cmd>}{<list>}| works like +%% \[`\DoWith{<cmd>}<list>\StopDoing':\] +\def\DoWithAllOf#1#2{\DoWith#1#2\StopDoing} +%% +%% === `&\do' being the Command === +%% \label{sec:do} +%% When the <list> is worked at a single time in the \TeX\ run +%% where assignments are possible, instead of introducing a new +%% macro name for <cmd> you can use `\do' for <cmd> as a +%% ``temporary" macro and define it right before +%% \[`\DoWith{\do}<list>\StopDoing'\] +%% However, we provide \[|\DoDoWith{<cmd>}<list>\StopDoing|\] +%% as a substitute for the former line that at least saves one token. +%% For the definition of `\do', we provide +%% |\setdo{<def-text>}|. +%% It works similarly to \[`\renewcommand{\do}[1]{<def-text>}',\] +%% so <def-text> should contain a `#1': +\def\setdo{\long\def\do##1} +%% With |\letdo<cmd>| that is provided next where <cmd> is defined +%% elsewhere, you could type +%% \[`\letdo<cmd>\DoDoWith<list>\StopDoing'\] +%% It seems to me, however, that you better type +%% \[`\dowith<cmd><list>\StopDoing'\] instead. +%% So I provide `\letdo' although I consider it useless here. +%% It is provided somewhat for the sake of ``completeness," +%% thinking that it might be useful at other occasions such as +%% preceding `\dospecials'. +\def\letdo{\let\do} +%% |\DoDoWith| has been described above: +\def\DoDoWith{\DoWith\do} +%% By analogy to `\DoWithAllOf', we provide +%% |\DoDoWithAllOf{<list>}|: +\def\DoDoWithAllOf{\DoWithAllOf\do} +%% +%% === Expand List Macro === +%% The former facilities may be quite useless +%% as such a <list> will not be typed at a single place in the +%% source code, rather the items to run <cmd> on may be collected +%% occasionally when some routines run. The elements may be collected +%% in a macro <list-macro> expanding to <list>. +%% So we provide \[|\DoWithAllIn{<cmd>}{<list-macro>}|\] +%% (or `\DoWithAllIn<cmd><list-macro>'). +%% There is no need to type `\StopDoing' here: +\def\DoWithAllIn#1#2{% + \expandafter\DoWith\expandafter#1#2\StopDoing} +%% |\DoDoWithAllIn{<list-macro>}| saves a backslash or token +%% for `\do' as above in Sec.~\ref{sec:do}: +\def\DoDoWithAllIn{\DoWithAllIn\do} +%% +%% +%% == Handling List Macros == +%% === Initializing === +%% Here is some advanced `\let<cmd>\empty', perhaps a little +%% irrelevant for practical purposes. Both +%% \[|\InitializeListMacro{<list-macro>}|\] and +%% \[|\ReInitializeListMacro{<list-macro>}|\] attempt to ``empty" +%% <list-macro>, and when we don't believe that \LaTeX\ has been +%% loaded, both do the same indeed. Otherwise the first one +%% complains when <list-macro> seems to have been used earlier +%% while the second complains when <list-macro> seems \emph{not} to +%% have been used before: +\ifltx %% v0.3 + \def\InitializeListMacro#1{\@ifdefinable#1{\let#1\empty}} + \def\ReInitializeListMacro#1{% + \edef\@tempa{\expandafter\@gobble\string#1}% + \expandafter\@ifundefined\expandafter{\@tempa}% + {\@latex@error{\noexpand#1undefined}\@ehc}% + {\let#1\empty}} +\else + \def\InitializeListMacro#1{\let#1\empty} %% not \@empty 2011/11/07 + \let\ReInitializeListMacro\InitializeListMacro +\fi +%% |\ToListMacroAdd{<list-macro>}{<cmd-or>}| +%% appends <cmd-or> to the replacement token list of <list-macro>. +%% <cmd-or> may either be tokenized into a single token, +%% or it is some `{<balanced>}'. +\def\ToListMacroAdd#1#2{\DefExpandStart#1{#1#2}} +\def\DefExpandStart#1{\expandafter\def\expandafter#1\expandafter} +%% +%% === Testing for Occurrence of a Token === +%% |\TestListMacroForToken{<list-macro>}{<cmd>}| +%% sets `\in@true' when <cmd> occurs in <list-macro> +%% and sets `\in@false' otherwise: %% 2011/11/07 +\def\TestListMacroForToken#1#2{% + \expandafter \in@ \expandafter #2\expandafter{#1}} +%% Indeed I removed an earlier `\IfTokenInListMacro', +%% now it's a kind of compromise between having a shorthand macro +%% below and a generalization for users of the package. +%% +%% === Adding and Removing === +%% |\FromTokenListMacroRemove{<list-macro>}{<cmd>}| +%% removes the token corresponding to <cmd> from the list +%% stored in <list-macro> +%% (our parsing method does not work with braces): %% 2011/11/07 +\def\FromTokenListMacroRemove#1#2{% +%% I am not happy about defining \emph{two} parser macros, +%% but for now ... + \TestListMacroForToken#1#2% + \ifin@ + \def\RemoveThisToken##1#2{##1}% + \expandafter \DefExpandStart + \expandafter #1\expandafter {% + \expandafter\RemoveThisToken #1}% +%% TODO warning otherwise? + \fi} +%% %% 2011/11/07: +%% ... but this only removes a single occurrence ... +%% \[|\InTokenListMacroProvide{<list-macro>}{<cmd>}|\] +%% avoids multiple entries of a token +%% by \emph{not} adding anything when <cmd> +%% already occurs in <list-macro> (again, this does not work with +%% braces, try `\in@{{}}{{}}'). +\def\InTokenListMacroProvide#1#2{% + \TestListMacroForToken#1#2% + \ifin@ \else %% TODO warning? + \ToListMacroAdd#1#2% + \fi} +%% +%% +%% == Leaving and History == +\PopLetterCatAt %% v0.3 +\endinput + +VERSION HISTORY +v0.1 2011/06/23/28 stored separately +v0.2 2011/11/02 simpler, documented + 2011/11/03 corrected \if/\else for init + 2011/11/07 \TestListMacroForToken, \InListMacroProvide; + doc.: \pagebreak, structure + 2011/11/19 modified LaTeX supplements +v0.21 2012/05/14 fix for "generic" and `typeoutfileinfo': + @ before ...! +v0.21a 2012/05/19 \labels sec:apply, sec:core; \pagebreak? +v0.22 2012/06/04 allow {} items +v0.3 2012/11/05 updating copyright, using `plainpkg', + rewording documentation there |