scalerel (10mar14)

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

2 files changed, 113 insertions, 20 deletions

diff --git a/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf b/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf
index a7916e39f86..6364b9c517f 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 ad4793bc2b2..0aa91a3bc7d 100644
--- a/Master/texmf-dist/doc/latex/scalerel/scalerel.tex
+++ b/Master/texmf-dist/doc/latex/scalerel/scalerel.tex
@@ -1,6 +1,5 @@
 \documentclass{article}
-\def\version{1.5}
-%% Copyright 2013 Steven B. Segletes
+\def\version{1.6}
 %
 % This work may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.3
@@ -29,12 +28,19 @@
 %       using current display style).
 % V1.5 -Eliminated mathstyle package because of incompatibilites with
 %       many other packages.  Implemented \mathchoice approach instead.
+% V1.6 -Made available \LMex and \LMpt lengths (Local Math ex and
+%       Local Math pt), usable inside \ThisStyle arguments (1ex/pt in
+%       \textstyle and \displaystyle, 0.7ex/pt in \scriptstyle, and
+%       0.5ex/pt in \scriptscriptstyle).
+%      -Revised/shortened/improved \Isnextbyte.
+%      -Replaced ifthen package calls with etoolbox calls.
 \parskip 1em
 \parindent 0em
 \newcommand\rl{\rule{2em}{0in}}
 \usepackage{scalerel}
 \usepackage{verbatim}
 \usepackage[only,llbracket,rrbracket,llparenthesis,rrparenthesis]{stmaryrd}
+\usepackage{stackengine}
 \usepackage{accsupp} % for ensuring the right Unicode codepoint upon pasting
 \def\sr{\textsf{scalerel}}
 \let\vb\verb
@@ -81,13 +87,23 @@ implemented as composites of the four basic commands, they are
   \vstretch{scale}{object}
   \scaleobj{scale}{object}
 \end{verbatim}
-There are also several auxiliary commands, supporting backward
-compatibility, \textit{etc.}:
+Unless delimited for text mode, \texttt{object} is assumed to be a math
+object and wil be processed in the \textit{current} math style.  On the
+other hand, \texttt{reference} will take on the current mode (text
+or math).  If in math mode, \texttt{reference} will likewise be taken in the 
+current math style.
+
+There are also several auxiliary commands, useful in their own
+right and, in some cases, supporting backward compatibility:
 \begin{verbatim}
-  \ignoremathstyle
-  \discernmathstyle
   \ThisStyle{...\SavedStyle...}
+  \LMex
+  \LMpt
+  \def\scriptstyleScaleFactor{0.7}
+  \def\scriptscriptstyleScaleFactor{0.5}
   \Isnextbyte[[v] OR q]{test byte}{string}
+  \ignoremathstyle
+  \discernmathstyle
 \end{verbatim}
 
 In all cases, \vb|object| is the object to be scaled or 
@@ -153,19 +169,6 @@ commands are, by default processed in math mode.  In a like manner,
 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} \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
-\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.
-
 A useful auxiliary command \vb|\ThisStyle{}| has been introduced for
 \margcmd{ThisStyle}%
 remembering the current math style.  When invoked, this command will
@@ -178,6 +181,25 @@ are being set within the math environment, since the prevailing math
 style does not carry into the box, without the use of
 \vb|\SavedStyle|.
 
+The lengths \verb|\LMex| and \verb|\LMpt| work in conjunction with 
+\verb|\ThisStyle|
+\margcmd{LMex}%
+\margcmd{LMpt}%
+and are what I am calling the ``local-mathstyle `ex'\,''
+and ``local-mathstyle `pt','' respectively.
+They are lengths, available for use within the argument of \verb|\ThisStyle|,
+ that scale with the current mathstyle, equalling 1ex and 1pt in
+\verb|\displaystyle| and \verb|\textstyle| math, and scaled by a 
+factor of 0.7 in \verb|\scriptstyle| and 0.5 in \verb|\scriptscriptstyle|.
+Such a scalable length is useful when {\sr} is used to place objects 
+\margcmd{scriptstyleScaleFactor}%
+relative to each other across various mathstyles.  The 0.7 and 0.5
+relative height factors apply to the default Computer Modern font.
+\margcmd{\footnotesize scriptscriptstyleScaleFactor}%
+For other fonts, these scale factors may be reset with a \verb|\def|
+on the macros \verb|\scriptstyleScaleFactor| and 
+\verb|\scriptscriptstyleScaleFactor|.
+
 A service routine \vb|\Isnextbyte| was employed by this package.
 \margcmd{Isnextbyte}%
 Because of its more general utility, it is made accessible to the user.
@@ -189,6 +211,19 @@ 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|.
 
+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
+\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.
+
 \section{Usage Examples}
 
 Now for a few examples.  Let us define
@@ -367,6 +402,64 @@ is given as
 \(\scaleobj{2}{\sum_{i=0}^{n}}\) versus
 \[\scaleobj{2}{\sum_{i=0}^{n}}\]
 
+\subsection{The \textbackslash\texttt{ThisStyle}, \textbackslash\texttt{SavedStyle},
+\textbackslash\texttt{LMex}, and \textbackslash\texttt{LMpt} Commands}
+
+These are very powerful macros that provide the ability to save the current
+math style and to import it to various places (for example, inside boxes and other
+macros) where the math style would otherwise be lost.  These commands are
+part of this package because the various {\sr} macros employ them to
+automatically import the current math style into their arguments.
+
+The easiest way to show how these macros are used is to provide a working 
+example, such as the one given below.
+
+\begin{verbatim}
+\documentclass{article}
+\usepackage{stackengine}
+\usepackage{graphicx}
+\usepackage{scalerel}
+\stackMath
+\def\ccdot{\scalebox{1.15}{$\SavedStyle\cdot$}}
+\def\altdiv{\mathbin{\ThisStyle{%
+  \stackunder[-.6\LMex]{%
+    \stackon[-.45\LMex]{\SavedStyle\sim}{\ccdot}%
+  }{\ccdot}}}}
+\begin{document}
+$A \altdiv B ~~A \div B$\par
+$\scriptstyle A \altdiv B ~~A \div B$\par
+$\scriptscriptstyle A \altdiv B ~~A \div B$\par
+\end{document}
+\end{verbatim}
+
+The output of this example shows a fabricated glyph (\verb|\altdiv|) across the 
+math styles, comparing it to \verb|\div|:
+
+\stackMath
+\def\ccdot{\scalebox{1.15}{$\SavedStyle\cdot$}}
+\def\altdiv{\mathbin{\ThisStyle{%
+  \stackunder[-.6\LMex]{\stackon[-.45\LMex]{\SavedStyle\sim}{\ccdot}}{\ccdot}}}}
+\rl\scalebox{3}{\parbox{2in}{
+$A \altdiv B ~~A \div B$\par
+$\scriptstyle A \altdiv B ~~A \div B$\par
+$\scriptscriptstyle A \altdiv B ~~A \div B$\par
+}}
+
+The difficulties that must be overcome are several:  the composite glyph is created by
+way of a stack, which processes its arguments in either text mode or \verb|\textstyle|
+math mode; and the stacking distances between the components of the composite
+glyph need to vary with the mathstyle.  To overcome the first issue, the \verb|\altdiv|
+macro is wrapped in a \verb|\ThisStyle{...}| wrapper.  Whenever one of the glyph
+components (\textit{e.g.}, \verb|\sim| or \verb|\cdot|) is employed within the 
+\textsf{stackengine} where the mathstyle is
+otherwise lost, it is prepended with a \verb|\SavedStyle| to reinstate the current
+math style.  Thus, the glyph components will present in the proper mathstyle.  
+Likewise, the vertical stacking gaps between the glyph components, 
+given as optional arguments to the stacking commands, are here specified in 
+multiples of \verb|\LMex|.  In this way, the stacking gaps will shrink with the 
+smaller math styles, keeping the spacings on the same relative scale as the size
+of the smaller glyphs.
+
 \section{Real World Application}
 
 \subsection{White Curly Brackets}
@@ -562,6 +655,6 @@ in that regard, it will inform him how best to proceed.
 
 \section{Code Listing}
 
-\verbatiminput{scalerel.sty}
+\small\verbatiminput{scalerel.sty}
 
 \end{document}