summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-10-05 21:16:43 +0000
committerKarl Berry <karl@freefriends.org>2016-10-05 21:16:43 +0000
commit3a791c3ce1d5a2f61d7e82669b386db5b86f6a52 (patch)
tree5b53609baf43492cddac7790775b12854cec6ed2 /Master/texmf-dist/doc/latex
parenta8ef7b0b48c3a8fc592bf4b632c9d23f5a115293 (diff)
tabstackengine (5oct16)
git-svn-id: svn://tug.org/texlive/trunk@42214 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r--Master/texmf-dist/doc/latex/tabstackengine/README9
-rw-r--r--Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdfbin314836 -> 562549 bytes
-rw-r--r--Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex661
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
Binary files differ
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}