scalerel (7may13)

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

3 files changed, 85 insertions, 19 deletions

diff --git a/Master/texmf-dist/doc/latex/scalerel/README b/Master/texmf-dist/doc/latex/scalerel/README
new file mode 100644
index 00000000000..41de8401702
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/scalerel/README
@@ -0,0 +1,10 @@
+The package provides four primary commands for vertically scaling and
+stretching objects, and a number of derivative commands.  Its primary
+function is the ability to scale/stretch and shift one object to conform
+to the vertical size of a specified second object. This feature can be
+useful in both equations and schematic diagrams.
+
+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.
+
diff --git a/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf b/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf
index 1e081a9877c..e66d782c307 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 ec38c1b77c8..cd153d1fa66 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.3}
+\def\version{1.4}
 %% Copyright 2013 Steven B. Segletes
 %
 % This work may be distributed and/or modified under the
@@ -20,13 +20,21 @@
 % V1.2  Added \scaleleftright and \stretchleftright; revised docs.
 % V1.3  Corrected missing % in stretch routines, added \hstretch and
 %       \vstretch commands; fixed version number in .sty file
+% V1.4 -Auto-detect mathmode and style; use the proper math display
+%       style; Allow \ignoremathstyle and \discernmathstyle to
+%       revert to former approach in rare cases and return to new
+%       approach.
+%      -Added \Isnextbyte as a supplemental routine
+%      -Added \scaleobj (like \scalebox, but defaults to math mode
+%       using current display style).
 \parskip 1em
 \parindent 0em
-\newcommand\rl{\rule{3em}{0in}}
+\newcommand\rl{\rule{2em}{0in}}
 \usepackage{scalerel}
 \usepackage{verbatim}
 \usepackage[only,llbracket,rrbracket,llparenthesis,rrparenthesis]{stmaryrd}
 \usepackage{accsupp} % for ensuring the right Unicode codepoint upon pasting
+\def\sr{\textsf{scalerel}}
 
 \begin{document}
 \begin{center}
@@ -57,16 +65,24 @@ of which have star variants:
   \scaleto[max_width]{object}{height}
   \stretchto[min_aspect]{object}{height}
 \end{verbatim} 
-In addition, there are four added commands that have been implemented as
-composites of the four basic commands, they are
+In addition, there are a number of added commands that have been
+implemented as composites of the four basic commands, they are
 \begin{verbatim}
   \scaleleftright[max_width]{left-obj.}{reference}{right-obj.}
   \stretchleftright[min_aspect]{left-obj.}{reference}{right-obj.}
   \hstretch{scale}{object}
   \vstretch{scale}{object}
-\end{verbatim} 
+  \scaleobj{scale}{object}
+\end{verbatim}
+There are also several auxiliary commands, supporting backward
+compatibility, \textit{etc.}:
+\begin{verbatim}
+  \ignoremathstyle
+  \discernmathstyle
+  \Isnextbyte[[v] OR q]{test byte}{string}
+\end{verbatim}
 
-In all cases, \verb|object| is the object to be scaled or vertically
+In all cases, \verb|object| is the object to be scaled or 
 stretched.  It can be as simple as a symbol, like a summation sign
 ($\sum$), or it can be an object of complex description.  Likewise, in
 cases of \textit{relative} scaling and stretching, \verb|reference| is
@@ -119,7 +135,32 @@ The \verb|\hstretch| and \verb|\vstretch commands| merely take the
 second argument and either horizontally or vertically stretch it by a
 scale factor given by the first argument.  The scale is not given in
 percent, like some aforementioned commands.  Remember also, that these
-commands are, by default processed in math mode.
+commands are, by default processed in math mode.  In a like manner,
+\verb|\scaleobj| performs a scale of the object.  It is like the
+\verb|\scalebox| command of the \textsf{graphicx} package, except that
+its argument (like others in this package) defaults to math mode, and is
+displayed in the current math display style.
+
+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} \verb|object| is given in mixed mode
+(containing \verb|$| characters in the middle of the \verb|object|.  In
+order to maintain backward compatibility, the user may invoke
+\verb|\ignoremathstyle|.  Thereafter, {\sr} objects will be processed in
+the prior (pre-version 1.4) manner, until the command
+\verb|\discernmathstyle| is later invoked to restore the more modern
+package settings.
+
+A service routine \verb|\Isnextbyte| was employed by this package.
+Because of its more general utility, it is made accessible to the user.
+It is an improved version of the command \verb|\isnextbyte| from the
+\textsf{stringstrings} package.  It will determine if the first
+byte from a passed string argument matches a specified
+\textit{match}-character.  It produces a \verb|T| or \verb|F| result,
+which is printed out by default.  With the use of the \verb|q| optional
+argument, the output can be suppressed, with the result instead being
+stored in a macro \verb|\theresult|.
 
 \section{Usage Examples}
 
@@ -271,8 +312,9 @@ $\scaleleftright[3ex]{\prod}{\blob}{\coprod}$
 \rl\verb|$\stretchleftright[450]{.}{\blob}{\in}$        |
 $\stretchleftright[450]{.}{\blob}{\in}$
 
-\subsection{The $\backslash$\texttt{hstretch} and
- $\backslash$\texttt{vstretch} Commands}
+\subsection{The $\backslash$\texttt{hstretch},
+ $\backslash$\texttt{vstretch}, and $\backslash$\texttt{scaleobj}
+ Commands}
 
 These commands simply perform horizontal or vertical stretching,
 respectively.  They use a scale factor, rather than an absolute length.
@@ -280,12 +322,24 @@ If the stretch factor is greater than 1, the stretched length is larger
 than the original.  If less than one, it is compressed with respect to
 the original.
 
-\rl\verb|$\otimes\hstretch{3}{\otimes}\hstretch{0.5}{\otimes}$   |
+\rl\verb|$\otimes\hstretch{3}{\otimes}\hstretch{0.5}{\otimes}$ |
 $\otimes\hstretch{3}{\otimes}\hstretch{0.5}{\otimes}$
 
-\rl\verb|$\otimes\vstretch{3}{\otimes}\vstretch{0.5}{\otimes}$   |
+\rl\verb|$\otimes\vstretch{3}{\otimes}\vstretch{0.5}{\otimes}$ |
 $\otimes\vstretch{3}{\otimes}\vstretch{0.5}{\otimes}$
 
+The \verb|\scaleobj| command performs scaling in the fashion of a
+\verb|\scalebox| command, except that its argument is processed in math
+mode of the current math display style, by default.  Thus, the
+difference between the following two invocations:
+\begin{verbatim}
+  \(\scaleobj{2}{\sum_{i=0}^{n}}\)
+  \[\scaleobj{2}{\sum_{i=0}^{n}}\]
+\end{verbatim}
+is given as
+\(\scaleobj{2}{\sum_{i=0}^{n}}\) versus
+\[\scaleobj{2}{\sum_{i=0}^{n}}\]
+
 \section{Real World Application}
 
 \subsection{White Curly Brackets}
@@ -314,14 +368,14 @@ brace and a vertical strut, calling them \verb|\llbrace| and
 $x$):
 
 \def\wbrace{\scalebox{5}{$\llbrace x\rrbrace$}}
-\indent\wbrace
+\rl\wbrace
 
 But they found that when represented in reduced size fonts, the symbol
 glyphs of the brace and the strut separated (note: \verb|\tiny| font has
 been scaled up to match prior figure's height):
 
 \def\tinywbrace{\scalebox{3}{\tiny$\llbrace x\rrbrace$}}
-\indent$\scalerel*{\tinywbrace}{\wbrace}$
+\rl$\scalerel*{\tinywbrace}{\wbrace}$
 
 This happens because font designers don't merely scale their fonts when
 shrunk down in size, but they do things (like thickening up lines and
@@ -350,7 +404,8 @@ both normal size and tiny size:
 \savebox{\rXbrace}{$\rrbrace$}
 \def\lxbrace{\scalerel*{\usebox{\lXbrace}}{\llbrace}}
 \def\rxbrace{\scalerel*{\usebox{\rXbrace}}{\rrbrace}}
-\indent$\scalerel*{\lxbrace x\rxbrace$\tiny$\lxbrace x\rxbrace}{\wbrace}$
+\rl$\scalerel*{\lxbrace x\rxbrace}{\wbrace}$
+{\tiny$\scalerel*{\lxbrace x\rxbrace}{\wbrace}$}
 
 Note that the brace is the properly formed scale of the normal-sized
 brace in both cases, even as the $x$ adjusts to the fontsize reduction.
@@ -369,19 +424,20 @@ to give the following
 
 \def\lxbrace{\hstretch{0.6}{\scalerel*{\usebox{\lXbrace}}{\llbrace}}}
 \def\rxbrace{\hstretch{0.6}{\scalerel*{\usebox{\rXbrace}}{\rrbrace}}}
-\indent$\scalerel*{\lxbrace x\rxbrace$\tiny$\lxbrace x\rxbrace}{\wbrace}$
+\rl$\scalerel*{\lxbrace x\rxbrace}{\wbrace}$
+{\tiny$\scalerel*{\lxbrace x\rxbrace}{\wbrace}$}
 
 Likewise, the \verb|\left| and \verb|\right| features of equation mode
 cannot be used with the white braces, 
 
-\indent \(\llbrace \left\llbracket\left\{\left[(a) \cdot
+\rl \(\llbrace \left\llbracket\left\{\left[(a) \cdot
 bc^{2^3}\right]^4\right\}^5\right\rrbracket \rrbrace\)
 
 but \textsf{scalerel} can fix that, too:
 
 \def\core{ \left\llbracket\left\{\left[(a) \cdot
 bc^{2^3}\right]^4\right\}^5\right\rrbracket}%
-\indent
+\rl
 \(\scalerel[1.5ex]{\lxbrace}{\core}\scalerel*[1.5ex]{\rxbrace}{\core}\)
 
 with 
@@ -465,11 +521,11 @@ arbitrarily wide oversymbols may be constructed:
 \end{array}%
 }
 
-\indent
+\rl
 $\reallywideparen{POQ}$ $+ \reallywidehat{QOR} + \reallywidehat{ROP}=
 2\pi r$
 
-\indent $\reallywidehat{zbcdefghijklm}$
+\rl $\reallywidehat{zbcdefghijklm}$
 
 \section{Future Development}