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