\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}