From 476d676a816ee6b8b116b2a0b4e49d69aabd6f56 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Thu, 20 Feb 2014 23:10:33 +0000
Subject: tabstackengine (19feb14)

git-svn-id: svn://tug.org/texlive/trunk@33006 c570f23f-e606-0410-a88d-b1316a301751
---
 .../doc/latex/tabstackengine/tabstackengine.tex    | 173 +++++++--------------
 1 file changed, 59 insertions(+), 114 deletions(-)

(limited to 'Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex')

diff --git a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
index 81264dd36cd..70f71e3cf6d 100644
--- a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
+++ b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
@@ -94,8 +94,7 @@ 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 
@@ -150,6 +149,9 @@ brace may be selected.
 \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.
@@ -183,9 +185,9 @@ 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.$|
+\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.$}
+{\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}
 
@@ -222,11 +224,12 @@ 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}|
+\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}}
+\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.
@@ -240,7 +243,6 @@ This is for stacking two items with specifiable alignment pattern.
 \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
@@ -262,6 +264,48 @@ inside of an environment that already uses the \verb|&| character as a tab, such
 \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}}
 
@@ -343,119 +387,13 @@ 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
+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|
@@ -466,7 +404,14 @@ there is nothing equivalent to \verb|\hline| available for use in
 
 \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}
-- 
cgit v1.2.3

