summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/scalerel
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-03-02 01:12:44 +0000
committerKarl Berry <karl@freefriends.org>2013-03-02 01:12:44 +0000
commit36f9061a512acdc9fa1866e89fa967b0bae3464c (patch)
tree0c6c8dbe8468ef6a3f827f28166fa35c5ef93b99 /Master/texmf-dist/doc/latex/scalerel
parent6b9ce3b95f36f4da56f4ed73515ce224f956e7f5 (diff)
scalerel (28feb13)
git-svn-id: svn://tug.org/texlive/trunk@29261 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/scalerel')
-rw-r--r--Master/texmf-dist/doc/latex/scalerel/scalerel.pdfbin0 -> 187074 bytes
-rw-r--r--Master/texmf-dist/doc/latex/scalerel/scalerel.tex221
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
Binary files differ
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}