mathtools

amsmath n'a presque pas bougé depuis les années 1990. La stabilité est une vertu, mais le prix en fut une pile croissante de petites contrariétés que personne ne pouvait corriger : l'allure de :=, des barres de valeur absolue qui refusent de suivre la hauteur de leur contenu, une longue condition sous un signe somme qui étire toute la formule. mathtools est le package LaTeX créé en 2002 pour accueillir ces correctifs, et il ne remplace pas amsmath : il charge amsmath et bâtit par-dessus. Cette page parcourt \DeclarePairedDelimiter, \coloneqq, \mathclap, \prescript, matrix*, dcases et showonlyrefs, mesures à l'appui. Chacun est un pas qu'amsmath seul ne pouvait franchir.

amsmath ou mathtools : lequel charger ?

Il suffit de charger mathtools. Il tire amsmath avec lui, un \usepackage{amsmath} séparé est donc inutile. Les options destinées à amsmath passent aussi telles quelles : \usepackage[fleqn,tbtags]{mathtools} équivaut à \usepackage[fleqn,tbtags]{amsmath} suivi de \usepackage{mathtools}. Nul besoin de nommer les deux ni de se soucier de l'ordre.

% one line is enough: mathtools loads amsmath itself
\usepackage{mathtools}

% options aimed at amsmath are passed straight through
\usepackage[fleqn,tbtags]{mathtools}

Ce parti pris – « bâtir sur amsmath » – a survécu à trois générations de mainteneurs. Le bloc de copyright de mathtools.sty indique 2002–2011 Morten Høgholm, 2012–2019 Lars Madsen, et depuis 2020 Lars Madsen avec le projet LaTeX3. mathtools est ainsi passé de la boîte à outils d'un individu à un quasi-standard entretenu par l'équipe qui développe LaTeX lui-même. Cela se voit : dans le préambule d'un document contenant des mathématiques, la première ligne nomme désormais plus souvent mathtools qu'amsmath. mathtools dépend en outre du paquet auxiliaire mhsetup, que les distributions comme TeX Live incluent ; il ne réclame donc aucune attention.

Valeurs absolues et normes qui s'ajustent seules : \DeclarePairedDelimiter

Une ligne dans le préambule — \DeclarePairedDelimiter\abs{\lvert}{\rvert} — fournit un \abs maison à trois tailles commutables. Le \newcommand{\abs}[1]{\lvert#1\rvert} artisanal auquel on pense d'abord obtient bien le bon espacement horizontal, mais dès qu'on lui donne un contenu haut comme \abs{\frac{a}{b}}, les barres refusent de grandir et restent plantées à côté d'une fraction qui les dépasse. C'est exactement là que \DeclarePairedDelimiter prend le relais. Entourer le nom de commande d'accolades, \DeclarePairedDelimiter{\abs}{\lvert}{\rvert}, compile tout aussi bien.

% in the preamble; braces around the command name are optional
\DeclarePairedDelimiter\abs{\lvert}{\rvert}
\DeclarePairedDelimiter\norm{\lVert}{\rVert}

% three ways to call it
\[
  \abs{x} = \abs{-x}
  \qquad
  \abs*{\frac{a}{b}} = \frac{\abs{a}}{\abs{b}}
  \qquad
  \norm[\big]{v}
\]

La différence n'est pas affaire d'impression : elle se mesure. Sous TeX Live 2024, \sbox0{$\abs{\frac ab}$} fait 7,5 pt de haut, tandis que \abs*{\frac ab} avec étoile fait 8,50006 pt. L'étoile enveloppe le corps dans \left … \right ; les barres ont donc grandi de la hauteur de la fraction. La troisième forme, avec [\big], [\Big], [\bigg] ou [\Bigg], choisit un cran à la main ; ici [\big] mesurait aussi 8,50006 pt, tombant sur le cran retenu par l'automatisme. Retenez : étoile = étirer, crochets = figer à ce cran. Pour une notation exigeant un séparateur à l'intérieur du délimiteur, comme \Set{x}{x>0}, employez \DeclarePairedDelimiterX.

Pourquoi := a mauvaise allure et ce que \coloneqq change vraiment

Deux points sont à corriger : la hauteur du deux-points et l'espace entre le deux-points et le signe égal. Une explication répandue veut que l'espacement soit faux parce que : ne serait pas une relation — c'est inexact. Demandez à LaTeX le math code de : : la réponse est 12346, soit "303A en hexadécimal, dont le 3 initial signale la classe 3, une relation. Écrire $a\mathrel{:=}b$ ne change donc strictement rien. La mesure le confirme : $a:=b$ et $a\mathrel{:=}b$ donnent tous deux exactement 25,68855 pt.

Que fait donc \coloneqq ? Sa définition est \vcentcolon\mathrel{\mkern-1.2mu}=. D'abord, au lieu du : ordinaire elle emploie \vcentcolon, un deux-points centré sur l'axe mathématique (mesuré : $:$ fait 4,30554 pt de haut, $\vcentcolon$ 4,65277 pt, soit 0,34723 pt de plus). Ensuite, un crénage négatif de -1.2mu rapproche le deux-points du signe égal : lorsque deux relations se suivent, TeX insère aussi entre elles une espace de relation, et : et = se lisent alors comme deux symboles distincts. Résultat : $a\coloneqq b$ mesure 25,02191 pt, soit 0,66664 pt de moins qu'un := brut — exactement 1,2 mu à 10 pt.

\[
  f(x) \coloneqq x^2 + 1, \qquad y \eqqcolon g(x), \qquad
  A \Coloneqq B
\]

Un piège : mathtools a changé le sens de \coloneq. Aujourd'hui, par défaut, \coloneq compose le même « := » que \coloneqq ; dans l'ancienne définition, il composait un deux-points et un tiret, « :− ». Même chose pour \eqcolon, qui rejoint désormais \eqqcolon sur « =: ». Pour les documents qui réclament les anciens glyphes, \usepackage[legacycolonsymbols]{mathtools} est prévu. À l'inverse, \coloneqq et \eqqcolon n'ont jamais été abandonnés et donnent le même résultat dans les deux réglages — dans le doute, écrivez celui à deux q. La famille comprend encore \dblcolon (::), \Coloneqq (::=), \Eqqcolon, \colonapprox, \colonsim, ainsi que les plus récents \approxcolon et \simcolon.

Une longue condition sous une somme élargit la formule : \mathclap et \smashoperator

Mettez la condition dans une boîte de largeur nulle et le problème disparaît. \sum_{1 \le i \le j \le n} a_{ij} mesure 48,21771 pt de large ; enveloppée en \sum_{\mathclap{1 \le i \le j \le n}} a_{ij}, la même formule mesure 28,43983 pt, soit 19,78 pt de moins. Les caractères de la condition ne disparaissent pas : ils restent bien visibles sous le signe somme. Ils cessent simplement de compter dans la largeur de la formule. \mathclap répartit le débord des deux côtés, \mathllap le rejette à gauche et \mathrlap à droite. Le \clap du mode texte repose sur la même idée.

% the wide condition stretches the whole formula
\[ \sum_{1 \le i \le j \le n} a_{ij} \]

% zero-width box: same look, width of the operator only
\[ \sum_{\mathclap{1 \le i \le j \le n}} a_{ij} \]

% same result, but this one can flatten a single side
\[ \smashoperator{\sum_{1 \le i \le j \le n}} a_{ij} \]
\[ \smashoperator[r]{\sum_{1 \le i \le j \le n}} a_{ij} \]

mathtools propose un second outil, \smashoperator. Mesuré, \smashoperator{\sum_{1 \le i \le j \le n}} donne 28,43983 pt, exactement le chiffre de \mathclap. La différence tient à la souplesse : \smashoperator reçoit l'opérateur et ses indices ensemble et permet de choisir quel côté aplatir via [l], [r] ou [lr] (par défaut). Quand le signe somme est en marge gauche et ne doit pas y déborder, [r] est la réponse : mesuré à 38,32878 pt, à mi-chemin entre l'écrasement bilatéral et l'original. \mathclap vise un point à l'intérieur d'une formule ; \smashoperator s'occupe de l'opérateur en début de ligne.

Des indices à gauche du symbole : \prescript et \adjustlimits

Trois arguments — \prescript{dessus}{dessous}{base} — accrochent des indices en haut à gauche et en bas à gauche d'un symbole. La notation des isotopes est le cas le plus net : \prescript{238}{92}{\mathbf{U}} compose l'uranium 238, le nombre de masse 238 en haut à gauche et le numéro atomique 92 en bas à gauche. On peut aussi écrire {}^{238}_{92}\mathbf{U} à la main, mais les indices pendent alors à un groupe vide et leur position comme leur taille manquent de fiabilité. Si le bas à gauche est inutile, laissez le deuxième argument vide, {}. La fonte des indices se change via prescript-sub-format et prescript-sup-format dans \mathtoolsset.

\[
  \prescript{238}{92}{\mathbf{U}}, \qquad
  \prescript{n}{}{C}_{k}
\]

% limits of two nested operators lined up
\[ \adjustlimits \sum_{i} \sum_{j} a_{ij} \]

Un outil de plus a sa place ici, discret mais utile. \adjustlimits aligne les limites inférieures de deux opérateurs imbriqués. Lorsque des indices de tailles différentes se suivent, comme dans \sum_i \sum_j, la seconde limite peut sembler légèrement flotter, et \adjustlimits absorbe ce décrochement. Mesuré : \sum_i\sum_j fait 30,55557 pt et \adjustlimits\sum_i\sum_j 32,2222 pt — un écart de 1,66663 pt, soit exactement 3 mu. Il rend le même service quand des opérateurs de largeurs différentes se suivent, comme \lim_{n\to\infty}\sup_{x}.

Aligner les colonnes d'une matrice : pmatrix* et [r], [l], [c]

Le pmatrix d'amsmath centre toujours ses colonnes. Cela devient gênant dès qu'apparaissent des nombres négatifs : avec -1 au-dessus de 2, les chiffres semblent décalés de la largeur du signe moins. mathtools fournit une version étoilée de chaque environnement — matrix*, pmatrix*, bmatrix*, Bmatrix*, vmatrix*, Vmatrix*, smallmatrix* — qui accepte en argument optionnel le même spécificateur de colonne qu'array. Écrivez \begin{pmatrix*}[r] et les colonnes s'alignent à droite, les signes moins débordant proprement vers la gauche. La valeur par défaut est c : l'étoile seule ne change donc rien. L'alignement par défaut des petites variantes se règle par smallmatrix-align dans \mathtoolsset.

\[
  \begin{pmatrix*}[r]
    -1 &  3 \\
     2 & -4
  \end{pmatrix*}
  \qquad
  \begin{pmatrix}
    -1 &  3 \\
     2 & -4
  \end{pmatrix}
\]

Distinctions de cas et une ligne trop longue : dcases, rcases, multlined

Le cases d'amsmath compose son contenu en style texte, si bien qu'une fraction s'y écrase : \frac{1}{2} rétrécit. Le dcases de mathtools garde la même syntaxe mais compose le corps en taille hors texte ; le d vient de displaystyle. Si l'accolade doit plutôt se trouver à droite — plusieurs conditions menant à une conclusion —, employez rcases et faites suivre \end{rcases} d'un \Rightarrow ou de ce qu'il faut. Il existe un drcases combiné, ainsi que dcases* et rcases* qui composent la dernière colonne comme du texte. Pour un environnement de cas sur mesure, \newcases en fabrique un.

\[
  f(x) =
  \begin{dcases}
    \frac{1}{2} & x > 0 \\
    0           & x \le 0
  \end{dcases}
  \qquad
  \begin{rcases}
    a \\ b
  \end{rcases} \Rightarrow c
\]

% [t] aligns on the first row; the second optional argument fixes the width
\[
  \begin{multlined}[t][0.6\textwidth]
    a + b + c + d \\ {} + e + f
  \end{multlined}
\]

multlined est l'environnement multline d'amsmath enfermé dans une seule boîte. multline accapare toute une ligne hors texte et ne peut donc servir dans align ni à droite d'un =. multlined, étant un environnement, s'insère n'importe où dans une formule et permet de ne replier que le long membre de droite. Il prend deux arguments optionnels : le premier est l'alignement vertical par rapport à l'entourage (t, b, centré par défaut), le second la largeur. Sans largeur indiquée, il ne prend que ce qu'il lui faut. Pour glisser une flèche entre deux lignes alignées, il y a \ArrowBetweenLines ; pour desserrer l'interligne de tout un alignement, l'environnement spreadlines.

Numéroter uniquement les équations citées : showonlyrefs

Écrivez \mathtoolsset{showonlyrefs} et seules les équations citées dans le texte reçoivent un numéro ; les autres perdent le leur. Dans un brouillon, les numéros d'équation apparaissent et disparaissent sans cesse, et numéroter une équation que personne ne cite envoie le relecteur chercher où « (7) » est utilisée. En composant sous TeX Live 2024 un align de deux équations et en n'en citant qu'une par \eqref, l'équation citée a reçu (1) et l'autre aucun numéro. Une seule condition : citer avec \eqref, non avec \ref. Si les numéros posés à la main par \tag{} doivent survivre aussi, ajoutez showmanualtags.

\mathtoolsset{
  showonlyrefs,        % number only what \eqref points at
  showmanualtags,      % but keep \tag{} numbers visible
  centercolon          % a bare : is set at axis height
}

Lesquelles viennent d'amsmath, lesquelles de mathtools ?

Ne charger que mathtools brouille la frontière, mais elle compte dès qu'on retouche le document d'autrui ou qu'on rencontre des règles de soumission n'autorisant qu'amsmath. Les fichiers .sty tranchent. Les flèches extensibles \xrightarrow et \xleftarrow viennent d'amsmath (définies dans amsmath.sty) ; ce que mathtools ajoute, c'est le reste de la famille — les \xRightarrow, \xLeftarrow et \xLeftrightarrow à double trait, le \xleftrightarrow bidirectionnel, les \xhookrightarrow et \xhookleftarrow à crochet, la flèche d'application \xmapsto, le plus long \xlongrightarrow, ainsi que les harpons. Toutes prennent la même forme [dessous]{dessus}. \intertext est d'amsmath, le \shortintertext resserré est de mathtools. \overset, \underset et \substack sont d'amsmath ; les \overbracket et \underbracket à angle droit sont de mathtools.