diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/dowith/dowith.tex')
-rw-r--r-- | Master/texmf-dist/source/generic/dowith/dowith.tex | 264 |
1 files changed, 183 insertions, 81 deletions
diff --git a/Master/texmf-dist/source/generic/dowith/dowith.tex b/Master/texmf-dist/source/generic/dowith/dowith.tex index a0cb6ac3099..eb099d1e5e3 100644 --- a/Master/texmf-dist/source/generic/dowith/dowith.tex +++ b/Master/texmf-dist/source/generic/dowith/dowith.tex @@ -1,17 +1,17 @@ -\ProvidesFile{dowith.tex}[2012/06/03 documenting dowith.sty] +\ProvidesFile{dowith.tex}[2012/11/19 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 + 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{16}%% 2011/09/06 + \MakeJobDoc{18}%% 2012/11/05 for v0.3 {\SectionLevelTwoParseInput} } \documentclass[fleqn]{article}%% TODO paper dimensions!? \input{makedoc.cfg} %% shared formatting settings @@ -25,7 +25,11 @@ 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}} \makeatletter %% etc. 2012/05/17b +%% TODO `actcodes'!? 2012/11/02 \newcommand*{\GetOtherChar}[2]{% \@ifdefinable#1{% \edef#1{\expandafter\@gobble\string#2}}} @@ -67,9 +71,10 @@ \newcommand*{\pdots}{~.\kern\fontdimen3\font .\kern\fontdimen3\font. } \providecommand*{\Chi}{\mathrm{X}} +\renewcommand*{\httpprefix}{\theHTTPprefix} \begin{document} \maketitle -\begin{MDabstract}\noindent +\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$>$ @@ -78,11 +83,12 @@ This package provides macros for applying a % 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. +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. +% 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: @@ -90,14 +96,19 @@ Loop and list macros in other packages are discussed. % 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}. +% 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. \MDaddtoabstract{Related packages} \let\pkg\ctanpkgref \pkg{catoptions}, -\pkg{etextools}, \pkg{etoolbox}, \pkg{forarray}, -\pkg{forloop}, \pkg{multido}, \pkg{moredefs}, \pkg{lmake}, +\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 @@ -110,17 +121,21 @@ 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})\foothttpurlref{ctan.org/pkg/catcodes} +must be installed as well. -With \LaTeX, -you load 'dowith.sty' (as usually) by -\begin{verbatim} - \usepackage{dowith} -\end{verbatim} -below the `\documentclass' line(s) and above `\begin{document}'. -However, the package can also be used with other formats, just -\begin{verbatim} - \input dowith.sty -\end{verbatim} +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} @@ -241,52 +256,117 @@ are ignored when a macro looks for its argument. %% 2012/05/17b % % 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{% - Alan Jeffrey: \tugbartref{tb11-2/tb28jeffrey}{``Lists in \TeX's Mouth,"} - TUGboat Vol.~11 (1990), No.~2, 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). +% 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" 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. +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 mouth +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 mouth, maybe apart from ``primitive" - tokens that have a ``pre-assigned meaning" when a \TeX run + 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 @@ -310,7 +390,9 @@ 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 +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} @@ -331,32 +413,35 @@ for brevity.\footnote{I am suggesting the question mark for named tokens 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. +%% 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 mouth by ``tokenization" as described above, +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 mouth ``from within," -by the manipulation inside \TeX's mouth. +appear in \TeX's gullet ``from within," +by the manipulation inside \TeX's gullet. More formally, those manipulations are called ``expansion," -and \TeX's mouth can be conceived of as a \emph{token buffer} +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 mouth that +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 mouth +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 construct. +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 mouth, +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}) @@ -562,10 +647,11 @@ In ``retrospect," the result of tokenizing \ref{eq:toks} should be \end{equation} and the intention is that it works like \begin{equation} - \ntok{typein}.\codelb.&a.\coderb\, - \ntok{typein}.\codelb.&a.\coderb\, - \ntok{typein}.\codelb \ntok{a}.\coderb\, - \ntok{typein}.\codelb.&a.\coderb + %% 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.) @@ -583,7 +669,8 @@ the token buffer's content will just be\footnote{If you use \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 ``command buffer," and you should get a screen +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 @@ -612,7 +699,7 @@ Let $\Chi_E$ be the set of character tokens of category code in $E$ Let $\circ$ be the \emph{concatenation} operation among token lists.\footnote{% %% 2012/05/18 - TODO: Define for representations by maps, or: + \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}) @@ -700,7 +787,7 @@ What <cmd>s are allowed? 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: + 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, @@ -735,7 +822,7 @@ What <cmd>s are allowed? % 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 +% 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 @@ -781,9 +868,19 @@ 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} +like the few that are here.\footnote{\ctanpkgref{arrayjobx}% %% % 2012/11/05 provides somewhat ``exotic" handling of ``lists".} %% 2012/05/10 -(I~do not want to load that much.) +%% 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 @@ -793,7 +890,7 @@ with lists without separators. By contrast, \LaTeX's |\@for| deals with 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"), +However, when \LaTeX\ analyzes such lists (in ``\TeX's gullet"), it uses representations by \emph{character tokens} of them. %% moved here 2012/05/17b: @@ -906,13 +1003,14 @@ 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 mouth (`\do' or so must have been defined earlier) +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 somewhere \emph{behind} ``\TeX's mouth." -That place might be called the ``command buffer" to which +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). @@ -1004,12 +1102,12 @@ Addition and removal commands are provided as well. 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,"} -% TUGboat Vol.~11 (1990), No.~2, pp.~237--245), +% \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 TUGboat Vol.~8 (1987), No.~2, pp.~184f.\ +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 @@ -1054,3 +1152,7 @@ VERSION HISTORY 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) |