From bb7ef4b993327dd47fb8f1848e1603f93f12eb64 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 5 Mar 2018 22:11:19 +0000 Subject: tabstackengine (5mar18) git-svn-id: svn://tug.org/texlive/trunk@46848 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/tabstackengine/tabstackengine.pdf | Bin 569190 -> 598495 bytes .../doc/latex/tabstackengine/tabstackengine.tex | 208 +++++++++++++++++---- 2 files changed, 168 insertions(+), 40 deletions(-) (limited to 'Master/texmf-dist/doc/latex/tabstackengine') diff --git a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf index c288ddfd20f..66dd8ba232b 100644 Binary files a/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf and b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.pdf differ 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{} \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 F} \TABstackMath @@ -216,15 +318,17 @@ The package also provides a set of declarations that can be used to define the \TABstackMathstyle{} \TABstackTextstyle{} \clearTABstyle -\setstackEOL{} ! +\setstackEOL{} !1 \setstackTAB{} \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{} \TABcellRaw[,] @@ -237,6 +341,7 @@ The following macros can be used for parsing tabbed data outside of a \TABht{} \TABdp{} \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{|\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} -- cgit v1.2.3