etextools update (23sep09)

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

1 files changed, 100 insertions, 31 deletions

diff --git a/Master/texmf-dist/doc/latex/etextools/etextools-examples.tex b/Master/texmf-dist/doc/latex/etextools/etextools-examples.tex
index 572e76e479d..6d86965ec67 100644
--- a/Master/texmf-dist/doc/latex/etextools/etextools-examples.tex
+++ b/Master/texmf-dist/doc/latex/etextools/etextools-examples.tex
@@ -21,44 +21,51 @@
 %%       etextools.sty, etextools.pdf, etextools.ins,
 %% and   etextools-examples.tex
 %% 
-%%% etextools : more e-TeX useful tools for LaTeX package writers (v.
-
+%%% etextools : e-TeX tools for LaTeX Users and package Writers (v.3.0)
 \documentclass[11pt,french,a4paper,oneside]{scrartcl}
 \usepackage[latin1]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage[american]{babel}
-\usepackage{geometry,doc,ltxdockit,txfonts,fancyhdr,stmaryrd,graphicx,fancyvrb}
+\usepackage{geometry,doc,ltxdockit,txfonts,fancyhdr,stmaryrd,graphicx,enumitem}
 \usepackage{etextools}
+
+\usepackage{fancyvrb}
+
+\def\textvb#1{{\usefont{T1}{txtt}{m}{n}#1}}
+\def\thispackage{\textsf{etextools}}
 \hypersetup{colorlinks,pdfstartview={FitH}}
 \geometry{top=1.5cm,bottom=1.2cm,left=2.5cm,right=1cm}
 \fancyhf{}
-\fancyhead[L]{Examples for the \sty{etextools} package}
+\fancyhead[L]{Examples for the \thispackage package}
 \pagestyle{fancy}
-\MakeShortVerb{\|}
-
+\DefineShortVerb{\|}
+\catcode`\§ \active\def§{\par\nobreak\vskip-\parskip}
 \makeatletter
+\DefineVerbatimEnvironment{VerbLines}{Verbatim}
+   {gobble=1,commandchars=!(),frame=lines,framesep=6pt,fontfamily=txtt,fontseries=m}
+\apptocmd\@list@extra{\parsep\parskip\topsep\z@\itemsep\z@}{}{}
+
 \def\smex{\leavevmode\hb@xt@2em{\hfil$\longrightarrow$\hfil}}
 \def\FE{\setbox8\hbox{$\m@th\bindnasrepma$}%
          \textcolor{fecc}{\scalebox{2}{$\copy8\mkern-13.5mu\copy8\mkern-13.5mu\copy8$}}}
+\def\pdfFE{\setbox8\hbox{$\m@th\bindnasrepma$}%
+         \textcolor{fecc}{\llap{\textsf{pdf}\TeX{}\,}\scalebox{2}{$\copy8\mkern-13.5mu\copy8\mkern-13.5mu\copy8$}}}
 \definecolor{fecc}{rgb}{.2,.6,.2}
-\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}}
+\definecolor{dg}{rgb}{0.00,0.37,0.00} \newrobustcmd\dg{\color{dg}}   \newrobustcmd\dgbf{\dg\bfseries}
+
+\newrobustcmd\blue{\color{blue}
+\newrobustcmd\nnn{\normalfont\mdseries\upshape}
+
+\def\make@macro#1{\string\def\string#1\parameters@meaning#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}
+\newcommand\@preline[2][1.5ex]{\noindent\hskip6pt\textvb{\make@macro#2}\par\ifblank{#1}{}{\vskip#1}}
 
-\def\meaningcs#1{\expandafter\meaning\csname#1\endcsname}
-\def\Meaningcs#1{\expandafter\strip@meaning\csname #1\endcsname}
-\@ifundefined{pdfstrcmp}{\let\ifpdfTeX\iffalse}{\let\ifpdfTeX\iftrue}
+\ifdef\pdfstrcmp{\let\ifpdfTeX\iffalse}{\let\ifpdfTeX\iftrue}
 
-\newcommand*\test{\@ifstar{\let\fe\relax\testi}{\let\fe\FE\testi}}
+\newcommand*\test{\@ifstar{\let\fe\pdfFE\testi}{\let\fe\FE\testi}}
 \newcommand\testi[1]{%
    \csname test#1\endcsname
-   \edef\usercmd{\Meaningcs{test#1}}\edef\result{\meaningcs{#1Test}}\noindent
+   \edef\usercmd{\strip@meaningcs{test#1}}\edef\result{\meaningcs{#1Test}}\noindent
    \begin{tabular}{lp{15cm}}
    \multicolumn{2}{l}{\textcolor{blue}{\llap{\fe\,\smex}\tt \usercmd}} \\[1.5ex]
    \cmd{#1Test}= & \tt\bfseries\result
@@ -66,12 +73,12 @@
 
 \begin{document}
 \title{etextools examples}
-\subtitle{Examples for some macros provided by the \sty{etextools} package}
+\subtitle{Examples for some macros provided by the \thispackage package}
 \author{Florent Chervet}
 \date{July 22, 2009}
 \maketitle
 
-\tableofcontents
+\tableofcontents\hyperdef{ettlex}{toc}{}
 
 \section{\cmd{expandnext} examples}
 
@@ -88,7 +95,7 @@
 \preline\xx
 \test{expandnext}
 
-\clearpage
+\ClearPage
 \subsection{Test if the replacement text of a macro is blank (empty or spaces)}
 
 \def\xx{something}
@@ -102,12 +109,74 @@
 \preline\xx
 \test{expandnext}
 
-\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{\cmd{ExpandNext} examples}
+
+Example of the main documentation file to reverse the order of the characters in a string:
+
+\def\swap#1#2{{#2#1}}   \def\do[#1]#2{\swap #2}% \do{abcdef}   -> \swap ab + cdef   -> {ba}cdef
+                                               % \do{{ba}cdef} -> \swap {ba}c + def -> {cba}def
+
+\edef\result{\naturalloop[\do]{4}{12345}}
+\ExpandNext{\def\RESULT}{\naturalloop[\do]{4}{12345}}
+
+\begin{VerbLines}
+\def\swap#1#2{{#2#1}}   \def\do[#1]#2{\swap #2}
+\edef\result{\naturalloop[\do]{4}{12345}}
+\meaning\result = !bfseries!meaning!result
+\ExpandNext{\def\RESULT}{\naturalloop[\do]{4}{12345}}
+\meaning\RESULT = !bfseries!meaning!RESULT
+\end{VerbLines}
+
+\subsection{Test the parameter string of a macro}
+
+The following commands create the filter for the string: "\textvb{[\#1]\#2"}":§
+\begin{VerbLines}[commandchars=!()]
+\ExpandNext{(!blue\DeclareStringFilter\ParaFilt)}
+      {\ExpandAftercmds\@gobblescape{\expandafter\string\csname(!blue[#1]#2)\endcsname}}
+\end{VerbLines}
+
+\ExpandNext{\DeclareStringFilter\ParaFilt}
+      {\ExpandAftercmds\@gobblescape{\expandafter\string\csname[#1]#2\endcsname}}
+
+\begin{enumerate}[label=\arabic*)~,noitemsep,nolistsep]
+\item |\csname[#1]#2\endcsname| is expanded first
+\item Immediately after: |\string|
+\item At this stage: |\[#1]#2| (everything in category code other) is no more expandable
+\item Then |\ExpandAftercmds| expands |\@gobblescape|
+\item |[#1]#2| is no more expandable
+\item Then |\ExpandNext| expands its first argument: |\DeclareStringFilter\ParaFilt{[#1]#2}|
+\end{enumerate}
+
+Remark: |\detokenize| would have doubled the \# characters. Another possibility is to temporarily change the
+category code of \# to 12 (other):
+\begin{VerbLines}[commandchars=!()]
+\begingroup\catcode`\#=12
+  (!blue\DeclareStringFilter\ParaFilt{[#1]#2})     !nnn global declaration
+\endgroup
+\end{VerbLines}
+
+\def\macroA#1#2{Something to do with #1 and #2}
+\def\macroB[#1]#2{Something to do with #1 and #2}
+
+\makeatother
+
+\preline[]\macroA
+\preline*[]\macroB
+\begin{Verbatim}[commandchars=!()]
+ !blue\ExpandNext{\ParaFilt=.}{\parameters@meaning\macroA}{macro complies with [\#1]\#2}
+                                                     !blue{macro does not comply }
+\end{Verbatim}
+\makeatletter
+\hfill\textvb{\dgbf\ExpandNext{\ParaFilt=.}{\parameters@meaning\macroA}{macro complies with [\#1]\#2}
+                                                     {macro does not comply }}
+\begin{Verbatim}[commandchars=!()]
+ !blue\ExpandNext{\ParaFilt=.}{\parameters@meaning\macroB}{macro complies with [\#1]\#2}
+                                                     !blue{macro does not comply }
+\end{Verbatim}
+\hfill\textvb{\dgbf\ExpandNext{\ParaFilt=.}{\parameters@meaning\macroB}{macro complies with [\#1]\#2}
+                                                     {macro does not comply }}
+\par\hrulefill\par
+\makeatother
 
 \section{Testing characters}
 \subsection{\cmd{ifsinglechar} versus \cmd{iffirstchar}}
@@ -211,13 +280,13 @@
    \edef\getlistindexTest{\getlistindex{alpha}\mylist}
 }\hrulefill\par
 \noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
-\test{getlistindex}
+\test*{getlistindex}
 
 \leavevmode\vadjust{\textsl{Require the }\string\pdfstrcmp\ \textsl{primitive (pdf\TeX{}) :}}
 \def\testgetlistindex{%
    \edef\getlistindexTest{\getcsvlistindex*{alpha}{one,two,three,four,five,alpha,beta}}
 }\hrulefill\par
-\test{getlistindex}
+\test*{getlistindex}
 \fi
 
 \hrulefill\par
@@ -243,7 +312,7 @@
 }\hrulefill\par
 \noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
 \preline*\x
-\test{xgetlistindex}
+\test*{xgetlistindex}
 \fi
 
 \subsubsection{\cmd{getlistindex} with \cmd{ifcase}}