tabstackengine (5oct16)

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

3 files changed, 449 insertions, 221 deletions

diff --git a/Master/texmf-dist/doc/latex/tabstackengine/README b/Master/texmf-dist/doc/latex/tabstackengine/README
index a394d8979e5..5c8f2fa519f 100644
--- a/Master/texmf-dist/doc/latex/tabstackengine/README
+++ b/Master/texmf-dist/doc/latex/tabstackengine/README
@@ -14,5 +14,10 @@ Steven B. Segletes
 steven.b.segletes.civ@mail.mil
 
 
-THIS MATERIAL IS SUBJECT TO THE LaTeX Project Public License
-
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+  http://www.latex-project.org/lppl.txt
+and version 1.3c or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf
index f4c2185ce2e..68b8d116cdb 100644
--- a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf
+++ b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf
diff --git a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
index 70f71e3cf6d..f4a448f4029 100644
--- a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
+++ b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
@@ -1,4 +1,6 @@
 \documentclass{article}
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
 \usepackage{tabstackengine}
 \usepackage{verbatimbox}
 \usepackage{xcolor}
@@ -7,12 +9,23 @@
 
 % 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
+\def\ste{\textsf{stackengine}}   \def\loi{\textsf{listofitems}}
+\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}}
 
+\catcode`>=\active %
+\catcode`<=\active %
+\catcode`!=\active %
+\def\vbspecial#1>{\textit{\rmfamily#1}}
+\def\vbdelim{\catcode`<=\active \catcode`>=\active \catcode`!=\active \def<{\vbspecial}\def>{}\def!{\textrm{(provided by \ste)}}}
+\catcode`!=12 %
+\catcode`>=12 %
+\catcode`<=12 %
+\def\endvbdelim{\catcode`>=12 \catcode`<=12 }
+
 \begin{document}
 
 \begin{center} \LARGE The {\tst} Package\\ \rule{0em}{.7em}\small
@@ -27,21 +40,58 @@ Steven B. Segletes\\ steven.b.segletes.civ@mail.mil\\
 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)
+When invoked, {\tst} loads the {\ste} package and initializes it in
+such a way 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).
+The EOL separator can be changed using \ste{}'s \vb|\setstackEOL| macro.
 
 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.
+other tokens using the \verb|\setstackTAB| macro.
 
+\begin{sloppypar}
 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.
+\end{sloppypar}
+
+\section{Modes and Styles of \tst}
+
+\begin{sloppypar}
+Like the \ste{} package which provides the modes \vb|\stackText| and
+  \vb|\stackMath|, the \tst{} package provides the modes
+  \vb|\TABstackText| and  \vb|\TABstackMath|.\margcmd{TABstackText}%
+  \margcmd{TABstackMath}  
+However, the \tst{} package honors the underlying mode of \ste, and
+  so if either \vb|\stackMath| or \vb|\TABstackMath| are set, all
+  TABstacking arguments will be processed in math mode.%
+  \footnote{The one exception here is if \ste{} macros are embedded (nested)
+  inside \tst{} macro arguments.  In this case, the embedded \ste{} macro will
+  only respond to the \ste{} mode, and not the \tst{} mode.}
+So what are the differences?\vspace{-\parskip}
+\begin{itemize}
+\item \vb|\TABstackMath| and \vb|\TABstackText| are local settings, whereas
+  \vb|\stackMath| and \vb|\stackText| are global settings.
+\item As of version 2.00, 
+  \tst{} provides the means to add additional styles to a stack, 
+  associated with \vb|\TABstackMath| and \vb|\TABstackText|.
+  In particular,
+  the macros \vb|\TABstackMathstyle| and \vb|\TABstackTextstyle|%
+  \margcmd{TABstackMathstyle}\margcmd{TABstackTextstyle}
+  can be used to add custom styles to stacks.  For example, 
+  \vb|\TABstackMathstyle{\displaystyle}| will cause all stacked items
+  processed in TABstack-math mode to be set in display style.  Likewise
+  \vb|\TABstackTextstyle{\scriptsize}| will cause all stacked items
+  processed in TABstack-text mode to be set in script size.
+  Styles (for both math and text modes) can be cleared with the command
+  \vb|\clearTABstyle|\margcmd{clearTABstyle}.
+\end{itemize}
+\end{sloppypar}
+
 
 \section{Tabbing Variations within \tst}
 
@@ -63,13 +113,14 @@ 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
+\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.
+The default is \texttt{F}.
+When set true, additional 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
@@ -80,10 +131,10 @@ but this value can be reset with the macro
 
 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|}|.
+  gap introduced after the right-aligned (odd-numbered) columns.  
+However, the default gap introduced after the left-aligned (even-numbered) 
+  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
@@ -95,12 +146,14 @@ 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.
  
+\clearpage
 \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.
+Below are the new TABstack making commands introduced by \tst.  
+In the syntax shown below, when there are multiple commands delimited by 
+  braces,  any one of the commands within the brace may be selected.
 
+\vbdelim
 \ttfamily\footnotesize
 \(\left.\Centerstack[r]{%
   \textcolor{red}{\cmd tabbed}\\\\
@@ -112,13 +165,14 @@ brace may be selected.
   Longunderstack\\Centerstack\\Vectorstack}
 \right\}%
 \left\{\Centerstack[c]{
-  \textcolor{red}{[alignment]}\\\\
+  \textcolor{red}{[<alignment>]}\\\\
   \\\\
-  \textcolor{blue}{\{column alignments\}}
-}\right\}\)\{tabbed EOL-separated string\}
+  \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\}\$
+\(\displaystyle\$\left\{\Centerstack[r]{\cmd\\ \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}\\\\
@@ -127,18 +181,18 @@ brace may be selected.
 \left\{
 \Centerstack[c]{stackon\\stackunder\\stackanchor}
 \right\}%
-\mathtt{[stack gap]}\left\{\Centerstack[l]{
+\mathtt{[<stack gap>]}\left\{\Centerstack[l]{
 \\\\
 \\\\
 \textcolor{blue}{\{col.\ alignments\}}
-}\right\}\)\{tabbed anchor\}\{tabbbed~argument\}
+}\right\}\)\{<tabbed anchor>\}\{\rlap{<tabbed~argument>\}}
 
 \cmd setstack\(\left\{\Centerstack{
   \textcolor{red}{tabbed}\\\\
   \textcolor{teal}{align}\\\\
   \textcolor{blue}{tabular}
-}\right\}\)gap\{length\}
-\hspace{3em}Initial Defaults:\(\left\{\Centerstack{
+}\right\}\)gap\{<length>\}
+\hspace{3em}\textrm{Initial Defaults:}\(\left\{\Centerstack{
   \textcolor{red}{0pt}\\\\
   \textcolor{teal}{1em}\\\\
   \textcolor{blue}{\cmd tabcolsep}
@@ -146,76 +200,101 @@ brace may be selected.
 
 \rmfamily\normalsize
 
-\begin{verbnobox}[\footnotesize]
-\fixTABwidth{T or F}
-\setstackTAB{tabbing character}
+The macro\margcmd{ensureTABstackMath}
+\begin{verbnobox}[\footnotesize\vbdelim]
+\ensureTABstackMath{<commands involving TABstacks>}
+\end{verbnobox}
+will force any \tst{} stacks within its argument to be 
+  processed in math mode, even
+  if the prevailing mode is otherwise \vb|\TABstackText|.
+The package also provides a set of declarations that can be used to define the
+  manner in which subsequent TABstacks will be processed:
+\begin{verbnobox}[\footnotesize\vbdelim]
+\fixTABwidth{T <or> F}
+\TABstackMath
+\TABstackText
+\TABstackMathstyle{<directive>}
+\TABstackTextstyle{<directive>}
+\clearTABstyle
+\setstackEOL{<end-of-line character>}      !
+\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{}
+The following macros can be used for parsing tabbed data outside of a
+  TABstack and also provide various stack metrics for the most recently 
+  parsed \tst{} data.
+\begin{verbnobox}[\footnotesize\vbdelim]
+\readTABstack{<tabbed EOL-separated string>}
+\TABcellRaw[<row>,<column>]
+\TABcell{<row>}{<column>}
+\TABcellBox[<alignment>]{<row>}{<column>}
+\getTABcelltoks[<row>,<column>]     \the\TABcelltoks
+\TABcells{<row> or blank}
+\TABstrut{<row>}
+\TABwd{<column>}
+\TABht{<row>}
+\TABdp{<row>}
 \end{verbnobox}
 
 \subsection{Command Examples}
 
 Below we give examples of the various types of commands made available through
-the \textsf{stackengine} package.
+the \tst{} 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]|.
+Here, the optional argument \vb|[l]| defines the alignment of \textit{all} the
+columns as ``left.''  The default alignment is \vb|[c]|.
 
-\verb|\tabbedShortunderstack[l]{A&B&CCC\\aaa&bbb&c\\1111&2&3}|
+\vb|\TABstackTextstyle{\scshape}|\\
+\vb|\tabbedShortunderstack[l]{This& Is &The\\Time & Of&Man's\\ Great&Dis&content}|
 
-{\small\tabbedShortunderstack[l]{A&B&CCC\\aaa&bbb&c\\1111&2&3}}
+{\small\TABstackTextstyle{\scshape}%
+  \tabbedShortunderstack[l]{This& Is &The\\Time & Of&Man's\\ Great&Dis&content}}
+
+Note that spaces around the arguments are absorbed and discarded.  Furthermore, the
+text style has been set to \vb|\scshape|.
 
 \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|.
+In an \texttt{align}-stack, the column alignments will always be \vb|rlrl...|
+The gap following the left-aligned columns is set by \vb|\setstackaligngap|.
 
-\verb|\stackMath$Z:\left\{\alignCenterstack{%|\\
-\verb|  y=&mx+b,&0=&Ax+By+C\\y_1=&W_1,&y_2=&W_2}\right.$|
+\vb|$\ensurestackMath{Z:\left\{\alignCenterstack{%|\\
+\vb|  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.$}
+{\small$\ensurestackMath{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]}|
+\vb|\stackText\tabularLongstack{rllc}{%|\\
+\vb|  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}
+\subsection*{Matrix Stacks}
 
-The \texttt{Matrix}-stacks are a tabbed variant of \textsf{stackengine}'s \texttt{Vector}-stacks.
+The \texttt{Matrix}-stacks are tabbed variants of \ste's \texttt{Vector}-stacks.
 
-\verb|\setstacktabbedgap{1.5ex}|\\
-\verb|$I = \bracketMatrixstack{1&0&0\\0&1&0\\0&0&1}$|
+\vb|\setstacktabbedgap{1.5ex}|\\
+\vb|$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.
+The optional argument is a stacking gap,
+as in the syntax of the \ste{} package.
 
-\verb|\setstacktabbedgap{1ex}|\\
-\verb|\tabbedstackon[4pt]{Jack&drove&the car&home.}{SN&V&DO&IO}|
+\vb|\setstacktabbedgap{1ex}|\\
+\vb|\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}}
 
@@ -223,199 +302,343 @@ as in the syntax of the \textsf{stackengine} package.
 
 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}|
+\vb|\TABstackMath\setstackaligngap{3em}|\\
+\vb|\alignstackunder[8pt]{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}}
+{\small\TABstackMath\setstackaligngap{3em}
+\alignstackunder[8pt]{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}}
+\vb|\TABbinary\TABstackMath\setstacktabulargap{1ex}%|\\
+\vb|  \tabularstackanchor[-1pt]{rcl}%|\\
+\vb|  {\rule{7ex}{1pt}&\belowbaseline[0pt]{$\triangle$}%|\\
+\vb|    &\rule{7ex}{1pt}}{1 + 3(4-3) &=& 7 - 6/2}|\vspace{1ex}
+
+{\small\TABbinary\TABstackMath\setstacktabulargap{1ex}
+\tabularstackanchor[-1pt]{rcl}{\rule{7ex}{1pt}&\belowbaseline[0pt]{%
+$\triangle$}&\rule{7ex}{1pt}}{1 + 2(4-3) &=& 6 - 6/2}}
+
+Note the use of \vb|\TABbinary|, which applies a group to the beginning and
+  end of each cell, in the event a binary treatment of leading/trailing
+  operators is desired. 
+So, in this case, a cell containing \vb|=| will be set as \vb|{}={}|.
+In the absence of that declaration, the cell containing
+the equal sign would have to have been explicitly defined as \vb|{}=| 
+  in order to override the \vb|\unaryLeft| default setting of the package,
+  which only places a group at the end of each cell.  
+Note also the use of a negative stacking gap, which is a perfectly 
+  acceptable syntax and can be used to achieve overlap, if desired.
 
 \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.
+With the \vb|\fixTABwidth| mode set\margcmd{fixTABwidth}, the stack 
+  will have fixed-width columns, based on the overall widest entry.
+Compare with versus without fixed width for the following TABstack.
 
-\verb|\fixTABwidth{T}\setstacktabbedgap{1ex}%|\\
-\verb|$\left(\tabbedCenterstack[r]{1&34&544\\4324329&0&8\\89&123&1}\right)$|
+\vb|\setstacktabbedgap{1ex}\fixTABwidth{T}%|\\
+\vb|$\left(\tabbedCenterstack[r]{1&34&544\\4324329&0&8\\89&123&1}\right)$|\\
+\vb|versus \fixTABwidth{F}%|\\
+\vb|$\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)$}
+{\small\setstacktabbedgap{1ex}\fixTABwidth{T}
+$\left(\tabbedCenterstack[r]{1&34&544\\4324329&0&8\\89&123&1}\right)$
+versus \fixTABwidth{F}%
+$\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.
+\begin{sloppypar}
+By default, for the parsing of columns within a given row, this package employs 
+  the \vb|&| character to delimit the columns.  
+This value can be changed via \vb|\setstackTAB{|<tabbing character>\vb|}|,%
+  \margcmd{setstackTAB} 
+  where the argument is the newly desired tabbing token.  
+It can be any of various tokens, including  a space token, if one wishes to 
+  parse a space-separated list of columns.  
+\end{sloppypar}
+
+\subsection*{TABstacks Inside the \texttt{tabular} Environment}
+
+When invoking a TABstack inside another tabbed environment, such as
+  \vb|tabular|, \vb|align|, or other similar environments, one must group
+  the TABstacks in their own braces \vb|{}|:
+\begin{verbnobox}[\footnotesize\vbdelim]
+\ensureTABstackMath{%
+\begin{tabular}{c|c}
+Left Eqn. & Right Eqn.\\
+\hline
+{\tabularCenterstack{lr}{a_1 & 12\\c & 1234}} & \
+{\tabularCenterstack{rl}{a_1 & 12\\c & 1234}}\\
+\hline
+\end{tabular}
+}
+\end{verbnobox}
+{%
+\ensureTABstackMath{%
+\begin{tabular}{c|c}
+Left Eqn. & Right Eqn.\\
+\hline
+{\tabularCenterstack{lr}{a_1 & 12\\c & 1234}} & 
+{\tabularCenterstack{rl}{a_1 & 12\\c & 1234}}\\
+\hline
+\end{tabular}
+}
 
-\subsection*{Unary versus Binary Operators/Relations at Cell Ends}
+\subsection*{Math Relations/Operators at Cell Left/Right Extrema}
 
-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.  
+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.  
+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.
+  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 operation.  
+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$.
+This is the minus used as a unary operator.
+
+Because a TABstack cell has no intimate knowledge of the adjacent cell content, 
+  it is up to the user to employ his tabbing separators in a way that produces
+  the desired result.  
+By default, \tst{} 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).
+
+\stackMath
+Thus, under the default setting \vb|\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: 
+  \vb|\TABunaryRight|\margcmd{TABunaryRight} (identical to 
+  \vb|\TABbinaryLeft|)\margcmd{TABbinaryLeft}; alternately,
+  one may use \vb|\TABbinary|\margcmd{TABbinary}, which will 
+  present both leading \textit{and} trailing 
+  operators in their binary form.  
+The default can be restored with \vb|\TABunaryLeft| (identical to 
+  \vb|\TABbinaryRight|).\margcmd{TABunaryLeft}\margcmd{TABbinaryRight}
+
+Without changing any of the package strut modes, an operator, such as minus, 
+  can always be forced into its unary mode by enclosing it in braces: \vb|{-}|.  
+Likewise, it can be forced into its binary mode by placing empty braces on 
+  both sides of it: \vb|{}-{}|.
+
+\subsection*{The Parsing Macros \texttt{\textbackslash readTABstack}, <etc.>}
+
+As of version 2.00 of the \tst{} package, the parsing functions of the package 
+  were delegated to the very powerful \loi{} package. 
+As such {\bfseries the \vb|\readTABrow| macro is no longer supported}.
+For typical parsing functionality, therefore, please consult the 
+  documentation to the \loi{} package and its \vb|\readlist| macro.
+I commend it to your inspection and use for a variety of parsing tasks. 
+
+However, there may still be a need to access the various stacking related data
+  in either a recently composed TABstack, or even one that is yet to be typeset.
+When a TABstack is constructed by the \tst{} package, a call is made to the routine
+  \vb|\readTABstack|\margcmd{readTABstack}, in order to parse the data.
+This macro may be independently called by the user to read TABstack data
+  without producing a constructed TABstack, by passing it the same tabbed,
+  EOL-separated data that would otherwise be used to construct a stack.%
+  \footnote{Alternately, TABstacking data can be read without generating a
+  TABstack by using the \texttt{\cmd renewcommand\cmd quietstack\{T\}} 
+  setting of \ste{} to suppress the stack output, without supressing its 
+  construction.}
+If the routine is not called independently by the user, data from the most 
+  recent TABstacking operation is still available for interrogation.
+
+Take the example
+
+\vb|\TABstackMath\TABstackMathstyle{\displaystyle}\setstackgap{S}{5pt}%|\\
+\vb|\alignShortstack{\frac{A}{Q}x=&B\\ C= &\frac{Dx}{2}\\E=&F}}|
+
+which presents as
+
+\TABunaryLeft
+\TABstackMath\TABstackMathstyle{\displaystyle}\setstackgap{S}{5pt}%
+  \alignShortstack{\frac{A}{Q}x=&B\\ C= &\frac{Dx}{2}\\E=&F}
+
+Let us say we were interested in information about the cell in the 1st
+  column of the 2nd row.  
+I can obtain its dimensions as the column-1 width \vb|\TABwd{1}|%
+  \margcmd{TABwd}, as well as the row-2 height and depth 
+  \vb|\TABht{2}|\margcmd{TABht} and \vb|\TABdp{2}|\margcmd{TABdp}.
+Note that these macros provide dimensions of the TABstack \textit{cell}, which 
+  in this case is larger than the mere ``\TABcell{2}{1}'' content.
+Those dimensions are as follows, followed by a \vb|\rule| depicting the total 
+  size of the cell:
+
+Width: \TABwd{1},\hfill Height/Depth: \TABht{2}/\TABdp{2},\hfill Rule: 
+  \rule[-\TABdp{2}]{\TABwd{1}}{\dimexpr\TABdp{2}+\TABht{2}\relax}
+
+One can also obtain information about what is in the cell.
+Here, use the macro \vb|\TABcellRaw[2,1]|\margcmd{TABcellRaw}, which will
+  expand to the tokens employed in the stack definition (shown here in an
+  \vb|\fbox| to show that the leading/trailing spaces have been discarded):
+
+\fboxsep=1pt
+\fbox{\TABcellRaw[2,1]}
+
+If one would like to see the cell data presented in the prevailing
+  (\textsf{tab})\ste{} mode and style, the macro 
+  \vb|\TABcell{2}{1}|\margcmd{TABcell} may be used (again shown in
+  an \vb|\fbox|):
+ 
+\fbox{\TABcell{2}{1}}
+
+Note, however, that the \vb|\TABcell| still does not account for three things: 
+\vspace{-\parskip}\begin{itemize}
+  \item it is not strutted to reflect the height of the full row content; 
+  \item it does not reflect the full column width (nor the alignment within
+     the column); and
+  \item it does not provide any of the empty group treatments that would
+     otherwise make leading/trailing math operators perform in a binary fashion.
+\end{itemize}\vspace{-\parskip}
+A strut of the given row height may be obtained with  \vb|\TABstrut{2}|%
+  \margcmd{TABstrut}:
+
+\fboxsep=0pt
+\fbox{\TABstrut{2}} $\quad\leftarrow$the strut is boxed here to show 
+  its vertical extent
+
+However, to obtain the fully rendered cell, \textit{as it appears within the
+  actual TABstack}, one needs \vb|\TABcellBox{2}{1}|\margcmd{TABcellBox},
+  shown (in an \vb|\fbox|) as
+
+\fbox{\TABcellBox{2}{1}}\quad% ACCOUNTS FOR \TABunaryLeft, etc.
+
+Since the \vb|\readTABstack| macro, itself, neither knows nor determines the
+  eventual cell alignment of a future stack, the actual \texttt{lcr} 
+  alignment of a \vb|\TABcellBox| will only be known when applied to
+  a previously constructed stack.
+Therefore, if \vb|\TABcellBox| is called following an independent 
+  invocation of \vb|\readTABstack|, center alignment
+  of the cell content will be provided, by default, which can be overridden
+  with the optional argment to \vb|\TABcellBox|.
+
+Note that the height/depth of the \vb|\TABcellBox| reflects the height and
+  depth of the row content of the TABstack.  
+For short stacks, the specified gap between rows is \textit{in addition} 
+  to these strutted boxes.
+For long stacks, the inter-row spacing is independent of the box height and
+  depth.
+However, even for long stacks, the height of the top row and the depth of 
+  the bottom row of a stack still affect the overall dimensions of the stack.
+
+\begin{sloppypar}
+If one wishes to recover the \textit{actual tokens} that were employed in a 
+  given TABstack cell (rather that just something that will \textit{expand}
+  to those tokens), that can be accomplished in one of two ways.
+The macro \vb|\TABcellRaw[]| can be expanded twice in the manner of
+\end{sloppypar}
+
+\vb|\expandafter\detokenize%|\\
+\vb|\expandafter\expandafter\expandafter{\TABcellRaw[2,2]}|
+
+\expandafter\detokenize%
+\expandafter\expandafter\expandafter{\TABcellRaw[2,2]}
+
+Alternately, the macro \vb|\getTABcelltoks[]|\margcmd{getTABcelltoks} will
+  produce a token list named  \vb|\TABcelltoks|\margcmd{the\cmd TABcelltoks} that 
+  contains the cell's tokens:
+
+\vb|\getTABcelltoks[2,2]\detokenize\expandafter{\the\TABcelltoks}|
+
+\getTABcelltoks[2,2]\detokenize\expandafter{\the\TABcelltoks}
 \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}
+In summary then, \tst{} cell content can be accessed in a number of ways:\\
+\renewcommand\arraystretch{1.2}
+\begin{tabular}{@{}l@{~--~}p{3.5in}@{}}
+\vb|\TABcellRaw| & expands into the tokens of the cell\\
+\vb|\TABcell| & presents the cell content in the prevailing mode (text
+  or math) and style set by \ste{} and \tst{}\\
+\vb|\TABcellBox| & presents the cell content, in the prevailing mode
+  and style, strutted to the proper row height/depth, set in a box of the
+  proper cell width, flanked by the appropriate \vb|{}| groups defined by
+  \tst's unary and/or binary declarations,
+  and (when knowable) set in the proper \texttt{lcr} alignment\\
+\vb|\getTABcelltoks| & creates a token list register \vb|\TABcelltoks| 
+  that contains the actual tokens employed in the cell, accessible by
+   way of \vb|\the\TABcelltoks|
+\end{tabular}
+
+\section*{TABstack Array Dimensions}
+
+Consider the example
+
+\setstacktabbedgap{.5em}
+\tabbedLongstack{a & b & c & d\\ e & f & g & h & H\\ i & j & k & l}
+
+The macros \vb|\TABwd|, \vb|\TABht|, and \vb|\TABdp| were presented as the
+  means to get the physical dimensions of various rows and columns of a TABstack.
+But what if the information sought is the number of rows and columns?
+
+The macro \vb|\TABcells{}|\margcmd{TABcells} performs the function. 
+When passed a blank argument, it returns the number of rows of the most
+  recently constructed TABstack (or \vb|\readTABstack|).
+
+$\textrm{Rows} = \vb|\TABcells{}| = \TABcells{}$
+
+On the other hand, pass it a row number for its arguments and it will tell you
+how many columns below to that row
+
+$\textrm{Columns} = \vb|\TABcells{1}| = \TABcells{1}$
+
+Note that \tst{} uses the number of columns provided in row 1 to determine the
+  dimensions of the subsequent TABstack.
+If the 2nd or 3rd rows of the above stack were [accidentally] defined with 5 
+  columns of data, the last column would be ignored, since the 1st row only
+  has 4 columns.  
+However, in that case, \vb|\TABcells{2}| would, in fact, yield \TABcells{2}.
+ 
 
-\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.
+\section{Absent Features}
 
-\item \textbf{Nothing Equivalent to} \verb|\hline|
+\textbf{Nothing Equivalent to} \vb|\hline| or \vb`|`
 
 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}
+there is nothing equivalent to \vb|\hline| available for use in 
+\tst{} arguments. 
+Furthermore, vertical lines may \textbf{not} be added to a tabular stack 
+  with the use of \vb`|` elements in the column specifier.
 
+\endvbdelim
 \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.
+I would like to thank Christian Tellechea for his development of the 
+  \loi{} package (which was directly inspired by my deficient
+  \textsf{getargs} package).
+The macros provided by Christian were directly implemented for version 2.00
+  of the \tst{} package.
+
+I would also thank the user ``Werner'' at \textsf{tex.stackexchange.com} for
+helping me to understand some of the details of the \textsf{etoolbox} package:
+
+\vb|http://tex.stackexchange.com/questions/140372/|\\
+\vb|loop-multi-contingency-using-etoolbox|
 
-\clearpage
 \section{Code Listing}
 
 \verbfilenobox[\footnotesize]{tabstackengine.sty}
-
 \end{document}