1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
|
\ProvidesFile{dowith.tex}[2012/06/03 documenting dowith.sty]
\title{%%%\kern-\baselineskip
\textsf{\huge dowith.sty}\\---\\Apply Command to
% Elements of Lists without Separators\,---\,%%% 2012/05/14
% and without Iterator\thanks{This
%% 2012/05/15, "in" 2012/05/18:
Each Item \\ in a List of Arguments in ``\TeX's Mouth"\thanks{This
document describes version
\textcolor{blue}{\UseVersionOf{\jobname.sty}}
of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
{ \RequirePackage{makedoc} \ProcessLineMessage{}
\renewcommand*\mdSectionLevelOne{\string\subsection}
\renewcommand*\mdSectionLevelTwo{\string\subsubsection}
\MakeJobDoc{16}%% 2011/09/06
{\SectionLevelTwoParseInput} }
\documentclass[fleqn]{article}%% TODO paper dimensions!?
\input{makedoc.cfg} %% shared formatting settings
% \ReadPackageInfos{dowith}
\usepackage{dowith} %% 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
\makeatletter %% etc. 2012/05/17b
\newcommand*{\GetOtherChar}[2]{%
\@ifdefinable#1{%
\edef#1{\expandafter\@gobble\string#2}}}
\makeatother
\GetOtherChar\codeLB\{
\GetOtherChar\codeRB\}
% \GetOtherChar\codeSP\ % %% ???
{\MakeOther\ \xdef\codeSP{ }}
\newcommand*{\codelb}{\code\codeLB}
\newcommand*{\coderb}{\code\codeRB}
\newcommand*{\codesp}{\code\codeSP}
\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}}
\begin{document}
\maketitle
\begin{MDabstract}\noindent
This package provides macros for applying a
%% mod. 2012/05/15:
% ``command" <cmd> to all items of a list $<arg-1><arg-2>\dots<arg-$n$>$
``command" to all items in a ``list of possible macro arguments," %% v0.21a
% in ``\TeX's mouth,"
% such as `\DoWithAllIn{<cmd>}{<list-macro>}',
and also for extending and reducing macros storing such lists.
``Brace groups" are single items of such lists, as opposed to
token lists.
%%% ---pleading for mathematical rigour in \TeX ology!) %% rm. 2012/05/17b
Applications in mind belonged to \LaTeX, but the package should work
with other formats as well.
Loop and list macros in other packages are discussed.
% %% 2012/05/09:
% There is an emphasis on expandability
% %% mod./add. 2012/05/15:
% (no \wikienref{Iterator}{iterator;}
% essential within \cs{write} as with \CtanPkgRef{morehype}{blog.sty}),
% without relying on \CtanPkgRef{e-tex}{$\varepsilon$-\TeX}.
%% 2012/05/18:
Iteration is implemented within ``\TeX's mouth," so works within
`\write' as with \CtanPkgRef{morehype}{blog.sty}. There is no need for
\CtanPkgRef{e-tex}{$\varepsilon$-\TeX}.
\MDaddtoabstract{Related packages}
\let\pkg\ctanpkgref \pkg{catoptions},
\pkg{etextools}, \pkg{etoolbox}, \pkg{forarray},
\pkg{forloop}, \pkg{multido}, \pkg{moredefs}, \pkg{lmake},
\pkg{texapi}, \pkg{xfor}, \pkg{xspace}
\end{MDabstract}
\tableofcontents
% \newpage
\section{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
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}
% \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{\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).
\begin{smallpar}
The ``characters you type" are somewhere in front of ``\TeX's mouth",
while \emph{in} \TeX's mouth, there are \emph{tokens}.
Before \TeX\ \emph{swallows} them, it often manipulates them
in some ways, after they got \emph{into} its mouth.
More formally, \TeX\ has a \emph{character buffer.}
It forms a single token from an initial segment of the buffer content---unless
there is a special situation with blank spaces or something pathological.
When an \emph{escape character}, as the backslash usually is one,
has been noticed recently (that isn't followed by another one immediately),
the character buffer may need to be feeded from more outside,
until it contains enough material to form a token from.
The character(s) \emph{after} the escape character until
some delimiting character form a \emph{string} that is the
\emph{name} of the token that is formed.
What has been used to form a token is removed from the character buffer.
There are \emph{two kinds of tokens} here: \emph{named} tokens
and \emph{character} tokens. ``Named" tokens usually are referred
to as ``control sequence tokens" or just ``control sequences"---I~really
want to avoid those horrible confusions from \TTb.
There never are any ``parameter tokens" in \TeX's mouth
(perhaps unless one considers a one-step macro expansion
a two-or-more-step procedure).
For every \emph{string of characters}, there is exactly one
(possible) \emph{named token} whose name the string is.\footnote{``Possible"
refers to the fact that \TeX\ does not store named tokens anywhere
before they appear in its mouth, maybe apart from ``primitive"
tokens that have a ``pre-assigned meaning" when a \TeX run
starts.---What is more bad with my claim is that
the \TeX\ program by design cannot extend its memory arbitrarily---even
not using the ``cloud''---, so it doesn't support tokens
whose name lengths are above a certain limit.}
It is so common (starting from \TTb) to denote the token whose name
is <string> by \lq\verb+\+<string>\rq. For instance, the token whose
name is `input' is denoted by \qtd{&\input}. On the other hand,
on page~7 of \TTb\ \qtd{&\input} is a ``string of characters."
With this notation, it is already difficult to explain what
the \LaTeX\ command `\DeclareRobustCommand' does or what the difference
between a starred \LaTeX\ command and a starred \LaTeX\ environment is.\footnote{%
A reader knowing \LaTeX\ only thinks that \qtd{\code{&\\\codesp}}
is the result of typing a double backslash and a space
and that \qtd{\cs{equation*}} is the ``command" \cs{equation}
followed by a `*'.}
\TTb\ makes it worse by saying on page~39:
\meta{``A control sequence is considered to be a single object
that is no longer composed of a sequence of symbols."}
So ``it depends" whether \qtd{&\input} is a string of characters or not---it \emph{is
before} tokenization, but \emph{no longer} afterwards.
So if you have two computers and start a \TeX\ run on each of them
with a little difference in time, there will be a moment where
\qtd{&\input} is a string on the one computer but not on the other?
This is like saying \meta{``When we apply the square root function to
the number 4, the number 4 will no longer be the number 4,
it will be the number 2 instead."}
\end{smallpar}
\TTb\ does offer an alternative notation for named tokens: ``boxing;"
so the token whose name is `input' can be denoted by the rather
``graphical" notation \qtd{|input|} (used only exceptionally).\footnote{%
The box notation is introduced on page~38 without explanation,
as if it explained something.}
\emph{I}~would suggest something like
\qtd{\NTOK{input}} for clarity and \qtd{\ntok{input}}
for brevity.\footnote{I am suggesting the question mark for named tokens
since \TeX\ ``must look up the current definition" of a named token
according to \TTbp.~39, while the meaning of character tokens rather
is ``fixed," at least according to \TTbp.~39. However,
\emph{active}-character such as .&~ are in the same situation
as named tokens as to this respect. The dot notation may be fine for them,
though.}
\begin{smallpar}
\emph{Character tokens} get into \TeX's mouth by tokenization
when characters begin the buffer content while \emph{not} scanning
a name for a named token. A single character then is removed from the
character buffer, and a token storing its character code and current
category code is pushed into \TeX's mouth.
Named tokens may get into \TeX's mouth by ``tokenization" as described above,
i.e., they are drawn from the character buffer. But they also can
appear in \TeX's mouth ``from within,"
by the manipulation inside \TeX's mouth.
More formally, those manipulations are called ``expansion,"
and \TeX's mouth can be conceived of as a \emph{token buffer}
that is feeded to the right (or end) by tokenization from the character buffer.
Expansion means that certain tokens in the token buffer are substituted
by other ones. This way tokens may get into \TeX's mouth that
emerged from tokenization a ``long time ago", maybe in a previous
run that created the \emph{format} (\TeX's variant \code{INITEX});
or tokens may appear by some hardwired expansion function.
However, \emph{named tokens} may get into \TeX's mouth
also by \emph{expansion}, never having been drawn by tokenization
and not being hardwired. This happens by the `\csname' name construct.
The input \emph{code} may contain
\[`\csname tupni\endcsname'\]
This may be converted into 7 tokens entering \TeX's mouth,
the first one being \NTOK{csname}, the last one
\NTOK{endcsname}, and five character tokens in between.
Due to some \emph{function} (which I would denote as *\code{csname})
originally associated with the token \NTOK{csname},
those seven tokens then are replaced by \NTOK{tupni},
the named token whose name is `tupni'. It is not required that
the \TeX\ program knows about a token \NTOK{tupni},
neither anybody must type \qtd{&\tupni} in any file.\footnote{These
considerations may not be essential here,
rather a draft for a paper. Using 'dowith',
one better just thinks of the arglist items one actually lists.}
\end{smallpar}
\subsection{Arglists vs.\ Lists of Tokens---Example}
% \subsection{Arglists and 'dowith' \TeX nically}
% In the \TeX nical sense, I think of arglists \emph{and their items}
% as follows. Arglists are lists (or sequences) of tokens.
% What is somewhat difficult is that the \emph{items} of a token list
% usually are \emph{tokens.} Especially, the curly braces in the code
% you type usually are converted into certain \emph{character tokens}
% that are single items of the resulting token list.\footnote{I discover
% this conceptual puzzle 2012-05-16.}
%
% The conceptual trap here may have resulted from denoting lists
% in a \emph{\Wikienref{juxtaposition}} notation.
% In Section~\ref{sec:lists-intuit}, I have written `aa' for a
% ``list" of \emph{two} items. ``List" is rather a \emph{computer science}
% term, its mathematical counterpart rather is the notion of (finite)
% \emph{sequences.} The usual \emph{mathematical} notation for a finite sequence
% writes list items surrounded by \emph{\wikienref{bracket}{brackets}}
% (round---\emph{\Wikienref{parentheses}}---seems to be more common than square,
% also \wikienref{angle brackets}{chevrons} are used).
%
% So the \emph{string} `aa' can be written more clearly---mathematically---as
% $(`a',`a')$. The trap with `\a' is that it could be \emph{either} the \emph{string}
% $(`\',`a')$ \emph{or} the one-item list $(`\a')$ of strings.
% But even in the latter case, I urge not to consider it a \emph{\TeX\ token}.
% Rather, I consider `\a' a mistaken way of referring to the
% named token \NTOK{a} whose name is the string `a' (or $(`a')$).
% (Section~\ref{sec:toks}).
%
% However, the conceptual trap about arglists and token lists
% (there must have been some ``Arglist"!\@) lurks on another level,
% as follows. Recall \TTb's notation of \chtok{<char>}{<cat>}
% for the \emph{character token} that \TeX's tokenizer forms
% from <char> in the character buffer when <char>'s category code is <cat>.
% Usually, the \emph{character} `a' is converted into the
% \emph{character token} \lttok{a}, `{' is converted into \lbtok,
% and `}' is converted into \rbtok.
%
% We are turning to some \strong{examples} and \strong{counterexamples}.
% Let us see what confusions occurred in the ``intuitive" view on
% arglists in Section~\ref{sec:arglists-intuit}.
%
% % \begin{example}{1} It
% First, it was bad in Section~\ref{sec:arglists-intuit}
% to think that `aa' is a two-item arglist. It was confused with something
% like $\lttok{a}\lttok{a}$. The latter looks like a token list---or is it an arglist?
% Both? Anyway, it is juxtaposition notation applied to tokens,
% mathematically it is $(\lttok{a},\lttok{a})$, so~\dots
% % \end{example}
%
% Now let us reconsider the ``intuitive recursive definition" of arglist.
% Or let us look at a recursive definition of \emph{token} list.
% \inlineitem{1} There is nothing wrong with saying the the empty list is
% a token list, the same holds for arglists.
% \inlineitem{2} a.~When we attach an arbitrary token to a \emph{token} list
% (at the left), the result is another token list---fine.
% There are only certain difficulties with ``handling" special token lists
% such as $\lbtok\lttok{a} = (\lbtok,\lttok{a})$.
% And the latter is \emph{not} an \emph{arglist!} \
% b.~When we attach a \emph{named} token to an arglist (at the left),
% the result \emph{is} an \emph{arglist}.\footnote{This is
% a \emph{conjecture} only right now---2012-05-16---in which I strongly believe.
% Likewise later.}
% c.~When we attach a \emph{letter} token \lttok{<char>} to an arglist
% (at the left), the result \emph{is} an \emph{arglist}.
% d.~When we talked about ``brace groups," they seemed to be \emph{strings}
% of characters. Instead, I would like to suggest that a brace group
% is an \emph{arglist}\pdots
% When \lbtok\ is attached to the left of an arglist and \rbtok\ to the right,
% the result is an arglist---this is what I would call a ``brace group"!
% e.~The \Wikienref{concatenation} of two arglists is an arglist.
%
% \begin{smallpar}
% The above notion of ``attaching" a token to a token list or an arglist
% % should be clarified, but instead of a general definition in terms of
% % ``words" of formal languages, examples may suffice here and now.\footnote{2012-05-16.}
% should be clarified. Attaching an item $j$ at the left of a list $\lambda$
% is the same as concatenating the one-item list $(j)$ with $\lambda$\pdots
% but the English \wikienref{append}{Wikipedia} seems to explain concatenation by
% \emph{appending}. As we \emph{remove} items one-by-one from the \emph{left}
% (beginning) of a list, I prefer the inverse \emph{prepending} items as basic operation
% for building lists---cf.\ \Wikienref{CAR and CDR}.
% \end{smallpar}
%
% We won't complete a formal (recursive) definition of arglist here and
% now.\footnote{2012-05-16.} Just observe that ``brace groups"
% make the difference between token lists and arglists.
% Recall that an ``item" of an arglist ``operationally" is defined
% as something that a one-parameter macro removes.
% Such a macro removes certain single tokens
% (space tokens not among them)---and entire ``brace groups"!
% Especially, consider \[\lbtok\rbtok\]%%%.
% Actually, this is another ambiguous notation.
% If it refers to $(\lbtok,\rbtok)$, it is a \emph{token} list,
% not an arglist. If it refers to $(\lbtok\rbtok)$---it should
% better refer to $((\lbtok,\rbtok))$, which is a
% \emph{one-item arglist} whose only item is the former two-item token list!
%
%% <- 2012/05/17b ->
Let us reconsider the examples from Sections~\ref{sec:lists-intuit}
and~\ref{sec:arglists-intuit}, and pack them into a single example.
If you type a file line
\begin{equation}
`a a\a{a}'
\end{equation}
(\emph{eight} keystrokes),
it should usually be converted into this \emph{seven}-item list
of (five) tokens:
\begin{equation}
\label{eq:toks}
\lttok{a}\;\sptok\;\lttok{a}\;\NTOK{a}\;\lbtok\;\lttok{a}\;\rbtok
\end{equation}
---with notation from Section~\ref{sec:toks} and
\TTb's notation \chtok{<char>}{<cat>}
for the \emph{character token} that \TeX's tokenizer forms
from <char> in the character buffer when <char>'s category code is <cat>.
It turns out that the token list in \ref{eq:toks}
provides an arglist of \emph{four} items: The token \lttok{a}
at the first and third place, the named token \NTOK{a}, and the entire
token list $\lbtok\lttok{a}\rbtok$ as a single item---a ``brace group."
The space token is ignored.\footnote{\TTbp.~201: ``\TeX\ doesn't use
single spaces as undelimited arguments."}
You can try this after `\renewcommand{\a}{A}'\footnote{Otherwise
\cs{a} is a one-parameter macro that breaks 'dowith''s control.}
with 'dowith':
\begin{equation}
\label{eq:sample-code}
`\DoWith\typein a a\a{a}\StopDoing'
\end{equation}
Then \LaTeX\ shows `a', `a', `A' from `\a', and another `a' from within
the braces---`\typein' (as any macro with arguments) removes them.
% \show\a
% \a{a}
\renewcommand*{\a}{A}
% {\MakeNormalHere\# \newcommand*{\TypeOut}[1]{\typein{#1}}
% \global\let\TypeOut\TypeOut}
% \let\TypeOut\typein
% \let\TypeOut\typeout
% \DoWith\TypeOut a a\a{a}\StopDoing
% \DoWith\typein a a\a{a}\StopDoing
% { %%% \tracingmacros=1 \tracingonline=1
% \MakeNormalHere\# \AssignCatCodeTo{2}\]
% \DoWith\typein #a\a{a]\StopDoing}
I have avoided saying \ref{eq:toks} \emph{were} an arglist of 4 items.
The mathematical basic way of writing lists---understood as finite
\emph{\wikienref{sequence}{sequences}}---as ``commma-separated lists"
within \wikienref{bracket}{brackets} may clarify the difference
(that the \Wikienref{juxtaposition} notation tends to conceal).
The \emph{token} list is
\begin{equation}
\label{eq:toks,}
(\lttok{a}, \sptok, \lttok{a}, \NTOK{a}, \lbtok, \lttok{a}, \rbtok)
\end{equation}
while the list of macro arguments is
\begin{equation}
\label{eq:args}
(\lttok{a}, \lttok{a}, \NTOK{a}, (\lbtok, \lttok{a}, \rbtok)).
\end{equation}
\ref{eq:toks} or \ref{eq:toks,} simply is \emph{not} an arglist
(since neither \lbtok\ nor \rbtok\ can be a macro argument),
and the arglist \ref{eq:args} ``provided" by the list of tokens
is \emph{not} a list of \emph{tokens}---its final item is a
three-item list of tokens, and a token cannot be a list of
two or more tokens itself(\emph{!?}).
\subsection{Another Notation and the Example's Steps}
\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}
\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
\cs{DoWithAllOf&\typein\codeLB a\codeSP a&\a\codeLB a\codeRB\codeRB}
instead, the entire token sequence \ref{eq:retro} will appear in the
token buffer ``at once."}
\begin{equation}
\ntok{typein}.\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 ``command buffer," and you should get a screen
message with `a' and a prompt. When you have entered something,
the remaining \ntok{expandafter} tokens and the \ntok{fi} will be
removed from the character buffer, and it contains only
\begin{equation}
\ntok{DoWith}\,\ntok{typein}
\end{equation}
Another token is ordered from the tokenizer to provide a second
argument for expanding \ntok{DoWith}. The token .\codesp\ comes in,
but that doesn't serve as a macro argument. It is removed, and the
next token is .&a. The same story as before happens, until the
named token \ntok{a} is found\pdots
\end{smallpar}
\subsection{Summary of Possible Arglist Items}
\begin{smallpar}
For $0\leq i\leq 15$, let $\Chi_i$ be the set of character tokens
of category code $i$. $\Chi_1$ is the set of tokens working like
$\lbtok$, and $\Chi_2$ is the set of tokens working like $\rbtok$.
Let $E$ be the set $\{3,4,6,7,8,11,12,13\}$.
These numbers are the category codes for
\meta{math}, \meta{align}, \meta{parameter}, \meta{super}, \meta{sub},
\meta{letter}, \meta{other}, \meta{active} respectively.
Let $\Chi_E$ be the set of character tokens of category code in $E$
(so $\Chi_E=\bigcup_{i\in E}\Chi_i$).
Let $\circ$ be the \emph{concatenation} operation among token lists.\footnote{%
%% 2012/05/18
TODO: Define for representations by maps, or:
``Concatenation is about as basic as natural numbers and is
understood in terms of axioms rather than by a definition.''---See
notes from 2011 (even with attempts with \Wikienref{Category theory})
% the \wikienref{Sequence}{English}
the English Wikipedia for
\wikienref{Sequence}{sequences}---\wikideref{Folge (Mathematik)}{German}
article too much restricted to maps.}
The following kinds of token lists form a single arglist item,
i.e., can serve as an argument for an undelimited parameter:
\begin{enumerate}
\item a \emph{named} token, or the single-token list consisting of it,
if you prefer that;
\item a \emph{character} token from $\Chi_E$ or the list consisting of it;
\item a \emph{brace group.}
That is a token list meeting the following conditions:
\inlineitem{1} its \emph{first} token is in $\Chi_1$,
\inlineitem{2} its \emph{last} token is in $\Chi_2$,
\inlineitem{3} it has as many occurrences of tokens from $\Chi_1$ as from $\Chi_2$,
\inlineitem{4} if it is split as $\lambda\circ\rho$, there are not
more $\Chi_2$ occurrences in $\lambda$ than $\Chi_1$ occurrences in $\rho$
(``don't close before opening").
\end{enumerate}
The second claim can be checked with
\begin{equation}
`\DoWith\typein$#^_a1~\StopDoing'
\end{equation}
% \begingroup
% \def\a{A}\MakeNormalHere\#
% \DoWith\typein$# ^_a1~\StopDoing
% \DoWith\typein#1\StopDoing
% \endgroup
as to what works.
(The claim is not affected by one or two surprises.)\footnote{Moreover,
\cs{DoWith&\typein&\StopDoing} tells something about
``parameter tokens."}
Characters with different category codes
either are not converted into a character token\footnote{\TTbp.~47.}
or are not accepted as macro arguments. The latter applies to ``brace" tokens
in $\Chi_1$, $\Chi_2$ and to the single space token \sptok.
As to \emph{``brace groups"}, the third and fourth condition above
are intended to say that what is between the two outer tokens
is $\langle$balanced text$\rangle$ in the sense of \TTbp p.~275f. and~385;
i.e., for two tokens $a$, $b$ and a token list $\beta$,
$(a)\circ\beta\circ(b)$ is a brace group exactly if $a$ is from $\Chi_1$,
$b$ is from $\Chi_2$, and $\beta$ is $\langle$balanced text$\rangle$.
The conditions are more formal than what I can find in \TTb,
but still they don't give me an idea of all possibities.
This should be improved by the following recursive definition:
\begin{trivlist}\item
B1.~The empty list is balanced text.
B2.~For any token $t$ not in $\Chi_1$ or $\Chi_2$,
the single-item token list $(t)$ is balanced text.
(Such a token is either a \emph{named} token or a
\emph{character} token from $\Chi_E$ or \emph{the space token}~\sptok.)
B3.~If $\alpha$ and $\beta$ are balanced texts,
then $\alpha\circ\beta$ is balanced text.
B4.~If $\beta$ is balanced text,
$a$ is from $\Chi_1$, and $b$ is from $\Chi_2$,
then $(a)\circ\beta\circ(b)$ is balanced text.
(This is a brace group, and the only way of getting a brace group.)
B5.~Nothing else is balanced text.
\end{trivlist}
In other words, a token list is a brace group if and only if
it is balanced text and starts with a token from $\Chi_1$
and ends with a token from $\Chi_2$.\footnote{Again, this may be more
of a draft for a paper, or notes for it, than package documentation.}
\end{smallpar}
\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:
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 mouth."\footnote{Cf.\ documentation
% of the \ctanpkgref{bitelist} package.}
% \TeX's mouth processes tokens formed from character input.
% It may turn a list `<toks-a><toks_b><toks-c>' of tokens
% into a list `<toks-a><toks-B><toks-c>', i.e.,
% replace <toks-b> by <toks-B>---by so-called ``expansion".
% The result may be subject to expansion as well.
% When nothing is left to be expanded, results are passed to another,
% more interior subprocessor of \TeX. This one is deeper than \TeX's mouth,
% we are not concerned with that here.
%
% Not \emph{all} of those tokens in ``\TeX's mouth" are formed
% (``directly") from input characters.
% Rather, some \cs{csname} function may form \emph{new} tokens
% from other tokens in \TeX's mouth---and place them there again.
% This way characters `\csname a\endcsname' you type may just work like
% `\a'.
%
% It is difficult to tell on the \emph{character level} what the
% present package does. The relation between incoming characters
% and resulting tokens can hardly be explained by a single sentence or so.
% However, <cmd> here refers to a command <macro> with a single
% undelimited macro. More precisely, a certain character sequence
% (``string") in the code you type, will be converted into a TODO
%
% \subsection{Separators}
% TODO
%
% \subsection{Iterators and \TeX's Mouth}
% TODO
%
\section{Similar Commands in other Packages}
%% <- 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}
provides somewhat ``exotic" handling of ``lists".} %% 2012/05/10
(I~do not want to load that much.)
\subsection{Separators} %% add. heading 2012/05/17b
Regarding \LaTeX\ macros in `latex.ltx', the basic macro `\DoWith' of
the present package resembles |\@tfor| very much, which likewise deals
with lists without separators. By contrast, \LaTeX's |\@for| deals with
\emph{comma-separated} lists (such as lists of package options).
With comma-separated lists, a ``string" of characters counts as
an item when it is delimited by commas, or by a comma and the
list ``border," or spaces may be used as separators additionally.
However, when \LaTeX\ analyzes such lists (in ``\TeX's mouth"),
it uses representations by \emph{character tokens} of them.
%% moved here 2012/05/17b:
% %% 2011/11/10:
% Also Heiko Oberdiek's \ctanpkgref{zref} deals with ``lists" of
% ``properties" of ``entities,"
%% 2011/11/11: comma separated!
%% 2012/05/09f.:
The more recent \ctanpkgref{lmake}
(Shengjun Pan) %% 2012/05/18
provides a key-value syntax for printing lists of
complex mathematical expressions easily (using some assignments)
as well as defining commands according to a pattern from a list.
Those lists are comma-separated.
\subsection{``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 mouth (`\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
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,"}
% TUGboat 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.\
(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.\
|