path: root/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex

\documentclass{article}
\usepackage{tabstackengine}
\usepackage{verbatimbox}
\usepackage{xcolor}
 \parindent 0in\parskip 1em \newlength\dotscale


% FOR CLOSE-BOXING ARGUMENTS \fboxsep=0pt\fboxrule=.6pt
\def\rl{\rule[-.3pt]{2ex}{.6pt}} \def\tst{\textsf{tabstackengine}}
\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}}

\begin{document}

\begin{center} \LARGE The {\tst} Package\\ \rule{0em}{.7em}\small
Front-end to the {\ste} package, allowing tabbed stacking\\ \rule{0em}{2.7em}\large
Steven B. Segletes\\ steven.b.segletes.civ@mail.mil\\
\rule{0em}{1.7em}\today\\ \tabstackengineversionnumber \end{center}

\tableofcontents

\section{Introduction}

The {\tst} package provides a front end to the {\ste} package that
allows for the use of tabbing characters within the stacking arguments.
\textbf{Familiarity with the syntax of the {\ste} package is assumed.}
When invoked, {\tst} loads the {\ste} package with the
\texttt{[usestackEOL]} option set, so that the end-of-line (EOL)
character in certain stacking arguments will be taken, by default, 
as \vb|\\|, rather
than a space (which is the default EOL separator in \ste).

With \tst, command variations are introduced to allow several variants
of tabbing within the macro arguments. The default tabbing character is
the ampersand (\vb|&|); however, the tabbing character can be reset to
other values.

In most cases (where it makes sense), a {\ste} macro name may be
prepended with the word \texttt{tabbed}, \texttt{align}, or
\texttt{tabular} to create a new {\tst} macro that allows for tabbed
arguments.

\section{Tabbing Variations within \tst}

The {\tst} package syntax allows three types of tabbing variation
denoted by the words \texttt{tabbed}, \texttt{align}, and
\texttt{tabular} in the macro name itself. In the case of
\texttt{tabbed} macros, the tabbed columns all share the same alignment,
as dictated by the \vb|\stackalignment| setting or perhaps provided as
an optional argument in some macro forms.

In the case of \texttt{align} macros, the alignment in columns is
alternately specified as right, then left, \textit{etc.}, in the manner
of the \texttt{align} environment of the \textsf{amsmath} package.

Finally, in the case of \texttt{tabular} macros, an extra argument is
passed to the macro that specifies the left-center-right alignment for
each individual column, in the manner of \vb|{lccr}|.

\section{Column Spacing within \tst}

Intercolumn space can be introduced to {\tst} output in one of two ways.
\margcmd{fixTABwidth}First, there is a macro setting to force all columns to be the same 
width (namely, the width of the widest entry in the stack), using the
syntax
\vb|\fixTABwidth{T| \textit{or} \vb|F}|.
When set true, column space will be introduced to all but the widest
column of a stack, so as to make all columns of a width equal to that
of the widest column.

Secondly,\margcmd{setstacktabbedgap} 
each of the tabbing variations has the means to introduce a
fixed amount of space between columns.  By default, the \texttt{tabbed}
stacking macros add no space (\texttt{0pt}) between adjacent columns, 
but this value can be reset with the macro 
\vb|\setstacktabbedgap{|\textit{length}\vb|}|.

In\margcmd{setstackaligngap}  
the case of the \texttt{align} stacking macros, there is never any 
gap introduced after the right-aligned columns.  However, the default
gap introduced after the left-aligned columns is, by default, 
\texttt{1em} (the same gap as \cmd{quad}).  It can be reset with the 
macro \vb|\setstackaligngap{|\textit{length}\vb|}|.

For\margcmd{setstacktabulargap} 
the \texttt{tabular} stacks, the default intercolumn gap is the
value of \cmd{tabcolsep}.  The default value may be reset with the macro
\vb|\setstacktabulargap{|\textit{length}\vb|}|.

Note that these \cmd{setstack...gap} macros are for setting horizontal
gaps between columns of a stack.  They should not be confused with
the \cmd{setstackgap} macro of {\ste} that sets the vertical gap
for long and short stacks.
 
\section{Command Summary}

Below are the new commands introduced by this package.  When there are 
multiple commands delimited by braces,  any one of the commands within the
brace may be selected.

\ttfamily\footnotesize
\(\left.\Centerstack[r]{%
  \textcolor{red}{\cmd tabbed}\\\\
  \textcolor{teal}{\cmd align}\\\\
  \textcolor{blue}{\cmd tabular}
}\right\}%
\left\{
\Centerstack[c]{Shortstack\\Shortunderstack\\Longstack\\
  Longunderstack\\Centerstack\\Vectorstack}
\right\}%
\left\{\Centerstack[c]{
  \textcolor{red}{[alignment]}\\\\
  \\\\
  \textcolor{blue}{\{column alignments\}}
}\right\}\)\{tabbed EOL-separated string\}

\(\displaystyle\$\left\{\Centerstack[r]{\cmd paren\\\cmd brace\\\cmd bracket\\\cmd vert}\right\}\)%
\textcolor{red}{Matrix}stack[alignment]\{tabbed EOL-separated string\}\$

\(\left.\Centerstack[r]{
  \textcolor{red}{\cmd tabbed}\\\\
  \textcolor{teal}{\cmd align}\\\\
  \textcolor{blue}{\cmd tabular}}\right\}%
\left\{
\Centerstack[c]{stackon\\stackunder\\stackanchor}
\right\}%
\mathtt{[stack gap]}\left\{\Centerstack[l]{
\\\\
\\\\
\textcolor{blue}{\{col.\ alignments\}}
}\right\}\)\{tabbed anchor\}\{tabbbed~argument\}

\cmd setstack\(\left\{\Centerstack{
  \textcolor{red}{tabbed}\\\\
  \textcolor{teal}{align}\\\\
  \textcolor{blue}{tabular}
}\right\}\)gap\{length\}
\hspace{3em}Initial Defaults:\(\left\{\Centerstack{
  \textcolor{red}{0pt}\\\\
  \textcolor{teal}{1em}\\\\
  \textcolor{blue}{\cmd tabcolsep}
}\right\}\)

\rmfamily\normalsize

\begin{verbnobox}[\footnotesize]
\fixTABwidth{T or F}
\setstackTAB{tabbing character}
\TABunaryLeft    (\TABbinaryRight)
\TABunaryRight   (\TABbinaryLeft)
\TABbinary
\end{verbnobox}
The following macros are macros that can be used for parsing tabbed data outside of a
TABstack.
\begin{verbnobox}[\footnotesize]
\readTABrow{row ID}{tab-separated string}
\TABcell{row ID}{column number}
\TABcells{row ID}
\TABstrut{row ID}
\TABstackMath
\TABstackText
\ensureTABstackMath{}
\end{verbnobox}

\subsection{Command Examples}

Below we give examples of the various types of commands made available through
the \textsf{stackengine} package.

\subsection*{Tabbed End-of-Line (EOL)-delimited Stacks}

Here, the optional argument \verb|[l]| defines the alignment of \textit{all} the
columns.  The default alignment is \verb|[c]|.

\verb|\tabbedShortunderstack[l]{A&B&CCC\\aaa&bbb&c\\1111&2&3}|

{\small\tabbedShortunderstack[l]{A&B&CCC\\aaa&bbb&c\\1111&2&3}}

\subsection*{Align End-of-Line (EOL)-delimited Stacks}

In an \texttt{align}-stack, the column alignments will always be \verb|rlrl...|
The gap following the left-aligned columns is set by \verb|\setstackaligngap|.

\verb|\stackMath$Z:\left\{\alignCenterstack{%|\\
\verb|  y=&mx+b,&0=&Ax+By+C\\y_1=&W_1,&y_2=&W_2}\right.$|

{\small\stackMath$Z:\left\{\alignCenterstack{y=&mx+b,&0=&Ax+By+C\\y_1=&W_1,&y_2=&W_2}\right.$}

\subsection*{Tabular End-of-Line (EOL)-delimited Stacks}

In a \texttt{tabular}-stack, the alignment of each column is specified in a separate
leading argument.

\verb|\stackText\tabularLongstack{rllc}{%|\\
\verb|  9)& $y_1=mx+b$ &linear&*\\10)& $y_2=e^x$ &exponential&[23]}|

{\small\stackText\tabularLongstack{rllc}{9)& $y_1=mx+b$ &linear&*\\10)& $y_2=e^x$ &exponential&[23]}}

\subsection*{Matrix Stack}

The \texttt{Matrix}-stacks are a tabbed variant of \textsf{stackengine}'s \texttt{Vector}-stacks.

\verb|\setstacktabbedgap{1.5ex}|\\
\verb|$I = \bracketMatrixstack{1&0&0\\0&1&0\\0&0&1}$|

{\small\setstacktabbedgap{1.5ex} $I = \bracketMatrixstack{1&0&0\\0&1&0\\0&0&1}$}

\subsection*{Tabbed Stack}

This variant of a \texttt{tabbed}-stack stacks exactly two items.  
Its arguments don't need to be protected.  The optional argument is a stacking gap,
as in the syntax of the \textsf{stackengine} package.

\verb|\setstacktabbedgap{1ex}|\\
\verb|\tabbedstackon[4pt]{Jack&drove&the car&home.}{SN&V&DO&IO}|

{\small\stackText\setstacktabbedgap{1ex}\tabbedstackon[4pt]{Jack&drove&the car&home.}{SN&V&DO&IO}}

\subsection*{Align Stack}

This is for stacking two items with \texttt{rlrl...} alignment pattern.

\verb|\stackMath\setstackaligngap{3em}|\\
\verb|\alignstackunder[10pt]{y=&mx+b,&0=&Ax+By+C}{y_1=&W_1,&y_2=&W_2}|

{\small\stackMath\setstackaligngap{3em}
\alignstackunder[10pt]{y=&mx+b,&0=&Ax+By+C}{y_1=&W_1,&y_2=&W_2}}

\clearpage
\subsection*{Tabular Stack}

This is for stacking two items with specifiable alignment pattern.

\verb|\stackMath\setstacktabulargap{1ex}\tabularstackanchor[4pt]{rcl}%|\\
\verb|  {\bullet\bullet\bullet\bullet&\belowbaseline[-2pt]{\triangle}%|\\
\verb|    &\bullet\bullet\bullet\bullet}%|\\
\verb|  {1 + 3(4-3) & = & 7 - 6/2}|\vspace{1ex}

{\small\stackMath\setstacktabulargap{1ex}
\tabularstackanchor[4pt]{rcl}{\bullet\bullet\bullet&\belowbaseline[-2pt]{%
\triangle}&\bullet\bullet\bullet}{1 + 2(4-3) & = & 6 - 6/2}}

\subsection*{Fixed Tab Width (equal width columns, based on largest)}

With this mode set, the stack will have fixed-width columns, based on the overall
widest entry.

\verb|\fixTABwidth{T}\setstacktabbedgap{1ex}%|\\
\verb|$\left(\tabbedCenterstack[r]{1&34&544\\4324329&0&8\\89&123&1}\right)$|

{\small\setstacktabbedgap{1ex}\fixTABwidth{T}$\left(\tabbedCenterstack[r]{1&34&544\\4324329&0&8\\89&123&1}\right)$}

\subsection*{Setting the Stack Tabbing Character}

By default, for the parsing of columns within a row, this package employs the \verb|&| character to delimit the
columns.  This value can be changed via \verb|\setstackTAB{}|, where the argument is the
newly desired tabbing character.  It can be any of various characters, including  a space token, 
if one wishes to use a space-separated
list to parse the columns.  Generally, it may need to be changed if you are building a TABstack
inside of an environment that already uses the \verb|&| character as a tab, such as the
\verb|tabular| environment for text or the various math environments in the \textsf{amsmath}
package.

\subsection*{Unary versus Binary Operators/Relations at Cell Ends}

There are two things to keep in mind regarding TABstacked content.  First, a TABstack cell has
no precise understanding up what content precedes it in the cell to the immediate left, nor what
content follows it in the cell to the immediate right.  It does, however know the overall height/depth
of the content across the whole row and creates a vertical ``strut'' of that height and depth, which must,
in some way,  be applied to every cell in the row.  

This vertical strut can be applied to the cell immediately
prior to or immediately following the cell content, as we shall see.  However, such an action will
have an effect on math operators and relations found at the leading or trailing ends of the cell
content.  

Math operators and relations can be categorized as unary or binary; some
may be both, depending on their usage context, such as the minus sign.  When used as $a-b$, the
relation is binary, because it connects $a$ and $b$ in a mathematical relationship.  Note how space
appears both before and after the minus sign.  Alternatively, when used as $-\pi$, the minus sign
operates only upon what follows, in this case $\pi$, to produce a negative.  Note how no space is
introduced between the minus sign and $\pi$.

Because a TABstack cell has no intimate knowledge of the adjacent cell content, it is up to
the user to employ his tabbing seperators in a way that produces the desired result.  By default,
\textsf{tabstackengine} will place the strut after the cell content.  This means that any trailing
math operator in a cell will present itself in its binary form (regardless of what comes in the
cell to the right), because the strut will appear as trailing data against which the operator can 
be set.  Similarly, any leading math operator will present itself as unary (regardless of what
content appears in the cell to the left).

Thus, \verb|\tabbedLongstack{y =&-mx +& b}| will present as 
{\tabbedLongstack{y =&-mx +& b}}, by default,
with the trailing equal and plus signs as binary, and the leading minus sign as unary.  The package
can reverse the default with the following declarative modes: 
\verb|\TABunaryRight| (identical to \verb|\TABbinaryLeft|); as well
as \verb|\TABbinary|, which will present both leading \textit{and} trailing operators in
their binary form.  The default can be restored with 
\verb|\TABunaryLeft| (identical to \verb|\TABbinaryRight|).

Without changing any of the package strut modes, an operator, such as minus, can be 
forced into its unary mode
by enclosing it in braces: \verb|{-}|.  Likewise, it can be forced into its binary mode by
placing empty braces on both sides of it: \verb|{}-{}|.

\subsection*{The Macros \texttt{\textbackslash readTABrow}, \texttt{\textbackslash TABcell(s)}, 
and \texttt{\textbackslash TABstrut}}

One of the nice features of \textsf{tabstackengine} is that it gives you access to its parser,
which can be used for tasks unrelated to building stacks.  
It provides several macros, including 
{\itshape\verb|\readTABrow{|ident\verb|}{|tab-separated-string\verb|}|} for 
digesting a list and assigning it a global ID, in this case, ``{\itshape ident}''. It also provides 
{\itshape\verb|\TABcells{|ident\verb|}|} to tell you how many items are in the list named 
``{\itshape ident}'', as well as the macro {\itshape\verb|\TABcell{|ident\verb|}{|column number\verb|}|} to 
provide the value of the specified column from the ID'ed row.   For example,

\begin{verbatim}
\setstackTAB{,}
\TABstackMath
\readTABrow{myident}{1,2,   3x , 4, 5,x^2,,g,\textbf{bold 9}}
\TABcells{myident} items in dataset ``myident''\\
The 6th data item is \TABcell{myident}{6}\\
The 9th data item is \TABcell{myident}{9}
\end{verbatim}

will yield the following result:

\TABstackMath
{\setstackTAB{,}
\readTABrow{myident}{1,2,   3x , 4, 5,x^2,,g,\textbf{bold 9}}
\TABcells{myident} items in dataset ``myident''\\
The 6th data item is \TABcell{myident}{6}\\
The 9th data item is \TABcell{myident}{9}}

{\fboxsep=1pt%
The result provided by {\itshape\verb|\TABcell{|ident\verb|}{|column number\verb|}|} has
been processed in the following way: 1) leading and trailing spaces have been removed
from the column's data, and 2) the column will have been processed in math mode if
\verb|\TABstackMath| (see below) had been in force.  Thus, placing the cell contents in
a box, \verb|\fbox{\TABcell{myident}{3}}|
is \fbox{\TABcell{myident}{3}}.

If one, however, wished to access the raw
data, with leading/trailing spaces still intact (and ignoring the \verb|\TABstackMath| setting),
one can compose the macro, 
{\itshape\verb|\csname TABX|ident\verb|X\romannumeral| column number\verb|\endcsname|},
such that \verb|\fbox{\csname TABXmyidentX\romannumeral 3\endcsname}|, using the above example,
would give \fbox{\csname TABXmyidentX\romannumeral 3\endcsname}.%
}

Finally, the macro \verb|\TABstrut{myident}| provides a strut that spans the vertical height of the
complete row content.
Here is \verb|\TABstrut{myident}| (that has been boxed with \verb|\fboxsep=0pt|) 
compared to the boxed content of the row itself:\\
{\TABstackMath\fboxsep=0pt\fboxrule=.2pt\fbox{\TABstrut{myident}}
\fbox{$12   3x  4 5x^2g\textbf{bold 9}$}}.  As you can see, the \verb|\TABstrut{myident}|
captures the vertical extent of the complete row data, including the descending $g$ and 
the superscript of the $x^2$.  The \verb|\TABstrut{}|, when paired with the column content, 
is useful when one wishes to make all column entries of a row display with equal height and depth, 
even when their native height varies from column to column.
\TABstackText

\subsection*{\texttt{\textbackslash TABstackMath},  \texttt{\textbackslash ensureTABstackMath}, and 
\texttt{\textbackslash TABstackText}}

These macros are \textit{not} needed when building stacks in \textsf{tabstackengine}.
When constructing TABstacks, their presence is superfluous 
because their companion macros, \verb|\stackMath|, \verb|\ensurestackMath|, 
and \verb|\stackText|, will
carry over from the \textsf{stackengine} package.

However, there is one application where their use is required.  And that is when you
use the facilities of this package \textit{not} to build TABstacks, but \textit{instead} use it to parse
data with \verb|\readTABrow{}{}| and present it with \verb|\TABcell{}{}|, respectively.
Notably \verb|\TABcell{}{}| does not access the \textsf{stackengine} setting for 
the status of \verb|\stackMath| and therefore pays attention only to the current setting
specified by \verb|\TABstackMath|.

One should note, however, that TABstacks pay attention to both settings.  Therefore, 
\bfseries if EITHER \verb|\stackMath| or \verb|\TABstackMath| have been
invoked, the TABstack argument will be processed by \verb|\TABcell| in math 
mode\mdseries.  This is a good reason to avoid the ``TAB'' versions of these 
macros, unless employing them to parse data (and then, reset to 
\verb|\TABstackText| when you are done with parsing).

\section{Known Bugs/Missing Features}

\begin{enumerate}

\item \textbf{No Horizontal Equivalent of \textbackslash TABstrut}

Currently, there is no macro that provides the width of a
column's content.  I hope to remedy this deficiency in a future release.

\item \textbf{Nothing Equivalent to} \verb|\hline|

This is not a bug, so much as a notation of a missing feature.  Currently
there is nothing equivalent to \verb|\hline| available for use in 
\textsf{tabstackengine} arguments.

\end{enumerate}

\section*{Acknowledgements}

I would like to thank Prof. Enrico Gregorio of \textsf{tex.stackexchange.com} for
his considerable assistance rendered.  Many of the improvements he offered towards 
my \textsf{stackengine} package were carried over directly into this package, as
well, resulting in a more robust implementation.

\clearpage
\section{Code Listing}

\verbfilenobox[\footnotesize]{tabstackengine.sty}

\end{document}