scalerel (18feb15)

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

3 files changed, 54 insertions, 12 deletions

diff --git a/Master/texmf-dist/doc/latex/scalerel/README b/Master/texmf-dist/doc/latex/scalerel/README
index 41de8401702..a66e87fae6f 100644
--- a/Master/texmf-dist/doc/latex/scalerel/README
+++ b/Master/texmf-dist/doc/latex/scalerel/README
@@ -8,3 +8,6 @@ Additionally, the scaling and stretching commands offer constraints on
 maximum width and/or minimum aspect ratio, which are often used to
 preserve legibility or for the sake of general appearance.
 
+The package will, by default, preserve the current math style in the
+arguments to its macros.  For the sake of compilation efficiency,
+however, this feature may be turned off and on at will by the user.
diff --git a/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf b/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf
index 6364b9c517f..9a6233bbe7c 100644
--- a/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf
+++ b/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf
diff --git a/Master/texmf-dist/doc/latex/scalerel/scalerel.tex b/Master/texmf-dist/doc/latex/scalerel/scalerel.tex
index 0aa91a3bc7d..ddfdcc7524b 100644
--- a/Master/texmf-dist/doc/latex/scalerel/scalerel.tex
+++ b/Master/texmf-dist/doc/latex/scalerel/scalerel.tex
@@ -1,5 +1,5 @@
 \documentclass{article}
-\def\version{1.6}
+\def\version{1.7}
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -34,6 +34,16 @@
 %       0.5ex/pt in \scriptscriptstyle).
 %      -Revised/shortened/improved \Isnextbyte.
 %      -Replaced ifthen package calls with etoolbox calls.
+% V1.7 -Note that the V1.5 implementation with \mathchoice seemed to
+%       have made the use of \ignoremathstyle and \discernmathstyle 
+%       vestigial.  Thus, \ignoremathstyle was revised to be used
+%       for the purpose of streamlining package efficiency when 
+%       only textstyle (or displaystyle with \ignoremathstyle[D])
+%       processing is required.
+%      -Fixed use of dot {.} as null argument in \scaleleftright{}{}{} 
+%       and \stretchleftright{}{}{}, which had been causing overflow.
+%      -Made \hstretch and \vstretch routines more efficient, using
+%       optional arguments of \scalebox, instead of \scalerel.
 \parskip 1em
 \parindent 0em
 \newcommand\rl{\rule{2em}{0in}}
@@ -60,6 +70,11 @@ steven.b.segletes.civ@mail.mil\\
 v\version
 \end{center}
 
+{\footnotesize
+Note for V1.7 users: If you are noticing compilation efficiency issues
+with your use of the \sr{} package, please see section~\ref{s:nm}.
+\par}
+
 \section{Commands and Description}
 The \textsf{scalerel} package is used to scale and vertically stretch
 objects, either relative to other objects, or in absolute terms.  Its
@@ -102,7 +117,7 @@ right and, in some cases, supporting backward compatibility:
   \def\scriptstyleScaleFactor{0.7}
   \def\scriptscriptstyleScaleFactor{0.5}
   \Isnextbyte[[v] OR q]{test byte}{string}
-  \ignoremathstyle
+  \ignoremathstyle[D]
   \discernmathstyle
 \end{verbatim}
 
@@ -211,18 +226,42 @@ which is printed out by default.  With the use of the \vb|q| optional
 argument, the output can be suppressed, with the result instead being
 stored in a macro \vb|\theresult|.
 
+\subsection{Efficiency of nested \sr{} macros\label{s:nm}}
+
 As of version 1.4, {\sr} commands will autodetect the current math
-display style and process its arguments in the same mode.  However, this
-improvement could ``break'' a prior (rare but) accepted usage of the
-package in which the {\sr} \vb|object| is given in mixed mode
-(containing \vb|$| characters in the middle of the \vb|object|.  In
-order to maintain backward compatibility, the user may invoke
+display style (so-called display-style, text-style, script-style, and/or
+scriptscript-style) and process its arguments in the same mode.  The
+overhead associated with this capability is an invocation of 
+\vb|\mathchoice|, which must create 4 boxes (one in each math style) 
+before selecting one
+to typeset.  While a small overhead in itself, an efficiency issue
+can arise when \sr{} macros are nested, since if 3 \sr{} macros
+are nested, \vb|\mathchoice| will build $4^3=64$ boxes in order
+to select the proper one to typeset (and a nesting level of 4 yields
+256 boxes).
+
+With the use of \vb|\ignoremathstyle|, the math style of the \sr{}
 \margcmd{ignoremathstyle}%
-\vb|\ignoremathstyle|.  Thereafter, {\sr} objects will be processed in
-the prior (pre-version 1.4) manner, until the command
-\margcmd{discernmathstyle}
-\vb|\discernmathstyle| is later invoked to restore the more modern
-package settings.
+processing can be fixed in a single math style, thus eliminating the
+construction of \vb|\mathchoice| boxes.  The increase in processing
+efficiency can be noticeable when operating on deeply nested \sr{}
+macros.
+
+The invocation of \vb|\ignoremathstyle| will force all subsequent 
+\sr{} calls to process its arguments in \vb|\textstyle| math.  
+Alternately, \vb|\ignoremathstyle[D]| will force the processing
+of \sr{} macros in \vb|\displaystyle| math.
+
+\begin{sloppypar}
+This streamlining can be undone, reinstating the more general
+math-style preserving approach, with the invocation of
+\vb|\discernmathstyle|.
+\margcmd{discernmathstyle}%
+These macros can be used anywhere in a document by a user, to turn off 
+and on the \vb|\mathchoice| feature of \sr{}, or they may be
+used within user macro definitions, to fix the math style by which
+\sr{} processes its macros within the confines of the user macro.
+\end{sloppypar}
 
 \section{Usage Examples}