From 9c4953f7ee1a441f6db0c463d8e21c09513a0386 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 11 Feb 2014 23:44:27 +0000 Subject: tabstackengine (11feb14) git-svn-id: svn://tug.org/texlive/trunk@32944 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/tabstackengine/tabstackengine.tex | 477 +++++++++++++++++++++ 1 file changed, 477 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex (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 new file mode 100644 index 00000000000..81264dd36cd --- /dev/null +++ b/Master/texmf-dist/doc/latex/tabstackengine/tabstackengine.tex @@ -0,0 +1,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} + + + -- cgit v1.2.3