summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/mathtools/mathtools.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-03-25 03:01:53 +0000
committerNorbert Preining <norbert@preining.info>2020-03-25 03:01:53 +0000
commite32477e40d853a81951c9811f8554455dbff4014 (patch)
tree12744b350742c71cbb3c768354084a5c50369ce7 /macros/latex/contrib/mathtools/mathtools.dtx
parente9af7499b89170ca5c737240b0cdb9563dcf6c5a (diff)
CTAN sync 202003250301
Diffstat (limited to 'macros/latex/contrib/mathtools/mathtools.dtx')
-rw-r--r--macros/latex/contrib/mathtools/mathtools.dtx296
1 files changed, 267 insertions, 29 deletions
diff --git a/macros/latex/contrib/mathtools/mathtools.dtx b/macros/latex/contrib/mathtools/mathtools.dtx
index 0a08c4fb26..472c713942 100644
--- a/macros/latex/contrib/mathtools/mathtools.dtx
+++ b/macros/latex/contrib/mathtools/mathtools.dtx
@@ -1,7 +1,8 @@
% \iffalse meta-comment
%
% Copyright (C) 2004-2011 by Morten Hoegholm
-% Copyright (C) 2012- by Lars Madsen
+% Copyright (C) 2012-2019 by Lars Madsen
+% Copyright (C) 2020 by Lars Madsen, The LaTeX3 team
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
@@ -68,7 +69,7 @@
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
-\Msg{* Package: mathtools 2020/01/17 v1.23}
+\Msg{* Package: mathtools 2020/03/24 v1.24}
\Msg{************************************************************************}
\keepsilent
@@ -79,7 +80,8 @@
This is a generated file.
Copyright (C) 2002-2011 by Morten Hoegholm
-Copyright (C) 2012- by Lars Madsen
+Copyright (C) 2012-2019 by Lars Madsen
+Copyright (C) 2020 by Lars Madsen, the LaTeX3 project
This work may be distributed and/or modified under the
@@ -93,7 +95,7 @@ LaTeX version 2005/12/01 or later.
This work has the LPPL maintenance status "maintained".
This Current Maintainer of this work is
-Lars Madsen
+Lars Madsen and the LaTeX3 project
This work consists of the main source file mathtools.dtx
and the derived files
@@ -131,7 +133,7 @@ and the derived files
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{mathtools.drv}%
- [2020/01/17 v1.23 mathematical typesetting tools]
+ [2020/03/24 v1.24 mathematical typesetting tools]
\documentclass{ltxdoc}
\IfFileExists{fourier.sty}{\usepackage{fourier}}{}
\addtolength\marginparwidth{-25pt}
@@ -319,12 +321,12 @@ colorlinks,
%
% \GetFileInfo{mathtools.drv}
%
-% \CheckSum{3144}
+% \CheckSum{3333}
%
% \title{The \pkg{mathtools} package\thanks{This file has version number
% \fileversion, last revised \filedate.}}
%
-% \author{Morten H\o gholm, Lars Madsen}
+% \author{Morten Høgholm, Lars Madsen and the \LaTeX3 project}
% \date{\filedate}
%
% \maketitle
@@ -354,19 +356,20 @@ colorlinks,
% lists over the years, although more often than not without being
% released as stand-alone packages.
%
-%
% The \pkg{mathtools} package is exactly what its name implies: tools
% for mathematical typesetting. It is a collection of many of these
% often needed small tweaks---with some big tweaks added as well. It
% can only do so by having harvesting newsgroups for code and/or you
% writing the maintainers with wishes for code to be included, so if
% you have any good macros or just macros that help you when writing
-% mathematics, then don't hesitate to report them. It is
-% easiest to just contact Lars Madsen at
-% \begin{quote}\email{daleif@math.au.dk}\end{quote}
-% This is of course also the address to use in case of bug reports.
-% Please put `\texttt{mathtools}' in the subject line.
-%
+% mathematics, then don't hesitate to report them.
+%
+% As of 2020, \pkg{mathtools} (and \pkg{empheq}) is now hosted at the
+% \LaTeX3 team GitHub at
+% \begin{center}
+% \url{https://github.com/latex3/mathtools}
+% \end{center}
+% So if you have any issue, feel free to register an issue there.
%
% \medskip\noindent
% Update 2013: We now make \cs{(}\cs{)} and \cs[\cs]
@@ -1117,6 +1120,12 @@ colorlinks,
% A &\xrightleftharpoons[below]{above} B &
% A &\xleftrightharpoons[below]{above} B \\
% \end{align*}
+% Change in 2020: In \cs{xLeftarrow}, \cs{xRightarrow} and
+% \cs{xLeftrightarrow} we added a space to the argument(s), making
+% the arrow slightly longer and moving the argument away from the
+% large arrow head.
+%
+%
%
%
%
@@ -1748,16 +1757,22 @@ colorlinks,
% doing this as a normal line in an alignment leaves us with excessive
% space which \verb?\shortvdotswithin{=}? takes care with for us.
%
-% \verb?\shortvdotswithin{=}? corresponds to
+% The macro call \verb?\shortvdotswithin{=}? corresponds to
+% \begin{verbatim}
+% \MTFlushSpaceAbove
+% & \vdotswithin{=}
+% \MTFlushSpaceBelow
+% \end{verbatim}
+% whereas \verb?\shortvdotswithin*{=}? is the case with
% \begin{verbatim}
% \MTFlushSpaceAbove
-% & \vdotswithin{=} \\
+% \vdotswithin{=} &
% \MTFlushSpaceBelow
% \end{verbatim}
-% whereas \verb?\shortvdotswithin*{=}? is the case with
-% \verb?\vdotswithin{=} & \\?. This also means one cannot write more
-% on the line when using \verb?\shortvdotswithin? or the starred
-% version. But one can de-construct the macro and arrive at
+% Note how \verb?\MTFlushSpaceBelow? implicitly adds a \verb?\\? at
+% the end of the line. Thus one cannot have more on the line when
+% using \verb?\shortvdotswithin? or the starred version. But, if
+% needed, one can de-construct the macro and arrive at
% \begin{verbatim}
% \begin{alignat*}{3}
% A&+ B &&= C &&+ D \\
@@ -2635,8 +2650,8 @@ colorlinks,
% \subsection{Split fractions}
%
% \begin{codesyntax}
-% \SpecialUsageIndex{\splitfrac}\cs{splitfrac}\marg{numer}\marg{denom}\texttt{~~}
-% \SpecialUsageIndex{\splitdfrac}\cs{splitdfrac}\marg{numer}\marg{denom}
+% \SpecialUsageIndex{\splitfrac}\cs{splitfrac}\marg{start line}\marg{continuation}\\
+% \SpecialUsageIndex{\splitdfrac}\cs{splitdfrac}\marg{start line}\marg{continuation}
% \end{codesyntax}
% \cttPosting{Michael J.~Downes}{2001/12/06}
% These commands provide split fractions e.g., multiline fractions:
@@ -2666,6 +2681,160 @@ colorlinks,
% }
% {z}
% \]
+% The difference between \cs{splitfrac} and \cs{splitdfrac} is that
+% the former forces its arguments to be typeset in text-mode math, the
+% latter does not.
+%
+% \medskip\noindent \textbf{Note:} If you try to nest \cs{splitfrac}
+% inside each other you may need to add \cs{mathstrut} to the first
+% argument of the nested fraction to get the spacing look even. It is
+% not added by default as often a more cramped looked is desired:
+% \begin{verbatim}
+% \[
+% \frac{
+% \splitfrac{xy + xy + xy + xy + xy}
+% {
+% \splitfrac{xy + xy + xy + xy + xy}
+% {+ xy + xy + xy + xy}
+% }
+% }
+% {z}
+% =\frac{
+% \splitfrac{xy + xy + xy + xy + xy}
+% {
+% \splitfrac{\mathstrut xy + xy + xy + xy + xy}
+% {+ xy + xy + xy + xy}
+% }
+% }
+% {z}
+% \]
+% \end{verbatim}
+% \[
+% \frac{
+% \splitfrac{xy + xy + xy + xy + xy}
+% {
+% \splitfrac{xy + xy + xy + xy + xy}
+% {+ xy + xy + xy + xy}
+% }
+% }
+% {z}
+% =\frac{
+% \splitfrac{xy + xy + xy + xy + xy}
+% {
+% \splitfrac{\mathstrut xy + xy + xy + xy + xy}
+% {+ xy + xy + xy + xy}
+% }
+% }
+% {z}
+% \]
+% Note how the line spaces aren't even on the left hand side.
+%
+% For even more control, one can use \env{aligned} or \env{gathered}
+% instead of \cs{splitfrac}.
+%
+%
+% \newpage
+%
+% \section{New additions}
+%
+% \subsection{Variable math strut}
+% \begin{codesyntax}
+% \SpecialUsageIndex{\xmathstrut}\cs{xmathstrut}\oarg{depth increase}\marg{increase}
+% \end{codesyntax}
+% \FeatureRequest{Frank Mittelbach}{2020} In typography we use
+% \emph{struts} to ensure specific line spacing. In text we have the
+% \cs{strut} and in math \cs{mathstrut}. Both have no width, but
+% equals the height and depth of an »(« from the current text/math
+% font and size. In math we often need to make minute adjustments in
+% macro definitiones etc. The \emph{extended} math strut
+% \cs{xmathstrut} allows to \emph{increase} (decrease if negative)
+% the math strut in two ways.
+%
+% For an \meta{increase} (a decimal number), say~\verb|0.1|,
+% \begin{center}
+% \verb|\xmathstrut{0.1}|
+% \end{center}
+% will give you a new strut where 10\% of the \emph{total height of
+% the normal math stut} (\verb|\mathstrut=\mathstrut{0}|) will be
+% added to both \emph{the height} and \emph{the depth} of the
+% original strut (thus 20\% gets added in total). On the other hand
+% \begin{center}
+% \verb|\xmathstrut[0.2]{0.1}|
+% \end{center}
+% will result in a strut where 20\% is added to the depth and 10\% is
+% added to the height, resulting in a strut that is 30\% larger than
+% normal.
+%
+% The following example is inspired (with permission) from an example
+% showcasing \cs{xmathstrut} in the upcoming third edition of
+% \emph{The LaTeX Companion}. The example is very relevant as the
+% entries of the \env{cases(*)} environment are typeset in \emph{text
+% style} math and thus may end up looking quite
+% squished.\footnote{Which is why Frank suggested the macro
+% (including its implementation) in the first place.}
+% \[
+% \begin{cases*}
+% \frac{\frac{ x-1 }{ x-\sin x} }{ \sqrt{ 1 -x }} & $x >0$ \\
+% 0 & otherwise
+% \end{cases*}
+% \qquad\text{vs.}\qquad
+% \begin{cases*}
+% \frac{\frac{ \xmathstrut{0.1} x-1 }{ \xmathstrut{0.25} x-\sin x} }{\xmathstrut{0.4} \sqrt{ 1 -x }} & $x >0$ \\
+% 0 & otherwise
+% \end{cases*}
+% \]
+% \begin{verbatim}
+% \[ \begin{cases*}
+% \frac{\frac{ x-1 }{ x-\sin x} }{ \sqrt{ 1 -x }} & $x >0$ \\
+% 0 & otherwise
+% \end{cases*}
+% \qquad\text{vs.}\qquad
+% \begin{cases*}
+% \frac{ \frac{ \xmathstrut{0.1} x-1 }
+% { \xmathstrut{0.25} x-\sin x} }
+% {\xmathstrut{0.4} \sqrt{ 1 -x } } & $x >0$ \\
+% 0 & otherwise
+% \end{cases*} \]
+% \end{verbatim}
+%
+% To showcase the optional argument, it is
+% probably easiest to make the strut visible. Here you'll see that
+% \verb|\mathstrut| and \verb|\xmathstrut{0}| is the same:
+% \newcommand\vfb[1]{\begingroup\fboxsep=0pt\boxed{\,#1\,}\endgroup}
+% \[
+% \llap{\rlap{\rule{18mm}{0.1pt}}\quad}a \vfb{\mathstrut} \ \vfb{\xmathstrut{0}}\
+% \vfb{\xmathstrut{0.5} } \ \vfb{\xmathstrut{-0.1} }\ \vfb{\xmathstrut[0.5]{0}} a
+% \]
+% \begin{verbatim}
+% \newcommand\vfb[1]{\begingroup\fboxsep=0pt\boxed{\,#1\,}\endgroup}
+% \[
+% a \vfb{\mathstrut} \ % normal strut
+% \vfb{\xmathstrut{0}} \ % just 0 => normal strut
+% \vfb{\xmathstrut{0.5} } \ % twice as large 50% + 50%
+% \vfb{\xmathstrut{-0.1} } \ % negative gives something smaller
+% \vfb{\xmathstrut[0.5]{0}} a % change only the depth
+% \]
+% \end{verbatim}
+% -- the last box showcases a strut where we have only changed the
+% depth of the strut. One can see \verb|\xmathstrut[B]{0}| kind of the
+% opposite of \verb|\smash[b]{...}|, the former makes the depth larger
+% and the latter ignores the depth.
+%
+%
+%
+%
+%
+%
+%
+%
+%
+%
+%
+%
+%
+%
+%
+%
%
%
%
@@ -2676,6 +2845,10 @@ colorlinks,
%
%
%
+%
+%
+%
+%
%
%
%
@@ -2789,10 +2962,12 @@ colorlinks,
% Ellen Swanson,
% \emph{Mathematics into type}.
% American Mathematical Society, updated edition, 1999.
-% Updated by Arlene O'Sean and Antoinette Schleyer.
+% Updated by Arlene O'Sean and Antoinette Schleyer. Available from
+% the AMS at \url{http://www.ams.org/arc/styleguide/mit-2.pdf}
+%
% \bibitem{TBT}
% Victor Eijkhout, \emph{\TeX\ by Topic, A Texnician's Reference}, 2007.
-% Freely available at \url{http://ctan.org/tex-archive/info/texbytopic}.
+% Freely available at \url{https://ctan.org/pkg/texbytopic}.
% \end{thebibliography}
%
%
@@ -2806,7 +2981,7 @@ colorlinks,
% \begin{macrocode}
%<*package>
\ProvidesPackage{mathtools}%
- [2020/01/17 v1.23 mathematical typesetting tools]
+ [2020/03/24 v1.24 mathematical typesetting tools]
% \end{macrocode}
% \changes{v1.10}{2011/02/12}{Might as well make sure that we need the
% latest version of \texttt{mhsetup}}
@@ -3361,17 +3536,20 @@ colorlinks,
% \begin{macro}{\xLeftrightarrow}
%
% These are straight adaptions from \pkg{amsmath}.
+% \changes{v1.24}{2020/03/13}{Added spaces to move the argument away
+% from the arrow head in \cs{xLeftarrow}, \cs{xRightarrow} and
+% \cs{xLeftrightarrow}. Suggested by FM}
% \begin{macrocode}
\providecommand*\xleftrightarrow[2][]{%
\ext@arrow 3095\MT_leftrightarrow_fill:{#1}{#2}}
\def\MT_leftrightarrow_fill:{%
\arrowfill@\leftarrow\relbar\rightarrow}
\providecommand*\xLeftarrow[2][]{%
- \ext@arrow 0055{\Leftarrowfill@}{#1}{#2}}
+ \ext@arrow 0055{\Leftarrowfill@}{\ #1}{\ #2}}
\providecommand*\xRightarrow[2][]{%
- \ext@arrow 0055{\Rightarrowfill@}{#1}{#2}}
+ \ext@arrow 0055{\Rightarrowfill@}{#1\ }{#2\ }}
\providecommand*\xLeftrightarrow[2][]{%
- \ext@arrow 0055{\Leftrightarrowfill@}{#1}{#2}}
+ \ext@arrow 0055{\Leftrightarrowfill@}{\ #1\ }{\ #2\ }}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6138,7 +6316,7 @@ colorlinks,
{\textstyle#1\quad\hfill}%
{\textstyle\hfill\quad\mathstrut#2}%
}
-\newcommand*\splitdfrac[2]{%
+\newcommand*\splitdfrac[2]{%
\genfrac{}{}{0pt}{0}{#1\quad\hfill}{\hfill\quad\mathstrut #2}%
}
% \end{macrocode}
@@ -6266,6 +6444,66 @@ colorlinks,
% \end{macrocode}
% \end{macro}
%
+% \section{Additional features 2020–}
+%
+% The selection below is meant for additions addeed 2020 onwards that
+% are not integrated into existing macros.
+%
+% \subsection{\cs{xmathstrut}}
+%
+% \begin{macro}{\xmathstrut@box}
+% \begin{macro}{\xmathstrut@dim}
+% \begin{macro}{\xmathstrut}
+% \begin{macro}{\xmathstrut@}
+% \begin{macro}{\xmathstrut@do}
+% Suggested and implemented by Frank Mittelbach. The basic idea is to
+% add (or subtract) a fraction of the total height of the normal math
+% strut to both the height and depth of the new strut. The input from
+% the user is suppose to be a decimal number. The value zero results
+% in no change compared to the normal math strut.
+% \changes{v1.24}{2020/03/06}{Added \cs{xmathstrut}}
+% \begin{macrocode}
+\newbox\xmathstrut@box
+\newdimen\xmathstrut@dim
+\def\xmathstrut{\@dblarg\xmathstrut@}
+\def\xmathstrut@[#1]#2{%
+ \def\xmathstrut@dp{#1}%
+ \vphantom{\mathpalette\xmathstrut@do{#2}}%
+}
+% \end{macrocode}
+% The algorithm is simple. Start by recording the size (a box) of \verb|$($|
+% in the current style (via \verb|\mathpalette|)
+% \begin{macrocode}
+\def\xmathstrut@do#1#2{%
+ \setbox\xmathstrut@box\hbox{$#1($}%)%emacs
+ \xmathstrut@dim\dimexpr\ht\xmathstrut@box+\dp\xmathstrut@box\relax
+% \end{macrocode}
+% Then manipulate the size of the box by adding the user input times
+% the total height of the original box to the height and depth
+% respectfully.
+% \begin{macrocode}
+ \ht\xmathstrut@box\dimexpr\ht\xmathstrut@box
+ +#2\xmathstrut@dim
+ \relax
+ \dp\xmathstrut@box\dimexpr\dp\xmathstrut@box
+ +\xmathstrut@dp\xmathstrut@dim
+ \relax
+% \end{macrocode}
+% In the end ship the modified box (it is typeset inside a \verb|\vphantom|).
+% \begin{macrocode}
+ \box\xmathstrut@box}
+
+% \end{macrocode}
+% Do note that this means that for \verb|\xmathstrut{0.1}| 10\% is
+% added twice. But it make explaining \verb|\xmathstrut[0.2]{0.1}| a
+% lot easier as it is just 10\% added to the height and 20\% added to
+% the depth.
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% This is the end of the \pkg{mathtools} package.
% \begin{macrocode}
%</package>