summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/stackengine
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-07-11 23:26:05 +0000
committerKarl Berry <karl@freefriends.org>2013-07-11 23:26:05 +0000
commit1407e4e5ea60e9d4e79a57bca0c2f248f6e9de9a (patch)
treebeb13dc96321878b8635c0c02539fa663807fc70 /Master/texmf-dist/doc/latex/stackengine
parent2da7d143a3c5fa97ad562e2acfc3e487d53598d1 (diff)
stackengine (11jul13)
git-svn-id: svn://tug.org/texlive/trunk@31168 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/stackengine')
-rw-r--r--Master/texmf-dist/doc/latex/stackengine/README6
-rw-r--r--Master/texmf-dist/doc/latex/stackengine/stackengine.pdfbin282764 -> 285306 bytes
-rw-r--r--Master/texmf-dist/doc/latex/stackengine/stackengine.tex443
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
Binary files differ
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}