summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/etextools/etextools.dtx
blob: 921614fbe9ab0eb345e23122b95d352a64a9ba99 (plain)
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
% \iffalse meta-comment
%%% etextools : more e-TeX useful tools for LaTeX package writers
%%% Florent CHERVET
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license or (at your option) any later
% version. The latest version of this license is in
%    http://www.latex-project.org/lppl.txt
%
% This work consists of the main source file etextools.dtx
% and the derived files
%    etextools.sty, etextools.pdf, etextools.ins,
% Unpacking:
%    (a) If etextools.ins is present:
%           etex etextools.ins
%    (b) Without etextools.ins:
%           etex etextools.dtx
%    (c) If you insist on using LaTeX
%           latex \let\install=y\input{etextools.dtx}
%        (quote the arguments according to the demands of your shell)
%
% Documentation:
%           (pdf)latex etextools.dtx; ...
%
%<*ignore>
\begingroup
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
\Msg{* Package: etextools 2009/07/14 v2e e-TeX more useful tools for LaTeX package writers}
\Msg{************************************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax
\preamble

This is a generated file.

Copyright (C) 2009 by Florent Chervet <florent.chervet@free.fr>

This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
version 1.3 of this license or (at your option) any later
version. The latest version of this license is in
   http://www.latex-project.org/lppl.txt

This work consists of the main source file etextools.dtx
and the derived files
   etextools.sty, etextools.pdf, etextools.ins,

\endpreamble
\let\MetaPrefix\DoubleperCent

\generate{%
  \file{etextools.ins}{\from{etextools.dtx}{install}}%
  \file{etextools.sty}{\from{etextools.dtx}{package}}%
}

\obeyspaces
\Msg{************************************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* file into a directory searched by TeX:}
\Msg{*}
\Msg{*     etextools.sty}
\Msg{*}
\Msg{* To produce the documentation run the file `etextools.drv'}
\Msg{* through LaTeX.}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}

\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\documentclass[a4paper,oneside]{ltxdockit}
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
\usepackage{doc,stmaryrd,amsmath,graphics,geometry,fancyhdr,framed,bbding,trace}\CodelineNumbered
\lastlinefit999
\font\ding=dingbat scaled 800
\geometry{totalheight=26cm,marginparwidth=14pt}
\fancyhf{}\fancyhead[L]{The \sty{etextools} package -- an \eTeX\, package for \LaTeX\,}
\fancyfoot[L]{\color[gray]{.35}\scriptsize\sty{etextools}\quad\copyright\,\lower.3ex\hbox{\NibRight}\,Florent Chervet}
\fancyfoot[R]{\oldstylenums{\thepage} / \oldstylenums{\pageref{LastPage}}}
\pagestyle{fancy}
\definecolor{spot}{rgb}{.7,0.1,0.2}
\newcommand\fecccolor{\color{fecc}}\definecolor{fecc}{rgb}{.2,.6,.2}
\newcommand\macrocodecolor{\color{macrocode}}\definecolor{macrocode}{rgb}{0.18,0.00,0.45}
\newcommand\reflinkcolor{\color{reflink}}\definecolor{reflink}{rgb}{.3,0,0}
\newcommand\rmklinkcolor{\color{rmklink}}\definecolor{rmklink}{rgb}{.2,.2,.2}
\newcommand\rmkcolor{\color{rmk}\let\reflinkcolor\rmklinkcolor}\definecolor{rmk}{gray}{.35}
\newcommand\rmk{\par\nobreak\footnotesize\rmkcolor}
\definecolor{shadecolor}{rgb}{0.93,0.94,0.81} 
\renewcommand\ltxsyntaxlabelfont{\spotcolor \displayverbfont\bfseries}
\newcommand\eol{\textcolor[gray]{.5}{$\hookleftarrow$}}
\MakeShortVerb{\|}
\catcode`\§\active\def§{\par\nobreak\vskip-\parskip}
\renewcommand\partformat{}\let\thepart\partformat\renewcommand\raggedpart{\centering}
\newcommand\cmdref[1]{\hyperref[#1]{\underline{\sty{\reflinkcolor\textbackslash #1}}}}
\newcommand\cmdlabel[1]{\label{#1}}
\makeatletter
\AtBeginDocument{\g@addto@macro\macro@font{\macrocodecolor\let\AltMacroFont\macro@font}}
\def\FE{\setbox8\hbox{$\m@th\bindnasrepma$}%
   \marginpar{\fecccolor\scalebox{2}{$\copy8\mkern-13.5mu\copy8\mkern-13.5mu\copy8$}}\space}
\def\smex{\leavevmode\hb@xt@2em{\hfil\spotcolor$\longrightarrow$\hfil}}
\parindent\z@\topsep\z@\partopsep\z@\parskip.3\baselineskip
\makeatother
\font\manual=manfnt\def\dbend{\marginpar{\manual\char127}\space}
\titlepage{%
  title={The \sty{etextools} package},
  subtitle={An \etex package providing useful tools for LaTeX Users \\ and package Writers},
  url={http://www.ctan.org/tex-archive/macros/latex/contrib/etextools/},
  author={Florent CHERVET},
  email={florent.chervet@free.fr},
  revision={2\:$\boldsymbol{\varepsilon}$},
  date={14 July 2009}}
\hypersetup{%
  pdftitle={The etextools package},
  pdfsubject={An e-TeX package for more useful tools for LaTeX package writers},
  pdfauthor={Florent CHERVET},
  colorlinks,linkcolor=reflink,
  pdfkeywords={tex, e-tex, latex, package, programming},
  bookmarksopen=true,bookmarksopenlevel=2}
\begin{document}
   \DocInput{etextools.dtx}
\end{document}
%</driver>
% \fi
%  
%    \thispagestyle{plain}\printtitlepage
% \fontfamily{ua1}\selectfont
% \tableofcontents\vfil
% 
% \begin{shaded}\parindent0pt\noindent\large
%
% {\bfseries\catcode`\ \active\let =\,\hfil \* A b s t r a c t \*\hfil}\par
%
% The \sty{etextools} package is based on the \sty{etex} and \sty{etoolbox}
% packages and defines more tools for \LaTeX\ Users or package Writers.
% Before using this package, it is highly recommended to read the
% documentation (of this package and...) of the \sty{etoolbox} package.
%
% This package requires the \sty{etex} package from David Carlisle
% and the \sty{etoolbox} package from Philipp Lehman. Both of them
% are available on CTAN under the \sty{/latex/contrib/} directory \footnotemark.
%
% The main contributions of this package are :
% \begin{itemize}
%   \item the \cmdref{expandnext} macro;
%   \item the ability to define fully expandable macros with parameter and/or star version (with a small restriction)
%           -- see \cmdref{FE@testopt}, \cmdref{FE@ifstar};
%   \item a Command-List Parser constructor that fully uses this new feature : command-list parser are fully expandable
%           -- see \cmdref{csvloop} and \cmdref{listloop};
%   \item three macros that are lacking from the \sty{etoolbox} package for removing elements from lists :
%              \cmdref{listdel} and \cmdref{listgdel}, \cmdref{listxdel}.
% \end{itemize}
%
% \end{shaded}
%
% \footnotetext{This documentation is produced with the \sty{ltxdockit}
% classe and package by Philipp Lehman using the |DocStrip| utility.
% \begin{tabbing}
% \qquad\=\smex\=To get the documentation, \= run (twice):\quad\= \sty{pdflatex etextools.dtx} \\
% \>\smex\>To get the package, \> run:\>        \sty{etex etextools.dtx}
% \end{tabbing}}
%
% \vfil\eject
% 
% \section{Introduction}
%
% \subsection{Identification}
%
%    \begin{macrocode}
%<*package>
\NeedsTeXFormat{LaTeX2e}[1996/12/01]
\ProvidesPackage{etextools}
   [2009/07/14 v2e e-TeX more useful tools for LaTeX package writers]
\csname ettl@onlyonce\endcsname\let\ettl@onlyonce\endinput
%    \end{macrocode}
%
% \subsection{Requirements}
%
% This package requires both the \sty{etex} package by David Carlisle and
% the \sty{etoolbox} package by Philipp Lehman.
%
%    \begin{macrocode}
\RequirePackage{etex,etoolbox}
%    \end{macrocode}
%
% Furthermore, the space token must have its natural catcode (10) all along this package.
%
%    \begin{macrocode}
\edef\ettl@restore@space@catcode{\catcode`\ =\the\catcode`\ }
\AtEndOfPackage{\ettl@restore@space@catcode
   \let\ettl@restore@space@catcode\ettl@undefined}
\catcode`\ =10
%    \end{macrocode}
%
% \subsection{Acknowledgements -- Thank You !}
%
% Thanks to Philipp Lehman for the \sty{etoolbox} package (and also for this nice class of documentation).
% Much of my work on lists are based on his work and package.
%
% Thank to Heiko Oberdiek who has done so much for the \TeX\ and \LaTeX\ community, and allows me to
% produce a package in one only \sty{.dtx} file.
%
% \subsection{Hint for the reader}
%
% Every command provided in this \sty{etextools} package are fully expandable
% unless explicitly specified. As it appears to be the philosophy of \sty{etoolbox}
% to make the most of its commands fully expandable (and this is very useful for package
% writing and/or document-style programming) the \FE fully expandable commands
% have a special sign in the margin (displayed here for information).
%
% Remain what a control sequence, a control word and a control character are...
%
% \iffalse The commands have been (extensively, more or less) tested.\fi
%
%
% \part*{User commands}
% \addtocontents{toc}{\protect\contentsline{part}{\large User commands}{}{}}
%
% \section{A few (\oldstylenums{7}) ``helper'' macros}
%
% \begin{ltxsyntax}
%
% \cmditem{ettl@afterelse} \cmdlabel{ettl@afterelse}
% \cmditem*{ettl@afterfi}   \cmdlabel{ettl@afterfi}\hfil\par
%
% Those two commands\FE are the copies of |\bbl@afterelse| and |\bbl@afterfi| from the \sty{babel} package.
% They allow to get out of |\if|...|\fi| conditionals.
%
%    \begin{macrocode}
\long\def\ettl@afterelse#1\else#2\fi{\fi#1}
\long\def\ettl@afterfi#1\fi{\fi#1}
%    \end{macrocode}
%
% {\rmk Those commands are used in \cmdref{iffirstchar} and \cmdref{expandnext} }
%
% \cmditem*{@gobblescape}\hfil\par
%
% This sequence\FE of command is very often used, even in \sty{latex.ltx}. So
% it appears to be better to put it in a macro. It's aim is to reverse the
% mechanism of |\csname|...|\endcsname|:
%    \begin{macrocode}
\newcommand*\@gobblescape{\expandafter\@gobble\string}
%    \end{macrocode}
%
% \cmditem{str@gobblescape}{string}\hfil\par
%
% With \FE \eTeX\space |\detokenize| it is now possible to invoke a |\string| on an arbitrary
% sequence of tokens. Unfortunately, |\detokenize| adds a
% space tokens at the very end of the sequence. |\str@gobblescape| acts exactly
% the same way as |@gobblescape| \ie it removes the first character from a string, but removes
% the trailing spaces as well:
%
%    \begin{macrocode}
\newcommand\str@gobblescape[1]{\expandafter\deblank\expandafter{%
         \expandafter\@gobble\detokenize{#1}}}
%    \end{macrocode}
%
% The \cmdref{deblank} command will be desbribed later.
%
% \end{ltxsyntax}
%
% \section{Expansion control}
%
% NOTA BENE: Pay attention\dbend that the expansion control macros are not \emph{primitives}!
% Therefore:
% \begin{tabbing}
% \qquad\= |\expandafter\controlsequence\noexpandcs{|\prm{csname}|}|\\
% \> |\expandafter\controlsequence\expandonce{|\prm{command}|}|
% \end{tabbing}
% etc. etc. may not lead to the result you expected.
% The |\expandonce| macro from \sty{etoolbox} worth the same warning.
%
% For expansion control, it's better to use primitives, unless you clearly knows what
% you do and what will happen... \textbf{In particular,\dbend you'd very better avoid to use
% expansion control macros at the very beginning of the definition of a command, for if this command
% is preceded (in the user's code) by \sty{\textbackslash expandafter}, you will be lead
% to undesirable result and most probably to an error !}

% \begin{ltxsyntax}
%
% \cmditem{noexpandcs}{csname}
%
% In an \FE expansion context (|\edef|) we often want a control sequence whose name results
% from the expansion of some macros and/or other tokens to be created, but not expanded at that point.
% Roughly:§
% \qquad |\edef{\noexpandcs{<balanced text to be expanded as a cs-name>}}|§
% will expand to: |\"cs-name"| but this (new) control sequence itself will not be expanded.
% A typical use is shown in the following code:§
% \smex |\edef\abc{\noexpandcs{abc@\@gobblescape\controlword}}|§
% \smex if equivalent to:\quad|\def\abc{\abc@controlword}|.
%
%    \begin{macrocode}
\newcommand*\noexpandcs[1]{\expandafter\noexpand\csname #1\endcsname}
%    \end{macrocode}
%
% {\rmk|\noexpandcs| is used in the definition of \cmdref{DeclareListCmdParser}.}
%
% \cmditem{noexpandafter}\hfil\par
%
% |\noexpandafter|\FE only means |\noexpand\expandafter| and is shorter to type.
%
%    \begin{macrocode}
\newcommand\noexpandafter{\noexpand\expandafter}
%    \end{macrocode}
%
% {\rmk This command is used in the definition of \cmdref{DeclareListCmdParser}.}
% \iffalse
% \cmditem{afterexpandafter}
%
% |\afterexpandafter|\FE means to delay the expansion twice :§
% \qquad |\afterexpandafter\a\expandafter\b\c|\quad will replace |\c| by its \prm{replacement text}, then
% expand place |\b| before and replace it by its \prm{replacement text} as well, eventually consuming its
% parameters, and after that, place |\a| before the whole thing; then expansion goes further.
%
%    \begin{macrocode}
% \newcommand\afterexpandafter{\expandafter\expandafter\expandafter}
%    \end{macrocode}
% \fi
%
% \cmditem{expandnext}{cstoken}{first parameter of cstoken} \cmdlabel{expandnext}
%
% We\FE often want a control sequence to be expanded after its first argument. For example, if we want to test if a command
% |\foo| has a blank replacement text we will type :
%
% \qquad |\expandafter\ifblank\expandafter{\foo}|
%
% Now suppose you wish to define a macro |\detokenizecs{|\prm{csname}|}| that expands to the detokenized content
% of |\csname |\prm{csname}|\endcsname|. Without |\expandnext| you will have to say:
% \begin{tabbing}
% \qquad\= |\expandafter\expandafter\expandafter\detokenize| \\
% \>       |\expandafter\expandafter\expandafter{\csname |\prm{csname}|\endcsname}|
% \end{tabbing}
% \textbf{six} \cmd{expandafter}(s). With |\expandnext| you will just have to say:§
% \qquad|\expandnext\expandnext\detokenize{\csname #1\endcsname}|
%
% Now observe the following game :
% \begin{tabbing}
% \qquad\= |\def\foo{foo}| \qquad \= \smex \qquad \=  |\def\Foo{\foo}| \quad \= \eol \\
% \>       |\def\\FOo{\Foo}| \>   \smex \>    |\def\FOO{\FOo}| \> \eol \\
% \>       |\def\FOOL{\FOO}|
% \end{tabbing}
% And {\bfseries guess how many \cmd{expandafter} you will need in order to test ``|\ifblank{foo}|'' directly from |\FOOL| ??? }
%
% |\expandnext| solves this problem : |\FOOL| has 5 degrees of expansion until it expands to ``foo'', so one require exactly 5
% |\expandnext| : the solution is :
%
% \qquad |\expandnext\expandnext\expandnext\expandnext\expandnext\ifblank{\FOOL}|
%
% And now : if you define, say : |\csdef{bloody fool}{\FOO}| you just require 2 more |\expandnext| in order
% to test ``foo'' from  ``|\csname bloody fool\endcsname|'' ! \emph{just test it!}
%
%    \begin{macrocode}
\newcommand\expandnext[2]{%
   \ifx#1\expandnext
      \ettl@afterelse\expandafter\expandafter\expandafter
            \expandafter\@expandnext{#2}{\expandafter\expandafter\expandafter}
   \else\ettl@afterfi\expandafter#1\expandafter{#2}
   \fi}
\long\def\@expandnext#1#2#3{%
   \ifx#1\expandnext
      \expandafter\ettl@afterelse\expandafter\expandafter\expandafter
            \expandafter\@expandnext{#3}{\expandafter#2#2}
   \else
      \expandafter\ettl@afterfi#2#1#2{#3}
   \fi}
%    \end{macrocode}
%
% This code is not very tricky but difficult to explain. The better is to watch at the log if the reader is eager
% to understand the job of each \cmd{expandafter}.
%
% Note that the first argument of |\expandnext| must be a single \prm{cstoken} (for \cmd{expandnext} acts 
% only on the first following token).
%
% \end{ltxsyntax}
%
% \section{String manipulation}
%
% \subsection{String trimming}
%
% \begin{ltxsyntax}
%
% \cmditem{deblank}{string} \cmdlabel{deblank}
%
% The macro \FE |\deblank| will remove the extra blank space inserted by |\detokenize| at the
% very end of the \prm{string}. Actually, it removes all trailing spaces (charcode 32, catcode 10)
% from its argument:
%
%    \begin{macrocode}
\newcommand\deblank{}
\begingroup\catcode`\&=3% a & as a math shift
\long\gdef\deblank#1{\@deblank#1 &}
\long\gdef\@deblank#1 #2&{\ifblank{#2}{#1}{#1\@deblank#2 &}}
\endgroup
%    \end{macrocode}
%
% Note, by the way, that the leading spaces are also removed by \TeX's mastication mechanism.
% \goodbreak
%
% \subsection{Expanded string comparison}
%
% \cmditem{xifblank}{string}{true}{false}
%
% |\xifblank| is similar to |\ifblank| except that the \prm{string} is first expanded
% with |\protected@edef|:
%    \begin{macrocode}
\newrobustcmd\xifblank[1]{\begingroup
   \protected@edef\@xifblank{\endgroup
         \noexpand\ifblank{#1}%
   }\@xifblank}
%    \end{macrocode}
%
% \cmditem{xifstrequal}{string1}{string2}{true}{false}
%
% In the same way, |\xifstrequal| is similar to |\ifstrequal| but both \prm{string} arguments
% are expanded with |\protected@edef| before comparison:
%    \begin{macrocode}
\newrobustcmd\xifstrequal[2]{%
   \begingroup\protected@edef\@tempa{#1}\protected@edef\@tempb{#2}%
      \ifx\@tempa\@tempb   \aftergroup\@firstoftwo
      \else                \aftergroup\@secondoftwo
      \fi\endgroup}
%    \end{macrocode}
%
% \subsection{Testing characters}
%
% \cmditem{iffirstchar}{string1}{string2}{true}{false}
% \cmditem*{iffirstchar}{}{string}{true}{false}
%
% |\iffirstchar| will\FE compare the character codes of the \textbf{first} characters of each \prm{string}. The
% comparison is \emph{catcode agnostic} and the macro is fully expandable. Neither \prm{string1} not \prm{string2}
% is expanded before comparison.
%
% There is a ``special'' use of this command when the user want to test if a \prm{string} begins
% with an \emph{escape} character (\,\textbackslash\,) one may say:
% \begin{tabbing}
%\qquad\= |\iffirstchar \@backslashchar{|\prm{string}|}|\qquad\= or even easier:\\
% \>|\iffirstchar {}{|\prm{string}|}|
% \end{tabbing}
% Please note that the tests:
% \begin{tabbing}
% \qquad\qquad\=|\iffirstchar |\=|{|\prm{whatever string1 is}|}{}|\\
% and:\>|\iffirstchar |\>|{}{}|
% \end{tabbing}
%  are \textbf{always expanded into \underline{\prm{false}}}
% (for consistency with the shortcut-test for |\@backslashchar|):
%
%    \begin{macrocode}
\newcommand\iffirstchar[2]{%
   \if \expandafter\@car\string#2\relax\@nil\expandafter\@car#1\string\\\@nil
         \ettl@afterelse\ifblank{#2}\@secondoftwo\@firstoftwo
   \else \expandafter\@secondoftwo
   \fi}
%    \end{macrocode}
%
%
% \cmditem{ifsinglechar}{string1}{string2}{true}{false}
%
% |\ifsinglechar|\FE will perform the test |\iffirstchar| but will also check that \prm{string2} has only one character.
%
%    \begin{macrocode}
\newcommand\ifsinglechar[2]{%
%    \end{macrocode}
% Remember that neither \prm{string1} nor \prm{string2} is expanded.§
% First: test if |#2| is a single character:
%    \begin{macrocode}
   \expandnext\expandnext\ifblank{\expandafter\@cdr\string#2 \@nil}
%  \expandafter\expandafter\expandafter\ifblank
%     \expandafter\expandafter\expandafter{%
%        \expandafter\@cdr\string#2 \@nil}
%    \end{macrocode}
% The test returned \prm{true}: therefore test further the character codes of |#2| and |#1|, and
% switch to \prm{true} only in case of equality:
%    \begin{macrocode}
  {\iffirstchar{#1}{#2}}
%    \end{macrocode}
% Otherwise, switch to \prm{false}
%    \begin{macrocode}
   \@secondoftwo}
%    \end{macrocode}
%
% Now with the macro |\ifsinglechar| it becomes possible to write fully expandable macros with an option, \textbf{provided
% that this macro has at least one non-optional argument}, as far as we don't use |\futurelet| nor any assignation.
% The ``trick'' is the following:
% \begin{tabbing}
% \qquad\= |\def\MacroWithOption#1{\ifsing|\=|lechar|\=|[{#1}| \\
% \>\>|{\MacroHasOption[}| \\
% \>\>|{\MacroNoOption{#1}}}}|\\
% \> |\def\MacroHasOption[#1]#2|... \>\textit{definition} \\
% \> |\def\MacroNoOption#1|...\>\textit{definition}
% \end{tabbing}
%
% Moreover (in the style of |\@testopt|):
% \begin{tabbing}
%  \qquad\= |\def\MacroWithOption#1{\ifsing|\=|lechar|\=|[{#1}|\\
%  \>\>|{\MacroHasOption#1}|\\
%  \>\>|{\MacroHasOption[default]{#1}}}|
% \end{tabbing}
%
% Therefore, the following macro is defined:
%
% \subsection{Fully expandable macros with options}
%
% \cmditem{FE@testopt}{argument to be tested}{commands}{default option} \cmdlabel{FE@testopt}
%
%   |\FE@testopt| mimics the behaviour of |\@testopt| but is Fully Expandable (\sty{FE})\FE and can be used as follow:§
% \qquad |\def\MacroWithOption#1{\FE@testopt{#1}\MacroHasOption{default}}|\par
%
% Remember that |\MacroWithOption| \textbf{must have at least one mandatory argument.}
%
%    \begin{macrocode}
\newcommand\FE@testopt[3]{\ifsinglechar [{#1}{#2#1}{#2[{#3}]{#1}}}
%    \end{macrocode}
%
% \textbf{Limitation :}\dbend if you call such an option command without option and with |{[}| as mandatory
% argument, it will be considered that the command has an option, whose end will be at the next `\,]\,' found in the input string.
%
% {\rmk |\FE@testopt| is used in the definition of \cmdref{DeclareListCmdParser}.}
%
% \cmditem{FE@ifstar}{argument to be tested}{star-commands}{non-star commands} \cmdlabel{FE@ifstar}
%
% Similarly,\FE it becomes possible to mimic the behaviour of |\@ifstar| but in a fully expandable(\sty{FE}) way.
% |\FE@ifstar| can be used as follow :§
% \begin{tabbing}
% \qquad\= |\def\StarOrNotCommand#1{\FE@|\=|ifstar|\=|{#1}|\\
% \>\>|{\StarredCommand}|\\
% \>\>|{\NotStarredCommand}}|
% \end{tabbing}
%
% Remember that |\StarredCommand| and |\NotStarredCommand| \textbf{must have at least one mandatory argument.}
%
%    \begin{macrocode}
\newcommand\FE@ifstar[3]{\ifsinglechar *{#1}{#2}{#3{#1}}}
%    \end{macrocode}
%
% \textbf{Limitation :}\dbend if you call such a command with |{*}| as mandatory argument,
% it will be considered that the command is starred, and the mandatory argument will be found next inside the input string.
%
% \textbf{This ``limitation'' is in fact a benediction:} thank to it we can have
% {\it\catcode`\ \active\let =-Fully Expandable starred macros with option\/}!\nobreak
% {\rmk |\FE@ifstar| is used in the definitions of \cmdref{DeclareListCmdParser}, \cmdref{csvloop}, \cmdref{listloop}
% and \cmdref{csvtolist}.}
% \goodbreak
% \end{ltxsyntax}
%
% \section{List management}
%
% \subsection{The Command-List Parser}
%
% The \sty{etoolbox} package provides a way to define list parsers a fully expandable macros:
% the list parser is able to expand the auxiliary command |\do| on each item of a list.
% \iffalse
% Declaration of a list parser is done via the |\DeclareListParser| macro\footnotemark.
% \footnotetext{besides, \sty{etoolbox} defines the \sty{\textbackslash docsvlist} and the
% \sty{\textbackslash dolistloop} macros: the choice of this name is not very friendly
% and we expected to have a \sty{\textbackslash docsvloop} macro instead...}.
% \fi
%
% Here we provide a |\DeclareCmdListParser| macro that is compatible and slightly different, because the auxiliary
% command is not necessarily |\do|. Such a command-list-parser is fully expandable.
%
% The idea is that if |\csvloop| has been defined as a command-parser then, thank to the fully expandable macro |\FE@testopt|
% we can call for expansion:
% \begin{tabbing}
% \qquad\= |\csvloop*{item,item,...}|\,\= as a shortcut for\,\= |\csvloop*[\do]{item,...}|\\
% or:\>       |\csvloop*[\listadd\mylist]{item,item,...}|\quad
% \end{tabbing}
% for example to convert the csv-list into internal \sty{etoolbox} list.
%
% {\rmk The star-form of \cmdref{csvloop} will be explained below.}
%
% \begin{ltxsyntax}
%
% \cmditem{DeclareCmdListParser}{command}{separator}
%
% |\DeclareCmdListParser| acts in the same way as \sty{etoolbox}-|\DeclareListParser| and the command-list-parser
% are sensitive to the category code of the \prm{separator}
% {\catcode`\ =13\let =-\it(which is not necessarily a single character and shall not be a {\tt\&} with a catcode of 3)}.
%
% The command-list-parser will be defined only if it is definable:
%
%    \begin{macrocode}
\newrobustcmd*\DeclareCmdListParser[2]{%
  \@ifdefinable#1
    {\expandafter\etextools@defcmdparser\expandafter{#1}{#2}}}
%    \end{macrocode}
%
% Then the job is done by |\etextools@defcmdparser|: we need the `\,\&\,' to have a catcode of 3
% and globally define the macro inside a purposeful group:
%
%    \begin{macrocode}
\begingroup\catcode`\&=3
\gdef\etextools@defcmdparser#1#2{%
   \begingroup
%    \end{macrocode}
% Now the parser definition is made inside an protected-|\edef| in order to expand control sequences names:
%    \begin{macrocode}
   \protected@edef\defineparser{\endgroup
%    \end{macrocode}
% Here we define the entry-point: we first test if the command was starred.
% This is possible because the list-parser has always a mandatory argument (the \prm{list} itself or the \prm{listmacro}) :
%    \begin{macrocode}
   \long\def#1####1{\noexpand\FE@ifstar{####1}
      {\noexpandcs{ettl@lst@star\string#1}}
      {\noexpandcs{ettl@lst@nost\string#1}}}%
%    \end{macrocode}
% Both starred and not-starred versions have an optional argument which is the auxiliary command, whose name is |\do| if not specified.
% It is possible to test the option for the same reason:
%    \begin{macrocode}
   \long\csdef{ettl@lst@star\string#1}####1{\noexpand\FE@testopt{####1}
      {\noexpandcs{ettl@lst@star@pt\string#1}}{\noexpand\do}}%
   \long\csdef{ettl@lst@nost\string#1}####1{\noexpand\FE@testopt{####1}
      {\noexpandcs{ettl@lst@nost@pt\string#1}}{\noexpand\do}}%
%    \end{macrocode}
% Definition of the parser with its arguments :\quad |[optional command]{list or listmacro}|. If the starred version
% was used, then we do not have to expand the (mandatory) \prm{list}:
%    \begin{macrocode}
   \long\csdef{ettl@lst@star@pt\string#1}[####1]####2{%
      \noexpandcs{ettl@lst\string#1}{####2}{####1}}%
%    \end{macrocode}
% On the other hand, if the parser was not starred, the (mandatory) \prm{listmacro} is expanded once:
%    \begin{macrocode}
   \long\csdef{ettl@lst@nost@pt\string#1}[####1]####2{%
      \noexpandafter\noexpandcs{ettl@lst\string#1}\noexpandafter{%
                                          ####2}{####1}}%
%    \end{macrocode}
% ListParser is defined and leads to |\"ettl@lst\string\ListParser"| in all cases; here the \prm{list} is in first position,
% the auxiliary commands come after, so we reverse the order and add a \prm{separator} in case the \prm{list} is empty:
%    \begin{macrocode}
   \long\csdef{ettl@lst\string#1}####1####2{%
         \noexpandcs{ettl@lst@\string#1}{####2}####1\noexpand#2&}%
%    \end{macrocode}
% In the following macro, we extract the first item from the list (before the \prm{separator} |#2|), for treatment:
%    \begin{macrocode}
   \long\csdef{ettl@lst@\string#1}####1####2\noexpand#2####3&{%
%    \end{macrocode}
% Proceed with the first item, if not empty:
%    \begin{macrocode}
      \noexpand\ifblank{####2}
            {}
            {\noexpand\ettl@lst@doitem{####1}{####2}}%
%    \end{macrocode}
% If the remainder of the list is empty then break loop, otherwise restart extracting the next, first item for treatment:
%    \begin{macrocode}
      \noexpand\ifblank{####3}
            {\noexpand\ettl@listbreak}
            {\noexpandcs{ettl@lst@\string#1}{####1}####3}&}%
%    \end{macrocode}
% Now the definitions are ready, execute them:
%    \begin{macrocode}
   }\defineparser}%
%    \end{macrocode}
% |\ettl@lst@doitem| apply the auxiliary command(s) (in |#1|) to the item (|#2|):
% |\ettl@listbreak| breaks the loop, removing the extra \sty{\&}:
%    \begin{macrocode}
   \long\gdef\ettl@lst@doitem#1#2{#1{#2}}%
   \long\gdef\ettl@listbreak#1&{}%
%    \end{macrocode}
% Leave ``catcode-group'':
%    \begin{macrocode}
\endgroup
%    \end{macrocode}
%
% \subsection{Loops into lists}
%
% Now we have to declare two command-list-parsers : |\listloop| for \sty{etoolbox} lists
% and |\csvloop| for comma-separated lists.
%
% \cmditem{csvloop}[auxiliary commands]{csvlistmacro} \cmdlabel{csvloop}
% \cmditem*{csvloop*}[auxiliary commands]{item,item,item,...}
% \cmditem*{listloop}[auxiliary commands]{listmacro}    \cmdlabel{listloop}
% \cmditem*{listloop*}[auxiliary commands]{expanded list}
%
% |\listloop| acts exactly as \sty{etoolbox}-|\dolistloop| with an optional argument to change
% the default auxiliary command |\do| to apply to each item of the list :
% \begin{tabbing}
% \qquad\=|\listloop\mylist|\;\=\textit{is}\;\= |\listloop[\do]\mylist|\;\=\textit{and is also}\;\= |\dolistloop\mylist|\\
% \>      |\csvloop\csvlist|\> \textit{is}\> |\csvloop[\do]\csvlist|\> \textit{and is also}: \eol \\
% \>\>\> |\expandafter\docsvlist\expandafter{\csvlist}|
% \end{tabbing}
% Definition of |\csvloop| :
%    \begin{macrocode}
\DeclareCmdListParser\csvloop{,}
%    \end{macrocode}
%
% Definition of |\listloop| (with a `\,\textbar\,'  of catcode 3 -- cf.\sty{etoolbox}):
%    \begin{macrocode}
\begingroup\catcode`\|=3
   \gdef\do{\DeclareCmdListParser\listloop{|}\undef\do}\aftergroup\do
\endgroup
%    \end{macrocode}
%
% \subsection{Converting csv lists to \sty{etoolbox}-lists}
%
% \cmditem{csvtolist}{listmacro}{csvlistmacro} \cmdlabel{csvtolist}
% \cmditem*{csvtolist*}{listmacro}{item,item,item...}
%
% |\csvtolist| converts a comma separated list into an internal \sty{etoolbox} list. It is useful to insert more than one item
% at a time in a list. It's also the first application of the |\csvloop| macro just defined :
%
%    \begin{macrocode}
\newcommand\csvtolist[1]{\FE@ifstar{#1}\star@csvtolist\nost@csvtolist}
\def\star@csvtolist#1{\csvloop*[{\unexpanded{\listadd#1}}]}
\def\nost@csvtolist#1{\csvloop[{\unexpanded{\listadd#1}}]}
%    \end{macrocode}
%
% \end{ltxsyntax}
%
% \subsection{Removing elements from \sty{etoolbox}-lists}
%
% The \sty{etoolbox} package provides |\listadd|, |\listgadd| and |\listxadd| commands
% to add items to a list. However, no command is designed to remove an element from a
% list.
%
% \begin{ltxsyntax}
%
% \cmditem{listdel}{listmacro}{item}      \cmdlabel{listdel}
% \cmditem*{listgdel}{listmacro}{item}    \cmdlabel{listgdel}
% \cmditem*{listxdel}{listmacro}{item}    \cmditem{listxdel}
%
% The |\listdel| command removes the element \prm{item} from the list \prm{listmacro}. Note that the
% \prm{listmacro} is redefined after deletion:
%
%    \begin{macrocode}
\newrobustcmd\listdel[2]{\@listdel\def{#1}{#2}}
%    \end{macrocode}
%
% Commands |\listgdel| and |\listxdel| are similar, except that the assignment (\ie the redefinition
% of the list) is global; for the latter, the \prm{item} is first expanded using |\protected@edef|:
%
%    \begin{macrocode}
\newrobustcmd\listgdel[2]{\@listdel\gdef{#2}{#2}}
\newrobustcmd\listxdel[2]{\begingroup
   \protected@edef\@listxdel{\endgroup
      \unexpanded{\@listdel\def#1}{#2}%
   }\@listxdel}
%    \end{macrocode}
%
% Now you noticed the job is delayed to a general macro |\@listdel| which is relatively tricky !
% We need first to be placed in an environment where the `\,\textbar\,' delimiter has a category code of 3
% (cf \sty{etoolbox}-lists definitions):
%    \begin{macrocode}
 \begingroup\catcode`\|=3\catcode`\&=3
%    \end{macrocode}
% Inside this ``catcode-group'' the definition of |\@listdel| ought to be global:
%    \begin{macrocode}
 \long\gdef\@listdel#1#2#3{%
%    \end{macrocode}
% \qquad |#1|=|\def| or |\gdef|, |#2|=\prm{listmacro}, |#3|=\prm{item} to remove.\par
% In order to preserve the hash-table from temporary definitions, a group is opened:
%    \begin{macrocode}
   \begingroup
      \def\@tempa##1|#3|##2&{##1|##2\@tempb}%
%    \end{macrocode}
% |\@tempa| is a delimited macro whose aim is to remove the first \prm{item} found in the list
% and it adds |\@tempb| after the result. If the \prm{item} was not in the list, then |##2|
% will be empty. Note that |\@tempa| is the only macro whose definition depends on the \prm{item}
% (and then leads |\@listdel| not to be fully-expandable).
%
% The result of |\@tempa| expansion is then given to |\@tempb| whose purpose is to cancel out
% whatever is found between the two delimiters: \textbar|\@tempb|...\textbar|\@tempb|:
%    \begin{macrocode}
   \def\@tempb|##1|\@tempb##2|\@tempb{%
      \ifblank{##2}{\unexpanded{##1}}
%    \end{macrocode}
% If the \prm{item} \textsc{was not} is the list, then |##2| will be empty, and§
% \qquad |\@tempb|\textbar...\textbar\@tempb...\textbar|\@tempb|§
% is replaced by the \emph{original-}list (\ie |##1| -- that we shall not expand), then the loop is broken;
% otherwise the \prm{item} was in the list and |##1| is the \emph{shortened-}list without the \prm{item}. We have to loop
% to remove all the \prm{item{\tt s}} of the list, except in the case where the \emph{shortened-}list
% is empty after having removing \prm{item} (|##1| empty):
%    \begin{macrocode}
      {\ifblank{##1}{}{\@tempx##1&}}}%
%    \end{macrocode}
% Now we just have to (define and) expand |\@tempx| in an |\edef| which is going to redefine
% the \prm{listmacro}. |\@tempx| expands first |\@tempa| and then |\@tempb| on the result of
% the expansion of |\@tempa|. The macro |\@tempx| itself has an argument: it is (at first stage) the
% replacement text of \prm{listmacro}:
%    \begin{macrocode}
   \def\@tempx##1&{\expandafter\@tempb\@tempa|##1|\@tempb|#3|&}%
   \edef\@redef{\endgroup
      \unexpanded{#1#2}{% ie: \def or \gdef   \listmacro
%    \end{macrocode}
% |\@redef| redefines the list using (|\def| or |\gdef|), the replacement text is the result
% of the expansion of |\@tempx| on the \prm{listmacro} which is expanded once (to see  its items...):
%    \begin{macrocode}
      \expandafter\@tempx\unexpanded\expandafter{#2}&}%
%    \end{macrocode}
% Then just expand |\@redef| (fully expandable):
%    \begin{macrocode}
   }\@redef}% end of \@listdel
%    \end{macrocode}
% And ends the ``catcode-group'':
%    \begin{macrocode}
\endgroup
%    \end{macrocode}
%
% \end{ltxsyntax}
%
%
%
%
%

%
%
%
%
%
%
%
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
% \label{LastPage}
% \Finale