tabstackengine (5mar18)

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

2 files changed, 168 insertions, 40 deletions

diff --git a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf
index c288ddfd20f..66dd8ba232b 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 fa4be38a47b..02e3bf02bb4 100644
--- a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
+++ b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex
@@ -1,7 +1,7 @@
 \documentclass{article}
 \usepackage[T1]{fontenc}
 \usepackage{lmodern}
-\usepackage{tabstackengine}
+\usepackage[TABcline]{tabstackengine}
 \usepackage{verbatimbox}
 \usepackage{xcolor}
  \parindent 0in\parskip 1em \newlength\dotscale
@@ -20,12 +20,16 @@
 \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)}}}
+\def\vbdelim{\catcode`<=\active \catcode`>=\active \catcode`!=\active \def<{\vbspecial}\def>{}\def!{\stringrms}}
 \catcode`!=12 %
 \catcode`>=12 %
 \catcode`<=12 %
 \def\endvbdelim{\catcode`>=12 \catcode`<=12 }
 
+\def\stringrms#1{%
+  \ifx1#1\relax\textrm{(provided by \ste)}\fi%
+  \ifx2#1\relax\textrm{(only with \texttt{TABcline} package option)}\fi%
+}
 \begin{document}
 
 \begin{center} \LARGE The {\tst} Package\\ \rule{0em}{.7em}\small
@@ -45,12 +49,12 @@ 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.
+The EOL separator can be changed using \ste{}'s \cmd{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 tokens using the \verb|\setstackTAB| macro.
+other tokens using the \vb|\setstackTAB| macro.
 
 \begin{sloppypar}
 In most cases (where it makes sense), a {\ste} macro name may be
@@ -145,6 +149,99 @@ 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{Horizontal Rules}\label{s:hr}
+
+As of version 2.10, \tst{} provides the facility to lay down horizontal rules 
+  that fill up the TABstack cell width.
+There are two ways that this may be accomplished.
+First, the macro \vb|\TABrule[<|\textit{vertical shift}\vb|>]|%
+\margcmd{TABrule}
+  may be specified as the entry in a cell, in order to place a horizontal 
+  rule, of thickness \vb|\fboxrule| across the width of the cell.%
+\footnote{The width of the \cmd{TABrule} will actually be the width of
+  the widest data in that column.  This has implications when the
+  \cmd{fixTABwidth} switch is set true, in that some columns will
+   be typeset wider than their widest data.}
+The optional argument specifies the vertical shift of the rule.
+The default vertical shift, initially 0pt, may also be specified in the 
+  length \cmd{TABruleshift}.\margcmd{TABruleshift}
+
+So, for example,
+
+\vb|\tabbedstackon{a&bb&CCC&dddd}{&\TABrule&&\TABrule}|
+
+ will yield this result:
+  \tabbedstackon{a&bb&CCC&dddd}{&\TABrule&&\TABrule}.
+Note that the vertical spacing around the \vb|\TABrule| will conform
+  to the stackengine rules set by \vb|\setstackgap|, for both ``short'' and
+  ``long'' stacks.
+In essence, the \vb|\TABrule|s literally constitute their own row in the stack.
+
+A \vb|\TABrule| may also constitute a cell that contains actual [non-rule]
+  data elsewhere on the row.
+So, for example, 
+
+\vb|\tabbedLongstack{aa&\TABrule\\\TABrule&bbb}| 
+
+produces the result \tabbedLongstack{aa&\TABrule\\\TABrule&bbb}.
+
+If a row of the TABstack is to be composed solely of rules, then these rules 
+  can also be achieved in a second way.
+
+\subsection{The \texttt{TABcline} Package Option}\label{s:rtx}
+
+There is also introduced in version 2.10, a package option \vb|TABcline|,
+  invoked in the standard way via \vb|\usepackage[TABcline]{tabstackengine}|.
+This option reduces the efficiency of the package slightly, but provides
+  two macros that can enhance convenience.
+The two macros that are activated with this package option are \vb|\TABcline{}|%
+\margcmd{TABcline}
+  and \vb|\relaxTABsyntax|.
+The macro 
+
+\vb|\TABcline{<|\textit{col1}\vb|>,<|\textit{col2}\vb|>,<|%
+  \textit{col3--col4}\vb|>,...}|
+
+provides a shorthand notation for creating a row of \vb|\TABrule|s. 
+For example, in a five-column TABstack, the shorthand
+
+\vb|\TABcline{1,3-4}|
+
+is equivalent to (assuming column separator as \vb|&|, spaces 
+inserted for clarity)
+
+\vb|\TABrule & & \TABrule & \TABrule &|
+
+Furthermore, if the \vb|\TABcline| occurs prior to the last row of the 
+  TABstack, an end-of-line (EOL) token (\textit{e.g.}, \vb|\\|) is also
+  suffixed to the replacement.
+Thus,
+
+\vb|\tabbedShortstack{\TABcline{2-3}\TABcline{1,3-4}a&bb&CCC&dddd}|
+
+produces \tabbedShortstack{\TABcline{2-3}\TABcline{1,3-4}a&bb&CCC&dddd}.
+
+When the \texttt{TABcline} package option is selected,
+  the \vb|\relaxTABsyntax|%
+\margcmd{relaxTABsyntax}
+  switch may also be invoked to address an issue of 
+  bad syntax.
+Some users have a tendency to tack a trailing stack-EOL to the end of 
+  an input argument, in the manner of \vb|\tabbedLongstack{a&bb\\cc&d\\}|.
+This rightfully provokes a \loi{} invalid-index error in \tst{}, because 
+  the syntax implies the creation of a third row of a 2-column TABstack, 
+  for which no column separators have been specified.
+
+However, some may find the error message difficult to understand, especially
+  because similar syntax is benign in the \texttt{tabular} environment and
+  non-fatal in the \texttt{align} family of environments.
+If the switch \vb|\relaxTABsyntax| is in force, the compilation will instead 
+  succeed, with the trailing row of the TABstack left blank, in the manner
+  of {\relaxTABsyntax\tabbedLongstack{a&bb\\cc&d\\}}.
+Such syntax is still considered bad form, but by compiling without error,
+  the visual result may make the source of the problem more obvious to the 
+  user.
  
 \clearpage
 \section{Command Summary}
@@ -200,15 +297,20 @@ In the syntax shown below, when there are multiple commands delimited by
 
 \rmfamily\normalsize
 
-The macro\margcmd{ensureTABstackMath}
+The ``\textit{tabbed EOL separated string}'' can contain not only regular 
+  \LaTeX{} content, but
+  it may also contain \cmd{TABrule}s and/or \cmd{TABcline}s as discussed 
+  in section~\ref{s:hr}.
+The macro\margcmd{ensureTABstackMath}\vspace{-8pt}
 \begin{verbnobox}[\footnotesize\vbdelim]
 \ensureTABstackMath{<commands involving TABstacks>}
 \end{verbnobox}
+\vspace{-8pt}
 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:
+  manner in which subsequent TABstacks will be processed:\vspace{-8pt}
 \begin{verbnobox}[\footnotesize\vbdelim]
 \fixTABwidth{T <or> F}
 \TABstackMath
@@ -216,15 +318,17 @@ The package also provides a set of declarations that can be used to define the
 \TABstackMathstyle{<directive>}
 \TABstackTextstyle{<directive>}
 \clearTABstyle
-\setstackEOL{<end-of-line character>}      !
+\setstackEOL{<end-of-line character>}      !1
 \setstackTAB{<tabbing character>}
 \TABunaryLeft    (\TABbinaryRight)
 \TABunaryRight   (\TABbinaryLeft)
 \TABbinary
+\relaxTABsyntax                   !2
 \end{verbnobox}
 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.
+\vspace{-6pt}
 \begin{verbnobox}[\footnotesize\vbdelim]
 \readTABstack{<tabbed EOL-separated string>}
 \TABcellRaw[<row>,<column>]
@@ -237,6 +341,7 @@ The following macros can be used for parsing tabbed data outside of a
 \TABht{<row>}
 \TABdp{<row>}
 \end{verbnobox}
+\vspace{-12pt}
 
 \subsection{Command Examples}
 
@@ -249,10 +354,12 @@ Here, the optional argument \vb|[l]| defines the alignment of \textit{all} the
 columns as ``left.''  The default alignment is \vb|[c]|.
 
 \vb|\TABstackTextstyle{\scshape}|\\
-\vb|\tabbedShortunderstack[l]{This& Is &The\\Time & Of&Man's\\ Great&Dis&content}|
+\vb|\tabbedShortunderstack[l]{This& Is &The\\Time & Of&Man's\\ |\\
+\vb|  Great&Dis&content}|
 
 {\small\TABstackTextstyle{\scshape}%
-  \tabbedShortunderstack[l]{This& Is &The\\Time & Of&Man's\\ Great&Dis&content}}
+  \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|.
@@ -310,26 +417,25 @@ This is for stacking two items with \texttt{rlrl...} alignment pattern.
 
 \subsection*{Tabular Stack}
 
-This is for stacking two items with specifiable alignment pattern.
+This is for stacking items with specifiable alignment pattern.
+
+\vb|\TABbinary\TABstackMath\setstackgap{S}{0pt}\fboxrule=1pt\relax|\\
+\vb|\tabularShortstack{lcr}{1 + 2(4-3) &=& 6 - 6/2\\|\\
+\vb|  \TABcline{1-3}\kern6em & \triangle & \kern6em}|
 
-\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}}
+{\small\TABbinary\TABstackMath\setstackgap{S}{0pt}\fboxrule=1pt\relax
+\tabularShortstack{lcr}{1 + 2(4-3) &=& 6 - 6/2\\
+  \TABcline{1-3}\kern6em & \triangle & \kern6em}}
 
 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 
+the equal sign would have to have been explicitly defined as \vb|={}| 
+  (in accordance with the \vb|\TABunaryLeft| default setting of the package).  
+Negative vertical stacking gap, while not used here, is a perfectly 
   acceptable syntax and can be used to achieve overlap, if desired.
 
 \subsection*{Fixed Tab Width (equal width columns, based on largest)}
@@ -356,22 +462,32 @@ By default, for the parsing of columns within a given row, this package employs
 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 
+It can be any of various tokens\footnote{%
+Since \tst{} uses the \loi{} package for parsing rows and columns, 
+  see the \loi{} package documentation for limitations on the tokens that
+  can be used as a valid parsing separator.}
+, including  a space token, if one wishes to 
   parse a space-separated list of columns.  
 \end{sloppypar}
 
-\subsection*{TABstacks Inside the \texttt{tabular} Environment}
+\subsection*{TABstacks Inside the \texttt{tabular} or \texttt{align} 
+  Environments}
 
 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|{}|:
+  \vb|tabular|, \vb|align|, or other similar environments, one 
+  \textbf{no longer}\footnote{%
+  As of version 2.10, the problem of properly scoping TABstack argument
+  was resolved with the use of ``brace hacks'' described on p.\,385 of the 
+  \TeX book, and suggested to the author by Prof. Enrico Gregorio.
+}
+  needs to 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}}\\
+\tabularCenterstack{lr}{a_1 & 12\\c & 1234} & \
+\tabularCenterstack{rl}{a_1 & 12\\c & 1234}\\
 \hline
 \end{tabular}
 }
@@ -381,8 +497,8 @@ Left Eqn. & Right Eqn.\\
 \begin{tabular}{c|c}
 Left Eqn. & Right Eqn.\\
 \hline
-{\tabularCenterstack{lr}{a_1 & 12\\c & 1234}} & 
-{\tabularCenterstack{rl}{a_1 & 12\\c & 1234}}\\
+\tabularCenterstack{lr}{a_1 & 12\\c & 1234} & 
+\tabularCenterstack{rl}{a_1 & 12\\c & 1234}\\
 \hline
 \end{tabular}
 }
@@ -540,7 +656,7 @@ Since the \vb|\readTABstack| macro, itself, neither knows nor determines the
 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|.
+  with the optional argument to \vb|\TABcellBox|.
 
 Note that the height/depth of the \vb|\TABcellBox| reflects the height and
   depth of the row content of the TABstack.  
@@ -624,15 +740,13 @@ However, in that case, \vb|\TABcells{2}| would still, in fact, yield
 
 \section{Absent Features/Tricky Syntax}
 
-\textbf{1. Nothing Equivalent to} \vb|\hline| or \vb`|`
+\textbf{1. Nothing Equivalent to} \vb`|`
 
 This is not a bug, but rather a notation of a missing feature.  Currently
-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 
+vertical lines may \textbf{not} be added to a tabular stack 
   with the use of \vb`|` elements in the column specifier.
 
-\textbf{2. Empty Items Are Not Ignored (by Default)}
+\textbf{2. Trailing Row Separator/Empty Items Are Not Ignored (by Default)}
 
 The \loi{} package used to parse TABstack input, does not, by default,
   ignore empty items.
@@ -641,12 +755,12 @@ Take, for example, the well formed TABstack invocation,
 
 \vb|\tabularLongstack{rc}{11&12\\21&22\\31&32}|.
 
-Adding a trailing \vb|\\| to the input, as in:
+Adding a trailing \vb|\\| row separator to the input, as in:
 
 \vb|\tabularLongstack{rc}{11&12\\21&22\\31&32\\}|,
 
 however, breaks the parsing because 2 columns of data are expected
-  following the final \vb|\\| (even though such syntax is accepted
+  following the final \vb|\\| (even though such syntax is benign
   in, for example, the \texttt{tabular} environment).
 This syntax can be immediately made acceptable by
   invoking the \loi{} declaration \cmd{ignoreemptyitems}, in which case
@@ -663,11 +777,22 @@ To make this latter case work, when empty items are ignored, an
 
 \vb|\tabularLongstack{rc}{11&12\\21&{}\\31&32\\}|.
 
-These problems can be wholly avoided if care is used in the
-  construction of TABstack input.
+As of V2.1, the case of the trailing row separator can also be addressed 
+  in a 2nd way, if the \texttt{TABcline} package option has been
+  declared.
+In that case, the switch \cmd{relaxTABsyntax} will automatically
+  add the necessary column separators to \tst{} macro input, in 
+  order to avoid compilation error for the case of a trailing row
+  separator.
+See section~\ref{s:rtx} for more details.
+
+These problems arising from syntax can be wholly avoided, 
+  without the need to resort to
+  \cmd{ignoreemptyitems} or \cmd{relaxTABsyntax}, if care is used in the
+  construction of the TABstack input.
 
 \endvbdelim
-\section*{Acknowledgements}
+\section*{Acknowledgments}
 
 I would like to thank Christian Tellechea for his development of the 
   \loi{} package (which was directly inspired by my deficient
@@ -681,6 +806,9 @@ 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|
 
+Professor Enrico Gregorio is a constant source of knowledge and assistance
+  for which I am very grateful.
+
 \section{Code Listing}
 
 \verbfilenobox[\footnotesize]{tabstackengine.sty}