stackengine (6aug13)

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

3 files changed, 95 insertions, 43 deletions

diff --git a/Master/texmf-dist/doc/latex/stackengine/README b/Master/texmf-dist/doc/latex/stackengine/README
index a7806393faa..875851e8874 100644
--- a/Master/texmf-dist/doc/latex/stackengine/README
+++ b/Master/texmf-dist/doc/latex/stackengine/README
@@ -21,5 +21,5 @@ macros allow a wide variety of tasks, including:
 
 -subfigure stacking and labeling;
 
-This package is primarily intended for text mode, thought it can be
-adapted for use in math mode.
+This package can be set to process its arguments in either text mode or
+in math mode.
diff --git a/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf b/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf
index 8c29f3bd471..07332673858 100644
--- a/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf
+++ b/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf
diff --git a/Master/texmf-dist/doc/latex/stackengine/stackengine.tex b/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
index f11d23b691d..2a7173a334b 100644
--- a/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
+++ b/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
@@ -71,10 +71,10 @@ Notice the consistent inter-baseline spacing on a long stack:
 \Huge
 \Longstack{{{\rl t}} {{\rl y}} {{\rl k}} {{\rl e}}}
 %\Longstack{{{\rl a}} {{\rl h}} {{\rl g}} {{\rl b}}}
-\normalsize
+\normalsize\\
 
 In this package, the default spacing (\textit{i.e.}, stacklength) for
-the long stack, saved in the length \vb|\Lstackgap| is the value
+the long stack, saved in \vb|\Lstackgap| is the value
 \vb|\baselineskip|.  For short stacks, the default stacklength, stored in
 \vb|\Sstackgap|, is 3pt, which corresponds to the same spacing found in
 \TeX's \vb|\shortstack| command.  The default stack type constructed by
@@ -153,16 +153,16 @@ the \vb|\stackalignment| definition.
 \subsection{Defaults and How to Set Them}
 
 There are several macros that serve to store package default
-definitions.  When a macro does NOT explicitly ask for one of the
+definitions.  When a stacking macro does NOT explicitly ask for one of the
 quantities defined by these defaults, it will use the values of these
 parameters to serve as the default value.  However, some stacking macros
 may ask the user to specify an explicit value for any number of these
 parameters in the calling arguments.  In that case, an explicit value
-may be provided or else the variable holding the default value may
+may be provided or else the macro holding the default value may
 itself be provided as the argument.
 
 Let us first consider the stackgap defaults, associated with short and
-long stacks.  Those stackgaps are actually stored in the \verb|\def|'s
+long stacks.  Those stackgaps are actually stored in the \vb|\def|'s
 
 \vb|\Sstackgap|\\
 \vb|\Lstackgap|
@@ -175,8 +175,8 @@ any stacking command that builds a long stack.  It defaults to
 provided:
 
 \itshape
-\vb|\setstackgap{S}{|inter-item stackgap\verb|}|\\
-\vb|\setstackgap{L}{|inter-item baselineskip\verb|}|
+\vb|\setstackgap{S}{|inter-item stackgap\vb|}|\\
+\vb|\setstackgap{L}{|inter-item baselineskip\vb|}|
 \upshape
 
 In addition, there is another macro, which may be invoked by the user:
@@ -191,7 +191,7 @@ The macro \vb|\stackgap| will look at the current value of
 In addition to these lengths, there are several parameter definitions
 that define default behaviors for those stacking macros when explict
 values of these settings are not requested.  The parameters, each set
-with a \vb|\def| command, are
+with a \vb|\def| (or a \vb|\renewcommand|), are
 
 \itshape
 \vb|\def\stackalignment{l| or \vb|c| or \vb|r}|\\
@@ -231,11 +231,28 @@ limited application.  It only comes into play when using
 \vb|\stackanchor| with \vb|\stacktype| ``S''.  It is described in
 more detail in \S\ref{s:sa}.
 
-For macros which require explicit specification of some of these
+For macros that require explicit specification of some of these
 parameters, the parameter token itself (\textit{e.g.},
 \cmd{stackalignment}, \cmd{quietstack}, \textit{etc.}) may be provided
 as the argument, if the default behavior is desired.
 
+In addition to the parameters mentioned above, there are two mode
+settings:
+
+\itshape
+\vb|\stackMath|\\
+\vb|\stackText|
+\upshape
+
+By default, this package will assume that the arguments of the stacking
+commands are text.  However, an invocation of \vb|\stackMath| will
+change the default so that {\ste} arguments will be processed in inline
+math mode (so-called \vb|\textstyle| math).  Likewise, an invocation
+of \vb|\stackText| will reset the default processing of arguments to
+text mode.  Note that these two mode-setting commands are not themselves
+to be part of a {\ste} argument, but are to be issued as separate
+commands prior to a desired stacking macro.
+
 \subsection{Stacking Macros}
 
 \subsubsection{\cmd{stackengine}}
@@ -356,8 +373,8 @@ If the item ends with a macro, enclose the item in braces.  While not
 particularly intended for math mode (see \S\ref{s:mm} for more
 details), math items may be enclosed within dollar-sign delimiters.
 \bfseries Note that, because of the parsing algorithm, macros in the
-argument of \verb|\Shortstack| and \verb|\Longstack| may need to be
-\verb|\protect|'ed.\mdseries
+argument of \vb|\Shortstack| and \vb|\Longstack| may need to be
+\vb|\protect|'ed.\mdseries
 
 The alignment may be specified as an optional argument, with other
 parameters taken by their defaults.  The stacklength is taken as
@@ -367,7 +384,17 @@ To give an example of the braced syntax described above,
 the stack\\
 \vb|\Shortstack[r]{a {b c} {\P} $\beta^2$ ANCHOR}|
 will produce
-\Shortstack[r]{a {b c} {\P} $\beta^2$ ANCHOR}.
+\Shortstack[r]{a {b c} {\P} $\beta^2$ ANCHOR}.  Note that the use of the
+math delimiter (\vb|$|) in the \vb|\Shortstack| argument was needed
+only if the stack contains both inline math as well as text elements.
+If the stack is to contain only math-mode elements, then math arguments
+can be made the default:\\
+\vb|\stackMath|%
+\vb|\Shortunderstack[c]{{\alpha} {\beta} {\gamma}}|\\
+yielding
+\stackMath
+\Shortunderstack[c]{{\alpha} {\beta} {\gamma}}.
+\stackText
 
 \subsubsection{\cmd{Shortunderstack} and \cmd{Longunderstack}}
 
@@ -806,12 +833,12 @@ trying to achieve a desired horizontal alignment of disparate elements in
 tabular columns.
 
 \vb|\def\stacktype{S}\belowbaseline[0pt]{\imgi}|\\
-\vb|\belowbaseline[0pt -\heightof{\strutbox}]{\imgi}|:
+\vb|\belowbaseline[-\ht\strutbox]{\imgi}|:
 
 \def\stacktype{S}
 \def\imgi{\includegraphics[width=0.87in]{example-image}}
 \rl\blmark\rl\rl\belowbaseline[0pt]{\imgi}\rl\rl
-\belowbaseline[0pt -\heightof{\strutbox}]{\imgi}\rl\rl%
+\belowbaseline[-\ht\strutbox]{\imgi}\rl\rl%
 \fbox{\parbox[t]{1.8cm}{\raggedright A parbox with [t] alignment}}%
 \rl\rl\blmark\rl
 
@@ -912,6 +939,7 @@ Note from the definition used for figure~\ref{fg:subs}(c) that when a
 a space-separated argument, such as \vb|\Shortstack|,
 \vb|\Longstack|, and the corresponding understacks.
 
+\clearpage
 \section{Nested Stacking Commands}
 
 The macros \vb|\Shortstack|, \vb|\Longstack|, and the corresponding
@@ -962,16 +990,51 @@ nested stack.
 Therefore, to nest long stacks, only the second argument of the
 stackengine may be nested.
 
-\section{Math Mode Usage\label{s:mm}}
+\section{Math Mode and Mixed Mode Usage\label{s:mm}}
 \def\useanchorwidth{F}
 \setstackgap{S}{1pt}\def\stacktype{S} 
 
-The \textsf{stackengine} package is not really intended for math mode,
+As of V3.0, the {\ste} package was extended to allow its arguments to be
+processed, by default, using inline math-mode (\vb|\textstyle| math).
+The math-mode default is brought about with an invocation of
+\vb|\stackMath|, which can be later reversed via \vb|\stackText|.
+
+Except in circumstances that require the particular features of this
+package, {\ste} may not be the best package for math mode
 since there are many packages that already cater directly to the need to
 stack and align mathematical objects.  However, if there is a need to
 use {\ste} there, because of its particular facility with
 stacking gaps, there are several hints to remember.
 
+\textsc{Hints for use in math mode:} (operating under \vb|\stackMath|)
+\stackMath
+
+\begin{enumerate}
+
+\item Arguments to stacking commands are only taken in math mode, by
+default, following the invocation of the \vb|\stackMath| macro.
+
+\item The \vb|\stackMath| and \vb|\stackText| macros are not to be
+used within stacking arguments, but are invoked prior to stacking, to
+set the default manner in which stacking arguments are subsequently
+processed.
+
+\item As described in \S\ref{s:sls}, if the math argument has spaces in
+a command which uses space-separated lists, or if the argument ends in a
+macro, the argument must be enclosed in braces.
+
+\vb|\(y = \Shortstack{{a + b} {\odot} b} x\)|:\hfill
+\(y = \Shortstack{{a + b} {\odot} b} x\)
+
+\item In math mode, the \vb|\stackanchor| command seems to preserve
+the math axis better with an ``S'' \vb|\stacktype|, rather than type
+``L''.
+
+\end{enumerate}
+
+\textsc{Hints for using math in text mode:} (operating under \vb|\stackText|)
+\stackText
+
 %SAVE FOR FUTURE USE
 \begin{verbbox}[]
 \savestack{\a}{\(\sqrt{a + b}\)}
@@ -981,8 +1044,8 @@ stacking gaps, there are several hints to remember.
 
 \begin{enumerate}
 
-\item Stacking commands from this package can be used in math mode, but will
-set their arguments as text, not math.
+\item Stacking commands from this package can be used in math mode, but
+will set their arguments as text, 
 
 \vb|\( y = \stackunder{a}{+} x\)|:\hfill
 \( y = \stackunder{a}{+} x\)
@@ -1002,13 +1065,6 @@ only if \vb|\protect|'ed, in these space-separated argument lists).
 \vb|\(y = \Shortstack{$a$ . $b$} x\)|:\hfill
 \(y = \Shortstack{$a$ . $b$} x\)
 
-\item As described in \S\ref{s:sls}, if the math argument has
-spaces in a command which uses space-separated lists, the argument must
-be enclosed in braces.
-
-\vb|\(y = \Shortstack{{$a + b$} . $b$} x\)|:\hfill
-\(y = \Shortstack{{$a + b$} . $b$} x\)
-
 \item For more complex items, the \vb|\savestack| command can be used
 to save an intermediate math expression (even if it isn't actually a
 stack).
@@ -1018,10 +1074,6 @@ stack).
 \savestack{\dash}{- - - - -}
 \addvbuffer[\the\baselineskip]{\(y = \stackunder{\stackon{\dash}{\a}}{$b$} x\)}
 
-\item In math mode, the \vb|\stackanchor| command seems to preserve
-the math axis better with an ``S'' \vb|\stacktype|, rather than type
-``L''.
-
 \end{enumerate}
 
 \section{Backward Compatibility\label{s:bc}}
@@ -1031,25 +1083,25 @@ syntax of this package has changed between versions 1.0 and 2.0 of this
 package.  
 
 In version 1.0 of this package, stackgaps could be directly defined by
-setting the \LaTeX{} lengths \verb|\Sstackgap| and \verb|\Lstackgap|.
+setting the \LaTeX{} lengths \vb|\Sstackgap| and \vb|\Lstackgap|.
 The problem with this approach is that, under fontsize changes, these
 stackgaps were not automatically updated to reflect the new fontsize.
 As of V2.0, that deficiency was remedied.  The syntax that replaces
 these length specifications is
 
 \itshape
-\vb|  \setstackgap{S}{|inter-item stackgap\verb|}|\\
-\vb|  \setstackgap{L}{|inter-item baselineskip\verb|}|  .
+\vb|  \setstackgap{S}{|inter-item stackgap\vb|}|\\
+\vb|  \setstackgap{L}{|inter-item baselineskip\vb|}|  .
 \upshape
 
-Thus, \verb|\Sstackgap| and \verb|\Lstackgap| are no longer lengths (but
-instead \verb|\def|s), and cannot be set via the \verb|\Sstackgap=...|
-or \verb|\setlength{\Sstackgap}{...}| syntax.  It is these settings
+Thus, \vb|\Sstackgap| and \vb|\Lstackgap| are no longer lengths (but
+instead \vb|\def|s), and cannot be set via the \vb|\Sstackgap=...|
+or \vb|\setlength{\Sstackgap}{...}| syntax.  It is these settings
 which will need to be revised to modernize older code.
 
 While not encouraged, the V1.0 syntax may be recovered via
 
-\verb|  \usepackage[oldsyntax]{stackengine}|
+\vb|  \usepackage[oldsyntax]{stackengine}|
 
 If you retain the ``oldsyntax'' setting, you must remember that
 \textsf{stackengine} will honor your specified gap sizes
@@ -1059,7 +1111,7 @@ If you retain the ``oldsyntax'' setting, you must remember that
 when the text is \vb|\normalsize|, the gap length is set in a
 \vb|\normalsize| font, even if the fontsize is later changed.  To
 overcome this behavior, the stackgap must be redefined at the new
-fontsize, or better still, \verb|[oldsyntax]| usage needs to be
+fontsize, or better still, \vb|[oldsyntax]| usage needs to be
 relegated.
 
 \section{Acknowledgements}
@@ -1067,13 +1119,13 @@ relegated.
 I would like to thank Prof. Enrico Gregorio at tex.stackexchange for
 providing three lines of code to strip a leading backslash from an
 argument:\\
-\verb|http://tex.stackexchange.com/questions/42318/|\\
-\verb|removing-a-backslash-from-a-character-sequence|
+\vb|http://tex.stackexchange.com/questions/42318/|\\
+\vb|removing-a-backslash-from-a-character-sequence|
 
 Furthermore, Prof. Gregorio was of great assistance in making the
 transition from the deficient V1.0 syntax as painless as possible:\\
-\verb|http://tex.stackexchange.com/questions/123443/|\\
-\verb|defining-a-length-that-scales-with-fontsize-changes/123470#123470|
+\vb|http://tex.stackexchange.com/questions/123443/|\\
+\vb|defining-a-length-that-scales-with-fontsize-changes/123470#123470|
 
 \section{Code Listing}