1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
|
\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.
\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.
\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}
\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}}
\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}}
\clearpage
\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*{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).
\clearpage
\section{Known Bugs/Missing Features}
\begin{enumerate}
\item \textbf{Ending on a} \verb|\frac|
The following code demonstrates a bug when a row ends in \verb|\frac|,
when not followed by a space:
\begin{verbnobox}[\footnotesize]
\documentclass{article}
\usepackage{tabstackengine}
\stackMath
\setstackgap{S}{6pt}
\newcommand\tfrac[2]{\frac{\textrm{#1}}{\textrm{#2}}}
\scriptsize
\begin{document}
\noindent space after tfrac, all is OK:
\par\medskip\noindent\tabbedShortstack[l]{
\rho &= 2.04 &\tfrac{g}{cm$^3$} \\
M &= 56.10 &\tfrac{g}{mol} \\
c &= 0.05 &\tfrac{mol}{L} \\
}
\par\noindent no space after tfrac results in tfrac set in displaystyle\\
while the rest of the stack is in textstyle:
\par\medskip\noindent\tabbedShortstack[l]{
\rho &= 2.04 &\tfrac{g}{cm$^3$}\\
M &= 56.10 &\tfrac{g}{mol}\\
c &= 0.05 &\tfrac{mol}{L}\\
}
\end{document}
\end{verbnobox}
Here is the result of the above code, showing the difference when a space
is included after the \verb|\frac| versus when one is omitted:
{\stackMath
\setstackgap{S}{6pt}
\newcommand\tfrac[2]{\frac{\textrm{#1}}{\textrm{#2}}}
\scriptsize
\noindent space after tfrac, all is OK:
\par\medskip\noindent\tabbedShortstack[l]{
\rho &= 2.04 &\tfrac{g}{cm$^3$} \\
M &= 56.10 &\tfrac{g}{mol} \\
c &= 0.05 &\tfrac{mol}{L} \\
}
\par\noindent no space after tfrac results in tfrac set in displaystyle\\
while the rest of the stack is in textstyle:
\par\medskip\noindent\tabbedShortstack[l]{
\rho &= 2.04 &\tfrac{g}{cm$^3$}\\
M &= 56.10 &\tfrac{g}{mol}\\
c &= 0.05 &\tfrac{mol}{L}\\
}}
When the space is omitted, the stack is constructed in \verb|\textstyle|, whereas the
closing fractions appear to be constructed in \verb|\displaystyle|. The workaround is to not end
the \textsf{tabstackengine} field in a \verb|\frac| without an extra space.
\item \textbf{Unary versus Binary Minus Sign}
The package seems to want to use the minus sign that leads a number in binary
mode, that is, as an minus operator rather than as a negative sign.
\begin{verbnobox}[\footnotesize]
\setstacktabbedgap{1ex}
$\bracketMatrixstack[r]{
-0.84 & 0.21 & -0.11 & 0.110 & 0.13 & 0.34\\
0.21 & -0.43 & 0.14 & 0.06 & 0.30 & -0.22\\
0.27 & 0.13 & -0.54 & 0.25 & -0.27 & 0.16\\
-0.27 & -0.23 & 0.43 & -0.46 & 0.53 & -0.05\\
0.05 & 0.13 & -0.02 & -0.10 & -0.03 & -0.02\\
0.23 & -0.32 & 0.21 & -0.11 & 0.41 & -0.34
}$
\end{verbnobox}
\setstacktabbedgap{1ex}
$\bracketMatrixstack[r]{
-0.84 & 0.21 & -0.11 & 0.110 & 0.13 & 0.34\\
0.21 & -0.43 & 0.14 & 0.06 & 0.30 & -0.22\\
0.27 & 0.13 & -0.54 & 0.25 & -0.27 & 0.16\\
-0.27 & -0.23 & 0.43 & -0.46 & 0.53 & -0.05\\
0.05 & 0.13 & -0.02 & -0.10 & -0.03 & -0.02\\
0.23 & -0.32 & 0.21 & -0.11 & 0.41 & -0.34
}$
\vspace*{\baselineskip}
The workaround is to enclose the minus signs in braces:
\begin{verbnobox}[\footnotesize]
\setstacktabbedgap{1ex}
$\bracketMatrixstack[r]{
{-}0.84 & 0.21 & {-}0.11 & 0.110 & 0.13 & 0.34\\
0.21 & {-}0.43 & 0.14 & 0.06 & 0.30 & {-}0.22\\
0.27 & 0.13 & {-}0.54 & 0.25 & {-}0.27 & 0.16\\
{-}0.27 & {-}0.23 & 0.43 & {-}0.46 & 0.53 & {-}0.05\\
0.05 & 0.13 & {-}0.02 & {-}0.10 & {-}0.03 & {-}0.02\\
0.23 & {-}0.32 & 0.21 & {-}0.11 & 0.41 & {-}0.34
}$
\end{verbnobox}
$\bracketMatrixstack[r]{
{-}0.84 & 0.21 & {-}0.11 & 0.110 & 0.13 & 0.34\\
0.21 & {-}0.43 & 0.14 & 0.06 & 0.30 & {-}0.22\\
0.27 & 0.13 & {-}0.54 & 0.25 & {-}0.27 & 0.16\\
{-}0.27 & {-}0.23 & 0.43 & {-}0.46 & 0.53 & {-}0.05\\
0.05 & 0.13 & {-}0.02 & {-}0.10 & {-}0.03 & {-}0.02\\
0.23 & {-}0.32 & 0.21 & {-}0.11 & 0.41 & {-}0.34
}$
\item \textbf{No Horizontal Equivalent of \textbackslash TABstrut}
As of the initial package release, 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{Code Listing}
\verbfilenobox[\footnotesize]{tabstackengine.sty}
\end{document}
|