From 31a1ab5cea8b9eecd632b1320274f474b83dad88 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 6 Aug 2013 22:25:47 +0000 Subject: stackengine (6aug13) git-svn-id: svn://tug.org/texlive/trunk@31367 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/stackengine/README | 4 +- .../doc/latex/stackengine/stackengine.pdf | Bin 285306 -> 301186 bytes .../doc/latex/stackengine/stackengine.tex | 134 ++++++++++++++------- 3 files changed, 95 insertions(+), 43 deletions(-) (limited to 'Master/texmf-dist/doc/latex/stackengine') 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 Binary files a/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf and b/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf differ 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} -- cgit v1.2.3