summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/mathtools/mathtools.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/mathtools/mathtools.dtx')
-rw-r--r--Master/texmf-dist/source/latex/mathtools/mathtools.dtx307
1 files changed, 238 insertions, 69 deletions
diff --git a/Master/texmf-dist/source/latex/mathtools/mathtools.dtx b/Master/texmf-dist/source/latex/mathtools/mathtools.dtx
index eb20187e894..28526b0a88c 100644
--- a/Master/texmf-dist/source/latex/mathtools/mathtools.dtx
+++ b/Master/texmf-dist/source/latex/mathtools/mathtools.dtx
@@ -69,7 +69,7 @@
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
-\Msg{* Package: mathtools 2021/04/12 v1.27}
+\Msg{* Package: mathtools 2022/06/29 v1.29}
\Msg{************************************************************************}
\keepsilent
@@ -133,7 +133,7 @@ and the derived files
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{mathtools.drv}%
- [2022/02/07 v1.28a mathematical typesetting tools]
+ [2022/06/29 v1.29 mathematical typesetting tools]
\documentclass{ltxdoc}
\IfFileExists{fourier.sty}{\usepackage{fourier}}{}
@@ -333,7 +333,7 @@ colorlinks,
%
% \GetFileInfo{mathtools.drv}
%
-% \CheckSum{3581}
+% \CheckSum{3740}
%
% \title{The \pkg{mathtools} package\thanks{This file has version number
% \fileversion, last revised \filedate.}}
@@ -427,7 +427,7 @@ colorlinks,
% \begin{verbatim}
% \[
% \begin{gathered}
-% [p] = 100 \\
+% [t] = 100 \\
% [v] = 200
% \end{gathered}
% \]
@@ -439,15 +439,16 @@ colorlinks,
% [v] = 200
% \end{gathered}
% \]
-% Yes, the \texttt{[p]} has been gobbled without any warning
-% whatsoever.\footnote{\pkg{amsmath} thought the \texttt[p] was an
-% optional argument, checked if it was \texttt{t} or \texttt{b} and
-% when both tests failed, assumed it was a \texttt{c}.} This is
-% hardly what you'd expect as an end user, as the desired output was
-% probably something like this instead:
+% Yes, the \texttt{[t]} has been gobbled without warning! Note, with
+% modern \pkg{amsmath} \verb|\begin{gathered}[x]| will eat \verb|[x]|
+% and \emph{issue a warning unless} \texttt{x} is \texttt{t},
+% \texttt{b} or \texttt{c}.\footnote{Older \pkg{amsmath} will
+% silently gobble the argument.} This is hardly what you'd expect
+% as an end user, as the desired output was probably something like
+% this instead:
% \[
% \begin{gathered}[c]
-% [p] = 100 \\
+% [t] = 100 \\
% [v] = 200
% \end{gathered}
% \]
@@ -461,6 +462,15 @@ colorlinks,
% If you however want to preserve the more dangerous standard
% optional spaces, simply choose the option \opt{allowspaces}.
%
+% \begin{codesyntax}
+% \SpecialOptIndex{legacycolonsymbols}\opt{legacycolonsymbols}
+% \end{codesyntax}
+% As of Summer 2022, we've had to rename several \cs{...colon...}
+% symbol macros in order to have a consistent naming scheme across
+% different packages.\footnote{For example with \pkg{unicode-math}.}
+% If needed, this package option brings back the original
+% \cs{...colon...} definitions. See page~\pageref{colonsymbols} for
+% more information.
%
% \section{Tools for mathematical typesetting}
%
@@ -478,7 +488,8 @@ colorlinks,
% \end{verbatim}
% More information on the keys later on.
%
-% \subsection{Fine-tuning mathematical layout}
+%
+% \subsection{Fine-tuning mathematical layout}
%
% Sometimes you need to tweak the layout of formulas a little to get
% the best result and this part of the manual describes the various
@@ -1348,7 +1359,7 @@ colorlinks,
% \]
% Inside the \verb?Xsmallmatrix? construction a small space is
% inserted between the fences and the contents, the size of it can be
-% changed using \key{smallmatrix-align}=\meta{some spacing command},
+% changed using \key{smallmatrix-inner-space}=\meta{some spacing command},
% the default is \cs{,}.
%
% As an extra trick the fences will behave as open and closing fences
@@ -2209,6 +2220,15 @@ colorlinks,
% \cs{abs[\cs{big}]}\marg{arg}, we actually use \cs{bigl} and
% \cs{bigr}.
%
+% \medskip\noindent\textbf{Note 3:} In the unlikely event that you
+% choose to use, say, \verb+\section{Foo $\norm[\big]{bar}$}+ you will
+% get an error because \cs{big} is getting expanded too early. Sadly,
+% due to how \cs{DeclarePairedDelimiter} is implemented one cannot use
+% \verb|[\protect\big]|. At present (until \pkg{amsmath} makes
+% \cs{big} and friends robust), the best
+% solution\footnote{\protect\url{https://tex.stackexchange.com/a/639238/3929}}
+% is to load the \pkg{etoolbox} package and add \verb|\robustify\big|
+% and similar to your preamble.
%
% \subsubsection{Expert use}
%
@@ -2388,43 +2408,71 @@ colorlinks,
% it provide any hooks to deal with math. So currently no general
% solution exists for this problem.
%
-% \begin{codesyntax}
-% \SpecialUsageIndex{\coloneqq}\cs{coloneqq}\texttt{~~~~~}
-% \SpecialUsageIndex{\Coloneqq}\cs{Coloneqq}\texttt{~~~~~}
-% \SpecialUsageIndex{\coloneq}\cs{coloneq}\texttt{~~~}
-% \SpecialUsageIndex{\Coloneq}\cs{Coloneq}\\
-% \SpecialUsageIndex{\eqqcolon}\cs{eqqcolon}\texttt{~~~~~}
-% \SpecialUsageIndex{\Eqqcolon}\cs{Eqqcolon}\texttt{~~~~~}
-% \SpecialUsageIndex{\eqcolon}\cs{eqcolon}\texttt{~~~}
-% \SpecialUsageIndex{\Eqcolon}\cs{Eqcolon}\\
-% \SpecialUsageIndex{\colonapprox}\cs{colonapprox}\texttt{~~}
-% \SpecialUsageIndex{\Colonapprox}\cs{Colonapprox}\texttt{~~}
-% \SpecialUsageIndex{\colonsim}\cs{colonsim}\texttt{~~}
-% \SpecialUsageIndex{\Colonsim}\cs{Colonsim}\\
-% \SpecialUsageIndex{\dblcolon}\cs{dblcolon}
-% \end{codesyntax}
-% The font packages \pkg{txfonts} and \pkg{pxfonts} provide various
-% symbols that include a vertically centered colon but with tighter
-% spacing. For example, the combination |:=| exists as the symbol
-% \cs{coloneqq} which typesets as $\coloneqq$ instead of
-% $\vcentcolon=$. The primary disadvantage of using these fonts is
-% the support packages' lack of support for \pkg{amsmath} (and thus
-% \pkg{mathtools}) and worse yet, the side-bearings are way too
-% tight; see~\cite{A-W:MG04} for examples. If you're not using these
-% fonts, \pkg{mathtools} provides the symbols for you. Here are a few
-% examples:
-% \begin{verbatim}
-% \[
-% a \coloneqq b \quad c \Colonapprox d \quad e \dblcolon f
-% \]
-% \end{verbatim}
-% \[
-% a \coloneqq b \quad c \Colonapprox d \quad e \dblcolon f
-% \]
+% \subsubsection{Some extra symbols involving vertically centered colon}
%
+% Inspired by the \pkg{txfonts} and \pkg{pxfonts} we provide some colon+symbol combinations such that they will be
+% available even when current font does not provide the combined symbol.
%
+% \medskip\noindent \textbf{Breaking change Summer 2022:} As is listed in the manual for
+% \pkg{newtxmath}/\pkg{newpxmath}\footnote{These superceeds \pkg{txfonts} and \pkg{pxfonts}.}, the symbols
+% \cmd{\coloneq}/\cmd{\Coloneq} and \cmd{\eqcolon}/\cmd{\Eqcolon} in \pkg{txfonts}/\pkg{pxfonts} generated the wrong
+% symbols, or at least was not consistent with the naming converntion by other packages. This has now also been
+% fixed in \pkg{mathtools}, giving us the following colon symbol list:
%
-% \subsubsection{A few missing symbols}
+% \begin{center}
+% \small\label{colonsymbols}
+% \newcommand\SSS[1]{\SpecialUsageIndex{#1}\texttt{\detokenize{#1}}&$#1$}
+% \fbox{\begin{tabular}{*{8}{l} }
+% \SSS{\dblcolon} \\
+% \SSS{\coloneq} & \SSS{\Coloneq} & \SSS{\eqcolon} & \SSS{\Eqcolon}
+% \\
+% \SSS{\colonapprox} & \SSS{\Colonapprox} & \SSS{\colonsim} & \SSS{\Colonsim}
+% \\
+% \noalign{\smallskip}
+% \multicolumn{8}{l}{\itshape Legacy duplicate names:} \\
+% \noalign{\smallskip}
+% \SSS{\coloneqq} & \SSS{\eqqcolon} & \SSS{\Coloneqq} & \SSS{\Eqqcolon} \\
+% \noalign{\smallskip}
+% \multicolumn{8}{l}{\itshape Extra symbols added Summer 2022:} \\
+% \noalign{\smallskip}
+% \SSS{\approxcolon} & \SSS{\Approxcolon} & \SSS{\simcolon} & \SSS{\Simcolon} \\
+% \SSS{\colondash} & \SSS{\Colondash} & \SSS{\dashcolon} & \SSS{\Dashcolon} \\
+% \end{tabular}}
+% \end{center}
+%
+% \medskip\noindent If for some reason you need to revert to original (pre summer 2022) colon symbol names, use the
+% \opt{legacycolonsymbols} package option. In which case the macro names maps to:
+%
+% \begin{center}
+% \small\label{colonsymbols-legacy}
+% \makeatletter
+% \newcommand\SSS[2]{\SpecialUsageIndex{#1}\texttt{\detokenize{#1}}&$\@nameuse{#2}$}
+% \makeatother
+% \fbox{\begin{tabular}{*{8}{l}}
+% \SSS{\coloneqq}{MATHT@coloneq} & \SSS{\Coloneqq}{MATHT@dblcoloneq}
+% & \SSS{\coloneq}{MATHT@colondash} & \SSS{Coloneq}{MATHT@dblcolondash} \\
+% \SSS{\eqqcolon}{MATHT@eqcolon} & \SSS{\Eqqcolon}{MATHT@eqdblcolon}
+% & \SSS{\eqcolon}{MATHT@dashcolon} & \SSS{\Eqcolon}{MATHT@dashdblcolon} \\
+% \SSS{\colonapprox}{MATHT@colonapprox} & \SSS{\Colonapprox}{MATHT@dblcolonapprox}
+% & \SSS{\colonsim}{MATHT@colonsim} & \SSS{\Colonsim}{MATHT@dblcolonsim} \\
+% \SSS{\dblcolon}{MATHT@dblcolon}\\
+% \noalign{\smallskip}
+% \multicolumn{8}{l}{\itshape Extra symbols added Summer 2022:} \\
+% \noalign{\smallskip}
+% \SSS{\approxcolon}{MATHT@approxcolon} & \SSS{\Approxcolon}{MATHT@approxdblcolon}
+% & \SSS{\simcolon}{MATHT@simcolon} & \SSS{\Simcolon}{MATHT@simdblcolon} \\
+% \SSS{\colondash}{MATHT@colondash} & \SSS{\Colondash}{MATHT@dblcolondash}
+% & \SSS{\dashcolon}{MATHT@dashcolon} & \SSS{\Dashcolon}{MATHT@dashdblcolon}
+% \end{tabular}}\par\smallskip
+% Colon symbol names with \opt{legacycolonsymbols} package option.
+% \end{center}
+%
+% \medskip\noindent Note that the symbol names are added at the start of the document via the \cs{provide...} mechanism,
+% thus if some font package provide a symbol of the same macro name, we do nothing.
+%
+%
+%
+% \subsubsection{A few additional symbols}
%
% Most provided math font sets are missing the symbols \cs{nuparrow}
% and \cs{ndownarrow} (i.e.\ negated up- and downarrow) plus a `big'
@@ -3046,7 +3094,7 @@ colorlinks,
% \begin{macrocode}
%<*package>
\ProvidesPackage{mathtools}%
- [2022/02/07 v1.28a mathematical typesetting tools]
+ [2022/06/29 v1.29 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}}
@@ -3167,6 +3215,17 @@ colorlinks,
\MH_set_boolean_F:n {robustify}
}
% \end{macrocode}
+% \changes{v1.29}{2022/06/24}{Added package option to bring back old
+% colon symbols}
+% As of juni/july 2022 we've had to rename several of the provided
+% \cs{...colon...} macros. If needed this package option brings them back.
+% \begin{macrocode}
+\MH_new_boolean:n {legacycolonsymbols}
+\MH_set_boolean_F:n {legacycolonsymbols}
+\DeclareOption{legacycolonsymbols}{
+ \MH_set_boolean_T:n {legacycolonsymbols}
+}
+% \end{macrocode}
% Pass all other options directly to \pkg{amsmath}.
% \begin{macrocode}
\DeclareOption*{
@@ -3182,6 +3241,15 @@ colorlinks,
% \begin{macrocode}
\MHInternalSyntaxOff
\RequirePackage{amsmath}[2016/11/05]
+% \end{macrocode}
+% \changes{v1.29}{2022/06/27}{Added \pkg{unicode-math} warning}
+% \begin{macrocode}
+\@ifpackageloaded{unicode-math}{
+ \PackageWarning{mathtools}{For best results, please load mathtools
+ *before* \MessageBreak unicode-math}
+}{}
+% \end{macrocode}
+% \begin{macrocode}
\MHInternalSyntaxOn
\AtEndOfPackage{\MHInternalSyntaxOff}
% \end{macrocode}
@@ -3916,8 +3984,73 @@ colorlinks,
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
+% \begin{macro}{\MATHT@dblcolon}
+% \begin{macro}{\MATHT@coloneq}
+% \begin{macro}{\MATHT@dblcoloneq}
+% \begin{macro}{\MATHT@colondash}
+% \begin{macro}{\MATHT@dblcolondash}
+% \begin{macro}{\MATHT@eqcolon}
+% \begin{macro}{\MATHT@eqdblcolon}
+% \begin{macro}{\MATHT@dashcolon}
+% \begin{macro}{\MATHT@dashdblcolon}
+% \begin{macro}{\MATHT@colonapprox}
+% \begin{macro}{\MATHT@dblcolonapprox}
+% \begin{macro}{\MATHT@approxcolon}
+% \begin{macro}{\MATHT@approxdblcolon}
+% \begin{macro}{\MATHT@colonsim}
+% \begin{macro}{\MATHT@dblcolonsim}
+% \begin{macro}{\MATHT@simcolon}
+% \begin{macro}{\MATHT@simdblcolon}
+% We can now use \cs{vcentcolon} to define some colon related
+% symbols. Orinally the names of these macro names came from
+% \pkg{txfonts} and \pkg{pxfonts}. Though it turned out that some of
+% them we named inconsistently. Instead we now first name the macros
+% using an internal name and then later map these onto names similar
+% to those coming from \pkg{newtxmath} and \pkg{newpxmath}.
+% \changes{v1.08c}{2010/11/17}{Enclosed all in \cs{mathrel}}
+% \changes{v1.18}{2015/11/12}{Moved the enclosing \cs{mathrel} to
+% \cs{mkern}. This is a result of
+% \url{http://chat.stackexchange.com/transcript/message/23630342#23630342} and \url{http://chat.stackexchange.com/transcript/message/25348032#25348032}}
+% \changes{v1.29}{2022/06/27}{Moved symbol defs into separate MATHT named
+% macros}
+% \begin{macrocode}
+\newcommand*\MATHT@dblcolon{\vcentcolon\mathrel{\mkern-.9mu}\vcentcolon}
+\newcommand*\MATHT@coloneq{\vcentcolon\mathrel{\mkern-1.2mu}=}
+\newcommand*\MATHT@dblcoloneq{\dblcolon\mathrel{\mkern-1.2mu}=}
+\newcommand*\MATHT@colondash{\vcentcolon\mathrel{\mkern-1.2mu}\mathrel{-}}
+\newcommand*\MATHT@dblcolondash{\dblcolon\mathrel{\mkern-1.2mu}\mathrel{-}}
+\newcommand*\MATHT@eqcolon{=\mathrel{\mkern-1.2mu}\vcentcolon}
+\newcommand*\MATHT@eqdblcolon{=\mathrel{\mkern-1.2mu}\dblcolon}
+\newcommand*\MATHT@dashcolon{\mathrel{-}\mathrel{\mkern-1.2mu}\vcentcolon}
+\newcommand*\MATHT@dashdblcolon{\mathrel{-}\mathrel{\mkern-1.2mu}\dblcolon}
+\newcommand*\MATHT@colonapprox{\vcentcolon\mathrel{\mkern-1.2mu}\approx}
+\newcommand*\MATHT@dblcolonapprox{\dblcolon\mathrel{\mkern-1.2mu}\approx}
+\newcommand*\MATHT@approxcolon{\approx\mathrel{\mkern-1.2mu}\vcentcolon}
+\newcommand*\MATHT@approxdblcolon{\approx\mathrel{\mkern-1.2mu}\dblcolon}
+\newcommand*\MATHT@colonsim{\vcentcolon\mathrel{\mkern-1.2mu}\sim}
+\newcommand*\MATHT@dblcolonsim{\dblcolon\mathrel{\mkern-1.2mu}\sim}
+\newcommand*\MATHT@simcolon{\sim\mathrel{\mkern-1.2mu}\vcentcolon}
+\newcommand*\MATHT@simdblcolon{\sim\mathrel{\mkern-1.2mu}\dblcolon}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
% \end{macro}
-% \begin{macro}{\dblcolon}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\dblcolon}
% \begin{macro}{\coloneqq}
% \begin{macro}{\Coloneqq}
% \begin{macro}{\coloneq}
@@ -3931,26 +4064,62 @@ colorlinks,
% \begin{macro}{\colonsim}
% \begin{macro}{\Colonsim}
% This is just to simulate all the \cs{..colon..} symbols from
-% \pkg{txfonts} and \pkg{pxfonts}.
-% \changes{v1.08c}{2010/11/17}{Enclosed all in \cs{mathrel}}
-% \changes{v1.18}{2015/11/12}{Moved the enclosing \cs{mathrel} to
-% \cs{mkern}. This is a result of
-% \url{http://chat.stackexchange.com/transcript/message/23630342#23630342} and \url{http://chat.stackexchange.com/transcript/message/25348032#25348032}}
-% \begin{macrocode}
-\AtBeginDocument{
- \providecommand*\dblcolon{\vcentcolon\mathrel{\mkern-.9mu}\vcentcolon}
- \providecommand*\coloneqq{\vcentcolon\mathrel{\mkern-1.2mu}=}
- \providecommand*\Coloneqq{\dblcolon\mathrel{\mkern-1.2mu}=}
- \providecommand*\coloneq{\vcentcolon\mathrel{\mkern-1.2mu}\mathrel{-}}
- \providecommand*\Coloneq{\dblcolon\mathrel{\mkern-1.2mu}\mathrel{-}}
- \providecommand*\eqqcolon{=\mathrel{\mkern-1.2mu}\vcentcolon}
- \providecommand*\Eqqcolon{=\mathrel{\mkern-1.2mu}\dblcolon}
- \providecommand*\eqcolon{\mathrel{-}\mathrel{\mkern-1.2mu}\vcentcolon}
- \providecommand*\Eqcolon{\mathrel{-}\mathrel{\mkern-1.2mu}\dblcolon}
- \providecommand*\colonapprox{\vcentcolon\mathrel{\mkern-1.2mu}\approx}
- \providecommand*\Colonapprox{\dblcolon\mathrel{\mkern-1.2mu}\approx}
- \providecommand*\colonsim{\vcentcolon\mathrel{\mkern-1.2mu}\sim}
- \providecommand*\Colonsim{\dblcolon\mathrel{\mkern-1.2mu}\sim}
+% % \pkg{txfonts} and \pkg{pxfonts}.
+% \noindent
+% \textbf{2022/06/24:} Actually these were inconsistenly named in \pkg{txfonts}
+% and \pkg{pxfonts}. Some was properly renamed in \pkg{newtxmath} and
+% \pkg{newpxmath}, but not all.
+% \begin{macrocode}
+\MH_if_boolean:nTF {legacycolonsymbols}{
+ \AtBeginDocument{
+ \providecommand*\dblcolon{\MATHT@dblcolon}
+ \providecommand*\coloneqq{\MATHT@coloneq}
+ \providecommand*\Coloneqq{\MATHT@dblcoloneq}
+ \providecommand*\coloneq{\MATHT@colondash}
+ \providecommand*\Coloneq{\MATHT@dblcolondash}
+ \providecommand*\eqqcolon{\MATHT@eqcolon}
+ \providecommand*\Eqqcolon{\MATHT@eqdblcolon}
+ \providecommand*\eqcolon{\MATHT@dashcolon}
+ \providecommand*\Eqcolon{\MATHT@dashdblcolon}
+ \providecommand*\colonapprox{\MATHT@colonapprox}
+ \providecommand*\Colonapprox{\MATHT@dblcolonapprox}
+ \providecommand*\colonsim{\MATHT@colonsim}
+ \providecommand*\Colonsim{\MATHT@dblcolonsim}
+ % new
+ \providecommand*\approxcolon{\MATHT@approxcolon}
+ \providecommand*\Approxcolon{\MATHT@approxdblcolon}
+ \providecommand*\simcolon{\MATHT@simcolon}
+ \providecommand*\Simcolon{\MATHT@simdblcolon}
+ \providecommand*\colondash{\MATHT@colondash}
+ \providecommand*\Colondash{\MATHT@dblcolondash}
+ \providecommand*\dashcolon{\MATHT@dashcolon}
+ \providecommand*\Dashcolon{\MATHT@dashdblcolon}
+ }
+}{
+ \AtBeginDocument{
+ \providecommand*\dblcolon{\MATHT@dblcolon}
+ \providecommand*\coloneqq{\MATHT@coloneq} % duplet
+ \providecommand*\Coloneqq{\MATHT@dblcoloneq}% duplet
+ \providecommand*\coloneq{\MATHT@coloneq} % changed
+ \providecommand*\Coloneq{\MATHT@dblcoloneq} % changed
+ \providecommand*\eqqcolon{\MATHT@eqcolon} % duplet
+ \providecommand*\Eqqcolon{\MATHT@eqdblcolon}% duplet
+ \providecommand*\eqcolon{\MATHT@eqcolon} % changed
+ \providecommand*\Eqcolon{\MATHT@eqdblcolon} % changed
+ \providecommand*\colonapprox{\MATHT@colonapprox}
+ \providecommand*\Colonapprox{\MATHT@dblcolonapprox}
+ \providecommand*\colonsim{\MATHT@colonsim}
+ \providecommand*\Colonsim{\MATHT@dblcolonsim}
+ % new
+ \providecommand*\approxcolon{\MATHT@approxcolon}
+ \providecommand*\Approxcolon{\MATHT@approxdblcolon}
+ \providecommand*\simcolon{\MATHT@simcolon}
+ \providecommand*\Simcolon{\MATHT@simdblcolon}
+ \providecommand*\colondash{\MATHT@colondash}
+ \providecommand*\Colondash{\MATHT@dblcolondash}
+ \providecommand*\dashcolon{\MATHT@dashcolon}
+ \providecommand*\Dashcolon{\MATHT@dashdblcolon}
+ }
}
% \end{macrocode}
% \end{macro}