stringstrings update (16apr10)

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

1 files changed, 109 insertions, 1 deletions

diff --git a/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx b/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx
index 6b98d0183ea..656bcda8ef3 100644
--- a/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx
+++ b/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx
@@ -1,6 +1,6 @@
 % \iffalse
 %<package>\ProvidesPackage{stringstrings}
-%<package>[2009/11/02 v1.10
+%<package>[2010/02/23 v1.20
 %<package> Extensive array of string manipulation routines for
 %<package> cosmetic and programming application]
 %<package>\NeedsTeXFormat{LaTeX2e}
@@ -15,6 +15,7 @@
 % v1.10 -Fixed bug in convertword by adding @@@stringsize definition to 
 %        \whereisword
 %       -Added suite of routines to support \capitalizetitle functionality
+% v1.20 -Added ability to encode/decode arbitrary tokens
 \documentclass{ltxdoc}
 \usepackage{stringstrings}
 \DisableCrossrefs
@@ -325,6 +326,8 @@
 % |\Treatments{|{\it U-mode}|}{|{\it l-mode}|}{|{\it p-mode}|}{|{\it%
 %    n-mode}|}{|{\it s-mode}|}{|{\it b-mode}|}|\\ 
 % |\defaultTreatments|\\
+% |\encodetoken[|{\it index}|]{|{\it token}|}|\\
+% |\decodetoken[|{\it index}|]{|{\it token}|}|\\
 % |\+|\\
 % |\?|
 %
@@ -397,6 +400,25 @@
 % resets all treatment modes to their default settings, which are to
 % leave individual characters unaltered by a string manipulation.
 %
+% The commands |\encodetoken| \DescribeMacro{\encodetoken} and
+% |\decodetoken| \DescribeMacro{\decodetoken} have been introduced in
+% \stringstrings v1.20.  Prior to this version, the ability of
+% \stringstrings to handle a particular token was dependent on whether
+% provisions for encoding that token had been explicitly hardwired into
+% the \stringstrings package.  A large number of alphabetic and
+% diacritical marks had reserved encodings set aside in \stringstrings
+% for their treatment (see next paragraph or Table 2 for their enumeration).
+% However, requests would invariable come in for treating yet another
+% token, which required a new \stringstrings release for each revision.
+% The command |\encodetoken| allows the user to specify an arbitrary
+% token, to be assigned to the reserved encoding slot associated with the
+% index (permissible indices are in the range 1--3, 1 being the default).
+% Once assigned an encoding slot, a token may be successfully manipulated in
+% \stringstrings routines.  Once \stringstrings manipulation is
+% complete, the token must undergo a |\decodetoken| operation in order
+% for that token to be reset to a normal \LaTeX{} token again (lest it
+% display in its encoded \stringstrings form).
+% 
 % The commands |\+| and |\?| \DescribeMacro{\+}\DescribeMacro{\?}
 % are a pair that work in tandem to turn on \stringstrings encoding and
 % turn off \stringstrings encoding, respectively.  Generally, the user
@@ -1216,6 +1238,24 @@
 % THE FOLLOWING IS BETTER FOR T1 ENCODING, BUT BREAKS OT1 ENCODING
 %\def\Dollar{\SaveDollar}
 
+% |W IS RESERVED TO BE ASSIGNED TO AN ARBITRARY TOKEN
+\def\UvariCode{W}
+\def\EncodedUvari{\EscapeChar\UvariCode}
+\def\Uvari{Uvari}
+\let\uvari\EncodedUvari
+
+% |X IS RESERVED TO BE ASSIGNED TO AN ARBITRARY TOKEN
+\def\UvariiCode{X}
+\def\EncodedUvarii{\EscapeChar\UvariiCode}
+\def\Uvarii{Uvarii}
+\let\uvarii\EncodedUvarii
+
+% |Y IS RESERVED TO BE ASSIGNED TO AN ARBITRARY TOKEN
+\def\UvariiiCode{Y}
+\def\EncodedUvariii{\EscapeChar\UvariiiCode}
+\def\Uvariii{Uvariii}
+\let\uvariii\EncodedUvariii
+
 % |2 IS AN ENCODED ^ FOR USE IN TEXT MODE, ACCESSED VIA \carat
 \def\CaratCode{2}
 \def\EncodedCarat{\EscapeChar\CaratCode}
@@ -1587,6 +1627,53 @@
 %    \end{macrocode}
 % \end{macro}
 
+% \begin{macro}{\encodetoken}
+% The command |\encodetoken| assigns the supplied token to one of three
+% reserved \stringstrings user variables (the optional argument dictates
+% which user variable).  Once encoded, the supplied token cannot be used
+% in the normal way, but only in stringstrings routines, unless and
+% until it is decoded.
+%    \begin{macrocode}
+\newcommand\encodetoken[2][1]{%
+  \if 1#1%
+  \let\Uvari#2%
+  \let#2\uvari\else
+    \if 2#1%
+    \let\Uvarii#2%
+    \let#2\uvarii\else
+      \if 3#1%
+        \let\Uvariii#2%
+        \let#2\uvariii%
+      \fi
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\decodetoken}
+% The command |\decodetoken| deassigns the supplied token from the
+% reserved \stringstrings user variables (the optional argument dictates
+% which user variable), so that the token may be used in the normal way
+% again.
+%    \begin{macrocode}
+\newcommand\decodetoken[2][1]{%
+  \if 1#1%
+    \let#2\Uvari%
+    \def\Uvari{Uvari}\else
+    \if 2#1%
+      \let#2\Uvarii%
+      \def\Uvarii{Uvarii}\else
+      \if 3#1%
+        \let#2\Uvariii%
+        \def\Uvariii{Uvariii}%
+      \fi
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+
 %    \begin{macrocode}
 %%%%% COMMANDS TO MANIPULATE STRINGS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %    \end{macrocode}
@@ -2995,6 +3082,9 @@
 % symbol to end of string, in the fashion of macro |\@rotate|.
 %    \begin{macrocode}
 \newcommand\ESCrotate[1]{%
+     \if\UvariCode#1\@uvariaction\else
+    \if\UvariiCode#1\@uvariiaction\else
+   \if\UvariiiCode#1\@uvariiiaction\else
   \if\@fromcode#1\@tostring\else
    \if\PipeCode#1\@pipeaction\else
     \if\DollarCode#1\@dollaraction\else
@@ -3076,6 +3166,9 @@
     \fi
    \fi
   \fi
+   \fi
+    \fi
+     \fi
 }
 %    \end{macrocode}
 % \end{macro}
@@ -3111,6 +3204,12 @@
   \isnextbyte[q]{\EscapeChar}{#1}%
   \if T\theresult%
   \edef\@ESCcode{\expandafter\@gobble#1}%
+       \if\UvariCode\@ESCcode%
+       \expandafter\def\csname#2\endcsname{\Uvari}\else
+      \if\UvariiCode\@ESCcode%
+      \expandafter\def\csname#2\endcsname{\Uvarii}\else
+     \if\UvariiiCode\@ESCcode%
+     \expandafter\def\csname#2\endcsname{\Uvariii}\else
     \if\PipeCode\@ESCcode%
     \expandafter\def\csname#2\endcsname{\Pipe}\else
      \if\DollarCode\@ESCcode%
@@ -3209,6 +3308,9 @@
       \fi
      \fi
     \fi
+     \fi
+      \fi
+       \fi
   \else
     \expandafter\ifx\expandafter\&#1%
                            \expandafter\def\csname#2\endcsname{\&}\else
@@ -3242,6 +3344,9 @@
     \edef\@blankaction{\EncodedBlankSpace}%
     \def\@dollaraction{\EncodedDollar}%
     \def\@pipeaction{\EncodedPipe}%
+    \def\@uvariaction{\EncodedUvari}%
+    \def\@uvariiaction{\EncodedUvarii}%
+    \def\@uvariiiaction{\EncodedUvariii}%
     \def\@carataction{\EncodedCarat}%
     \def\@circumflexaction{\EncodedCircumflex}%
     \def\@tildeaction{\EncodedTilde}%
@@ -3301,6 +3406,9 @@
     \def\@blankaction{\BlankSpace}%
     \def\@dollaraction{\Dollar}%
     \def\@pipeaction{\Pipe}%
+    \def\@uvariaction{\Uvari}%
+    \def\@uvariiaction{\Uvarii}%
+    \def\@uvariiiaction{\Uvariii}%
     \def\@carataction{\Carat}%
     \def\@circumflexaction{\Circumflex}%
     \def\@tildeaction{\Tilde}%