stringstrings update (3nov09)

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

1 files changed, 176 insertions, 80 deletions

diff --git a/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx b/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx
index 33a8379c000..6b98d0183ea 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/10/01 v1.04
+%<package>[2009/11/02 v1.10
 %<package> Extensive array of string manipulation routines for
 %<package> cosmetic and programming application]
 %<package>\NeedsTeXFormat{LaTeX2e}
@@ -12,6 +12,9 @@
 % v1.03 -Documentation fix; notably removed 's' from \narg in \getargs
 % v1.04 -Removed \rotate command, as it conflicts with environment in
 %        \usepackage{rotating}
+% v1.10 -Fixed bug in convertword by adding @@@stringsize definition to 
+%        \whereisword
+%       -Added suite of routines to support \capitalizetitle functionality
 \documentclass{ltxdoc}
 \usepackage{stringstrings}
 \DisableCrossrefs
@@ -428,6 +431,10 @@
 % |\alphabetic[|{\it mode}|]{|{\it string}|}|\\ 
 % |\capitalize[|{\it mode}|]{|{\it string}|}|\\ 
 % |\capitalizewords[|{\it mode}|]{|{\it string}|}|\\
+% |\capitalizetitle[|{\it mode}|]{|{\it string}|}|\\ 
+% |\addlcword{|{\it word}|}|\\ 
+% |\addlcwords{|{\it word1 word2 word3 \ldots}|}|\\ 
+% |\resetlcwords|\\ 
 % |\reversestring[|{\it mode}|]{|{\it string}|}|\\
 % |\convertchar[|{\it mode}|]{|{\it
 %    string}|}{|{\it from-char}|}{|{\it to-string}|}|\\
@@ -537,6 +544,21 @@
 % character that follows one or more blankspaces.
 % Default mode is |[v]|.
 %
+% The command |\capitalizetitle| \DescribeMacro{\capitalizetitle} is a
+% command similar to |\capitalizewords|, except that words which have
+% been previously designated as ``lower-case words'' are not
+% capitalized (\eg prepositions, conjunctions, \etc).  In all cases,
+% the first word of the string is
+% capitalized, even if it is on the lower-case word list.  Words are
+% added to the lower-case word list with the commands
+% |\addlcword|\DescribeMacro{\addlcword}, in the case of a single word, 
+% or with |\addlcwords|\DescribeMacro{\addlcwords}, in the case of
+% multiple (space-separated) words.  Because the addition of many words
+% to the lower-case list can substantially slow-down the execution of
+% the |\capitalizetitle| command, the command
+% |\resetlcwords| \DescribeMacro{\resetlcwords} has been added to
+% allow the user to zero out the lower-case word list.
+% 
 % The command |\reversestring| \DescribeMacro{\reversestring} reverses
 % the sequence of characters in a string, such that what started as
 % the first character becomes the last character in the manipulated
@@ -559,9 +581,10 @@
 % command in which a specified match string in the original string
 % ({\it from-string}) is substituted with a different string ({\it
 % to-string}).  All occurances of {\it from-string} in the original
-% string are replaced.  
+% string are replaced.  If {\it from-string} includes spaces, use
+% hard-space |(~)| characters instead of blanks.
 % Default mode is |[v]|.
-% 
+%
 % The command |\rotateword| \DescribeMacro{\rotateword} takes the first
 % word of {\it string} (and its leading and trailing spaces)
 % and rotates them to the end of the string.  
@@ -1399,6 +1422,7 @@
 \newcounter{@maxrotation}
 \newcounter{@stringsize}
 \newcounter{@@stringsize}
+\newcounter{@@@stringsize}
 \newcounter{@revisedstringsize}
 \newcounter{@gobbleindex}
 \newcounter{@charsfound}
@@ -1414,6 +1438,7 @@
 \newcounter{@matchsize}
 \newcounter{@matchmax}
 \newcounter{@skipped}
+\newcounter{@lcwords}
 %    \end{macrocode}
 %    \begin{macrocode}
 %%%%% CONFIGURATION COMMANDS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1955,6 +1980,153 @@
 %    \end{macrocode}
 % \end{macro}
 
+% \begin{macro}{\convertword}
+% Takes a string, a replaces each occurance of a specified string
+% with a replacement string.  
+%    \begin{macrocode}
+\newcounter{@@matchloc}
+% LIKE \convertchar, EXCEPT FOR WORDS
+\newcommand\convertword[4][v]{%
+  \+\edef\@@teststring{#2}%
+  \edef\@fromstring{#3}%
+  \edef\@tostring{#4}\?%
+  \edef\@@@teststring{\@@teststring}%
+  \def\@buildfront{}%
+  \edef\@buildstring{\@@teststring}%
+  \setcounter{@charsfound}{0}%
+  \whiledo{\the@charsfound > -1}{%
+%    \end{macrocode}
+% Seek occurance of |\@fromstring| in larger |\@@teststring|
+%    \begin{macrocode}
+    \whereisword[q]{\@@teststring}{\@fromstring}%
+    \setcounter{@matchloc}{\theresult}%
+    \ifthenelse{\the@matchloc = 0}%
+      {%
+%    \end{macrocode}
+% Not found.  Done.
+%    \begin{macrocode}
+        \setcounter{@charsfound}{-1}%
+      }%
+      {%
+%    \end{macrocode}
+% Potential matchstring.
+%    \begin{macrocode}
+        \addtocounter{@charsfound}{1}%
+%    \end{macrocode}
+% Grab current test string from beginning to point just prior
+% to potential match.
+%    \begin{macrocode}
+        \addtocounter{@matchloc}{-1}%
+        \substring[e]{\@@@teststring}{1}{\the@matchloc}%
+%    \end{macrocode}
+% The string |\@buildfront| is the total original string, with
+% string substitutions, from character 1 to current potential match.
+%    \begin{macrocode}
+        \edef\@buildfront{\@buildfront\thestring}%
+%    \end{macrocode}
+% See if potential matchstring takes us to end-of-string\ldots
+%    \begin{macrocode}
+        \addtocounter{@matchloc}{1}%
+        \addtocounter{@matchloc}{\the@matchsize}%
+        \ifthenelse{\the@matchloc > \the@@@stringsize}%
+        {%
+%    \end{macrocode}
+% \ldots if so, then match is last one in string.  Tack on replacement
+% string to |\@buildfront| to create final string.  Exit.
+%    \begin{macrocode}
+          \setcounter{@charsfound}{-1}%
+          \edef\@buildstring{\@buildfront\@tostring}%
+        }%
+        {%
+%    \end{macrocode}
+% \ldots if not, redefine current teststring to begin at point following
+% the current substitution.  Make substitutions to current
+% |\@buildstring| and |\@buildfront|.  Loop through logic again on new
+% teststring.
+%    \begin{macrocode}
+          \substring[e]{\@@@teststring}{\the@matchloc}{\@MAXSTRINGSIZE}%
+          \edef\@@teststring{\thestring}%
+          \edef\@@@teststring{\@@teststring}%
+          \edef\@buildstring{\@buildfront\@tostring\@@@teststring}%
+          \edef\@buildfront{\@buildfront\@tostring}%
+        }%
+      }%
+  }%
+  \substring[#1]{\@buildstring}{1}{\@MAXSTRINGSIZE}%
+}
+%    \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\resetlcwords}
+% Removes all words from designated ``lower-case words'' list.  This can
+% be useful because large lists of lower-case words can significantly
+% slow-down the function of |\capitalizetitle|.
+%    \begin{macrocode}
+\setcounter{@lcwords}{0}
+% RESET LOWER-CASE WORD COUNT; START OVER
+\newcommand\resetlcwords[0]{%
+  \setcounter{@lcwords}{0}%
+}
+%    \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\addlcwords}
+% Add words to the list of designated ``lower-case words'' which will
+% not be capitalized by |\capitalizetitle|.  The input should consist of 
+% space-separated words, which are, in turn, passed on to |\addlcword|.
+%    \begin{macrocode}
+% PROVIDE LIST OF SPACE-SEPARATED WORDS TO REMAIN LOWERCASE IN TITLES
+\newcommand\addlcwords[1]{%
+  \getargs{#1}%
+  \setcounter{@wordindex}{0}%
+  \whiledo{\value{@wordindex} < \narg}{%
+    \addtocounter{@wordindex}{1}%
+    \addlcword{\csname arg\roman{@wordindex}\endcsname}%
+  }
+}
+%    \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\addlcword}
+% Add a word to the list of designated ``lower-case words'' which will
+% not be capitalized by |\capitalizetitle|.
+%    \begin{macrocode}
+% PROVIDE A SINGLE WORD TO REMAIN LOWERCASE IN TITLES
+\newcommand\addlcword[1]{%
+  \addtocounter{@lcwords}{1}%
+  \expandafter\edef\csname lcword\roman{@lcwords}\endcsname{#1}
+}
+%    \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\capitalizetitle}
+% Makes every word of a multi-word input string capitalized, except for
+% specifically noted ``lower-case words'' (examples might include
+% prepositions, conjunctions, \etc).  The first word of the input string
+% is capitalized, while lower-case words, previously designated with
+%  |\addlcword| and |\addlcwords|, are left in lower case.
+%    \begin{macrocode}
+% CAPITALIZE TITLE, EXCEPT FOR DESIGNATED "LOWER-CASE" WORDS
+\newcommand\capitalizetitle[2][v]{%
+% First, capitalize every word (save in encoded form, not printed)
+  \capitalizewords[e]{#2}%
+% Then lowercase words that shouldn't be capitalized, like articles,
+% prepositions, etc. (save in encoded form, not printed)
+  \setcounter{@wordindex}{0}%
+  \whiledo{\value{@wordindex} < \value{@lcwords}}{%
+    \addtocounter{@wordindex}{1}%
+    \edef\mystring{\thestring}%
+    \edef\lcword{\csname lcword\roman{@wordindex}\endcsname}%
+    \capitalize[e]{\lcword}%
+    \edef\ucword{\thestring}%
+    \convertword[e]{\mystring}{\ucword~}{\lcword~}%
+  }
+% Finally, recapitalize the first word of the Title, and print it.
+  \capitalize[#1]{\thestring}%
+}
+%    \end{macrocode}
+% \end{macro}
+
 % \begin{macro}{\rotateword}
 % Moves first word of given string |#2| to end of string, including
 % leading and trailing blank spaces.
@@ -2263,6 +2435,7 @@
   \edef\@@@@teststring{#2}%
   \edef\@matchstring{#3}%
   \@getstringlength{#2}{@@stringsize}%
+  \setcounter{@@@stringsize}{\value{@@stringsize}}
   \@getstringlength{#3}{@matchsize}%
   \setcounter{@matchmax}{\the@@stringsize}%
   \addtocounter{@matchmax}{-\the@matchsize}%
@@ -2387,83 +2560,6 @@
 %    \end{macrocode}
 % \end{macro}
  
-% \begin{macro}{\convertword}
-% Takes a string, a replaces each occurance of a specified string
-% with a replacement string.  
-%    \begin{macrocode}
-\newcounter{@@matchloc}
-% LIKE \convertchar, EXCEPT FOR WORDS
-\newcommand\convertword[4][v]{%
-  \+\edef\@@teststring{#2}%
-  \edef\@fromstring{#3}%
-  \edef\@tostring{#4}\?%
-  \edef\@@@teststring{\@@teststring}%
-  \def\@buildfront{}%
-  \edef\@buildstring{\@@teststring}%
-  \setcounter{@charsfound}{0}%
-  \whiledo{\the@charsfound > -1}{%
-%    \end{macrocode}
-% Seek occurance of |\@fromstring| in larger |\@@teststring|
-%    \begin{macrocode}
-\whereisword[q]{\@@teststring}{\@fromstring}%
-    \setcounter{@matchloc}{\theresult}%
-    \ifthenelse{\the@matchloc = 0}%
-      {%
-%    \end{macrocode}
-% Not found.  Done.
-%    \begin{macrocode}
-        \setcounter{@charsfound}{-1}%
-      }%
-      {%
-%    \end{macrocode}
-% Potential matchstring.
-%    \begin{macrocode}
-        \addtocounter{@charsfound}{1}%
-%    \end{macrocode}
-% Grab current test string from beginning to point just prior
-% to potential match.
-%    \begin{macrocode}
-        \addtocounter{@matchloc}{-1}%
-        \substring[e]{\@@@teststring}{1}{\the@matchloc}%
-%    \end{macrocode}
-% The string |\@buildfront| is the total original string, with
-% string substitutions, from character 1 to current potential match.
-%    \begin{macrocode}
-        \edef\@buildfront{\@buildfront\thestring}%
-%    \end{macrocode}
-% See if potential matchstring takes us to end-of-string\ldots
-%    \begin{macrocode}
-        \addtocounter{@matchloc}{1}%
-        \addtocounter{@matchloc}{\the@matchsize}%
-        \ifthenelse{\the@matchloc > \the@@stringsize}%
-        {%
-%    \end{macrocode}
-% \ldots if so, then match is last one in string.  Tack on replacement
-% string to |\@buildfront| to create final string.  Exit.
-%    \begin{macrocode}
-          \setcounter{@charsfound}{-1}%
-          \edef\@buildstring{\@buildfront\@tostring}%
-        }%
-        {%
-%    \end{macrocode}
-% \ldots if not, redefine current teststring to begin at point following
-% the current substitution.  Make substitutions to current
-% |\@buildstring| and |\@buildfront|.  Loop through logic again on new
-% teststring.
-%    \begin{macrocode}
-          \substring[e]{\@@@teststring}{\the@matchloc}{\@MAXSTRINGSIZE}%
-          \edef\@@teststring{\thestring}%
-          \edef\@@@teststring{\@@teststring}%
-          \edef\@buildstring{\@buildfront\@tostring\@@@teststring}%
-          \edef\@buildfront{\@buildfront\@tostring}%
-        }%
-      }%
-  }%
-  \substring[#1]{\@buildstring}{1}{\@MAXSTRINGSIZE}%
-}
-%    \end{macrocode}
-% \end{macro}
-
 % \begin{macro}{\wordcount}
 % Counts words (space-separated text) in a string.  Simply removes one
 % word at a time, counting the words as it goes.  With each removal,