summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/stackengine
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-09-12 23:16:05 +0000
committerKarl Berry <karl@freefriends.org>2013-09-12 23:16:05 +0000
commit3ce8f395f1980ebc8f4e95d66e79ac7f29f99222 (patch)
tree8fd77a6b66bf5ad07a125f812dc52cfb75d3effe /Master/texmf-dist/doc/latex/stackengine
parent1e5cfa8d8b476492b05fa4fa3c01b565dde35783 (diff)
stackengine (12sep13)
git-svn-id: svn://tug.org/texlive/trunk@31637 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/stackengine')
-rw-r--r--Master/texmf-dist/doc/latex/stackengine/stackengine.pdfbin301186 -> 317215 bytes
-rw-r--r--Master/texmf-dist/doc/latex/stackengine/stackengine.tex424
2 files changed, 316 insertions, 108 deletions
diff --git a/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf b/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf
index 07332673858..0c7772aead6 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 2a7173a334b..7aeacf2b2bc 100644
--- a/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
+++ b/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
@@ -1,4 +1,5 @@
\documentclass{article}
+\usepackage{fixltx2e}
\usepackage{scalerel}
\usepackage{stackengine}
\usepackage{verbatimbox}
@@ -13,7 +14,7 @@
% FOR CLOSE-BOXING ARGUMENTS
\fboxsep=0pt\fboxrule=.6pt
-\def\rl{\protect\rule[-.3pt]{2ex}{.6pt}}
+\def\rl{\rule[-.3pt]{2ex}{.6pt}}
\def\ste{\textsf{stackengine}}
\def\bs{\texttt{\char'134}}
\let\vb\verb
@@ -41,7 +42,7 @@ steven.b.segletes.civ@mail.mil\\
\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.
+existing V1.0 stackengine code. See \S\ref{s:bc} for details.
\rmfamily%
\section{Definitions and Terms}
@@ -50,7 +51,7 @@ 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}
+\strutshortanchors{T}
\def\stacktype{L}
\Huge\setstackgap{S}{.4ex}
\setstackgap{L}{2.2ex}\normalsize
@@ -147,10 +148,10 @@ The {\ste} package defaults to center alignment, unless reset by way of
the \vb|\stackalignment| definition.
-\section{Defaults and Macros Provided by \ste}
+\section{Parameter Defaults, Modes, and Macros Provided by \ste}
-\subsection{Defaults and How to Set Them}
+\subsection{Parameter Defaults and How to Set Them}
There are several macros that serve to store package default
definitions. When a stacking macro does NOT explicitly ask for one of the
@@ -167,11 +168,14 @@ long stacks. Those stackgaps are actually stored in the \vb|\def|'s
\vb|\Sstackgap|\\
\vb|\Lstackgap|
-The parameter \vb|\Sstackgap| is the default inter-item gap for any
+The
+\margcmd{Sstackgap}\margcmd{Lstackgap}%
+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|. To change these defaults, the following macro is
+\vb|\baselineskip|. To change these defaults
+\margcmd{setstackgap}, the following macro is
provided:
\itshape
@@ -179,13 +183,10 @@ provided:
\vb|\setstackgap{L}{|inter-item baselineskip\vb|}|
\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
+In \margcmd{stackgap}addition, there is the \vb|\stackgap| macro, which
+may be invoked by the user. This macro 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
@@ -197,61 +198,101 @@ with a \vb|\def| (or a \vb|\renewcommand|), are
\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}|
+\vb|\def\stacktype{S| or \vb|L}|
\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
+The parameter \vb|\stackalignment| \margcmd{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| \margcmd{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|\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
+The parameter \vb|\useanchorwidth| \margcmd{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| \margcmd{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 that require explicit specification of some of these
parameters, the parameter token itself (\textit{e.g.},
\cmd{stackalignment}, \cmd{quietstack}, \textit{etc.}) may be provided
as the argument, if the default behavior is desired.
-In addition to the parameters mentioned above, there are two mode
+\subsection{Stacking Modes\label{s:sm}}
+
+In addition to parameter definitions, there are several {\ste} mode
settings:
\itshape
\vb|\stackMath|\\
-\vb|\stackText|
+\vb|\stackText|\\
+\vb|\strutlongstacks{T| or \vb|F}|\\
+\vb|\strutshortanchors{T| or \vb|F}|\\
+\vb|\setstackEOL{|end-of-line character\vb|}|
\upshape
By default, this package will assume that the arguments of the stacking
-commands are text. However, an invocation of \vb|\stackMath| will
+commands are text. However, an invocation of \vb|\stackMath|
+\margcmd{stackMath}will
change the default so that {\ste} arguments will be processed in inline
math mode (so-called \vb|\textstyle| math). Likewise, an invocation
-of \vb|\stackText| will reset the default processing of arguments to
-text mode. Note that these two mode-setting commands are not themselves
-to be part of a {\ste} argument, but are to be issued as separate
-commands prior to a desired stacking macro.
+of \vb|\stackText|
+\margcmd{stackText}will reset the default processing of arguments to
+text mode.
+
+By default, stacks made by {\ste} are set in unframed boxes that are
+flush with the top and bottom of the stack. The \vb|\addstackgap|
+macro (\S\ref{s:asg}) is one way to add a buffer space above and below a stack.
+Such an approach makes more sense for short stacks, where a constant
+buffer size determines the gap between objects. But for long stacks, a
+method invoving \vb|\strut|'s makes more sense. The mode
+\vb|\strutlongstacks|
+\margcmd{strutlongstacks}, when set true (\vb|T|), will automatically
+cause {\ste} to condition each row of a long stack with a \vb|\strut|
+during its construction (see \S\ref{s:ag} for more details).
+
+The \vb|\strutshortanchors|
+\margcmd{strutshortanchors}macro (\S\ref{s:sa}) is used to set the mode of how
+two items may be vertically combined into a split short-stack anchor.
+By default true (\vb|T|), a split short-stack anchor is set so that the
+middle of the stack gap falls halfway up the height of the \vb|\strut|.
+This will give the short-stack anchor the appearance of being split
+relative to text that sits atop the baseline. When set false, however,
+any short-stack anchor that is constucted has its gap split across the
+baseline itself.
+
+Until V3.1 of \ste, the \vb|\Longstack|, \vb|\Shortstack|,
+\vb|\Longunderstack|, and \vb|\Shortunderstack| macros used,
+exclusively, space tokens as the end-of-line seperators between
+rows of these stacks. Not only is such a syntax atypical of \LaTeX{},
+but it can be inconvenient when the items within a stack row
+also contain spaces. The \vb|\setstackEOL|
+\margcmd{setstackEOL}macro allows the end-of-line (EOL)
+character to be defined to a more convenient setting, such as \vb|\\|,
+though any charcter will work. There is a package option
+\vb|[usestackEOL]| \margtt{[usestackEOL]\rmfamily\\\raggedleft package
+option} which sets the end-of-line symbol to be used when parsing stack
+arguments to \vb|\\|. When the stacking EOL is something other than a
+space token, leading and trailing spaces are ignored in the row data for
+the four cited stacking commands.
+
+Note that these five mode-setting commands are not themselves parameters
+to be part of a {\ste} argument, but are instead to be issued as separate
+commands prior to the invocation of a desired stacking macro.
\subsection{Stacking Macros}
@@ -319,6 +360,7 @@ 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}
+\vspace{-0.8ex}
\subsubsection{\cmd{stackon} and \cmd{stackunder}}
@@ -341,13 +383,14 @@ an optional argument.
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.
+stacked above or below it is the second mandatory argument.\vspace{-0.8ex}
\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:
+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, by default, in a space-separated list, as
+follows:
\itshape
\vb|\Shortstack[|alignment%
@@ -374,7 +417,9 @@ 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 \vb|\Shortstack| and \vb|\Longstack| may need to be
-\vb|\protect|'ed.\mdseries
+\vb|\protect|'ed. \mdseries Better still, using the \textsf{fixltx2e} package
+eliminates the need to protect things like \vb|\rule|, \vb|\usebox|,
+\textit{etc}.
The alignment may be specified as an optional argument, with other
parameters taken by their defaults. The stacklength is taken as
@@ -396,6 +441,22 @@ yielding
\Shortunderstack[c]{{\alpha} {\beta} {\gamma}}.
\stackText
+As of V3.1 of \ste, the user may define the the argument to
+\vb|\Longstack|, \vb|\Shortstack|, \vb|\Longunderstack|, and
+\vb|\Shortunderstack| with a row separator different than a space.
+The \vb|[usestackEOL]| package option will make the EOL character within
+these stacking commands a \vb|\\| character instead of a space. Here
+are an example of equivalent stack arguments for two different EOL
+characters:
+
+Space EOL:~~~~\vb|{a {b c} {\P} $\beta^2$ ANCHOR}|\\
+\vb|\\| EOL:~~~~~~~~\,\vb|{a\\b c\\ \P\\ $\beta^2$ \\ANCHOR}|
+
+Note that leading and trailing spaces are ignored for rows in the second
+case. The \vb|\setstackEOL| macro allows any arbitrary character to be
+set as the ``EOL'' character (for the purposes of parsing these
+stacking macros).
+
\subsubsection{\cmd{Shortunderstack} and \cmd{Longunderstack}}
The \vb|\Shortunderstack| and \vb|\Longunderstack| commands are the
@@ -429,7 +490,7 @@ the baseline.
\subsubsection{Top and bottom lapping macros\label{s:lapdef}}
-\tclap{Top}and \bclap{bottom}~lapping is achievable through the creation of various
+\tclap{\smash{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
@@ -458,6 +519,7 @@ macros have been introduced:
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.
+\vspace{-0.8ex}
\subsubsection{\cmd{stackanchor}}
@@ -478,9 +540,9 @@ 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'').
+\vb|\strutshortanchors{}| mode setting will determine whether the split
+occurs at the mid-height of the strutbox (``T'') or whether it will
+occur about the baseline (``F'').
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)
@@ -513,38 +575,103 @@ 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}}
+\subsubsection{\cmd{stackinset}\label{s:iis}}
-The macros \vb|\topinset| and \vb|\bottominset| are for insetting
-smaller items (\textit{e.g.}, images) inside of a larger background
+The macro \vb|\stackinset| is for insetting
+smaller items (\textit{e.g.}, images or text) 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|\stackinset{|H-align%
+ \vb|}{|H-offset%
+ \vb|}{|V-align%
\vb|}{|V-offset%
- \vb|}{|H-offset\vb|}|
+ \vb|}{|inset item%
+ \vb|}{|anchor item\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
+In addition to providing the inset and background items as the last two
+arguments, the inset may be vertically and horizontally offset relative
+to various references. The first argument \textit{H-align}, is either
+an \vb|l|, \vb|c|, or \vb|r|, indicating whether the horizontal offset
+is relative to the left, center, or right of the anchor. The second
+argument is a length corresponding to the actual horizontal offset,
+relative to the horizontal alignment. For \vb|l| and \vb|c| alignments,
+a positive horizontal offset is rightward, whereas it is leftward for
+a \vb|r| alignment.
+
+In the case of vertical measures, the third argument, \textit{V-align},
+can have values of \vb|t|, \vb|c|, or \vb|b|, corresponding to top,
+center, and bottom, respectively. The fourth argument is a length
+corresponding to the vertical offset from the alignment location.
+For \vb|b| and \vb|c| alignments, a positive vertical offset is upward,
+whereas it is downward for a \vb|t| alignment.
+
+For horizontal and vertical offsets, negative lengths are allowed.
+However, this macro is always executed with the \vb|\usestackanchor|
+parameter set as true (meaning that the resultant stack will be the
+horizontal size of the anchor, even if the inset spills outside of it).
+
+While this command was designed with inlaid images in mind (see
+\S\ref{s:ii}), there is nothing that prevents its 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}|.
+\stackinset{c}{}{c}{-.25ex}{*}{O}, accomplished with
+\vb|\stackinset{c}{}{c}{-.25ex}{*}{O}|.
+
+\subsubsection{\cmd{addstackgap}\label{s:asg}}
+\def\stacktype{S}
+
+The \vb|\addstackgap| macro provides a user-requested feature to add a
+specified gap above and below an object. The syntax is
+
+\itshape
+ \vb|\addstackgap[|%
+ stackgap%
+ \vb|]{|%
+ item%
+ \vb|}|
+\upshape
+
+When a stack is otherwise created, it by default will vertically extend
+from the top of the top-most item in the stack to the bottom of the
+bottom-most item in the stack, but with no extra gap applied. Depending
+on how the user employs that stack, there may not be enough vertical gap
+between the stack and its adjacent objects. This macro will apply a
+fixed gaplength (either specified or, by default, an amount given by
+\vb|\Sstackgap|) above and below the argument of the macro. Negative
+gaps will have no effect on the vertical extent of the item.
+
+Here's an example a stack, before and after an \vb|\addstackgap| is
+applied, framed for clarity:
+\vb|\stackon{g}{a}|: \fbox{\stackon{g}{a}} versus
+\vb|\addstackgap{\stackon{g}{a}}| \fbox{\addstackgap{\stackon{g}{a}}}.
+This macro provides a slightly different result than the
+\vb|\strutlongstacks| mode descirbed in \S\ref{s:sm}. For more details
+of the comparison, see \S\ref{s:ag}.
+
+\subsubsection{\cmd{hsmash}}
+\def\stacktype{L}
+
+The macro \vb|\hsmash| is a horizontal version of the popular
+\vb|\smash| macro:
+
+\itshape
+ \vb|\hsmash{|item\vb|}|
+\upshape
+
+In this case, the result is centered over its zero-width anchor
+position. If one wanted left or right aligned versions of this macro,
+the existing \LaTeX{} macros \vb|\rlap| and \vb|\llap| would suffice.
+
+The primary utility of this macro is in applying \vb|\hsmash| to an
+object (often wider than the \vb|\textwidth|), in order to extend the
+object into the margins in a controllable manner, such as in the case of
+these items below:
+
+{\centering\hsmash{\fbox{\stackon[3pt]{%
+ \rule{1.1\textwidth}{.1ex}}{wide object}}}\par}
+\hsmash{\rule{5ex}{1ex}}\hfill\hsmash{\rule{2ex}{0ex}\rule{5em}{1ex}}
\subsubsection{\cmd{savestack}}
@@ -683,7 +810,7 @@ containing the verbatim text ``\tcl,'' created with the
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}.
+remember. See \S\ref{s:lapdef}.\vspace{-1ex}
\section{Shifting the Anchor's Baseline}
@@ -741,11 +868,10 @@ middle of parentheses, were they located on the original baseline.
\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.
+height, but rather at the baseline, the \vb|\strutshortanchors{F}| mode
+may be set prior to the \vb|\stackanchor| invocation.
-\def\usestackstrut{F}%
+\strutshortanchors{F}%
\Large
\blmark\rl\rl%
\def\stackalignment{l}%
@@ -755,15 +881,16 @@ invocation.
\rl\rl\blmark
\def\stackalignment{c}%
\normalsize%
-\def\usestackstrut{T}%
+\strutshortanchors{T}%
-The \vb|\usestackstrut| parameter will only affect short stacks
+The \vb|\strutshortanchors| mode will only affect short stacks
(\vb|\stacktype| ``S''), since long stacks do not use a strut as part
of the \vb|\stackanchor| definition.
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|.
+then, finally, shift the anchor by applying \vb|\stackanchor| to these
+two ``substacks.''
\Large
\setstackgap{S}{1ex}%
@@ -852,9 +979,9 @@ A negative gap can be used to overlap things. For example, \newdot plus
~\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
+actually very similar to the \vb|\stackinset| macro described in
\S\ref{s:iis} and \S\ref{s:ii}. The issue of negative stackgaps is also
-discussed in section~\ref{s:bbl}.
+discussed in \S\ref{s:bbl}.
\section{The {\cmd{useanchorwidth}} Option\label{s:uaw}}
\setstackgap{S}{-1.2pt}
@@ -881,30 +1008,81 @@ stack when \vb|\useanchorwidth| is defined as ``T''.
\def\useanchorwidth{F}
\fboxrule=0.6pt
+\section{Adding Gap Above and Below a Stack\label{s:ag}}
+\setstackgap{L}{\baselineskip}
+
+By default, a stack is vertically clipped with no gap as in these
+two \vb|\Longstack| examples:
+\fbox{\Longstack{A G}}
+\fbox{\Longstack{a g}}
+
+This package provides two ways to conveniently add gaps above and below
+a stack. For any type of stack (short or long), the \vb|\addstackgap|
+macro (\S\ref{s:asg}) adds a fixed amount of gap above and below a
+completed object. Alternately, during the construction of long stacks,
+the \vb|\strutlongstacks| mode (\S\ref{s:sm}) will automatically employ
+struts in each row of a long stack during its construction. However,
+these two approaches are not equivalent:
+
+\vb|\addstackgap[3pt]{}|:
+\fbox{\addstackgap[3pt]{\Longstack{A G}}}
+\fbox{\addstackgap[3pt]{\Longstack{a g}}}
+~~~~\vb|\strutlongstacks{T}|:
+\strutlongstacks{T}
+\fbox{\Longstack{A G}}
+\fbox{\Longstack{a g}}
+\strutlongstacks{F}
+
+Make sure you use the one that best applies to your situation.
+
\section{Image Insets\label{s:ii}}
+\setstackgap{L}{18pt}%
-The commands \vb|\topinset| and \vb|\bottominset| allow images to be
+The command \vb|\stackinset| allows 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}}
-\def\stackalignment{r}
-\savestack{\imga}{\topinset{\imgii}{\imgi}{2pt}{3pt}}
-\def\stackalignment{l}
-\savestack{\imgb}{\bottominset{\imgii}{\imgi}{2pt}{3pt}}
+\savestack{\imga}{\stackinset{r}{3pt}{t}{2pt}{\imgii}{\imgi}}
+\savestack{\imgb}{\stackinset{l}{3pt}{b}{2pt}{\imgii}{\imgi}}
\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
-\vb|\bottominset{\imgii}{\imgi}{2pt}{3pt}|,
+\vb|\stackinset{l}{3pt}{b}{2pt}{\imgii}{\imgi}|,
showing that \vb|\imgii| was offset 2pt from the bottom and 3pt from
the left edge of \vb|\imgi|.
+The syntax of \vb|\stackinset| allows for a convenient nesting of
+figure text labels. For example,
+
+\begin{verbatim}
+\stackinset{l}{ .1in}{b}{.2in}{Note 1}{%
+\stackinset{r}{ .1in}{t}{.2in}{Note 2}{%
+\stackinset{c}{-.5in}{c}{.4in}{Note 3}{%
+\stackinset{r}{ .8in}{b}{.6in}{Note 4}{%
+\stackinset{r}{ .1in}{c}{.0in}{\imgi}{%
+\includegraphics[width=3in]{example-image}%
+}}}}}
+\end{verbatim}
+
+gives the following result:\begin{verbbox}[\small]\stackinset\end{verbbox}
+
+\bxfigure[ht]
+{An example of \theverbbox}
+{%
+\stackinset{l}{ .1in}{b}{.2in}{Note 1}{%
+\stackinset{r}{ .1in}{t}{.2in}{Note 2}{%
+\stackinset{c}{-.5in}{c}{.4in}{Note 3}{%
+\stackinset{r}{ .8in}{b}{.6in}{Note 4}{%
+\stackinset{r}{ .1in}{c}{.0in}{\imgi}{%
+\includegraphics[width=3.0in]{example-image}%
+}}}}}%
+}
+
+\clearpage
\section{Stacking for Subfiguring and Baseline Manipulation}
The stacking commands provide a convenient way to underset a subfigure
@@ -913,13 +1091,20 @@ 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}.
+Examples of this are shown in figure~\ref{fg:subs}.
+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 (If the
+\textsf{fixltx2e} package is used, the need to \vb|\protect| may be
+alleviated).
%
\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)}
+\Shortstack{{\imgi} (c1) {} {\imgi} (c2)}
\end{myverbbox}%
\begin{myverbbox}%
{\figd}\belowbaseline[0pt]{\stackunder{\imgi}{(d)}}\end{myverbbox}%
@@ -933,11 +1118,6 @@ Examples of this are shown in figure~\ref{fg:subs}.
\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.
\clearpage
\section{Nested Stacking Commands}
@@ -1076,6 +1256,31 @@ stack).
\end{enumerate}
+\section{Deprecated Features}
+
+There are several definitions and macros from earlier versions of the
+{\ste} package that are still fully functional, but are discouraged
+because of more preferable alternatives. They have been omitted from the
+current documentation, except for mention here. They are:
+
+\begin{itemize}
+\item \vb|\def\usestackstrut{T/F}|. This definition is fully replaced
+by the mode setting given by the \vb|\strutshortanchors{T/F}| macro.
+The new name is less ambiguous and the macro form is chosen vis-\`a-vis
+the \vb|\def| form, because the macro represents a \textbf{mode} of
+stack construction, rather than an argument parameter.
+
+\item \vb|\bottominset| and \vb|\topinset|. These
+macros are subsumed by the much more versatile \vb|\stackinset| macro.
+The replacement offers insets relative to not only the top and bottom,
+but also the mid-height of the anchor. It also provides the capability
+to horizontally place the inset relative to the center of the anchor,
+in addition to the left or the right. Most importantly, the placement
+of the anchor as the last argument of \vb|\stackinset| means that the
+syntax for nested insets is much more readable vis-\`a-vis the nested
+syntax for \vb|\bottominset| and \vb|\topinset|.
+\end{itemize}
+
\section{Backward Compatibility\label{s:bc}}
The author of this package profoundly apologizes for the fact that the
@@ -1112,7 +1317,7 @@ 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, \vb|[oldsyntax]| usage needs to be
-relegated.
+relegated.\vspace{-1.5ex}
\section{Acknowledgements}
@@ -1127,6 +1332,9 @@ transition from the deficient V1.0 syntax as painless as possible:\\
\vb|http://tex.stackexchange.com/questions/123443/|\\
\vb|defining-a-length-that-scales-with-fontsize-changes/123470#123470|
+Thanks also to Dr. David Carlisle for explaining the need for argument
+expansion in certain situations.
+
\section{Code Listing}
\verbfilenobox[\footnotesize]{stackengine.sty}