texlive[59944] Master/texmf-dist: stackengine (15jul21)
commits+karl at tug.org
commits+karl at tug.org
Thu Jul 15 22:04:14 CEST 2021
Revision: 59944
http://tug.org/svn/texlive?view=revision&revision=59944
Author: karl
Date: 2021-07-15 22:04:14 +0200 (Thu, 15 Jul 2021)
Log Message:
-----------
stackengine (15jul21)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf
trunk/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
trunk/Master/texmf-dist/tex/latex/stackengine/stackengine.sty
Modified: trunk/Master/texmf-dist/doc/latex/stackengine/stackengine.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/stackengine/stackengine.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/stackengine/stackengine.tex 2021-07-15 20:03:48 UTC (rev 59943)
+++ trunk/Master/texmf-dist/doc/latex/stackengine/stackengine.tex 2021-07-15 20:04:14 UTC (rev 59944)
@@ -32,7 +32,7 @@
\rule{0em}{.7em}\small Highly customized stacking of objects, insets,
baseline changes, \textit{etc.}\\
\rule{0em}{2.7em}\large Steven B. Segletes\\
-steven.b.segletes.civ at mail.mil\\
+SSegletes at verizon.net\\
\rule{0em}{1.7em}\today\\
\stackengineversionnumber%
\end{center}
@@ -55,13 +55,13 @@
\Huge\setstackgap{S}{.4ex}
\setstackgap{L}{2.2ex}\normalsize
-In this package, ``Short'' refers to squeezing the extra space out of
-glyphs comprising the stack, so that the inter-item gap is solely what
+In this package, ``Short'' refers to squeezing or growing the empty space
+between glyphs comprising the stack, so that the inter-item gap is solely what
is set. Likewise, ``Long'' refers to a stack kept at constant
inter-item baseline spacing. Let's look at the following two
examples to see this clearly.
-Notice the consistent inter-item gap on a short stack:
+Notice the consistent inter-item gap between short stack items:
\Huge
\Shortstack{{\fbox{t}} {\fbox{y}} {\fbox{k}} {\fbox{e}}}%
{\quad\setstackgap{S}{\dimexpr.4ex+1.2pt}\Shortstack{t y k e}}
@@ -244,8 +244,10 @@
settings:
\itshape
-\vb|\stackMath|\\
-\vb|\stackText|\\
+\vb|\stackMath|\qquad \textup{and}\qquad \vb|\lstackMath|
+ \quad\textup{(global/local declaration)}\\
+\vb|\stackText|\qquad \textup{and}\qquad \vb|\lstackText|
+ \quad\textup{(global/local declaration)}\\
\vb|\strutlongstacks{T| or \vb|F}|\\
\vb|\strutshortanchors{T| or \vb|F}|\\
\vb|\setstackEOL{|end-of-line character\vb|}|
@@ -262,7 +264,9 @@
even within a macro, will continue to persist until later changed. If
you would like to have a single application stacked in math mode, without
changing the default mode setting, one could use the \vb|\ensurestackMath{}|
-macro (see \ref{s:esm}).
+macro (see \ref{s:esm}), or else the local versions that are scope
+limited, \vb|\lstackMath|\margcmd{lstackMath} and/or
+\vb|\lstackText|\margcmd{lstackText}.
By default, stacks made by {\ste} are set in unframed boxes that are
flush with the top and bottom of the stack. The \vb|\addstackgap|
@@ -301,12 +305,12 @@
the four cited stacking commands, as well as their derivatives
\vb|\Centerstack| and \vb|\Vectorstack|. (Note: other stacking commands
in the \vb|\stackon| / \vb|\stackunder| family will not ignore, but
-retain spaces in their arguments, since there is no issue associated
-with EOL seperators.)
+retain leading/trailing spaces in their arguments, since there are no
+EOL separators present.)
Note that these five mode-setting commands are not themselves parameters
to be part of a {\ste} argument, but are instead to be issued as separate
-commands prior to the invocation of a desired stacking macro.
+declarative commands prior to the invocation of a desired stacking macro.
\subsection{Stacking Macros}
@@ -381,8 +385,8 @@
While the stacking macros in the following sections offer the convenience
of a condensed syntax, which can be useful within your document, it may be
preferable to use the \vb|\stackengine| macro to create your own
-stacking macros, since one can achieve the stacking result without
-having to modify the package defaults.
+stacking macros, since one can achieve the stacking result regardless of
+how the package defaults are set.
\subsubsection{\cmd{stackon} and \cmd{stackunder}\label{s:sou}}
@@ -394,11 +398,11 @@
\itshape
\vb|\stackon[|stacklength%
\vb|]{|anchor%
- \vb|}{|item
+ \vb|}{|item%
\vb|}|\\
\vb|\stackunder[|stacklength%
\vb|]{|anchor%
- \vb|}{|item
+ \vb|}{|item%
\vb|}|
\upshape
@@ -464,8 +468,8 @@
\vb|\Longstack|, \vb|\Shortstack|, \vb|\Longunderstack|, and
\vb|\Shortunderstack| with a row separator different than a space.
The \vb|[usestackEOL]| package option will make the EOL character within
-these stacking commands a \vb|\\| character instead of a space. Here
-are an example of equivalent stack arguments for two different EOL
+these stacking commands a \vb|\\| macro instead of a space. Here
+is an example of equivalent stack arguments for two different EOL
characters:
Space EOL:~~~~\vb|{a {b c} {\P} $\beta^2$ ANCHOR}|\\
@@ -632,7 +636,7 @@
The macro \vb|\ensurestackMath{}| macro is used to force its argument
(a stacking command) to be processed in math mode, without setting
the global default stacking
-mode to math mode (otherwise accomplished via \vb|\stackMath|). Note
+mode to math mode (accomplished via \vb|\stackMath|). Note
that this macro does \textbf{not} ensure that
all elements of its argument are processed in math mode (\textit{i.e.},
it does not use, nor is it a replacement for \vb|\ensuremath|), but
@@ -708,8 +712,8 @@
While this command was designed with inlaid images in mind (see
\S\ref{s:ii}), there is nothing that prevents its use to inlay
character glyphs upon each other, as in
-\stackinset{c}{}{c}{-.25ex}{*}{O}, accomplished with
-\vb|\stackinset{c}{}{c}{-.25ex}{*}{O}|.
+\stackinset{c}{}{c}{-.3ex}{*}{O}, accomplished with
+\vb|\stackinset{c}{}{c}{-.3ex}{*}{O}|.
\subsubsection{\cmd{addstackgap}\label{s:asg}}
\def\stacktype{S}
@@ -1131,7 +1135,7 @@
\section{Image Insets\label{s:ii}}
\setstackgap{L}{18pt}%
-The command \vb|\stackinset| allows images to be
+The command \vb|\stackinset| allows images (or other data) to be
stacked atop one another, to produce the effect of an inset image. In
addition to specifying the two images, the effect can be tailored by
specifying the vertical and horizontal offset of the inset image.
@@ -1277,13 +1281,15 @@
\begin{enumerate}
-\item Arguments to stacking commands are only taken in math mode, by
-default, following the invocation of the \vb|\stackMath| macro.
+\item Arguments to stacking commands are only taken in math mode,
+\textit{by default}, following the invocation of the
+\vb|\stackMath| macro.
-\item The \vb|\stackMath| and \vb|\stackText| macros are not to be
-used within stacking arguments, but are invoked prior to stacking, to
-set the default manner in which stacking arguments are subsequently
-processed.
+\item The \vb|\stackMath| and \vb|\stackText| macros, as well as
+their locally scoped counterparts, \vb|\lstackMath| and \vb|\lstackText|,
+are not to be used within stacking arguments, but are invoked prior
+to stacking, to set the manner in which stacking arguments
+are subsequently processed.
\item As described in \S\ref{s:sls}, if the math argument has spaces in
a command which uses space-separated lists, or if the argument ends in a
@@ -1350,12 +1356,6 @@
current documentation, except for mention here. They are:
\begin{itemize}
-\item \vb|\def\usestackstrut{T/F}|. This definition is fully replaced
-by the mode setting given by the \vb|\strutshortanchors{T/F}| macro.
-The new name is less ambiguous and the macro form is chosen vis-\`a-vis
-the \vb|\def| form, because the macro represents a \textbf{mode} of
-stack construction, rather than an argument parameter.
-
\item \vb|\bottominset| and \vb|\topinset|. These
macros are subsumed by the much more versatile \vb|\stackinset| macro.
The replacement offers insets relative to not only the top and bottom,
@@ -1465,6 +1465,8 @@
\ref{s:nsc}, \ref{s:mm}\\
\cmd{Lstackgap}&\ref{s:parms}&\ref{s:st}, \ref{s:stackeng}, \ref{s:bbl},
\ref{s:nsc}, \ref{s:bc}\\
+\cmd{lstackMath}&\ref{s:sm}&\\
+\cmd{lstackText}&\ref{s:sm}&\\
\cmd{parenVectorstack}&\ref{s:csvs}&\\
\cmd{quietstack}&\ref{s:parms}&\ref{s:stackeng}, \ref{s:qs}\\
\cmd{savestack}&\ref{s:ss}&\ref{s:sanc}, \ref{s:svs}, \ref{s:cae},
Modified: trunk/Master/texmf-dist/tex/latex/stackengine/stackengine.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/stackengine/stackengine.sty 2021-07-15 20:03:48 UTC (rev 59943)
+++ trunk/Master/texmf-dist/tex/latex/stackengine/stackengine.sty 2021-07-15 20:04:14 UTC (rev 59944)
@@ -1,6 +1,6 @@
-\def\stackengineversionnumber{v4.01}
+\def\stackengineversionnumber{v4.1}
\ProvidesPackage{stackengine}
-[2017/02/13 \stackengineversionnumber\
+[2021/07/15 \stackengineversionnumber\
Stacking text and objects in convenient ways]
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
@@ -78,6 +78,16 @@
% \setlength, which could also cause potential problems with the
% calc package.
% -Changed \global\def to \gdef and \global\edef to \xdef.
+% V4.1 -Removed \widthof type measurements in \stackinset and
+% \stackengine, instead setting things in saveboxes from the
+% outset and using \wd, thereby only setting stacked content
+% once. This is helpful for speed and also if counters are
+% present in arguments, which are now incremented only once.
+% -Save and restore counter entering/exiting \@stack, which
+% favorably resolves issue of nesting for multi-row stacks.
+% -Introduce \lstackMath and \lstackText as local versions of
+% \stackMath and \stackText (which are global).
+% -Eliminated \usestackstrut (became internal \@usestackstrut)
\RequirePackage{etoolbox}
\RequirePackage{listofitems}% REQUIRES listofitems.sty AND listofitems.tex
\usepackage{calc}
@@ -91,6 +101,8 @@
\newlength\@stackedboxwidth
\newsavebox\@addedbox
\newsavebox\@anchorbox
+\newsavebox\@insetbox
+\newsavebox\@backgroundbox
\newsavebox\stackedbox
\newsavebox{\@centerbox}
\newcounter{ROWcellindex@}
@@ -113,7 +125,7 @@
\newcommand\@readMANYrows[1]{%
\expandafter\setsepchar\expandafter{\SEP at char}%
\readlist*\stack at arg{#1}%
- \xdef\stackengine at args{\stack at arglen}%
+ \edef\stackengine at args{\stack at arglen}%
}
%%%%%
@@ -162,18 +174,17 @@
\def\stacktype{S}% S for constant gap shortstack;
% L for constant baselineskip longstack
-% DEPRECATED USAGE \def\usestackstrut{}; INSTEAD USE \strutshortanchors{}
-%\def\usestackstrut{T}
-
%%%%% MODES
\newcommand\stackMath{\gdef\stack at delim{$}}
\newcommand\stackText{\gdef\stack at delim{}}
+\newcommand\lstackMath{\def\stack at delim{$}}
+\newcommand\lstackText{\def\stack at delim{}}
\stackText
\newcommand\strutlongstacks[1]{\def\@strutlongstacks{#1}}
\strutlongstacks{F}
-\newcommand\strutshortanchors[1]{\def\usestackstrut{#1}}
+\newcommand\strutshortanchors[1]{\def\@usestackstrut{#1}}
\strutshortanchors{T}
%%%%% MACROS
@@ -192,10 +203,10 @@
\sbox{\stackedbox}{%
\sbox{\@anchorbox}{\@STRT\stack at delim#2\stack at delim}%
\sbox{\@addedbox}{\@STRT\stack at delim#3\stack at delim}%
- \settowidth{\@stackedboxwidth}{\@STRT\stack at delim#2\stack at delim}%
+ \setlength{\@stackedboxwidth}{\wd\@anchorbox}%
\if F#7%
\ifdim\wd\@addedbox>\@stackedboxwidth%
- \settowidth{\@stackedboxwidth}{\stack at delim\@STRT#3\stack at delim}%
+ \setlength{\@stackedboxwidth}{\wd\@addedbox}%
\fi%
\fi%
\setlength{\@boxshift}{#1}%
@@ -216,7 +227,7 @@
\usebox{\@anchorbox}%
\hspace{-.5\wd\@anchorbox}%
\hspace{-.5\wd\@addedbox}%
- \raisebox{\@boxshift}{\@STRT\stack at delim#3\stack at delim}%
+ \raisebox{\@boxshift}{\usebox{\@addedbox}}%
\hspace{-.5\wd\@addedbox}%
\hspace{.5\@stackedboxwidth}%
\else%
@@ -223,7 +234,7 @@
\if l#5%
\usebox{\@anchorbox}%
\hspace{-\wd\@anchorbox}%
- \raisebox{\@boxshift}{\@STRT\stack at delim#3\stack at delim}%
+ \raisebox{\@boxshift}{\usebox{\@addedbox}}%
\hspace{-\wd\@addedbox}%
\hspace{\@stackedboxwidth}%
\else%
@@ -232,7 +243,7 @@
\hspace{-\wd\@anchorbox}%
\usebox{\@anchorbox}%
\hspace{-\wd\@addedbox}%
- \raisebox{\@boxshift}{\@STRT\stack at delim#3\stack at delim}%
+ \raisebox{\@boxshift}{\usebox{\@addedbox}}%
\fi%
\fi%
\fi%
@@ -255,6 +266,7 @@
\newcommand*\Longunderstack[2][\stackalignment]{\@stack{#1}{#2}{U}{L}}
\newcommand*\@stack[4]{%
+ \edef\sv at stackindex{\the at stackindex}%
\bgroup% SO AS NOT TO INTERFERE WITH loi's \setsepchar
\@readMANYrows{#2}%
\if U#3%
@@ -286,6 +298,7 @@
}%
\if F\quietstack\usebox{\stackedbox}\fi%
\egroup%
+ \setcounter{@stackindex}{\sv at stackindex}%
}
% PERHAPS THESE SIX MACROS CAN BE REPLACED BY \toplap AND \bottomlap
@@ -312,12 +325,12 @@
\newcommand*\stackanchor[3][\stackgap]{%
\setlength{\stack at tmplength}{#1}%
\setlength{\stack at tmplength}{.5\stack at tmplength}%
- \if T\usestackstrut%
+ \if T\@usestackstrut%
\if S\stacktype\addtolength{\stack at tmplength}%
{.5\ht\strutbox-.5\dp\strutbox}\fi%
\fi%
\stackengine{\stack at tmplength}{}{#2}{O}{\stackalignment}{T}{F}{\stacktype}%
- \if T\usestackstrut%
+ \if T\@usestackstrut%
\if S\stacktype\addtolength{\stack at tmplength}%
{-\ht\strutbox+\dp\strutbox}\fi%
\fi%
@@ -350,28 +363,26 @@
%\stackinset{l/c/r}{x}{b/c/t}{y}{inset}{anchor}
\newcommand*\stackinset[6]{%
- \def\conditioned at inset{\stack at delim#5\stack at delim}%
- \def\conditioned at anchor{\stack at delim#6\stack at delim}%
+ \sbox\@backgroundbox{\stack at delim#6\stack at delim}%
+ \sbox\@insetbox{\stack at delim#5\stack at delim}%
\ifstrequal{#4}{}%
{\setlength{\stack at tmplength}{0pt}}%
{\setlength{\stack at tmplength}{#4}}%
\if c#3%
- \setlength{\temp at stkl}{%
- \heightof{\conditioned at anchor}+\depthof{\conditioned at anchor}%
- -\heightof{\conditioned at inset}-\depthof{\conditioned at inset}}%
+ \setlength{\temp at stkl}{\ht\@backgroundbox+\dp\@backgroundbox%
+ -\ht\@insetbox-\dp\@insetbox}%
\addtolength{\stack at tmplength}{.5\temp at stkl}%
\fi%
\ifstrequal{#2}{}{\def\stack at tmp{0pt}}{\def\stack at tmp{#2}}%
\def\stack at lroffset{\rule{\stack at tmp}{0pt}}%
- \addtolength{\stack at tmplength}{%
- \heightof{\conditioned at inset}+\depthof{\conditioned at inset}}%
+ \addtolength{\stack at tmplength}{\ht\@insetbox+\dp\@insetbox}%
\if c#1%
- \def\conditioned at inset{\stack at lroffset\stack at lroffset#5}%
+ \def\conditioned at inset{\stack at lroffset\stack at lroffset\usebox{\@insetbox}}%
\else%
- \def\conditioned at inset{\stack at lroffset#5\stack at lroffset}%
+ \def\conditioned at inset{\stack at lroffset\usebox{\@insetbox}\stack at lroffset}%
\fi%
- \stackengine{-\stack at tmplength}{#6}{\conditioned at inset}%
- {\inset at valign{#3}}{#1}{\quietstack}{T}{S}%
+ \stackengine{-\stack at tmplength}{\usebox{\@backgroundbox}}%
+ {\conditioned at inset}{\inset at valign{#3}}{#1}{\quietstack}{T}{S}%
}
\def\inset at valign#1{\if t#1O\else U\fi}
More information about the tex-live-commits
mailing list.