catoptions (19aug12)

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

2 files changed, 33 insertions, 11 deletions

diff --git a/Master/texmf-dist/doc/latex/catoptions/README b/Master/texmf-dist/doc/latex/catoptions/README
index 424170cc7d4..a37cfebb289 100644
--- a/Master/texmf-dist/doc/latex/catoptions/README
+++ b/Master/texmf-dist/doc/latex/catoptions/README
@@ -2,7 +2,7 @@ This is the README file for the 'catoptions' package.
 
 VERSION
 
-Version 0.2.7b, 2011/12/17
+Version 0.2.7d, 2012/08/02
 
 SUMMARY
 
@@ -35,8 +35,9 @@ Ahmed Musa
 
 RELATED PACKAGES
 
-The catcode section of the 'catoptions' package is based on the
-'pcatcode' package by Michael J. Downes and David M. Jones.
+The catcode section of the 'catoptions' package is an extension of
+the 'pcatcode' package by Michael J. Downes and David M. Jones.
+
 
 
 
diff --git a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
index 553438cd5b1..e4386d91223 100644
--- a/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
+++ b/Master/texmf-dist/doc/latex/catoptions/catoptions-guide.tex
@@ -17,6 +17,27 @@
 \makeindex
 \let\footnote\ltsfootnote
 
+
+\newcount\nr
+\def\alist{a1/b1/c1; a2/b2/c2; a3/b3/c3}
+\trace*
+\cptforeach*[;] \xa/\ya/\za \in \alist \do{%
+  \nr\z@pt
+  \cptforeach[,] \xb|\yb|\zb \in s1|t1|u1, s2|t2|u2, s3|t3|u3 \do{%
+    \advance\nr\@ne
+    \ifnum\nr>\@ne\ltsloopbreak\fi
+    % It is permissible to use #1, #2, #3, ##1, ##2, ##3, etc,
+    % to refer to the elements of each list, but they won't be
+    % despaced as \xa, \ya, \za, etc will be:
+    % \edef\cmda####1{#1#2#3*####1*##1##2##3}%
+    \edef\cmdb####1{\xa\ya\za*####1*\xb\yb\zb}%
+  }%
+}
+
+
+% \ifsingletokenTF
+% \ifblankTF
+
 \begin{document}
 
 \begin{frontmatter}
@@ -793,7 +814,7 @@ Here are some points to note about these list processors:
 \item White spaces before and after the list separator are always ignored by the normalizer called by \ffx'{\csv@@parse,\kv@@parse}. If an item contains \ang{parser} or starts with a space, it must, therefore, be wrapped in curly braces before commencing these loops.
 \item Since \ffx'{\csv@@loop,\kv@@loop} don't call the normalizer, they preserve outer/surrounding spaces in the entries. Empty entries in \ang{list} or \ang{listcmd} will be processed by \ffx'{\csv@@loop,\kv@@loop} if the boolean \fx{cpt@useempty} is true. You may thus issue the command \fx{\UseEmptyEntry} or \fx{\DiscardEmptyEntry}, which are based on the boolean \fx{cpt@useempty}, before commencing the iteration. If empty entries are important to the task at hand, then issuing \fx{\UseEmptyEntry} or \fx{\DiscardEmptyEntry} prior to the commencement of the loop is recommended, because a previous call to either \fx{\csv@@loop} or \fx{\kv@@loop} (perhaps by another package) could have set \fx{cpt@useempty} to a state that is no longer valid or desired.
 \item The commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse} can be nested to any level and can be mixed.
-\item In the commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse}, it is always possible to break out of the loop prematurely at any level of nesting, simply by issuing the command \fx{\loopbreak} (see the example below). Breaking an inner loop doesn't affect the continuation of the outer loop, and vice versa; that is, loop breaks are nest-level-dependent.
+\item In the commands \ffx'{\csv@@loop,\csv@@parse,\kv@@loop,\kv@@parse}, it is always possible to break out of the loop prematurely at any level of nesting, simply by issuing the command \fx{\ltsloopbreak} (see the example below). Breaking an inner loop doesn't affect the continuation of the outer loop, and vice versa; that is, loop breaks are nest-level-dependent.
 \item The user can insert \fx{\csvbreak} as an element in \ang{list} for any of the commands \ffx'{\csv@@loop, \csv@@parse, \kv@@loop, \kv@@parse, \dofunclist} with the aim of automatically breaking out of the list processing prematurely (\ie, before the list is exhausted). The tokens \ffx'{\listbreak, \breaklist} are not defined or used by the \pkg'{catoptions}, to avoid name clashes with other packages. The \pkg'{catoptions} instead uses \fx{\csvbreak}, which is an unexpandable token; if it were to be expandable, then experience has shown that a chaotic infinite loop could arise in an expansion context. Breaking out of the loop prematurely on the current nest level doesn't affect the continuation of the loop on the other levels.
 \end{enum}
 
@@ -820,7 +841,7 @@ Here are some points to note about these list processors:
   \def\csv@do##1{%
     \pushnumber\nrb
     |com(Breaking the inner loop here doesn't affect the outer loop:)
-    \ifnum\nrb>\@ne|R(\loopbreak)\fi
+    \ifnum\nrb>\@ne|R(\ltsloopbreak)\fi
     \csn@def{arg@\romannumeral\nra @\romannumeral\nrb}{#1,##1}%
   }%
   \csv@@parse*[;]\xb
@@ -911,7 +932,7 @@ Empty entries in \ang{list} will be ignored by the normalizer called by \fx{\dof
   \chardef\n@\z@
   \def\do##1{%
     \pushnumber\n@
-    \ifnum\n@>\@ne|R(\loopbreak)\fi
+    \ifnum\n@>\@ne|R(\ltsloopbreak)\fi
     \csn@def{w@\romannumeral\m@ @\romannumeral\n@}{#1,##1}%
   }%
   \dofunclist[;]{x;{y};z}%
@@ -932,13 +953,13 @@ Imagine an instance in which, while processing a csv list, you need not only the
 \finish{newmacro}
 \fxim*{\indrisloop,\indrisdepth,\currindris,\currindris@i,
 \nextindris,\nextindris@i,\indrisnr,\iflastindris}
-\fxi*{\ifloopbreak}
+\fxi*{\ifLTS@loopbreak}
 
 The \fx{\indrisloop} command can be used to iterate over a \ang{parser}-separated \ang{list} or \ang{listcmd} and execute the user-supplied one-parameter command \ang{fn} for every item in the list, passing the item as an argument and preserving outer braces.
 
-The \fx{\indrisloop} iterator is of particular interest. The loop provides the macros \ffx'{\indrisdepth, \currindris, \currindris@i, \nextindris, \nextindris@i, \indrisnr, \iflastindris, \ifloopbreak}, which mean, respectively, the current nested depth/level, the current item on the current level, the current item on an arbitrary level \quotedfx{i}, the next item on the current level, the next item on an arbitrary level \quotedfx{i}, the numerical order of the current item on the current level, the boolean that indicates that the last item of the list has been reached on the current level of nesting, and the boolean that can be used to break the loop prematurely (before the list is exhausted) on any level.
+The \fx{\indrisloop} iterator is of particular interest. The loop provides the macros \ffx'{\indrisdepth, \currindris, \currindris@i, \nextindris, \nextindris@i, \indrisnr, \iflastindris, \ifLTS@loopbreak}, which mean, respectively, the current nested depth/level, the current item on the current level, the current item on an arbitrary level \quotedfx{i}, the next item on the current level, the next item on an arbitrary level \quotedfx{i}, the numerical order of the current item on the current level, the boolean that indicates that the last item of the list has been reached on the current level of nesting, and the boolean that can be used to break the loop prematurely (before the list is exhausted) on any level.
 
-You can do \fx{\iflastindris...\fi} on any level. On any given level, it is possible to break out of the current loop by simply issuing \fx{\loopbreak}. This would not affect the progress of the loops on other levels. When \fx{\iflastindris} is true on a given level \quotedfx{i}, then \ffx'{\nextindris,\nextindris@i} are empty on that level, but not necessarily the macros \ffx'{\currindris,\currindris@i}.
+You can do \fx{\iflastindris...\fi} on any level. On any given level, it is possible to break out of the current loop by simply issuing \fx{\ltsloopbreak}. This would not affect the progress of the loops on other levels. When \fx{\iflastindris} is true on a given level \quotedfx{i}, then \ffx'{\nextindris,\nextindris@i} are empty on that level, but not necessarily the macros \ffx'{\currindris,\currindris@i}.
 
 The following provides a simple application of \fx{\indrisloop}, which I posted on \comptexttex in July~2011 in response to a posted question.
 
@@ -1009,7 +1030,7 @@ The starred variants of \ffx'{\tsv@@loop,\tsv@@parse} expand \ang{listcmd} once
 
 Empty entries in \ang{list} or \ang{listcmd} will be processed if the boolean \fx{cpt@useempty} is true. You may thus issue the command \fxi{\UseEmptyEntry} or \fxi{\DiscardEmptyEntry} before commencing the iteration. Both commands \ffx'{\tsv@@loop,\tsv@@parse} can be nested to any level and can be mixed.
 
-In the commands \ffx'{\tsv@loop,\tsv@@parse}, it is always possible to break out of the loop prematurely at any level of nesting by issuing the command \fx{\loopbreak}. Again, breaking an inner loop doesn't affect the continuation of the outer loop, and vice versa. The user can insert \fx{\tsvbreak} as an element in \ang{list} for any of the commands \ffx'{\tsv@@loop, \tsv@@parse} so as to automatically break out of the list processing prematurely (\ie, before the list is exhausted).
+In the commands \ffx'{\tsv@loop,\tsv@@parse}, it is always possible to break out of the loop prematurely at any level of nesting by issuing the command \fx{\ltsloopbreak}. Again, breaking an inner loop doesn't affect the continuation of the outer loop, and vice versa. The user can insert \fx{\tsvbreak} as an element in \ang{list} for any of the commands \ffx'{\tsv@@loop, \tsv@@parse} so as to automatically break out of the list processing prematurely (\ie, before the list is exhausted).
 
 \start+{example}[\tsv@@loop,\tsv@@parse]
 \newcount\m
@@ -1025,7 +1046,7 @@ In the commands \ffx'{\tsv@loop,\tsv@@parse}, it is always possible to break out
 \tsv@@loop{ a {b} {c} }
 \finish{example}
 
-    
+
 \docsection(sec:version-hist){Version history}
 
 The following change history highlights significant changes that affect user utilities and interfaces; mutations of technical nature are not documented in this section. The numbers on the right-hand side of the following lists are section numbers; the \stsign means the subject features in the package but is not reflected anywhere in this user guide.