etextools 2e (22jul09)

git-svn-id: svn://tug.org/texlive/trunk@14372 c570f23f-e606-0410-a88d-b1316a301751

7 files changed, 617 insertions, 97 deletions

diff --git a/Master/texmf-dist/doc/latex/etextools/README b/Master/texmf-dist/doc/latex/etextools/README
index a15dfe9ca60..3a58e58ebe2 100644
--- a/Master/texmf-dist/doc/latex/etextools/README
+++ b/Master/texmf-dist/doc/latex/etextools/README
@@ -1,6 +1,7 @@
 % This work consists of the main source file etextools.dtx
 % and the derived files
-%    etextools.sty, etextools.pdf, etextools.ins,
+%      etextools.sty, etextools.pdf, etextools.ins,
+% and  etextools-examples.tex
 %
 % Unpacking:
 %    (a) If etextools.ins is present:
diff --git a/Master/texmf-dist/doc/latex/etextools/etextools-examples.pdf b/Master/texmf-dist/doc/latex/etextools/etextools-examples.pdf
new file mode 100644
index 00000000000..12efa0070df
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/etextools/etextools-examples.pdf
diff --git a/Master/texmf-dist/doc/latex/etextools/etextools-examples.tex b/Master/texmf-dist/doc/latex/etextools/etextools-examples.tex
new file mode 100644
index 00000000000..a8b96ae1837
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/etextools/etextools-examples.tex
@@ -0,0 +1,182 @@
+%%
+%% This is file `etextools-examples.tex',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% etextools.dtx  (with options: `example')
+%% 
+%% 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,
+%% and   etextools-examples.tex
+%% 
+%%% etextools : more e-TeX useful tools for LaTeX package writers
+%%% Florent CHERVET
+\documentclass[11pt,french,a4paper,oneside]{scrartcl}
+\usepackage[latin1]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage[american]{babel}
+\usepackage{geometry,doc,ltxdockit,txfonts,fancyhdr}
+\usepackage{etextools}
+\hypersetup{colorlinks,pdfstartview={FitH}}
+\geometry{top=2cm,bottom=2cm,left=2.5cm,right=1cm}
+\fancyhf{}
+\fancyhead[L]{Examples for the \sty{etextools} package}
+\pagestyle{fancy}
+\MakeShortVerb{\|}
+
+\makeatletter
+\def\smex{\leavevmode\hb@xt@2em{\hfil$\longrightarrow$\hfil}}
+\def\strip@meaning{\expandafter\strip@prefix\meaning}
+\def\strip@macro{\expandafter\strip@macroprefix\meaning}
+\def\get@params#1{\expandafter\@get@params\meaning#1\@nil}
+\edef\@get@params{%
+   \def\noexpand\@get@params\detokenize{macro:}##1\detokenize{->}##2\noexpand\@nil{##1}%
+}\@get@params
+\def\make@macro#1{\string\def\string#1\get@params#1\string{\strip@meaning#1\string}}
+\newcommand\preline{\@ifstar{\@preline}{\hrulefill\par\@preline}}
+\def\@preline#1{\noindent\hskip6pt\texttt{\make@macro#1}\par\vskip1.5ex}
+
+\def\meaningcs#1{\expandafter\meaning\csname#1\endcsname}
+\def\Meaningcs#1{\expandafter\strip@meaning\csname #1\endcsname}
+
+\newcommand\test[1]{%
+   \csname test#1\endcsname
+   \edef\usercmd{\Meaningcs{test#1}}\edef\result{\meaningcs{#1Test}}\noindent
+   \begin{tabular}{lp{15cm}}
+   \multicolumn{2}{l}{\textcolor{blue}{\llap\smex\tt \usercmd}} \\[1.5ex]
+   \cmd{#1Test}= & \tt\bfseries\result
+   \end{tabular}\par\nobreak\hrulefill\null\goodbreak}
+
+\begin{document}
+\title{etextools examples}
+\subtitle{Examples for some macros provided by the \sty{etextools} package}
+\author{Florent Chervet}
+\date{July 22, 2009}
+\maketitle
+
+\tableofcontents
+
+\section{\cmd{expandnext} examples}
+
+\subsection{Test if the replacement text of a macro is blank (empty or spaces)}
+
+\def\xx{something}
+\def\testexpandnext{%
+   \edef\expandnextTest{\string\xx\ is \expandnext\ifblank{\xx}{}{not} blank}
+}
+\preline\xx
+\test{expandnext}
+
+\def\xx{    }
+\preline\xx
+\test{expandnext}
+
+\clearpage
+\subsection{Detokenize the replacement text of a named-sequence}
+\def\detokenizecs#1{\expandnext\expandnext\detokenize{\csname #1\endcsname}}
+\def\testexpandnext{%
+   \edef\expandnextTest{\detokenizecs{document}}}
+\preline\detokenizecs
+\test{expandnext}
+
+\section{Testing characters}
+\subsection{\cmd{ifsinglechar} versus \cmd{iffirstchar}}
+\def\testifsinglechar{%
+   \edef\ifsinglecharTest{\ifsinglechar *{*hello*}{ single star }{ something else }}
+}\hrulefill\par
+\test{ifsinglechar}
+
+\def\testiffirstchar{%
+   \edef\iffirstcharTest{\iffirstchar *{*hello*}{ first char is star }{ something else }}
+}\hrulefill\par
+\test{iffirstchar}
+
+\subsection{Fully Expandable starred macros}
+\def\starmacro#1{\FE@ifstar{#1}\starred\notstarred}
+\def\starred#1{your "#1" will be processed by the STAR form}
+\def\notstarred#1{your "#1" will be processed by the NORMAL form}
+\def\testFE@ifstar{%
+   \edef\FE@ifstarTest{\starmacro{sample text}}}
+\preline\starmacro
+\preline*\starred
+\preline*\notstarred
+\test{FE@ifstar}
+
+\def\testFE@ifstar{%
+   \edef\FE@ifstarTest{\starmacro*{sample text}}}
+\hrulefill\par
+\test{FE@ifstar}
+
+\subsection{Fully Expandable macros with options}
+\def\optmacro#1{\FE@testopt{#1}\OPTmacro{Mr.}}
+\def\OPTmacro[#1]#2{#1 #2}
+\def\testFE@testopt{%
+   \edef\FE@testoptTest{\optmacro{Woody Allen}}}
+\preline\optmacro
+\preline*\OPTmacro
+\test{FE@testopt}
+
+\def\testFE@testopt{%
+   \edef\FE@testoptTest{\optmacro[Ms.]{Vanessa Paradis}}}
+\hrulefill\par
+\test{FE@testopt}
+
+\section{Lists management}
+\subsection{\cmd{csvloop} and \cmd{csvloop*} examples}
+\subsubsection{\cmd{makequotes}}
+\def\makequotes#1{"#1"\space}
+\def\testcsvloop{%
+   \edef\csvloopTest{\csvloop*[\makequotes]{hello,world}}
+}
+\preline\makequotes
+\test{csvloop}
+\subsubsection{\cmd{detokenize}}
+\def\testcsvloop{%
+   \edef\csvloopTest{\csvloop*[\detokenize]{\un,\deux}}
+}\hrulefill\par
+\test{csvloop}
+\subsubsection{\cmd{numexpr}}
+\def\mylist{1,2,3,4,5}\def\BySeven#1{$#1\times 7 = \number\numexpr#1*7\relax$\par}
+\def\testcsvloop{%
+   \edef\csvloopTest{\csvloop[\BySeven]\mylist}}
+\preline\mylist
+\preline*\BySeven
+\test{csvloop}
+\subsubsection{protected \cmd{testbf}}
+\def\testcsvloop{%
+   \protected@edef\csvloopTest{\csvloop*[\textbf]{hello ,my ,friends}}
+}\hrulefill\par
+\test{csvloop}
+
+\subsection{\cmd{getlistitem}}
+\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}
+\def\testgetlistitem{%
+   \edef\getlistitemTest{\getlistitem\mylist{4}}
+}\hrulefill\par
+\noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
+\test{getlistitem}
+
+\subsection{\cmd{getlistindex} {\mdseries(not expandable)}}
+\getlistindex{four}\mylist
+\hrulefill\par
+\noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
+\noindent\hskip6pt\textcolor{blue}{\llap\smex\cmd{getlistindex}{four}\cmd{mylist}}\par\vskip1.5ex
+\noindent\hskip6pt\cmd{indexinlist}=\quad{\bfseries\meaning\indexinlist}\par\hrulefill\par
+
+\end{document}
+
+\endinput
+%%
+%% End of file `etextools-examples.tex'.
diff --git a/Master/texmf-dist/doc/latex/etextools/etextools.pdf b/Master/texmf-dist/doc/latex/etextools/etextools.pdf
index 345e0745102..77103fd7539 100644
--- a/Master/texmf-dist/doc/latex/etextools/etextools.pdf
+++ b/Master/texmf-dist/doc/latex/etextools/etextools.pdf
diff --git a/Master/texmf-dist/source/latex/etextools/etextools.dtx b/Master/texmf-dist/source/latex/etextools/etextools.dtx
index 921614fbe9a..5a8c2dcef83 100644
--- a/Master/texmf-dist/source/latex/etextools/etextools.dtx
+++ b/Master/texmf-dist/source/latex/etextools/etextools.dtx
@@ -10,7 +10,9 @@
 %
 % This work consists of the main source file etextools.dtx
 % and the derived files
-%    etextools.sty, etextools.pdf, etextools.ins,
+%        etextools.sty, etextools.pdf, etextools.ins,
+% and    etextools-examples.tex
+%
 % Unpacking:
 %    (a) If etextools.ins is present:
 %           etex etextools.ins
@@ -21,8 +23,8 @@
 %        (quote the arguments according to the demands of your shell)
 %
 % Documentation:
-%           (pdf)latex etextools.dtx; ...
-%
+%           (pdf)latex etextools.dtx
+%           (pdf)latex etextools-examples.tex
 %<*ignore>
 \begingroup
   \def\x{LaTeX2e}%
@@ -57,7 +59,8 @@ version. The latest version of this license is in
 
 This work consists of the main source file etextools.dtx
 and the derived files
-   etextools.sty, etextools.pdf, etextools.ins,
+      etextools.sty, etextools.pdf, etextools.ins,
+and   etextools-examples.tex
 
 \endpreamble
 \let\MetaPrefix\DoubleperCent
@@ -65,6 +68,7 @@ and the derived files
 \generate{%
   \file{etextools.ins}{\from{etextools.dtx}{install}}%
   \file{etextools.sty}{\from{etextools.dtx}{package}}%
+  \file{etextools-examples.tex}{\from{etextools.dtx}{example}}%
 }
 
 \obeyspaces
@@ -75,7 +79,7 @@ and the derived files
 \Msg{*}
 \Msg{*     etextools.sty}
 \Msg{*}
-\Msg{* To produce the documentation run the file `etextools.drv'}
+\Msg{* To produce the documentation run the file `etextools.dtx'}
 \Msg{* through LaTeX.}
 \Msg{*}
 \Msg{* Happy TeXing!}
@@ -88,40 +92,14 @@ and the derived files
 \fi
 %</ignore>
 %<*driver>
+\edef\thisfile{\jobname}
+\def\thisinfo{The \thispackage\ package -- an \eTeX{} package for \LaTeX{}}
 \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
+\usepackage{doc,stmaryrd,amsmath,graphics,geometry,fancyhdr,framed,bbding,trace,embedfile}\CodelineNumbered
+\embedfile{\thisfile.dtx}
 \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},
@@ -138,15 +116,48 @@ and the derived files
   pdfkeywords={tex, e-tex, latex, package, programming},
   bookmarksopen=true,bookmarksopenlevel=2}
 \begin{document}
-   \DocInput{etextools.dtx}
+   \DocInput{\thisfile.dtx}
 \end{document}
 %</driver>
 % \fi
-%  
-%    \thispagestyle{plain}\printtitlepage
+%
+% \makeatletter
+% \def\thispackage{\sty{\thisfile}}
+% \font\ding=dingbat scaled 800
+% \fancyhf{}\fancyhead[L]{The \sty{etextools} package -- an \eTeX\, package for \LaTeX}
+% \fancyfoot[L]{\color[gray]{.35}\scriptsize\thispackage\quad\copyright\,\lower.3ex\hbox{\NibRight}\,Florent Chervet}
+% \fancyfoot[R]{\oldstylenums{\thepage} / \oldstylenums{\pageref{LastPage}}}
+% \pagestyle{fancy}
+% \def\CTAN#1{\href{http://www.ctan.org/tex-archive/#1}{\nolinkurl{CTAN:#1}}}
+% \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$}}
+% \newenvironment{codecomment}{\par\vskip\parskip\begin{small}\color[gray]{.2}\parskip=0pt}{\end{small}}
+% \g@addto@macro\macro@font{\macrocodecolor\let\AltMacroFont\macro@font}
+% \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}}
+% \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}}
+% \font\manual=manfnt\def\dbend{\marginpar{\manual\char127}\space}
+% \parindent\z@\topsep\z@\partopsep\z@\parskip.3\baselineskip
+% \lastlinefit999
+% \makeatother
+%
+% \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
@@ -168,7 +179,10 @@ and the derived files
 %   \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}.
+%              \cmdref{listdel} and \cmdref{listgdel}, \cmdref{listxdel};
+%   \item macros that return the index of an item in a list: \cmdref{getlistindex} and \cmdref{xgetlistindex} and conversely
+%         the item at a given position in a list: \cmdref{getlistitem};
+%
 % \end{itemize}
 %
 % \end{shaded}
@@ -181,7 +195,7 @@ and the derived files
 % \end{tabbing}}
 %
 % \vfil\eject
-% 
+%
 % \section{Introduction}
 %
 % \subsection{Identification}
@@ -223,7 +237,7 @@ and the derived files
 % \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}
+% unless explicitly specified. As it (one of) 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).
@@ -236,7 +250,7 @@ and the derived files
 % \part*{User commands}
 % \addtocontents{toc}{\protect\contentsline{part}{\large User commands}{}{}}
 %
-% \section{A few (\oldstylenums{7}) ``helper'' macros}
+% \section{A few (\texorpdfstring{\oldstylenums{7}}{7}) ``helper'' macros}
 %
 % \begin{ltxsyntax}
 %
@@ -249,6 +263,8 @@ and the derived files
 %    \begin{macrocode}
 \long\def\ettl@afterelse#1\else#2\fi{\fi#1}
 \long\def\ettl@afterfi#1\fi{\fi#1}
+\long\def\ettl@afterfifi#1\fi\fi{\fi\fi#1}
+\long\def\ettl@afterelsefi#1\else#2\fi\fi{\fi#1}
 %    \end{macrocode}
 %
 % {\rmk Those commands are used in \cmdref{iffirstchar} and \cmdref{expandnext} }
@@ -267,7 +283,7 @@ and the derived files
 % 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 same way as |\@gobblescape| \ie it removes the first character from a string, but removes
 % the trailing spaces as well:
 %
 %    \begin{macrocode}
@@ -313,7 +329,7 @@ and the derived files
 \newcommand*\noexpandcs[1]{\expandafter\noexpand\csname #1\endcsname}
 %    \end{macrocode}
 %
-% {\rmk|\noexpandcs| is used in the definition of \cmdref{DeclareListCmdParser}.}
+% {\rmk|\noexpandcs| can be abbreviated in |\`#1`| in |\edef| that take place in a group. }
 %
 % \cmditem{noexpandafter}\hfil\par
 %
@@ -323,7 +339,7 @@ and the derived files
 \newcommand\noexpandafter{\noexpand\expandafter}
 %    \end{macrocode}
 %
-% {\rmk This command is used in the definition of \cmdref{DeclareListCmdParser}.}
+% {\rmk This command is used in the definition of \cmdref{DeclareCmdListParser}.}
 % \iffalse
 % \cmditem{afterexpandafter}
 %
@@ -388,7 +404,7 @@ and the derived files
 % 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 
+% Note that the first argument of |\expandnext| must be a single \prm{cstoken} (for \cmd{expandafter} acts
 % only on the first following token).
 %
 % \end{ltxsyntax}
@@ -443,7 +459,7 @@ and the derived files
 %
 % \subsection{Testing characters}
 %
-% \cmditem{iffirstchar}{string1}{string2}{true}{false}
+% \cmditem{iffirstchar}{string1}{string2}{true}{false} \cmdlabel{iffirstchar}
 % \cmditem*{iffirstchar}{}{string}{true}{false}
 %
 % |\iffirstchar| will\FE compare the character codes of the \textbf{first} characters of each \prm{string}. The
@@ -473,20 +489,19 @@ and the derived files
 %    \end{macrocode}
 %
 %
-% \cmditem{ifsinglechar}{string1}{string2}{true}{false}
+% \cmditem{ifsinglechar}{string1}{string2}{true}{false} \cmdlabel{ifsinglechar}
 %
 % |\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}
+%
+% \begin{codecomment}
 % 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:
@@ -497,6 +512,7 @@ and the derived files
 %    \begin{macrocode}
    \@secondoftwo}
 %    \end{macrocode}
+% \end{codecomment}
 %
 % 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.
@@ -534,7 +550,7 @@ and the derived files
 % \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}.}
+% {\rmk |\FE@testopt| is used in the definition of \cmdref{DeclareCmdListParser}.}
 %
 % \cmditem{FE@ifstar}{argument to be tested}{star-commands}{non-star commands} \cmdlabel{FE@ifstar}
 %
@@ -557,7 +573,7 @@ and the derived files
 %
 % \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}
+% {\rmk |\FE@ifstar| is used in the definitions of \cmdref{DeclareCmdListParser}, \cmdref{csvloop}, \cmdref{listloop}
 % and \cmdref{csvtolist}.}
 % \goodbreak
 % \end{ltxsyntax}
@@ -590,12 +606,13 @@ and the derived files
 %
 % \begin{ltxsyntax}
 %
-% \cmditem{DeclareCmdListParser}{command}{separator}
+% \cmditem{DeclareCmdListParser}{command}{separator}  \cmdlabel{DeclareCmdListParser}
 %
 % |\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)}.
 %
+% \begin{codecomment}
 % The command-list-parser will be defined only if it is definable:
 %
 %    \begin{macrocode}
@@ -611,6 +628,7 @@ and the derived files
 \begingroup\catcode`\&=3
 \gdef\etextools@defcmdparser#1#2{%
    \begingroup
+   \def\`##1`{\expandafter\noexpand\csname ##1\endcsname}%
 %    \end{macrocode}
 % Now the parser definition is made inside an protected-|\edef| in order to expand control sequences names:
 %    \begin{macrocode}
@@ -620,38 +638,37 @@ and the derived files
 % 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}}}%
+      {\`ettl@lst@star\string#1`}
+      {\`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}}%
+      {\`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}}%
+      {\`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}}%
+      \`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}}%
+      \noexpandafter\`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,
+% 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&}%
+         \`ettl@lst@\string#1`{####2}####1\unexpanded{#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&{%
+   \long\csdef{ettl@lst@\string#1}####1####2\unexpanded{#2}####3&{%
 %    \end{macrocode}
 % Proceed with the first item, if not empty:
 %    \begin{macrocode}
@@ -663,7 +680,7 @@ and the derived files
 %    \begin{macrocode}
       \noexpand\ifblank{####3}
             {\noexpand\ettl@listbreak}
-            {\noexpandcs{ettl@lst@\string#1}{####1}####3}&}%
+            {\`ettl@lst@\string#1`{####1}####3}&}%
 %    \end{macrocode}
 % Now the definitions are ready, execute them:
 %    \begin{macrocode}
@@ -679,6 +696,7 @@ and the derived files
 %    \begin{macrocode}
 \endgroup
 %    \end{macrocode}
+% \end{codecomment}
 %
 % \subsection{Loops into lists}
 %
@@ -690,7 +708,7 @@ and the derived files
 % \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
+% |\listloop|\FE 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|\\
@@ -702,12 +720,14 @@ and the derived files
 \DeclareCmdListParser\csvloop{,}
 %    \end{macrocode}
 %
+% \begin{codecomment}
 % 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}
+% \end{codecomment}
 %
 % \subsection{Converting csv lists to \sty{etoolbox}-lists}
 %
@@ -715,12 +735,27 @@ and the derived files
 % \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 :
+% at a time in a list. Those macros are not fully expandable because of the redefinition of \prm{listmacro} done by |\listadd|...
+%
+% It's also the first application of the \cmdref{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}}]}
+\newcommand\csvtolist{\@ifstar\star@csvtolist\nost@csvtolist}
+\def\star@csvtolist#1{\let#1\@empty\csvloop*[{\unexpanded{\listadd#1}}]}
+\def\nost@csvtolist#1{\let#1\@empty\csvloop[{\unexpanded{\listadd#1}}]}
+%    \end{macrocode}
+%
+% \cmditem{csvtolistadd}{listmacro}{csvlistmacro} \cmdlabel{csvtolistadd}
+% \cmditem*{csvtolistadd*}{listmacro}{item,item,item...}
+%
+% |\csvtolistadd| acts similarly but does not reset the \prm{listmacro} to |\@empty|:
+%
+%    \begin{macrocode}
+\newcommand\csvtolistadd{\@ifstar\star@csvtolistadd\nost@csvtolistadd}
+\def\star@csvtolistadd#1#2{\ifblank{#2}
+         {\let#1\@empty}{\csvloop*[{\unexpanded{\listadd#1}}]{#2}}}
+\def\nost@csvtolistadd#1#2{\ifblank{#2}
+         {\let#1\@empty}{\csvloop[{\unexpanded{\listadd#1}}]{#2}}}
 %    \end{macrocode}
 %
 % \end{ltxsyntax}
@@ -735,7 +770,7 @@ and the derived files
 %
 % \cmditem{listdel}{listmacro}{item}      \cmdlabel{listdel}
 % \cmditem*{listgdel}{listmacro}{item}    \cmdlabel{listgdel}
-% \cmditem*{listxdel}{listmacro}{item}    \cmditem{listxdel}
+% \cmditem*{listxdel}{listmacro}{item}    \cmdlabel{listxdel}
 %
 % The |\listdel| command removes the element \prm{item} from the list \prm{listmacro}. Note that the
 % \prm{listmacro} is redefined after deletion:
@@ -751,10 +786,11 @@ and the derived files
 \newrobustcmd\listgdel[2]{\@listdel\gdef{#2}{#2}}
 \newrobustcmd\listxdel[2]{\begingroup
    \protected@edef\@listxdel{\endgroup
-      \unexpanded{\@listdel\def#1}{#2}%
+      \unexpanded{\@listdel\gdef#1}{#2}%
    }\@listxdel}
 %    \end{macrocode}
 %
+% \begin{codecomment}
 % 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):
@@ -782,8 +818,8 @@ and the derived files
    \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|§
+% If the \prm{item} \textbf{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
@@ -813,24 +849,283 @@ and the derived files
 %    \begin{macrocode}
 \endgroup
 %    \end{macrocode}
-%
+% \end{codecomment}
 % \end{ltxsyntax}
 %
+% \subsection{Index of an element in a list}
 %
+% \begin{ltxsyntax}
 %
+% \cmditem{getlistindex}{item}{listmacro} \cmdlabel{getlistindex}
+% \cmditem*{xgetlistindex}{item}{listmacro} \cmdlabel{xgetlistindex}
+% \cmditem*{getlistindex*}{item}{list}
+% \cmditem*{xgetlistindex*}{item}{list}
 %
+% Sometimes it is interesting to know at which offset in a list lies a given item. |\getlistindex| answers to this question.
+% |\xgetlistindex| does the same thing but expand the \prm{item} (using |\protected@edef|) prior looking for it in the list.
+% The result (\ie the position of \prm{item} in \prm{list}) is stored in |\indexinlist|.
+% \begin{itemize}
+% \item \ If \prm{item} is not found in the \prm{list} then |\indexinlist| is 0
+% \item \ If \prm{item} is found in first position then |\indexinlit| is 1 and so on.
+% \end{itemize}
 %
-
-%
+% As for the command-list-parser, the star versions are designed in case the list (in the second argument) is already expanded.
+% \begin{codecomment}
+% We first need to get into a group where delimiter `\,\textbar\,' and `\,\&\,' have catcode 3:
+%    \begin{macrocode}
+\begingroup\catcode`\|=3\catcode`\&=3
+%    \end{macrocode}
+% The next two macros expands to the first item in a list or the remainder of the list respectively :
+%    \begin{macrocode}
+\gdef\ettl@list@first@item#1|#2&{#1}
+\gdef\ettl@list@other@item#1|#2&{#2}
+%    \end{macrocode}
+% |\getlistindex| may be defined, with its star form (no expansion of the list) and normal form (\prm{listmacro} expanded once);
+% The search-index is initialised at 1:
+%    \begin{macrocode}
+\gdef\getlistindex#1{\FE@ifstar{#1}{\ettl@getlistindex{}}
+                                   {\ettl@getlistindex\expandnext}}
+%   \@ifstar{\ettl@getlistindex{}}{\ettl@getlistindex{\expandnext}}}
+%    \end{macrocode}
+% |\xgetlistindex| is similar with prior expansion of \prm{item}:
+%    \begin{macrocode}
+\gdef\xgetlistindex#1{\FE@ifstar{#1}{\ettl@xgetlistindex{}}
+                                    {\ettl@xgetlistindex\expandnext}}
+\gdef\ettl@xgetlistindex#1#2#3{\begingroup
+   \protected@edef\next{\endgroup\unexpanded{\ettl@getlistindex{#1}{#2}}{#3}%
+   }\next}
+%    \end{macrocode}
+% Then the following macro does the job in a loop, which is not fully expandable because the use of |\ifstrequal|:
+%    \begin{macrocode}
+\gdef\ettl@getlistindex#1#2#3{\begingroup#1\ettl@get@list@idx{#3}{#2}{\numexpr1}}
+\gdef\ettl@get@list@idx#1#2#3{% #1=expanded list, #2=item, #3=index
+   \ifblank{#1}0% the (remainder of) the list is empty
+      {\expandnext\ifstrequal{\ettl@list@first@item#1&}{#2}
+         {\endgroup\edef\indexinlist{\number#3\relax}}
+         {\expandnext\ettl@get@list@idx{\ettl@list@other@item#1&}{#2}{#3+1}}}}
+\endgroup% catcode group
+%    \end{macrocode}
+% \end{codecomment}
+% \end{ltxsyntax}
 %
+% \subsection{Extract by index from a list}
 %
+% \begin{ltxsyntax}
 %
+% \cmditem{getlistitem}{listmacro}{index [numexpr expression]} \cmdlabel{getlistitem}
+% \cmditem*{getlistitem*}{list}{index}
 %
+% Now\FE the reverse operation of ``getting the index'' is ``getting the element'' whose index is known. Note that this macro
+% is fully expandable for we don't have to compare the items (just count the loop using |\numexpr| -- no counter). Therefore we use the
+% fully expandable version of |\ifstar| : \cmdref{FE@ifstar} to keep the ``fully-expand-ability'' of the star-form as well:
+% \begin{itemize}
+% \item \ If the \prm{index} is in the range $[1\dots n]$ then the macro expands to \prm{item}$_n$
+% \item \ If the \prm{index} is non positive or $>n$ then the macro expands to nothing (|{}|).
+%  \end{itemize}
 %
+%    \begin{macrocode}
+\newcommand\getlistitem[1]{\FE@ifstar{#1}\ettl@getlistitem
+                                        {\expandnext\ettl@getlistitem}}
+\begingroup\catcode`\&=3
+\long\gdef\ettl@getlistitem#1#2{%#1=listmacro, #2=index
+   \ettl@get@list@item{#1}{\number\numexpr#2}}
+\long\gdef\ettl@get@list@item#1#2{%
+   \ifblank{#1}{}
+      {\ifnum#2=1 \ettl@afterelsefi
+            \expandonce{\ettl@list@first@item#1&}
+      \else\ifnum#2>0 \ettl@afterfifi
+            \expandnext\ettl@getlistitem{\ettl@list@other@item#1&}{#2-1}%
+      \fi\fi}}
+\endgroup
+%    \end{macrocode}
 %
+% \end{ltxsyntax}
 %
 %    \begin{macrocode}
 %</package>
 %    \end{macrocode}
+%
+% \section{Example}
+%
+%    \begin{macrocode}
+%<*example>
+\documentclass[11pt,french,a4paper,oneside]{scrartcl}
+\usepackage[latin1]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage[american]{babel}
+\usepackage{geometry,doc,ltxdockit,txfonts,fancyhdr}
+\usepackage{etextools}
+\hypersetup{colorlinks,pdfstartview={FitH}}
+\geometry{top=2cm,bottom=2cm,left=2.5cm,right=1cm}
+\fancyhf{}
+\fancyhead[L]{Examples for the \sty{etextools} package}
+\pagestyle{fancy}
+\MakeShortVerb{\|}
+
+\makeatletter
+\def\smex{\leavevmode\hb@xt@2em{\hfil$\longrightarrow$\hfil}}
+\def\strip@meaning{\expandafter\strip@prefix\meaning}
+\def\strip@macro{\expandafter\strip@macroprefix\meaning}
+\def\get@params#1{\expandafter\@get@params\meaning#1\@nil}
+\edef\@get@params{%
+   \def\noexpand\@get@params\detokenize{macro:}##1\detokenize{->}##2\noexpand\@nil{##1}%
+}\@get@params
+\def\make@macro#1{\string\def\string#1\get@params#1\string{\strip@meaning#1\string}}
+\newcommand\preline{\@ifstar{\@preline}{\hrulefill\par\@preline}}
+\def\@preline#1{\noindent\hskip6pt\texttt{\make@macro#1}\par\vskip1.5ex}
+
+\def\meaningcs#1{\expandafter\meaning\csname#1\endcsname}
+\def\Meaningcs#1{\expandafter\strip@meaning\csname #1\endcsname}
+
+\newcommand\test[1]{%
+   \csname test#1\endcsname
+   \edef\usercmd{\Meaningcs{test#1}}\edef\result{\meaningcs{#1Test}}\noindent
+   \begin{tabular}{lp{15cm}}
+   \multicolumn{2}{l}{\textcolor{blue}{\llap\smex\tt \usercmd}} \\[1.5ex]
+   \cmd{#1Test}= & \tt\bfseries\result
+   \end{tabular}\par\nobreak\hrulefill\null\goodbreak}
+
+
+\begin{document}
+\title{etextools examples}
+\subtitle{Examples for some macros provided by the \sty{etextools} package}
+\author{Florent Chervet}
+\date{July 22, 2009}
+\maketitle
+
+\tableofcontents
+
+
+\section{\cmd{expandnext} examples}
+
+\subsection{Test if the replacement text of a macro is blank (empty or spaces)}
+
+\def\xx{something}
+\def\testexpandnext{%
+   \edef\expandnextTest{\string\xx\ is \expandnext\ifblank{\xx}{}{not} blank}
+}
+\preline\xx
+\test{expandnext}
+
+\def\xx{    }
+\preline\xx
+\test{expandnext}
+
+\clearpage
+\subsection{Detokenize the replacement text of a named-sequence}
+\def\detokenizecs#1{\expandnext\expandnext\detokenize{\csname #1\endcsname}}
+\def\testexpandnext{%
+   \edef\expandnextTest{\detokenizecs{document}}}
+\preline\detokenizecs
+\test{expandnext}
+
+
+\section{Testing characters}
+\subsection{\cmd{ifsinglechar} versus \cmd{iffirstchar}}
+\def\testifsinglechar{%
+   \edef\ifsinglecharTest{\ifsinglechar *{*hello*}{ single star }{ something else }}
+}\hrulefill\par
+\test{ifsinglechar}
+
+\def\testiffirstchar{%
+   \edef\iffirstcharTest{\iffirstchar *{*hello*}{ first char is star }{ something else }}
+}\hrulefill\par
+\test{iffirstchar}
+
+\subsection{Fully Expandable starred macros}
+\def\starmacro#1{\FE@ifstar{#1}\starred\notstarred}
+\def\starred#1{your "#1" will be processed by the STAR form}
+\def\notstarred#1{your "#1" will be processed by the NORMAL form}
+\def\testFE@ifstar{%
+   \edef\FE@ifstarTest{\starmacro{sample text}}}
+\preline\starmacro
+\preline*\starred
+\preline*\notstarred
+\test{FE@ifstar}
+
+\def\testFE@ifstar{%
+   \edef\FE@ifstarTest{\starmacro*{sample text}}}
+\hrulefill\par
+\test{FE@ifstar}
+
+\subsection{Fully Expandable macros with options}
+\def\optmacro#1{\FE@testopt{#1}\OPTmacro{Mr.}}
+\def\OPTmacro[#1]#2{#1 #2}
+\def\testFE@testopt{%
+   \edef\FE@testoptTest{\optmacro{Woody Allen}}}
+\preline\optmacro
+\preline*\OPTmacro
+\test{FE@testopt}
+
+\def\testFE@testopt{%
+   \edef\FE@testoptTest{\optmacro[Ms.]{Vanessa Paradis}}}
+\hrulefill\par
+\test{FE@testopt}
+
+\section{Lists management}
+\subsection{\cmd{csvloop} and \cmd{csvloop*} examples}
+\subsubsection{\cmd{makequotes}}
+\def\makequotes#1{"#1"\space}
+\def\testcsvloop{%
+   \edef\csvloopTest{\csvloop*[\makequotes]{hello,world}}
+}
+\preline\makequotes
+\test{csvloop}
+\subsubsection{\cmd{detokenize}}
+\def\testcsvloop{%
+   \edef\csvloopTest{\csvloop*[\detokenize]{\un,\deux}}
+}\hrulefill\par
+\test{csvloop}
+\subsubsection{\cmd{numexpr}}
+\def\mylist{1,2,3,4,5}\def\BySeven#1{$#1\times 7 = \number\numexpr#1*7\relax$\par}
+\def\testcsvloop{%
+   \edef\csvloopTest{\csvloop[\BySeven]\mylist}}
+\preline\mylist
+\preline*\BySeven
+\test{csvloop}
+\subsubsection{protected \cmd{testbf}}
+\def\testcsvloop{%
+   \protected@edef\csvloopTest{\csvloop*[\textbf]{hello ,my ,friends}}
+}\hrulefill\par
+\test{csvloop}
+
+\subsection{\cmd{getlistitem}}
+\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}
+\def\testgetlistitem{%
+   \edef\getlistitemTest{\getlistitem\mylist{4}}
+}\hrulefill\par
+\noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
+\test{getlistitem}
+
+\subsection{\cmd{getlistindex} {\mdseries(not expandable)}}
+\getlistindex{four}\mylist
+\hrulefill\par
+\noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
+\noindent\hskip6pt\textcolor{blue}{\llap\smex\cmd{getlistindex}{four}\cmd{mylist}}\par\vskip1.5ex
+\noindent\hskip6pt\cmd{indexinlist}=\quad{\bfseries\meaning\indexinlist}\par\hrulefill\par
+
+\end{document}
+%</example>
+%    \end{macrocode}
+%
+% \begin{thebibliography}{9}
+%
+% \bibitem{etex}
+%   David Carlisle and Peter Breitenlohner
+%   \textit{The \sty{etex} package};
+%   1998/03/26 v2.0;
+%   \CTAN{macros/latex/contrib/etex-pkg/etex.sty}.
+%
+% \bibitem{etoolbox}
+%   Philipp Lehman
+%   \textit{The \sty{etoolbox} package};
+%   2008/06/28 v1.7;
+%   \CTAN{macros/latex/contrib/etoolbox/etoolbox.dtx}.
+%
+% \end{thebibliography}
+%
+% \PrintIndex
+%
 % \label{LastPage}
 % \Finale
+
diff --git a/Master/texmf-dist/source/latex/etextools/etextools.ins b/Master/texmf-dist/source/latex/etextools/etextools.ins
index 9a94c04a435..79b0985e6af 100644
--- a/Master/texmf-dist/source/latex/etextools/etextools.ins
+++ b/Master/texmf-dist/source/latex/etextools/etextools.ins
@@ -18,7 +18,8 @@
 %% 
 %% This work consists of the main source file etextools.dtx
 %% and the derived files
-%%    etextools.sty, etextools.pdf, etextools.ins,
+%%       etextools.sty, etextools.pdf, etextools.ins,
+%% and   etextools-examples.tex
 %% 
 %%% etextools : more e-TeX useful tools for LaTeX package writers
 %%% Florent CHERVET
@@ -46,7 +47,8 @@ version. The latest version of this license is in
 
 This work consists of the main source file etextools.dtx
 and the derived files
-   etextools.sty, etextools.pdf, etextools.ins,
+      etextools.sty, etextools.pdf, etextools.ins,
+and   etextools-examples.tex
 
 \endpreamble
 \let\MetaPrefix\DoubleperCent
@@ -54,6 +56,7 @@ and the derived files
 \generate{%
   \file{etextools.ins}{\from{etextools.dtx}{install}}%
   \file{etextools.sty}{\from{etextools.dtx}{package}}%
+  \file{etextools-examples.tex}{\from{etextools.dtx}{example}}%
 }
 
 \obeyspaces
@@ -64,7 +67,7 @@ and the derived files
 \Msg{*}
 \Msg{*     etextools.sty}
 \Msg{*}
-\Msg{* To produce the documentation run the file `etextools.drv'}
+\Msg{* To produce the documentation run the file `etextools.dtx'}
 \Msg{* through LaTeX.}
 \Msg{*}
 \Msg{* Happy TeXing!}
@@ -72,6 +75,7 @@ and the derived files
 \Msg{************************************************************************}
 
 \endbatchfile
+
 \endinput
 %%
 %% End of file `etextools.ins'.
diff --git a/Master/texmf-dist/tex/latex/etextools/etextools.sty b/Master/texmf-dist/tex/latex/etextools/etextools.sty
index 93f0792044b..0a2382ba988 100644
--- a/Master/texmf-dist/tex/latex/etextools/etextools.sty
+++ b/Master/texmf-dist/tex/latex/etextools/etextools.sty
@@ -18,7 +18,8 @@
 %% 
 %% This work consists of the main source file etextools.dtx
 %% and the derived files
-%%    etextools.sty, etextools.pdf, etextools.ins,
+%%       etextools.sty, etextools.pdf, etextools.ins,
+%% and   etextools-examples.tex
 %% 
 %%% etextools : more e-TeX useful tools for LaTeX package writers
 %%% Florent CHERVET
@@ -33,6 +34,8 @@
 \catcode`\ =10
 \long\def\ettl@afterelse#1\else#2\fi{\fi#1}
 \long\def\ettl@afterfi#1\fi{\fi#1}
+\long\def\ettl@afterfifi#1\fi\fi{\fi\fi#1}
+\long\def\ettl@afterelsefi#1\else#2\fi\fi{\fi#1}
 \newcommand*\@gobblescape{\expandafter\@gobble\string}
 \newcommand\str@gobblescape[1]{\expandafter\deblank\expandafter{%
          \expandafter\@gobble\detokenize{#1}}}
@@ -83,28 +86,28 @@
 \begingroup\catcode`\&=3
 \gdef\etextools@defcmdparser#1#2{%
    \begingroup
+   \def\`##1`{\expandafter\noexpand\csname ##1\endcsname}%
    \protected@edef\defineparser{\endgroup
    \long\def#1####1{\noexpand\FE@ifstar{####1}
-      {\noexpandcs{ettl@lst@star\string#1}}
-      {\noexpandcs{ettl@lst@nost\string#1}}}%
+      {\`ettl@lst@star\string#1`}
+      {\`ettl@lst@nost\string#1`}}%
    \long\csdef{ettl@lst@star\string#1}####1{\noexpand\FE@testopt{####1}
-      {\noexpandcs{ettl@lst@star@pt\string#1}}{\noexpand\do}}%
+      {\`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}}%
+      {\`ettl@lst@nost@pt\string#1`}{\noexpand\do}}%
    \long\csdef{ettl@lst@star@pt\string#1}[####1]####2{%
-      \noexpandcs{ettl@lst\string#1}{####2}{####1}}%
+      \`ettl@lst\string#1`{####2}{####1}}%
    \long\csdef{ettl@lst@nost@pt\string#1}[####1]####2{%
-      \noexpandafter\noexpandcs{ettl@lst\string#1}\noexpandafter{%
-                                          ####2}{####1}}%
+      \noexpandafter\`ettl@lst\string#1`\noexpandafter{####2}{####1}}%
    \long\csdef{ettl@lst\string#1}####1####2{%
-         \noexpandcs{ettl@lst@\string#1}{####2}####1\noexpand#2&}%
-   \long\csdef{ettl@lst@\string#1}####1####2\noexpand#2####3&{%
+         \`ettl@lst@\string#1`{####2}####1\unexpanded{#2}&}%
+   \long\csdef{ettl@lst@\string#1}####1####2\unexpanded{#2}####3&{%
       \noexpand\ifblank{####2}
             {}
             {\noexpand\ettl@lst@doitem{####1}{####2}}%
       \noexpand\ifblank{####3}
             {\noexpand\ettl@listbreak}
-            {\noexpandcs{ettl@lst@\string#1}{####1}####3}&}%
+            {\`ettl@lst@\string#1`{####1}####3}&}%
    }\defineparser}%
    \long\gdef\ettl@lst@doitem#1#2{#1{#2}}%
    \long\gdef\ettl@listbreak#1&{}%
@@ -113,14 +116,19 @@
 \begingroup\catcode`\|=3
    \gdef\do{\DeclareCmdListParser\listloop{|}\undef\do}\aftergroup\do
 \endgroup
-\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}}]}
+\newcommand\csvtolist{\@ifstar\star@csvtolist\nost@csvtolist}
+\def\star@csvtolist#1{\let#1\@empty\csvloop*[{\unexpanded{\listadd#1}}]}
+\def\nost@csvtolist#1{\let#1\@empty\csvloop[{\unexpanded{\listadd#1}}]}
+\newcommand\csvtolistadd{\@ifstar\star@csvtolistadd\nost@csvtolistadd}
+\def\star@csvtolistadd#1#2{\ifblank{#2}
+         {\let#1\@empty}{\csvloop*[{\unexpanded{\listadd#1}}]{#2}}}
+\def\nost@csvtolistadd#1#2{\ifblank{#2}
+         {\let#1\@empty}{\csvloop[{\unexpanded{\listadd#1}}]{#2}}}
 \newrobustcmd\listdel[2]{\@listdel\def{#1}{#2}}
 \newrobustcmd\listgdel[2]{\@listdel\gdef{#2}{#2}}
 \newrobustcmd\listxdel[2]{\begingroup
    \protected@edef\@listxdel{\endgroup
-      \unexpanded{\@listdel\def#1}{#2}%
+      \unexpanded{\@listdel\gdef#1}{#2}%
    }\@listxdel}
  \begingroup\catcode`\|=3\catcode`\&=3
  \long\gdef\@listdel#1#2#3{%
@@ -135,6 +143,36 @@
       \expandafter\@tempx\unexpanded\expandafter{#2}&}%
    }\@redef}% end of \@listdel
 \endgroup
+\begingroup\catcode`\|=3\catcode`\&=3
+\gdef\ettl@list@first@item#1|#2&{#1}
+\gdef\ettl@list@other@item#1|#2&{#2}
+\gdef\getlistindex#1{\FE@ifstar{#1}{\ettl@getlistindex{}}
+                                   {\ettl@getlistindex\expandnext}}
+\gdef\xgetlistindex#1{\FE@ifstar{#1}{\ettl@xgetlistindex{}}
+                                    {\ettl@xgetlistindex\expandnext}}
+\gdef\ettl@xgetlistindex#1#2#3{\begingroup
+   \protected@edef\next{\endgroup\unexpanded{\ettl@getlistindex{#1}{#2}}{#3}%
+   }\next}
+\gdef\ettl@getlistindex#1#2#3{\begingroup#1\ettl@get@list@idx{#3}{#2}{\numexpr1}}
+\gdef\ettl@get@list@idx#1#2#3{% #1=expanded list, #2=item, #3=index
+   \ifblank{#1}0% the (remainder of) the list is empty
+      {\expandnext\ifstrequal{\ettl@list@first@item#1&}{#2}
+         {\endgroup\edef\indexinlist{\number#3\relax}}
+         {\expandnext\ettl@get@list@idx{\ettl@list@other@item#1&}{#2}{#3+1}}}}
+\endgroup% catcode group
+\newcommand\getlistitem[1]{\FE@ifstar{#1}\ettl@getlistitem
+                                        {\expandnext\ettl@getlistitem}}
+\begingroup\catcode`\&=3
+\long\gdef\ettl@getlistitem#1#2{%#1=listmacro, #2=index
+   \ettl@get@list@item{#1}{\number\numexpr#2}}
+\long\gdef\ettl@get@list@item#1#2{%
+   \ifblank{#1}{}
+      {\ifnum#2=1 \ettl@afterelsefi
+            \expandonce{\ettl@list@first@item#1&}
+      \else\ifnum#2>0 \ettl@afterfifi
+            \expandnext\ettl@getlistitem{\ettl@list@other@item#1&}{#2-1}%
+      \fi\fi}}
+\endgroup
 
 \endinput
 %%