scalerel (28feb13)

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

2 files changed, 221 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf b/Master/texmf-dist/doc/latex/scalerel/scalerel.pdf
new file mode 100644
index 00000000000..f7f4bc78681
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..1355ef516d4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/scalerel/scalerel.tex
@@ -0,0 +1,221 @@
+\documentclass{article}
+\def\version{1.0}
+\parskip 1em
+\parindent 0em
+\newcommand\rl{\rule{3em}{0in}}
+\usepackage{scalerel}
+\usepackage{verbatim}
+
+\begin{document}
+\begin{center}
+\LARGE The \textsf{scalerel} Package\\
+\rule{0em}{.7em}\small Routines for constrained scaling and stretching
+of objects, either relative to a reference object or in absolute terms\\
+\rule{0em}{2.7em}\large Steven B. Segletes\\
+steven.b.segletes.civ@mail.mil\\
+\rule{0em}{1.7em}\today\\
+v\version
+\end{center}
+
+\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
+commands may be invoked in either math mode or text mode (if there is no
+math in the objects to manipulate); however, the objects it manipulates
+will, by default, be processed in math mode.  Nonetheless, one may
+process the objects in text mode (assuming they do not contain
+math-specific characters or commands) by specifying arguments as
+\verb|{$object$}|, instead of the usual \verb|{object}|.
+
+There are four basic commands with the \textsf{scalerel} package, two
+of which have star variants:
+\begin{verbatim}
+  \scalerel[*][max_width]{object}{reference}
+  \stretchrel[*][min_aspect]{object}{reference}
+  \scaleto[max_width]{object}{height}
+  \stretchto[min_aspect]{object}{height}
+\end{verbatim} 
+In all cases, \verb|object| is the object to be scaled or vertically
+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
+the reference object in relation to which the manipulated
+\verb|object| is scaled or vertically stretched.  The \verb|reference|
+may likewise be of complex description (such as a mathematical
+expression).  When an \verb|object| is scaled or stretched
+\textit{relative} to a \verb|reference| object, it is also vertically
+shifted, if necessary, so that its vertical extent conforms to that of
+the \verb|reference| object.
+
+In cases of scaling or stretching \textit{to} a specified size,
+\verb|height| will the final vertical height of \verb|object| following
+a scale or stretch manipulation.  Since scaling or stretching to an
+absolute size provides no \verb|reference| object, the baseline of
+manipulated \verb|object| remains unchanged.
+
+In cases of scaling (relative or absolute), the constraint
+\verb|max_width| is optionally specified as the maximum width allowable
+for the manipulated object.  If the manipulated width would otherwise
+exceed this limit, the
+\verb|object| width is scaled back to this limit.  If the \verb|object|
+width is scaled back, its aspect ratio will change with respect to its
+original shape.
+
+By definition, vertical stretching will change the aspect ratio of an
+object.  In the case of stretching (relative or absolute), the
+constraint \verb|min_aspect| is the minimum aspect ratio allowed by the
+stretch.  Its value is given in \%, such that a parameter value of
+\texttt{100} indicates 100\% or an aspect ratio of 1.  If the stretch
+would otherwise cause the manipulated \verb|object|'s aspect ratio to
+fall below this value, the width of the manipulated \verb|object| is
+increased to meet this minimum threshold.  The value of
+\verb|min_aspect| must be an integer.
+
+Because \textit{relative} scaling or stretching is done
+\textit{relative} to a reference object, the \verb|\scalerel| and
+\verb|\stretchrel| commands will, by default, print out the
+manipulated \verb|object| followed immediately by the \verb|reference|
+object.  Because this may not always be desired, the star (*) version of
+these commands suppresses the output of the \verb|reference| object, so
+that only the \verb|object| that was manipulated is output.
+
+\section{Examples}
+
+Now for a few examples.  Let us define
+\begin{verbatim}
+    \def\preblob{\displaystyle\sum_{i=0}^3}
+    \def\blob{\displaystyle\frac{\displaystyle\frac{x^3}{z+r^3}}%
+              {\displaystyle\frac{y}{x^2}}%
+    }
+\end{verbatim}
+    \def\preblob{\displaystyle\sum_{i=0}^3}
+    \def\blob{\displaystyle\frac{\displaystyle\frac{x^3}{z+r^3}}%
+              {\displaystyle\frac{y}{x^2}}%
+    }
+Here are the raw definitions of \verb|$\preblob\blob$|, unscaled:
+
+    \rl$\preblob\blob$
+
+\subsection{The $\backslash$\texttt{scalerel} Command}
+
+Now we employ \verb|$\scalerel{\preblob}{\blob}$|
+
+    \rl$\scalerel{\preblob}{\blob}$
+
+If we wish constrain the width of the summation to 3ex, we employ\\
+\verb|$\scalerel[3ex]{\preblob}{\blob}$|
+
+    \rl$\scalerel[3ex]{\preblob}{\blob}$
+
+Of course, if the manipulated object contains text symbols, a width
+constraint will change their aspect ratio, which may not be desirable.
+
+Now let's say you wanted to introduce notation to bound mathematical
+expressions by triangles. After defining
+\verb|\blob| as before, you could use\\
+\verb|$\scalerel[3ex]{\triangleleft}{\blob}|\\
+\verb|\scalerel*[3ex]{\triangleright}{\blob}$|
+
+\rl%
+$\scalerel[3ex]{\triangleleft}{\blob}\scalerel*[3ex]{\triangleright}{\blob}$
+
+Here, the second call to \verb|\scalerel| was with the star (\verb|*|)
+option, indicating that \verb|\blob| should not be printed out following
+the right-hand delimiter.  A less-tall expression would appear in those
+same delimiters as
+
+\rl%
+$\scalerel[3ex]{\triangleleft}{Q}\scalerel*[3ex]{\triangleright}{Q}$
+
+Because the width limit had not been reached, no horizontal compression
+of the object was required.
+
+\subsection{The $\backslash$\texttt{stretchrel} Command}
+
+In its most simple application \verb|\stretchrel| can be used in the
+fashion of a \verb|\left\{| in math mode.  While there is no reason to
+replace that more efficient usage supplied by \LaTeX{}, it is
+nonetheless instructional to see a comparison of 
+\verb|$\left\{\blob\right.$| and \verb|$\stretchrel[400]{\{}{\blob}$|, to
+see how the aspect-ratio limiting option can be employed to avoid an
+overly stretched manipulation:
+
+\rl$\left\{\blob\right.$  ~~~~~ $\stretchrel[400]{\{}{\blob}$
+
+The expression on the right uses a standard \{ character, which has been
+vertically stretched, but limited to an aspect ratio of 4.  To use
+symbols for which the \verb|\left| nomenclature will not work,
+\verb|\stretchrel| provides a viable alternative, as shown in this
+stick-figure example:\\
+\verb|3m $\stretchrel[500]{\updownarrow\,}|\\
+\verb|{\fbox{\rule[-1.8em]{0ex}{4em}Work Table}}$|
+
+\rl3m $\stretchrel[500]{\updownarrow\,}
+  {\fbox{\rule[-1.8em]{0ex}{4em}Work Table}}$
+
+or in this use, \verb|$\stretchrel[225]{\int}{\blob} dx$|, of the
+stretched integral sign (aspect limited to 2.25):
+
+\rl$\stretchrel[225]{\int}{\blob} dx$
+
+
+\subsection{Baseline Shifts of \textit{Relative} Scales and Shifts}
+
+It was mentioned that when \verb|\scalerel| and \verb|\stretchrel| are
+employed, the manipulated object gets vertically shifted to match the
+extent of the reference object.  To see how this works, we provide the
+following example, that employs some inline math. and scaling.  
+
+\rl\underline{The baseline is the line that runs under this text}
+\fbox{$\scalerel{i}{\blob}$}\underline{\scaleto{i}{43.32pt}}
+
+The first case of the large letter ``i'' was generated with 
+\verb|\scalerel|, and so the baseline of the ``i'', normally not a
+descending letter, was dropped to conform to the descended reference
+equation.  All of this was set in an \verb|\fbox| to show the extent of
+the objects.  For comparison, an ``i'' of the samesize was then placed
+using a \verb|\scaleto| command, which does not change the baseline of
+the original object.
+
+\subsection{The $\backslash$\texttt{scaleto} and
+$\backslash$\texttt{stretchto} Commands}
+
+The \verb|\scaleto| and \verb|\stretchto| commands are comparable to the
+\verb|\scalerel| and \verb|\stretchrel| commands, except they do not
+accept a reference object as their second mandatory argument.  Rather,
+they take an absolute height (specified with units).  These commands use
+the same optional arguments as \verb|\scalerel| and \verb|\stretchrel|
+to constrain the width and/or the aspect ratio, respectively, of the
+manipulated object.
+
+As was mentioned in the prior section, a difference between these and
+the \textit{relative} commands is that an object's baseline is not
+altered with the use of \verb|\scaleto| and \verb|\stretchto|.  Because
+there is no reference object employed with these commands, there is no
+need for starred (\verb|*|) versions of these commands, which would
+otherwise suppress the printing of the reference object.
+
+Examples follow the established pattern established in prior sections.
+First, we scale the equation blob used as an example in this
+documentation to a vertical extent of 80pt, preserving the original
+aspect ratio,
+
+\rl\verb|$\scaleto{\blob}{80pt}$      | $\scaleto{\blob}{80pt}$
+
+Then, we stretch the Greek letter, capital phi, to 60pt, but constrain
+the aspect ratio to no less than 1.75.
+
+\rl\verb|$\stretchto[175]{\Phi}{60pt}$      | $\stretchto[175]{\Phi}{80pt}$
+
+\section{Future Development}
+
+It would be relatively straightforward to extend this approach to
+horizontal scaling problems.  However, it is not exactly clear to the
+author what format is best suited for user needs.  If he gets feedback
+in that regard, it will inform him how best to proceed.
+
+\section{Code Listing}
+
+\verbatiminput{scalerel.sty}
+
+\end{document}