stackengine (11jul13)

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

3 files changed, 273 insertions, 176 deletions

diff --git a/Master/texmf-dist/doc/latex/stackengine/README b/Master/texmf-dist/doc/latex/stackengine/README
index 9609ff53238..a7806393faa 100644
--- a/Master/texmf-dist/doc/latex/stackengine/README
+++ b/Master/texmf-dist/doc/latex/stackengine/README
@@ -13,11 +13,13 @@ macros allow a wide variety of tasks, including:
 
 -insetting graphical images atop larger background images; 
 
--top and bottom lapping; shifting the horizontal axis of a stack;
+-top and bottom lapping; 
+
+-shifting the horizontal axis of a stack;
 
 -changing the baseline of an object; 
 
--subfigure labeling;
+-subfigure stacking and 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
index fbdfe740062..8c29f3bd471 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 d320db28792..f11d23b691d 100644
--- a/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
+++ b/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
@@ -1,5 +1,4 @@
 \documentclass{article}
-\def\version{1.0}
 \usepackage{scalerel}
 \usepackage{stackengine}
 \usepackage{verbatimbox}
@@ -7,14 +6,14 @@
 \parindent 0in\parskip 1em
 \newlength\dotscale
 
-\dotscale=.4ex         % DOTSIZE<---CAN CHANGE THESE
+\setlength{\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
+\fboxsep=0pt\fboxrule=.6pt
 
-\newcommand\rl{\rule{2em}{0in}}
+\def\rl{\protect\rule[-.3pt]{2ex}{.6pt}}
 \def\ste{\textsf{stackengine}}
 \def\bs{\texttt{\char'134}}
 \let\vb\verb
@@ -24,6 +23,7 @@
 \newcommand\margcmd[1]{\marginpar{\hfill\ttfamily\char'134#1}}
 \newcommand\cmd[1]{\texttt{\char'134#1}}
 \def\lapmark{\rule[-.3\baselineskip]{.1ex}{\baselineskip}}
+\def\blmark{\rl\stackengine{-.9ex}{B}{\rule{.35ex}{0pt}L}{U}{l}{F}{T}{S}\rl}
 
 \begin{document}
 
@@ -34,11 +34,16 @@ 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
+\stackengineversionnumber
 \end{center}
 
 %\tableofcontents
 
+\sffamily%
+Note: A syntax change in version 2.0 may require minor changes in your
+existing V1.0 stackengine code.  See section~\ref{s:bc} for details.
+\rmfamily%
+
 \section{Definitions and Terms}
 
 Before I describe the various commands of this package, it is best for
@@ -47,10 +52,11 @@ 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 
+\Huge\setstackgap{S}{.4ex}
+\setstackgap{L}{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
+glyphs comprising 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.
@@ -62,23 +68,35 @@ Notice the consistent inter-item gap on a short stack:
 \normalsize
 
 Notice the consistent inter-baseline spacing on a long stack: 
-\def\rl{\protect\rule[-.05pt]{1ex}{.1pt}}\Huge
+\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.
+In this package, the default spacing (\textit{i.e.}, stacklength) for
+the long stack, saved in the length \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
+this package is short, denoted by the definition of \vb|\stacktype| as
+``S'' (as opposed to ``L'' for long stacks).  These defaults can be
+changed.
+
+\subsection{Baseline}
+\setstackgap{L}{.8\baselineskip}
+\setstackgap{S}{4pt}
+
+The baseline is the horizontal line on which the current (unstacked)
+text is set.  For non-descending letters, the bottom of the letters sit
+upon the baseline.  In this document, we will graphically use the symbol
+{\blmark} to denote the current baseline of the text, as in
+
+\blmark\rl\Shortunderstack{A B C}\rl\rl text continues here
 
 \subsection{(Over)Stacks and Understacks}
 
-\Lstackgap=.8\baselineskip
-\Sstackgap=4pt
+\setstackgap{L}{.8\baselineskip}
+\setstackgap{S}{4pt}
 In general terms, a stack is built up from the baseline, while an
 understack is built down from the baseline.  
 
@@ -110,7 +128,7 @@ 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%
+\setstackgap{S}{3pt}\setstackgap{L}{12pt}%
 
 {\centering
 Left: \Shortstack[l]{abcd abc ab a}~~
@@ -132,39 +150,48 @@ the \vb|\stackalignment| definition.
 \section{Defaults and Macros Provided by \ste}
 
 
-\subsection{Defaults}
+\subsection{Defaults and How to Set Them}
 
-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
+There are several macros 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 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
 itself be provided as the argument.
 
-Let us first consider the length defaults:
+Let us first consider the stackgap defaults, associated with short and
+long stacks.  Those stackgaps are actually stored in the \verb|\def|'s
 
-\itshape
-\vb|\Sstackgap=|length\\
-\vb|\Lstackgap=|length\\
-\vb|\stackgap|
-\upshape
+\vb|\Sstackgap|\\
+\vb|\Lstackgap|
 
 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''.
+\vb|\baselineskip|.  To change these defaults, the following macro is
+provided:
+
+\itshape
+\vb|\setstackgap{S}{|inter-item stackgap\verb|}|\\
+\vb|\setstackgap{L}{|inter-item baselineskip\verb|}|
+\upshape
+
+In addition, there is another macro, which may be invoked by the user:
+
+\vb|\stackgap|
+
+The macro \vb|\stackgap| will look at the current value of
+\vb|\stacktype| and will output either \vb|\Sstackgap| or
+\vb|\LStackgap|, depending on whether \vb|\stacktype| is defined as
+``S'' (short) or ``L'' (long).
 
 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
+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
 
 \itshape
 \vb|\def\stackalignment{l| or \vb|c| or \vb|r}|\\
@@ -209,7 +236,7 @@ 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}
+\subsection{Stacking Macros}
 
 \subsubsection{\cmd{stackengine}}
 
@@ -269,7 +296,7 @@ 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 
+if \vb|\stacktype| is ``L''.  Alternately, the  same stack could be 
 forced to be a long stack with right-alignment and be typeset using
 
 \begin{verbatim}
@@ -328,14 +355,17 @@ 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.
+\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
 
-The alignment may be spacified as an optional argument, with other
+The alignment may be specified 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}|
+\vb|\Shortstack[r]{a {b c} {\P} $\beta^2$ ANCHOR}|
 will produce
 \Shortstack[r]{a {b c} {\P} $\beta^2$ ANCHOR}.
 
@@ -370,7 +400,7 @@ 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}
+\subsubsection{Top and bottom lapping macros\label{s:lapdef}}
 
 \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.
@@ -389,7 +419,18 @@ The long-stacklength may be provided as an optional argument.
 \upshape
 
 See \S\ref{s:lap} for more information and examples of use for
-these lapping commands.
+these lapping commands.  If trying to remember the names of all these
+lapping commands is too tedious for you, two functionally identical
+macros have been introduced:
+
+\itshape
+\vb|\toplap[|stacklength\vb|]{|lap H-direction\vb|}{|item\vb|}|\\
+\vb|\bottomlap[|stacklength\vb|]{|lap H-direction\vb|}{|item\vb|}|
+\upshape
+
+The names are simpler to remember, but they require, as their first
+mandatory argument, the horizontal direction of lapping (l, c, or r),
+while the material to be lapped is now in the second mandatory argument.
 
 \subsubsection{\cmd{stackanchor}}
 
@@ -414,24 +455,36 @@ If a short stack is being created with a split anchor, the
 at the mid-height of the strutbox (``T'') or whether it will occur about
 the baseline (``F'').
 
-\subsubsection{\cmd{belowbaseline}}
+If a long stack is to be created with a split anchor, it is best to
+formulate and \vb|\savestack| both the upper portion (with a stack)
+and the lower portion (with an understack), and then \vb|\stackanchor|
+the two parts together.
+
+\subsubsection{\cmd{abovebaseline} and \cmd{belowbaseline}}
 
-The macro \vb|\belowbaseline| also creates the means to shift an
-item's baseline.  The syntax is
+The macros \vb|\abovebaseline| and \vb|\belowbaseline| also creates the
+means to shift an item's baseline.  The syntax is
 
 \itshape
+\vb|\abovebaseline[|stackgap\vb|]{|item\vb|}|\\
 \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.
+will define the upward (for \vb|\abovebaseline|) or downward shift
+(for \vb|\belowbaseline|) of the baseline of the item.  In a short
+stack, it will define the upward/downward vertical gap between the
+original baseline and the bottom/top of the shifted item.
 
-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.
+For long stacks, a negative stackshift for \vb|\belowbaseline| will
+produce the same result as the corresponding positive stackshift for
+\vb|\abovebaseline|.  But this will not be the case for short stacks.
+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 a useful technique to achieve horizontal
+alignment with other objects.  Negative stack gaps are valid (see
+\S\ref{s:bbl} for examples).
 
 \subsubsection{{\cmd{topinset}} and \cmd{bottominset}\label{s:iis}}
 
@@ -481,7 +534,7 @@ 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
+Note that while \vb|\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
@@ -496,9 +549,11 @@ 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.
+intermediate stack can be passed as an argument to the next stacking
+operation with a \vb|\usebox{\stackedbox}|.  That same \vb|\usebox|
+may be used to output the final stack, as long as \vb|\quietstack|
+remains defined as ``T''.  Otherwise, \vb|\quietstack| must again be
+defined ``F'' (false) to re-enable automatic output.
 
 \subsection{Saving a Stack without Printing It\label{s:svs}}
 
@@ -524,8 +579,7 @@ 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%
-
+\rl\rl\blmark%
 
 \section{Choosing the Anchor Element}
 
@@ -536,7 +590,7 @@ 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%
+\setstackgap{S}{2pt}\setstackgap{L}{12pt}%
 Here is a Longstack/understack example:
 \savestack{\pdq}{\Longstack{3 2 1 0}}%
 \Longunderstack[r]{{\pdq} -1 -2 -3 -4 -5}
@@ -554,7 +608,7 @@ anchor of the composite stack).
 \section{Top and Bottom Lapping\label{s:lap}}
 \def\stackalignment{c}
 \def\stacktype{L}%
-\Lstackgap=\baselineskip
+\setstackgap{L}{\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,
@@ -566,8 +620,8 @@ 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.
+(given by \lapmark~), defining the point of invocation.  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}
@@ -593,9 +647,16 @@ 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}}}|
+\vb|\tclap{\fbox{\parbox[b]{1.1in}{this is a top-center lap \tcl}}}|
 
-in the middle of the word ``well.''
+in the middle of the word ``well.''  (Note that \vb|\tcl| is a box
+containing the verbatim text ``\tcl,'' created with the
+\textsf{verbatimbox} package.)
+
+Note that \vb|\toplap| and \vb|\bottomlap| have also been introduced
+as macros that are functionally identical to these six lapping commands.
+While requiring an extra argument, their names may be easier for you to
+remember.  See section~\ref{s:lapdef}.
 
 \section{Shifting the Anchor's Baseline} 
 
@@ -624,14 +685,13 @@ items comprising the stacked anchor.
 \def\stacktype{L}%
 
 \Large
-\def\rl{\rule[-.05pt]{2ex}{.1pt}}
 \def\stackalignment{r}%
-\Lstackgap=.8\baselineskip%
-Baseline%
+\setstackgap{L}{.8\baselineskip}%
+\blmark%
 \rl\rl
 \stackanchor{\rl\rl\rl\rl top\rl}{\rl L-bottom\rl}%
 \rl\rl%
-Baseline
+\blmark
 \normalsize
 
 In the case of a short stack, the middle of the inter-item gap is
@@ -640,16 +700,16 @@ 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%
+\blmark\rl\rl%
 \def\rls{\rule[.5\ht\strutbox-.5\dp\strutbox]{2ex}{.1pt}}%
 \rls%
 \def\stackalignment{l}%
-\def\stacktype{S}\Sstackgap=1ex%
+\def\stacktype{S}\setstackgap{S}{1ex}%
 \savestack{\pdq}{\stackanchor{\fbox{top}}{\fbox{S-bottom}}}%
 \pdq%
 \rls%
 (Mid-strut)%
-\rl\rl Baseline
+\rl\rl\blmark
 \def\stackalignment{c}%
 \normalsize%
 
@@ -660,12 +720,12 @@ invocation.
 
 \def\usestackstrut{F}%
 \Large
-Baseline\rl\rl%
+\blmark\rl\rl%
 \def\stackalignment{l}%
 \def\stacktype{S}%
 \savestack{\pdq}{\stackanchor{\fbox{top}}{\fbox{S-bottom}}}%
 \pdq%
-\rl\rl Baseline
+\rl\rl\blmark
 \def\stackalignment{c}%
 \normalsize%
 \def\usestackstrut{T}%
@@ -674,104 +734,91 @@ 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.
+For stackanchors with more than two rows, one should compose the top
+portion with a stack and the bottom portion with an understack, and
+then, finally, shift the anchor by applying \vb|\stackanchor|.
 
 \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)
+\setstackgap{S}{1ex}%
+\savestack{\upperstack}{\Shortstack{{over text} {\fbox{top}}}}
+\savestack{\lowerstack}{\Shortstack{{\fbox{S-bottom}} {under text}}}
+\blmark\rl\rl\rls%
+\stackanchor{\upperstack}{\lowerstack}%
+\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 \vb|\belowbaseline| is intended to be used to set an item,
+such as a stack anchor, below the baseline (this discussion is equally
+valid for the macro \vb|\abovebaseline|, but in the opposite sense).
+The macro accomplishes this task by stacking the item below a null
+object.  However, \vb|\useanchorwidth| is temporarily 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%
+\Large
+\setstackgap{S}{6pt}%
 \def\stacktype{S}%
 Short stacktype\rl\rl\belowbaseline[0pt]{\fbox{0pt below baseline}}%
-\rl\belowbaseline{\fbox{6pt}}\rl\rl
+\rl\belowbaseline{\fbox{6pt}}\rl\belowbaseline[-6pt]{\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%
+\Large
+\setstackgap{L}{18pt}%
 \def\stacktype{L}%
 Long stacktype\rl\rl\belowbaseline[0pt]{\fbox{0pt below baseline}}%
-\rl\belowbaseline{\fbox{18pt}}\rl\rl
+\rl\belowbaseline{\fbox{18pt}}\rl\belowbaseline[-19pt]{\fbox{-18pt}}\rl
+\normalsize
+
+As the above images show, there is nothing to prevent the use of
+negative numbers being used to raise the the object above the baseline.
+But care must be taken, since a \vb|\belowbaseline| with a negative
+shift will not necessarily equal the \vb|\abovebaseline| with the
+corresponding positive shift (that equality only holds for long stacks).
+To better appreciate the meaning of negative baseline shifts, we
+compare, below, negative shifts for \vb|\belowbaseline| to
+\vb|\abovebaseline| with the corresponding positive argument.
+
+\Large
+\def\stacktype{S}%
+Short stacktype\rl\rl\belowbaseline[-6pt]{\fbox{-6pt below}}%
+\rl\abovebaseline[6pt]{\fbox{6pt above}}\rl\rl\blmark%
 \normalsize
 
-There is nothing to prevent the use of negative numbers being used to
-raise the the object above the baseline.
+\Large
+\def\stacktype{L}%
+Long stacktype\rl\rl\belowbaseline[-6pt]{\fbox{-6pt below}}%
+\rl\abovebaseline[6pt]{\fbox{6pt above}}\rl\rl\blmark%
+\normalsize
 
 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
+trying to achieve a desired horizontal alignment of disparate elements in
 tabular columns.
 
 \vb|\def\stacktype{S}\belowbaseline[0pt]{\imgi}|\\
-\vb|\belowbaseline[-\baselineskip]{\imgi}|:
+\vb|\belowbaseline[0pt -\heightof{\strutbox}]{\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.
+\rl\blmark\rl\rl\belowbaseline[0pt]{\imgi}\rl\rl
+\belowbaseline[0pt -\heightof{\strutbox}]{\imgi}\rl\rl%
+\fbox{\parbox[t]{1.8cm}{\raggedright A parbox with [t] alignment}}%
+\rl\rl\blmark\rl
 
 \section{Negative Stack Gap}
 \def\stacktype{S}
-\Sstackgap=-1.2pt
-\dotscale=1.ex
+\setstackgap{S}{-1.2pt}
+\setlength{\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:
 
@@ -779,11 +826,12 @@ A negative gap can be used to overlap things.  For example, \newdot plus
 
 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}.
+\S\ref{s:iis} and \S\ref{s:ii}.  The issue of negative stackgaps is also
+discussed in section~\ref{s:bbl}.
 
 \section{The {\cmd{useanchorwidth}} Option\label{s:uaw}}
-\Sstackgap=-1.2pt
-\dotscale=1.ex
+\setstackgap{S}{-1.2pt}
+\setlength{\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.
@@ -798,18 +846,20 @@ 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~
+\fboxrule=0.2pt
+\hfill 
+\scalebox{3}{th\fbox{\stackon{i}{\newdot}}s}%
+\hfill~
 \normalsize
 \def\useanchorwidth{F} 
+\fboxrule=0.6pt
 
 \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.
+The commands \vb|\topinset| and \vb|\bottominset| allow images to 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 offset of the inset image.
 
 \def\imgi{\includegraphics[width=0.87in]{example-image}}
 \def\imgii{\includegraphics[width=0.3in]{example-image}}
@@ -824,9 +874,9 @@ 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|.
+\vb|\bottominset{\imgii}{\imgi}{2pt}{3pt}|,
+showing that \vb|\imgii| was offset 2pt from the bottom and 3pt from
+the left edge of \vb|\imgi|.
 
 \section{Stacking for Subfiguring and Baseline Manipulation}
 
@@ -837,25 +887,26 @@ 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}
+%
+\setstackgap{S}{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}
+\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}
+{\blmark\rl\rl%
 \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
+}%
+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|,
@@ -865,15 +916,16 @@ a space-separated argument, such as \vb|\Shortstack|,
 
 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
+using a space separated argument list.  Because of parsing constraints
+on the space-separated list, however (see \S\ref{s:mm}), there may 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:
+applied for short stacks:\\
 
-\def\stacktype{S}\Sstackgap=3pt
+\def\stacktype{S}\setstackgap{S}{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}}}}|\\
@@ -883,7 +935,7 @@ 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}
+\stackon{\stackon{\stackon{\stackon{1}{2}}{3}}{4}}{5} \blmark
 
 In these cases, the nesting could be applied on either the first or the
 second argument of the \vb|\stackunder| or \vb|\stackon| commands,
@@ -891,11 +943,11 @@ 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
+\def\stacktype{L}\setstackgap{L}{\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}
+\stackon{\stackon{\stackon{\stackon{1}{2}}{3}}{4}}{5} \blmark
 
 In this case, nesting the second argument works as hoped, but nesting
 the first argument does not.  The reason for this ``failure'' stems
@@ -912,7 +964,7 @@ stackengine may be nested.
 
 \section{Math Mode Usage\label{s:mm}}
 \def\useanchorwidth{F}
-\Sstackgap=1pt\def\stacktype{S} 
+\setstackgap{S}{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
@@ -935,17 +987,17 @@ 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
+\item To set an argument in math style, 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|\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 be used, but
+only if \vb|\protect|'ed, in these space-separated argument lists).
 
 \vb|\(y = \Shortstack{$a$ . $b$} x\)|:\hfill
 \(y = \Shortstack{$a$ . $b$} x\)
@@ -972,13 +1024,56 @@ the math axis better with an ``S'' \vb|\stacktype|, rather than type
 
 \end{enumerate}
 
+\section{Backward Compatibility\label{s:bc}}
+
+The author of this package profoundly apologizes for the fact that the
+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|.
+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|}|  .
+\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
+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}|
+
+If you retain the ``oldsyntax'' setting, you must remember that
+\textsf{stackengine} will honor your specified 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, or better still, \verb|[oldsyntax]| usage needs to be
+relegated.
+
 \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
+\verb|http://tex.stackexchange.com/questions/42318/|\\
+\verb|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|
 
 \section{Code Listing}