stackengine (20jun13)

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

3 files changed, 1013 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/stackengine/README b/Master/texmf-dist/doc/latex/stackengine/README
new file mode 100644
index 00000000000..9609ff53238
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/stackengine/README
@@ -0,0 +1,23 @@
+The stackengine package provides a versatile way to vertically stack
+objects in a variety of customizable ways.  A number of useful macros
+are provided, all of which make use of the stackengine core.  These
+macros allow a wide variety of tasks, including: 
+
+-creating aligned stacks of specified inter-item gap;
+
+-creating aligned stacks of specified inter-item baselinse shift;
+
+-stacking both above and below the baseline; 
+
+-overlaying character glyphs; 
+
+-insetting graphical images atop larger background images; 
+
+-top and bottom lapping; shifting the horizontal axis of a stack;
+
+-changing the baseline of an object; 
+
+-subfigure labeling;
+
+This package is primarily intended for text mode, thought it can be
+adapted for use in math mode.
diff --git a/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf b/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf
new file mode 100644
index 00000000000..fbdfe740062
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..d320db28792
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
@@ -0,0 +1,990 @@
+\documentclass{article}
+\def\version{1.0}
+\usepackage{scalerel}
+\usepackage{stackengine}
+\usepackage{verbatimbox}
+\usepackage{boxhandler}
+\parindent 0in\parskip 1em
+\newlength\dotscale
+
+\dotscale=.4ex         % DOTSIZE<---CAN CHANGE THESE
+\def\newdot{\scalerel*{.}{\rule[-\dotscale]{1ex}{\dotscale}}}
+\def\newdot{\scalerel*{.}{\rule{1ex}{\dotscale}}}
+
+% FOR CLOSE-BOXING ARGUMENTS
+\fboxsep=0pt\fboxrule=.1pt
+
+\newcommand\rl{\rule{2em}{0in}}
+\def\ste{\textsf{stackengine}}
+\def\bs{\texttt{\char'134}}
+\let\vb\verb
+\reversemarginpar
+\marginparwidth 1.6in
+\newcommand\margtt[1]{\marginpar{\hfill\ttfamily#1}}
+\newcommand\margcmd[1]{\marginpar{\hfill\ttfamily\char'134#1}}
+\newcommand\cmd[1]{\texttt{\char'134#1}}
+\def\lapmark{\rule[-.3\baselineskip]{.1ex}{\baselineskip}}
+
+\begin{document}
+
+\begin{center}
+\LARGE The {\ste} Package\\
+\rule{0em}{.7em}\small Highly customized stacking of objects, insets,
+baseline changes, \textit{etc.}\\
+\rule{0em}{2.7em}\large Steven B. Segletes\\
+steven.b.segletes.civ@mail.mil\\
+\rule{0em}{1.7em}\today\\
+v\version
+\end{center}
+
+%\tableofcontents
+
+\section{Definitions and Terms}
+
+Before I describe the various commands of this package, it is best for
+you to familiarize yourself with a few terms as used in this package.
+
+\subsection{Short Stacks and Long Stacks\label{s:st}}
+\def\usestackstrut{T}
+\def\stacktype{L}
+\Huge\Sstackgap=.4ex\Lstackgap=2.2ex\normalsize 
+
+In this package, ``Short'' refers to squeezing the extra space out of
+glyphs comp.rising the stack, so that the inter-item gap is solely what
+is set.  Likewise, ``Long'' refers to a stack kept at constant
+inter-item baseline spacing.  Let's look at the following two
+examples to see this clearly.
+
+Notice the consistent inter-item gap on a short stack: 
+\Huge
+\Shortstack{{\fbox{t}} {\fbox{y}} {\fbox{k}} {\fbox{e}}}
+%\Shortstack{{\fbox{a}} {\fbox{h}} {\fbox{g}} {\fbox{b}}}
+\normalsize
+
+Notice the consistent inter-baseline spacing on a long stack: 
+\def\rl{\protect\rule[-.05pt]{1ex}{.1pt}}\Huge
+\Longstack{{{\rl t}} {{\rl y}} {{\rl k}} {{\rl e}}}
+%\Longstack{{{\rl a}} {{\rl h}} {{\rl g}} {{\rl b}}}
+\normalsize
+
+In this package, the default spacing for the long stack, saved in the
+length \vb|\Lstackgap| is the value \vb|\baselineskip|.  For short
+stacks, the default length, 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 this packkage (short or
+long) is indicated by the definition of \verb|\stacktype|.  These
+defaults can be changed.
+
+\subsection{(Over)Stacks and Understacks}
+
+\Lstackgap=.8\baselineskip
+\Sstackgap=4pt
+In general terms, a stack is built up from the baseline, while an
+understack is built down from the baseline.  
+
+So, for example,
+\Longstack{a b c}
+is a stack, while
+\Longunderstack{a b c}
+is an understack.
+
+With this package, both stacks and understacks can be long or short,
+depending on how the invocation is made.  Sometimes, in this
+documentation, a stack will be called an ``overstack'' in order to avoid
+confusion with ``understack.''
+
+\subsection{Anchors}
+
+The term ``anchor'' is used to denote an item in the stack whose
+baseline does not change in the course of the stacking operation.  In
+essence, stacking is done relative to the anchor.
+
+For example, in \Shortstack{a b c}, the letter ``c'' is the anchor.  
+
+In the understack \Shortunderstack{a b c}, ``a'' is the anchor.
+
+\subsection{Alignment\label{s:sal}}
+
+Anyone familiar with \LaTeX{} knows something about the horizontal
+alignment settings ``l'', ``c'' and ``r''.  As pertains to a stack, we
+refer to the alignment of the various rows of the stack, as shown in the
+following examples.
+
+\Sstackgap=3pt\Lstackgap=12pt%
+
+{\centering
+Left: \Shortstack[l]{abcd abc ab a}~~
+Center: \Shortstack[c]{abcd abc ab a}~~
+Right: \Shortstack[r]{abcd abc ab a}
+
+}
+The default alignment within a stack may be set with the
+\vb|\stackalignment| definition, to possible values of \vb|l|,
+\vb|c|, or \vb|r|, denoting left, center, and right alignments,
+respectively.  In addition, a number of the stacking macros provide the
+alignment as an argument or optional argument that can be specified at
+time of invocation.
+
+The {\ste} package defaults to center alignment, unless reset by way of
+the \vb|\stackalignment| definition.
+
+
+\section{Defaults and Macros Provided by \ste}
+
+
+\subsection{Defaults}
+
+There are several lengths and \vb|\def|'s that serve to store package
+default definitions.  When a 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 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
+itself be provided as the argument.
+
+Let us first consider the length defaults:
+
+\itshape
+\vb|\Sstackgap=|length\\
+\vb|\Lstackgap=|length\\
+\vb|\stackgap|
+\upshape
+
+The parameter \vb|\Sstackgap| is the default inter-item gap for any
+stacking command that builds a short stack.  It defaults to 3pt.
+Correspondingly, \vb|\Lstackgap| is the inter-item baselineskip for
+any stacking command that builds a long stack.  It defaults to
+\vb|\baselineskip|.  The macro \vb|\stackgap| is not actually a
+length, but a command that will look at the current value of
+\vb|\stacktype| and will define itself as either \vb|\the\Sstackgap| or
+\vb|\the\LStackgap|, depending on whether \vb|\stacktype| is defined
+as ``S'' or ``L''.
+
+In addition to these lengths, there are several parameter definitions
+that define default behaviors for those macros where explict values of
+these settings are not requested.  The parameters, each set with a
+\vb|\def| command, are
+
+\itshape
+\vb|\def\stackalignment{l| or \vb|c| or \vb|r}|\\
+\vb|\def\quietstack{T| or \vb|F}|\\
+\vb|\def\useanchorwidth{T| or \vb|F}|\\
+\vb|\def\stacktype{S| or \vb|L}|\\
+\vb|\def\usestackstrut{T| or \vb|F}|
+\upshape
+
+The parameter \vb|\stackalignment| defaults to ``c'' (center) and
+defines the default stacking alignment.  Other options include ``l''
+(left) and ``r'' (right).  See \S\ref{s:sal} for more discussion
+of this parameter.
+
+The parameter \vb|\quietstack| defaults to ``F'' (false) and
+determines whether the result of a stacking operation is supressed from
+the output.  If the output is suppressed by setting this parameter to
+``T'', the most recent stacking operation may be recovered with a
+\vb|\usebox{\stackedbox}|.  See \S\ref{s:qs} for more
+discussion of this parameter.
+
+The parameter \vb|\useanchorwidth| defaults to ``F'' (false) and
+indicates that, upon creation, the stack width should be taken as the
+widest element of the stack.  When set to ``T'', the stack width, upon
+creation, is instead taken as the width of the anchor.  Note that this
+parameter applies at the time of stack creation and cannot be used to
+retroactively change the characteristics of an existing stack.  See
+\S\ref{s:uaw} for more discussion of this parameter.
+
+The parameter \vb|\stacktype| defaults to ``S'' (short stack) and
+defines the default type of stack to build.  When set to ``L'', newly
+created stacks are, by default, long stacks.  Refer to
+\S\ref{s:st} for a definition of these terms.
+
+The parameter \vb|\usestackstrut| defaults to ``T'' (true) and has
+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
+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.
+
+\subsection{Macros}
+
+\subsubsection{\cmd{stackengine}}
+
+The basic (and most general) stacking macro provided by this package is
+\vb|\stackengine|.  Nearly all other macros of this package merely
+provide an abbreviated invocation form of this macro, tailored for a
+particular application.  The syntax is:
+
+\itshape
+\vb|\stackengine{\Sstackgap| or
+  \vb|\Lstackgap| or
+  \vb|\stackgap| or stacklength%
+  \vb|}|\\
+\vb|            {|anchor\vb|}|\\
+\vb|            {|item\vb|}|\\
+\vb|            {O| or \vb|U}|\\
+\vb|            {\stackalignment| or
+  \vb|l| or
+  \vb|c| or
+  \vb|r}|\\
+\vb|            {\quietstack| or \vb|T| or \vb|F}|\\
+\vb|            {\useanchorwidth| or \vb|T| or \vb|F}|\\
+\vb|            {\stacktype| or \vb|S| or \vb|L}|
+\upshape
+
+There are no optional arguments with \vb|\stackengine|.  The first
+item is a stacking length, which can mean different things depending on
+whether a short- or long-stack is being created, as discussed in
+\S\ref{s:st}.  The second argument is the stack anchor, whose
+baseline does not change.  The third argument is the item stacked
+relative to the anchor.  The fourth argument is either an ``O'' (for a
+normal or overstack) or a ``U'' (for an understack).  The fifth argument
+denotes a left, center, or right alignment of the stack items with the
+use of ``l'', ``c'', or ``r''.  The sixth argument is either a ``T'' or
+``F'' to denote whether the resulting stack is NOT printed (``T''
+denotes ``do NOT print'').  The seventh argument, also a ``T'' or an
+``F'', denotes when ``T'' that the width of the whole stack is to be
+taken as the width of the anchor.  Otherwise, the width of the stack
+conforms to the width of the widest item in the stack.  The final
+argument is defined as either an ``S'' or an ``L'' to denote whether a
+short stack or a long stack is being requested.
+
+While none of the arguments to \vb|\stackengine| have default values,
+there are various definitions in the package that store default values.
+When one wishes a stack to possess certain default properties, these
+default definitions may be passed as the values for the respective
+arguments to \vb|\stackengine|.  Arguments 1, 5, 6, 7, and 8 each
+possess a corresponding parameter containing the default variable.  So,
+for example,
+
+\begin{verbatim}
+\stackengine{\stackgap}{A}{BC}{O}{\stackalignment}
+            {\quietstack}{\useanchorwidth}{\stacktype}
+\end{verbatim}
+
+will stack the letters ``BC'' over ``A'' using the default values of
+\vb|\stackalignment|, \vb|\quietstack|, \vb|\useanchorwidth|,
+and \vb|\stacktype|.  In addition, the stackgap will be set to
+\vb|\Sstackgap| if \vb|\stacktype| is ``S'' or to \vb|\Lstackgap|
+if \vb|\stacktype| is ``L''.  Alternately, the  samestack could be 
+forced to be a long stack with right-alignment and be typeset using
+
+\begin{verbatim}
+\stackengine{\Lstackgap}{A}{BC}{O}{r}{F}{\useanchorwidth}{L}
+\end{verbatim}
+
+\subsubsection{\cmd{stackon} and \cmd{stackunder}}
+
+The \vb|\stackon| and \vb|\stackunder| macros are abbreviated forms
+of \vb|\stackengine| in which the default values of parameters are
+taken.  The only exception is the stacklength, which may be provided as
+an optional argument.
+
+\itshape
+\vb|\stackon[|stacklength%
+  \vb|]{|anchor%
+  \vb|}{|item
+  \vb|}|\\
+\vb|\stackunder[|stacklength%
+  \vb|]{|anchor%
+  \vb|}{|item
+  \vb|}|
+\upshape
+
+In the case of \vb|\stackon|, an (over)stack is created, whereas an
+understack is created with \vb|\stackunder|.  With both of these
+commands, the anchor is the first mandatory argument, and the item to be
+stacked above or below it is the second mandatory argument.
+
+\subsubsection{\cmd{Shortstack} and \cmd{Longstack}\label{s:sls}}
+
+The \vb|\Shortstack| and \vb|\Longstack| commands are stacking
+commands that allow more than two stacking rows to be specified at once.
+The items of a stack are provided in a space-separated list, as follows:
+
+\itshape
+\vb|\Shortstack[|alignment%
+  \vb|]{|item %
+  \vb|{|it em%
+  \vb|} {\|item%
+  \vb|} $|item%
+  \vb|$| ... anchor%
+  \vb|}|\\
+\vb|\Longstack[|alignment%
+  \vb|]{|item %
+  \vb|{|it em%
+  \vb|} {\|item%
+  \vb|} $|item%
+  \vb|$| ... anchor%
+  \vb|}|
+\upshape
+
+The first item is at the top of the stack, farthest from the baseline,
+while the last item is the anchor of the stack.  If an item (the
+contents of a single row) contains spaces, enclose the item in braces.
+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.
+
+The alignment may be spacified as an optional argument, with other
+parameters taken by their defaults.  The stacklength is taken as
+\vb|\stackgap|, which will depend on the value of \vb|\stacktype|.
+
+To give an example of the braced syntax described above,
+the stack\\
+\verb|\Shortstack[r]{a {b c} {\P} $\beta^2$ ANCHOR}|
+will produce
+\Shortstack[r]{a {b c} {\P} $\beta^2$ ANCHOR}.
+
+\subsubsection{\cmd{Shortunderstack} and \cmd{Longunderstack}}
+
+The \vb|\Shortunderstack| and \vb|\Longunderstack| commands are the
+understacking equivalents of \vb|\Shortstack| and \vb|\Longstack|.
+
+\itshape
+\vb|\Shortunderstack[|alignment%
+  \vb|]{|anchor item %
+  \vb|{|it em%
+  \vb|} {\|item%
+  \vb|} $|item%
+  \vb|$| ...%
+  \vb|}|\\
+\vb|\Longunderstack[|alignment%
+  \vb|]{|anchor item %
+  \vb|{|it em%
+  \vb|} {\|item%
+  \vb|} $|item%
+  \vb|$| ...%
+  \vb|}|
+\upshape
+
+The caveats to the specification of the space-separated list of items is
+the same as that mentioned above for \vb|\Shortstack| and
+\vb|\Longstack|.
+
+Note that the items are still specified from the top downward.
+In the case of understacks, however, that means that the anchor is the
+first item specified, while the last item in the list is farthest below
+the baseline.
+
+\subsubsection{Top and bottom lapping macros}
+
+\tclap{Top}and \bclap{bottom}~lapping is achievable through the creation of various
+long stacks.  The syntax is the same for all six of the macros provided.
+The six names differentiate whether the lap is to the top (t) or the
+bottom (b) of the calling point, and whether it should appear to the
+left (l), centered (c), or to the right (r) of the calling location.
+The long-stacklength may be provided as an optional argument.
+
+\itshape
+\vb|\tllap[|stacklength\vb|]{|item\vb|}|\\
+\vb|\tclap[|stacklength\vb|]{|item\vb|}|\\
+\vb|\trlap[|stacklength\vb|]{|item\vb|}|\\
+\vb|\bllap[|stacklength\vb|]{|item\vb|}|\\
+\vb|\bclap[|stacklength\vb|]{|item\vb|}|\\
+\vb|\brlap[|stacklength\vb|]{|item\vb|}|
+\upshape
+
+See \S\ref{s:lap} for more information and examples of use for
+these lapping commands.
+
+\subsubsection{\cmd{stackanchor}}
+
+The \vb|\stackanchor| macro is one way to create a stack where the
+baseline is split between two items in the stack.  The syntax is
+
+\itshape
+\vb|\stackanchor[|stackgap%
+  \vb|]{|top item%
+  \vb|}{|bottom item%
+  \vb|}|
+\upshape
+
+The stacking gap may be provided as an optional argument.  All other
+parameters taken are the defaults.  There are subtle differences in the
+way a short stack anchor versus a long stack anchor is split.
+One should consult \S\ref{s:sa} for a description of how the
+stack is constructed.
+
+If a short stack is being created with a split anchor, the
+\vb|\usestackstrut| parameter will determine whether the split occurs
+at the mid-height of the strutbox (``T'') or whether it will occur about
+the baseline (``F'').
+
+\subsubsection{\cmd{belowbaseline}}
+
+The macro \vb|\belowbaseline| also creates the means to shift an
+item's baseline.  The syntax is
+
+\itshape
+\vb|\belowbaseline[|stackgap\vb|]{|item\vb|}|
+\upshape
+
+where the stackgap defines the stackgap distance.  In a long stack, it
+will define the downward shift of the baseline of the item.  In a short
+stack, it will define the downward gap from the new baseline to the top
+of the item.  One should consult \S\ref{s:bbl} for more details.
+
+This command can also be employed to redefine the baseline of
+graphical objects, which can provide useful vertical alignment
+techniques.  A negative stack gap can be specified to raise the item's
+baseline above its original value.
+
+\subsubsection{{\cmd{topinset}} and \cmd{bottominset}\label{s:iis}}
+
+The macros \vb|\topinset| and \vb|\bottominset| are for insetting
+smaller items (\textit{e.g.}, images) inside of a larger background
+items (\textit{e.g.}, images).  The syntax is
+
+\itshape
+\vb|\topinset{|inset item%
+  \vb|}{|background item%
+  \vb|}{|V-offset%
+  \vb|}{|H-offset\vb|}|\\
+\vb|\bottominset{|inset item%
+  \vb|}{|background item%
+  \vb|}{|V-offset%
+  \vb|}{|H-offset\vb|}|
+\upshape
+
+In addition to providing the inset and background items as the first two
+arguments, the inset may be vertically and horizontally offset though
+the use of the last two arguments.  The vertical offset is relative to
+the top of the \vb|\topinset| background and relative to the bottom of
+the \vb|\bottominset| background.  The horizontal offset is relative
+to the left edge of the background for left stackalignment and relative
+to the right edge of the background for right stackalignment.
+Horizontal offset is meaningless for center stackalignment.
+
+While these commands were designed with inlaid images in mind (see
+\S\ref{s:ii}), there is nothing that prevents their use to inlay
+character glyphs upon each other, as in 
+\topinset{*}{O}{0.2ex}{0.0ex}, accomplished with
+\vb|\topinset{*}{O}{0.2ex}{0.0ex}|.
+
+
+\subsubsection{\cmd{savestack}}
+
+The macro \vb|\savestack| provides a means to save an intermediate
+result (in a box that can be recalled with the specified macro) without
+printing it.  It's syntax is
+
+\itshape
+\vb|\savestack{|macro token\vb|}{|stacking operation\vb|}|
+\upshape
+
+The macro token is a backslashed name that you can later use to recall
+the boxed intermediate result.  The stacking operation is the
+intermediate result you wish to save in a box without printing.  Reasons
+why this might be a useful macro are described in \S\ref{s:svs}.
+
+Note that while \verb|\savestack| is designed to save an intermediate
+stacking operation in a box, the reality is that you can use this macro
+to save any sequence of boxable output, even if it is not a stacking
+operation.  So, for example, \vb|\savestack{\mymacro}{\fbox{A}}| can
+later be recalled with an invocation of \vb|\mymacro|, to yield
+\fboxsep=1pt\savestack{\mymacro}{\fbox{A}}\mymacro.\fboxsep=0pt
+
+\section{Making a Stack in Stages}
+
+There are times where one needs to make a stack in several consecutive
+steps.  In order to do so, there are several ways, detailed below.  
+
+\subsection{Supressing Output\label{s:qs}}
+
+One can define \vb|\quietstack| as \vb|T| to supress output.  Then, the
+intermediate stack can be passed to the next stacking operation with a
+\vb|\usebox{\stackedbox}|.  Finally, \vb|\quietstack| must again be
+made false to re-enable output.
+
+\subsection{Saving a Stack without Printing It\label{s:svs}}
+
+Perhaps a quicker and better way is to use the package's
+\vb|\savestack| macro, of the form
+\itshape\vb|\savestack{|macro token\vb|}{|stacking operation\vb|}|
+\upshape.  This will perform the stacking operation and place it into
+the supplied token (without printing it), so that ths intermediate stack
+can be passed to the subsequent stacking operation by executing the
+token macro.
+
+For example,
+\begin{verbatim}
+\savestack{\pdq}{\Longstack[r]{6 5 4 {3 3}}}%
+\Longstack[l]{{\pdq} 2 1 0}%
+\end{verbatim}
+
+would first place ``\Longstack[r]{6 5 4 {3 3}}'' into \vb|\pdq|, without
+printing it, in a right-aligned fashion, with the ``3 3'' on the
+baseline.  Then, the second \vb|\Longstack| would place the first stack
+atop of the ``2'' in a left-aligned fashion.  The resulting stack would
+look as follows, with the ``0'' on the final baseline.
+
+\savestack{\pdq}{\Longstack[r]{6 5 4 {3 3}}}%
+\Longstack[l]{{\pdq} 2 1 0}
+\rl\rl\rl\rl Baseline%
+
+
+\section{Choosing the Anchor Element}
+
+All stacking done with the stackengine has a designated anchor element.
+The baseline of the anchor does not change.  Instead, the other items
+are placed relative to the anchor.
+By adding items at first above and then below the anchor, any
+arbitrary stack can be built around the anchor.
+
+\def\stackalignment{r}
+\Sstackgap=2pt\Lstackgap=12pt%
+Here is a Longstack/understack example:
+\savestack{\pdq}{\Longstack{3 2 1 0}}%
+\Longunderstack[r]{{\pdq} -1 -2 -3 -4 -5}
+that was achieved as follows:
+
+\begin{verbatim}
+\savestack{\pdq}{\Longstack{3 2 1 0}}%
+\Longunderstack[r]{{\pdq} -1 -2 -3 -4 -5}
+\end{verbatim}
+
+In the first stack, ``0'' is the anchor of \vb|\pdq|.  In the second
+stack, \vb|\pdq| is the anchor (which means that ``0'' remains the
+anchor of the composite stack).
+
+\section{Top and Bottom Lapping\label{s:lap}}
+\def\stackalignment{c}
+\def\stacktype{L}%
+\Lstackgap=\baselineskip
+Top and bottom lapping can be accomplished with a long stack, using a null
+item as the anchor, and \vb|\useachorwidth| set to \vb|T|.  This
+technique is encoded in six \vb|\|\textit{xy}\vb|lap| commands,
+where \textit{x} can be \vb|t| or \vb|b| (for ``top'' and
+``bottom,'' respectively) and \textit{y} can be \vb|l|, \vb|c|, or
+\vb|r| (for ``left,'' ``center,'' and ``right,'' respectively).  Note
+that this \textit{y} is not the same as the \vb|\stackalignment|, but
+rather refers to the direction where the lapped item is placed relative
+to the lap invocation.
+
+For illustration only, laps will be shown at a \textit{visible} lapmark
+(given by \lapmark~).  In these examples, I lap a \vb|\parbox| above
+or below the selected location.
+
+\begin{myverbbox}{\bll}\bllap\end{myverbbox}
+\begin{myverbbox}{\brl}\brlap\end{myverbbox}
+\begin{myverbbox}{\tll}\tllap\end{myverbbox}
+\begin{myverbbox}{\trl}\trlap\end{myverbbox}
+\begin{myverbbox}{\bcl}\bclap\end{myverbbox}
+\begin{myverbbox}{\tcl}\tclap\end{myverbbox}
+For example here\lapmark%
+\bllap{\parbox[t]{.7in}{this is a bottom-left lap \bll}}
+or el\lapmark%
+\brlap{\parbox[t]{.8in}{this is a bottom-right lap \brl}}%
+se here, or else I can put it here\lapmark%
+\tllap{\parbox[b]{.7in}{this is a top-left lap \tll}}
+or here\lapmark%
+\trlap{\parbox[b]{.7in}{this is a top-right lap \trl}}%
+.\
+
+Of course, I can per\lapmark
+\bclap{\fbox{\parbox[t]{1.1in}{this is a bottom-center lap \bcl}}}%
+form center lapping, as we\lapmark%
+\tclap{\fbox{\parbox[b]{1.1in}{this is a top-center lap \tcl}}}%
+ll.
+To see, for example, how the above was achieved, the last lap in the
+prior sentence was achieved by invoking
+
+\verb|\tclap{\fbox{\parbox[b]{1.1in}{this is a top-center lap \tcl}}}|
+
+in the middle of the word ``well.''
+
+\section{Shifting the Anchor's Baseline} 
+
+By default, the baseline of the anchor becomes the baseline of the
+stack.  If one wanted the stack baseline to \textbf{not} conform to
+the baseline of any of the individual stacked items, something needs
+to change.  If one quantitatively knows the shift desired, a simple
+\vb|\raisebox| could be used to vertically shift the anchor, after
+(or possibly prior to) stacking.  There are also some other options
+provided by the package.
+
+\subsection{The \cmd{stackanchor} Macro for ``L'' and ``S'' Stack Types%
+\label{s:sa}}
+
+If one would like the anchor's baseline to be ``midway'' between two
+vertically arrayed items, the \vb|\stackanchor| macro attempts to
+provide that capability for both ``L'' and ``S'' stack types, though the
+definitions of ``midway'' are different for each.  The macro
+\vb|\stackanchor| works for two-item stacks in both ``L'' and ``S''
+stack types, as shown below.
+
+In the case on a long stack, what is satisfied is that the baseline of
+the anchor is made equidistant from the baselines of the two respective
+items comprising the stacked anchor.
+
+\def\stacktype{L}%
+
+\Large
+\def\rl{\rule[-.05pt]{2ex}{.1pt}}
+\def\stackalignment{r}%
+\Lstackgap=.8\baselineskip%
+Baseline%
+\rl\rl
+\stackanchor{\rl\rl\rl\rl top\rl}{\rl L-bottom\rl}%
+\rl\rl%
+Baseline
+\normalsize
+
+In the case of a short stack, the middle of the inter-item gap is
+vertically located at the center of the font's \vb|\strutbox|, so that
+the middle of the stackgap would be at the same vertical level as the
+middle of parentheses, were they located on the original baseline.
+
+\Large
+Baseline\rl\rl%
+\def\rls{\rule[.5\ht\strutbox-.5\dp\strutbox]{2ex}{.1pt}}%
+\rls%
+\def\stackalignment{l}%
+\def\stacktype{S}\Sstackgap=1ex%
+\savestack{\pdq}{\stackanchor{\fbox{top}}{\fbox{S-bottom}}}%
+\pdq%
+\rls%
+(Mid-strut)%
+\rl\rl Baseline
+\def\stackalignment{c}%
+\normalsize%
+
+If one does not want to have the short-stack gap split at the mid-strut
+height, but rather at the baseline, the parameter
+\vb|\def\usestackstrut{F}| may be set prior to the \vb|\stackanchor|
+invocation.
+
+\def\usestackstrut{F}%
+\Large
+Baseline\rl\rl%
+\def\stackalignment{l}%
+\def\stacktype{S}%
+\savestack{\pdq}{\stackanchor{\fbox{top}}{\fbox{S-bottom}}}%
+\pdq%
+\rl\rl Baseline
+\def\stackalignment{c}%
+\normalsize%
+\def\usestackstrut{T}%
+
+The \vb|\usestackstrut| parameter will only affect short stacks
+(\vb|\stacktype| ``S''), since long stacks do not use a strut as part
+of the \vb|\stackanchor| definition.
+
+For stacks with more items, one can add stacks atop or under these
+shifted anchors.
+
+\Large
+\Sstackgap=1ex%
+\savestack{\pdq}{\stackanchor{\fbox{top}}{\fbox{S-bottom}}}%
+\savestack{\pdq}{\Shortstack{{over text} \pdq}}%
+\rls\rls%
+\Shortunderstack{{\pdq} {under text}}%
+\rls\rls(Mid-strut)
+\normalsize
+
+\subsection{\cmd{belowbaseline} for Moving the Anchor's
+Baseline\label{s:bbl}}
+
+The command \vb|\belowbaseline| is intended to be used to set an
+item, such as a stack anchor, below the baseline.  The macro
+accomplishes this task by stacking the item below a null object.
+However, \vb|\useanchorwidth| is set to \vb|F| so that the stacked
+object takes on the width of the under-placed object.
+
+The command can be used with both stacktypes.  With \vb|\stacktype|
+``S'', the optional argument will denote the stackgap below the baseline
+(default \vb|\Sstackgap|),
+
+\LARGE
+\Sstackgap=6pt%
+\def\stacktype{S}%
+Short stacktype\rl\rl\belowbaseline[0pt]{\fbox{0pt below baseline}}%
+\rl\belowbaseline{\fbox{6pt}}\rl\rl
+\normalsize
+
+When used in with a \vb|\stacktpe| ``L'', the optional length denotes
+the distance to the baseline of the understacked object (default
+\vb|\Lstackgap|).
+
+\LARGE
+\Lstackgap=18pt%
+\def\stacktype{L}%
+Long stacktype\rl\rl\belowbaseline[0pt]{\fbox{0pt below baseline}}%
+\rl\belowbaseline{\fbox{18pt}}\rl\rl
+\normalsize
+
+There is nothing to prevent the use of negative numbers being used to
+raise the the object above the baseline.
+
+The \vb|\belowbaseline| command is also useful for forcing objects,
+such as images, to be top-aligned.  This can be a useful feature when
+trying to achieve a desired vertical alignment of disparate elements in
+tabular columns.
+
+\vb|\def\stacktype{S}\belowbaseline[0pt]{\imgi}|\\
+\vb|\belowbaseline[-\baselineskip]{\imgi}|:
+
+\def\stacktype{S}
+\def\imgi{\includegraphics[width=0.87in]{example-image}}
+\rl\rl Baseline\rl\rl\belowbaseline[0pt]{\imgi}\rl\rl
+\belowbaseline[-\baselineskip]{\imgi}\rl\rl Baseline\rl\rl
+
+\section{Stack Gap ``Quirk''}
+\Lstackgap=10pt%
+\def\stacktype{L}
+
+This ``quirk'' is not peculiar to this package, but is true of all
+lengths in \LaTeX{}.  It is mentioned here as worthwhile to keep in mind
+if you build stacks in different font sizes.
+
+The \textsf{stackengine} package will honor your default gap sizes
+(\vb|\Sstackgap| and \vb|\Lstackgap|) at the time of their
+\textbf{definition}, rather than at the time of their
+\textbf{invocation}.  Thus, if \vb|\Sstackgap| is specified as 0.7ex
+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.
+
+For example, operating at \vb|\normalsize|,\\
+\Sstackgap=0.7ex
+\vb|\Sstackgap=0.7ex| gives
+\Shortstack{a b c d}.
+However, in the case of a transition to \vb|\LARGE|
+%\Sstackgap=3pt%
+%\vb|\Sstackgap=3pt| 
+the same stack gives a larger text, but an unchanged gap size,\\
+\LARGE\Shortstack{a b c d}\normalsize.
+Only when the gap is reset to \vb|0.7ex| under 
+\vb|\LARGE| does it give
+\LARGE%
+\Sstackgap=.7ex%
+\Shortstack{a b c d}\normalsize.  In the first stack the gap size is
+\vb|\normalsize 0.7ex| and in the latter stack, the gap is
+\vb|\LARGE 0.7ex|.  Of course, if the gap is specified in fontsize
+independent units, such as \vb|pts|, there is no confusion.
+
+\section{Negative Stack Gap}
+\def\stacktype{S}
+\Sstackgap=-1.2pt
+\dotscale=1.ex
+A negative gap can be used to overlap things.  For example, \newdot plus
+``i'' can make, when the stack gap is suitably negative, the following:
+
+~\hfill\scalebox{3}{\stackon{i}{\newdot}}\hfill~
+
+Note that the use of a negative stack gap for a two-item stack is
+actually very similar to the inset commands described in
+\S\ref{s:iis} and \S\ref{s:ii}.
+
+\section{The {\cmd{useanchorwidth}} Option\label{s:uaw}}
+\Sstackgap=-1.2pt
+\dotscale=1.ex
+
+Because\newdot has width larger than the dot glyph itself (we box its
+extent here: \fbox{\newdot}), stacking it could otherwise be a problem.
+For example, th\stackon{i}{\newdot}s uses the whole stackwidth to set
+the dotted-i in its place. 
+\def\useanchorwidth{T} 
+On the other hand, when \vb|\useanchorwidth| is defined as \vb|T|,
+``th\stackon{i}{\newdot}s'' uses only the anchor width to set the stack
+(where the ``i'' is the anchor).  
+
+Below, we show an \vb|\fbox| around the dotted i, clearly
+demonstrating that the dot does not influence the width of the
+stack when \vb|\useanchorwidth| is defined as ``T''.
+
+\Huge
+~\dotscale=1ex\hfill th\fbox{\stackon{i}{\newdot}}s\hfill~
+\normalsize
+\def\useanchorwidth{F} 
+
+\section{Image Insets\label{s:ii}}
+
+The commands 
+\vb|\topinset| and \vb|\bottominset| allow images be stacked atop
+one another, to produce the effect of an inset image.  In addition to
+specifying the two images, the effect can be tailored by specifying the
+vertical and horizontal offsets of the inset image.
+
+\def\imgi{\includegraphics[width=0.87in]{example-image}}
+\def\imgii{\includegraphics[width=0.3in]{example-image}}
+\def\stackalignment{r}
+\savestack{\imga}{\topinset{\imgii}{\imgi}{2pt}{3pt}}
+\def\stackalignment{l}
+\savestack{\imgb}{\bottominset{\imgii}{\imgi}{2pt}{3pt}}
+\imga~~~~\imgb
+\def\stackalignment{c}
+
+Note that the horizontal offset only works when \vb|\stackalignment|
+is set to \vb|l| or \vb|r|.
+
+The last figure was obtained with
+\verb|\bottominset{\imgii}{\imgi}{2pt}{3pt}|,
+showing that \verb|\imgii| was offset 2pt from the bottom and 3pt from
+the left edge of \verb|\imgi|.
+
+\section{Stacking for Subfiguring and Baseline Manipulation}
+
+The stacking commands provide a convenient way to underset a subfigure
+notation under the corresponding image.  Furthermore, because of the
+flexibility of the stacking commands, the baselines of the subfigures
+can be manipulated in many ways, which may come in handy depending on
+how you are choosing to lay out your subfigures.
+
+Examples of this are shown in figure~\ref{fg:subs}.
+
+\Sstackgap=3pt\def\stacktype{S}
+\begin{myverbbox}{\figa}\stackon{(a)}{\imga}\end{myverbbox}
+\begin{myverbbox}{\figb}\stackunder{\imgb}{(b)}\end{myverbbox}
+\begin{myverbbox}[\small]{\figc}
+\Shortstack{{\protect\imgi} (c1) {} {\protect\imgi} (c2)}
+\end{myverbbox}
+\begin{myverbbox}{\figd}\belowbaseline[0pt]{\stackunder{\imgi}{(d)}}\end{myverbbox}
+\def\CaptionJustification{\raggedright}
+\bxfigure[ht]
+{Image stacking with stacktype ``S'', stack gap set to 3pt and using: 
+(a)~\figa, (b)~\figb, (c)~\figc, and (d)~\figd\label{fg:subs}}
+{baseline\rule[-.05ex]{4ex}{.1ex}
+\stackon{(a)}{\imga}~~
+\stackunder{\imgb}{(b)}~~
+\Shortstack{{\protect\imgi} (c1) {} {\protect\imgi} (c2)}~~
+\belowbaseline[0pt]{\stackunder{\imgi}{(d)}}
+}
+Note from the definition used for figure~\ref{fg:subs}c that when a
+\vb|\savestack| has been used to place a graphic into a token
+(\textit{e.g.}, \vb|\imgi|) that it must be protected when used inside
+a space-separated argument, such as \vb|\Shortstack|,
+\vb|\Longstack|, and the corresponding understacks.
+
+\section{Nested Stacking Commands}
+
+The macros \vb|\Shortstack|, \vb|\Longstack|, and the corresponding
+understack macros are set up to conveniently stack multiple objects
+using a space separated argument list.  There may, however, be times
+that you would prefer building stacks by way of nesting the more
+primative stacking macros.
+
+Nesting can be accomplished, but some care must be taken, in the case of
+long stacks.  But first, let us see the ways in which nesting may be
+applied for short stacks:
+
+\def\stacktype{S}\Sstackgap=3pt
+\vb|\stackunder{1}{\stackunder{2}{\stackunder{3}{\stackunder{4}{5}}}}|\\
+\vb|\stackunder{\stackunder{\stackunder{\stackunder{1}{2}}{3}}{4}}{5}|\\
+\vb|\stackon{1}{\stackon{2}{\stackon{3}{\stackon{4}{5}}}}|\\
+\vb|\stackon{\stackon{\stackon{\stackon{1}{2}}{3}}{4}}{5}|
+
+will produce the following: 
+\stackunder{1}{\stackunder{2}{\stackunder{3}{\stackunder{4}{5}}}}
+\stackunder{\stackunder{\stackunder{\stackunder{1}{2}}{3}}{4}}{5}
+\stackon{1}{\stackon{2}{\stackon{3}{\stackon{4}{5}}}}
+\stackon{\stackon{\stackon{\stackon{1}{2}}{3}}{4}}{5}
+
+In these cases, the nesting could be applied on either the first or the
+second argument of the \vb|\stackunder| or \vb|\stackon| commands,
+with the same end result.
+
+In the case of long stacks however, employing the identical methodology
+gives a different, at first unexpected, result:
+\def\stacktype{L}\Lstackgap=\baselineskip
+\stackunder{1}{\stackunder{2}{\stackunder{3}{\stackunder{4}{5}}}}
+\stackunder{\stackunder{\stackunder{\stackunder{1}{2}}{3}}{4}}{5}
+\stackon{1}{\stackon{2}{\stackon{3}{\stackon{4}{5}}}}
+\stackon{\stackon{\stackon{\stackon{1}{2}}{3}}{4}}{5}
+
+In this case, nesting the second argument works as hoped, but nesting
+the first argument does not.  The reason for this ``failure'' stems
+not from a failure of logic, but an enforcement of it.  It stems from the
+very definition of a long stack, in which the baseline of the second
+argument is placed \vb|\LStackgap| below or above the baseline of the
+first argument.  By nesting the first argument, all the second arguments
+are placed \vb|\Lstackgap| from the unchanging stack baseline (thus
+overlapping), and not relative to the current top or bottom of the
+nested stack.
+
+Therefore, to nest long stacks, only the second argument of the
+stackengine may be nested.
+
+\section{Math Mode Usage\label{s:mm}}
+\def\useanchorwidth{F}
+\Sstackgap=1pt\def\stacktype{S} 
+
+The \textsf{stackengine} package is not really intended 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.
+
+%SAVE FOR FUTURE USE
+\begin{verbbox}[]
+\savestack{\a}{\(\sqrt{a + b}\)}
+\savestack{\dash}{- - - - -}
+\(y = \stackunder{\stackon{\dash}{\a}}{$b$} x\)
+\end{verbbox}
+
+\begin{enumerate}
+
+\item Stacking commands from this package can be used in math mode, but will
+set their arguments as text, not math.
+
+\vb|\( y = \stackunder{a}{+} x\)|:\hfill
+\( y = \stackunder{a}{+} x\)
+
+\item To set an argument in math, it must be set between math
+delimiters.
+
+\vb|\( y = \stackunder{\(a\)}{+} x\)|:\hfill
+\( y = \stackunder{\(a\)}{+} x\)
+
+\item Each space-separated item of the argument to \vb|\Shortstack|,
+\vb|\Longstack|, and the corresponding understacks must each be
+enclosed in their own set of dollar-sign math delimiters (Because of the
+way the argument is parsed, the \vb|\(| and \vb|\[| delimiters can
+not be used for 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).
+
+\theverbbox:\hfill
+\savestack{\a}{\(\sqrt{a + b}\)}
+\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{Acknowledgements}
+
+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:\\
+http://tex.stackexchange.com/questions/42318/\\
+removing-a-backslash-from-a-character-sequence
+
+\section{Code Listing}
+
+\verbfilenobox[\footnotesize]{stackengine.sty}
+
+\end{document}
+
+
+