% \iffalse meta-comment % % Copyright (C) 2004-2008 by Morten Hoegholm % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either % version 1.3 of this license or (at your option) any later % version. The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3 or later is part of all distributions of % LaTeX version 2005/12/01 or later. % % This work has the LPPL maintenance status "maintained". % % This Current Maintainer of this work is Morten Hoegholm. % % This work consists of the main source file mathtools.dtx % and the derived files % mathtools.sty, mathtools.pdf, mathtools.ins, mathtools.drv. % % Distribution: % CTAN:macros/latex/contrib/mh/mathtools.dtx % CTAN:macros/latex/contrib/mh/mathtools.pdf % % Unpacking: % (a) If mathtools.ins is present: % tex mathtools.ins % (b) Without mathtools.ins: % tex mathtools.dtx % (c) If you insist on using LaTeX % latex \let\install=y\input{mathtools.dtx} % (quote the arguments according to the demands of your shell) % % Documentation: % (a) If mathtools.drv is present: % latex mathtools.drv % (b) Without mathtools.drv: % latex mathtools.dtx; ... % The class ltxdoc loads the configuration file ltxdoc.cfg % if available. Here you can specify further options, e.g. % use A4 as paper format: % \PassOptionsToClass{a4paper}{article} % % Programm calls to get the documentation (example): % pdflatex mathtools.dtx % makeindex -s gind.ist mathtools.idx % pdflatex mathtools.dtx % makeindex -s gind.ist mathtools.idx % pdflatex mathtools.dtx % % Installation: % TDS:tex/latex/mh/mathtools.sty % TDS:doc/latex/mh/mathtools.pdf % TDS:source/latex/mh/mathtools.dtx % %<*ignore> \begingroup \def\x{LaTeX2e} \expandafter\endgroup \ifcase 0\ifx\install y1\fi\expandafter \ifx\csname processbatchFile\endcsname\relax\else1\fi \ifx\fmtname\x\else 1\fi\relax \else\csname fi\endcsname % %<*install> \input docstrip.tex \Msg{************************************************************************} \Msg{* Installation} \Msg{* Package: mathtools 20010/07/11 v1.08 (MH)} \Msg{************************************************************************} \keepsilent \askforoverwritefalse \preamble This is a generated file. Copyright (C) 2002-2010 by Morten Hoegholm This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 of this license or (at your option) any later version. The latest version of this license is in http://www.latex-project.org/lppl.txt and version 1.3 or later is part of all distributions of LaTeX version 2005/12/01 or later. This work has the LPPL maintenance status "maintained". This Current Maintainer of this work is Morten Hoegholm. This work consists of the main source file mathtools.dtx and the derived files mathtools.sty, mathtools.pdf, mathtools.ins, mathtools.drv. \endpreamble \generate{% \file{mathtools.ins}{\from{mathtools.dtx}{install}}% \file{mathtools.drv}{\from{mathtools.dtx}{driver}}% \usedir{tex/latex/mh}% \file{mathtools.sty}{\from{mathtools.dtx}{package}}% } \obeyspaces \Msg{************************************************************************} \Msg{*} \Msg{* To finish the installation you have to move the following} \Msg{* file into a directory searched by TeX:} \Msg{*} \Msg{* mathtools.sty} \Msg{*} \Msg{* To produce the documentation run the file `mathtools.drv'} \Msg{* through LaTeX.} \Msg{*} \Msg{* Happy TeXing!} \Msg{*} \Msg{************************************************************************} \endbatchfile % %<*ignore> \fi % %<*driver> \NeedsTeXFormat{LaTeX2e} \ProvidesFile{mathtools.drv}% [2010/07/11 v1.08 mathematical typesetting tools (MH)] \documentclass{ltxdoc} \IfFileExists{fourier.sty}{\usepackage{fourier}}{} \addtolength\marginparwidth{-25pt} \usepackage{mathtools} \setcounter{IndexColumns}{2} \providecommand*\pkg[1]{\textsf{#1}} \providecommand*\env[1]{\texttt{#1}} \providecommand*\email[1]{\href{mailto:#1}{\texttt{#1}}} \providecommand*\mode[1]{\texttt{[#1]}} \providecommand*\file[1]{\texttt{#1}} \usepackage{xcolor,varioref,amssymb} \makeatletter \newcommand*\thinfbox[2][black]{\fboxsep0pt\textcolor{#1}{\rulebox{{\normalcolor#2}}}} \newcommand*\thinboxed[2][black]{\thinfbox[#1]{\ensuremath{\displaystyle#2}}} \newcommand*\rulebox[1]{% \sbox\z@{\ensuremath{\displaystyle#1}}% \@tempdima\dp\z@ \hbox{% \lower\@tempdima\hbox{% \vbox{\hrule height\fboxrule\box\z@\hrule height\fboxrule}% }% }% } \newenvironment{codesyntax} {\par\small\addvspace{4.5ex plus 1ex}% \vskip -\parskip \noindent \begin{tabular}{|l|}\hline\ignorespaces}% {\\\hline\end{tabular}\nobreak\par\nobreak \vspace{2.3ex}\vskip -\parskip\noindent\ignorespacesafterend} \makeatletter \newcommand*\FeatureRequest[2]{% \hskip1sp \marginpar{% \parbox[b]{\marginparwidth}{\small\sffamily\raggedright \strut Feature request by\\#1\\#2% } }% } \newcommand*\ProvidedBy[2]{% \hskip1sp \marginpar{% \parbox[b]{\marginparwidth}{\small\sffamily\raggedright \strut Feature provided by\\#1\\#2% } }% } \newcommand*\cttPosting[2]{% \hskip1sp \marginpar{% \parbox[b]{\marginparwidth}{\small\sffamily\raggedright \strut Posted on \texttt{comp.text.tex} \\#1\\#2% }% }% } \expandafter\def\expandafter\MakePrivateLetters\expandafter{% \MakePrivateLetters \catcode`\_=11\relax } \providecommand*\SpecialOptIndex[1]{% \@bsphack \index{#1\actualchar{\protect\ttfamily #1} (option)\encapchar usage}% \index{options:\levelchar#1\actualchar{\protect\ttfamily #1}\encapchar usage}\@esphack} \providecommand*\opt[1]{\texttt{#1}} \providecommand*\SpecialKeyIndex[1]{% \@bsphack \index{#1\actualchar{\protect\ttfamily #1} (key)\encapchar usage}% \index{keys:\levelchar#1\actualchar{\protect\ttfamily #1}\encapchar usage}\@esphack} \providecommand*\key[1]{\textsf{#1}} \providecommand*\eTeX{$\m@th\varepsilon$-\TeX} \def\MTmeta#1{% \ensuremath\langle \ifmmode \expandafter \nfss@text \fi {% \meta@font@select \edef\meta@hyphen@restore {\hyphenchar\the\font\the\hyphenchar\font}% \hyphenchar\font\m@ne \language\l@nohyphenation #1\/% \meta@hyphen@restore }\ensuremath\rangle \endgroup } \makeatother \DeclareRobustCommand\meta{\begingroup\MakePrivateLetters\MTmeta}% \def\MToarg#1{{\ttfamily[}\meta{#1}{\ttfamily]}\endgroup} \DeclareRobustCommand\oarg{\begingroup\MakePrivateLetters\MToarg}% \def\MHmarg#1{{\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}\endgroup} \DeclareRobustCommand\marg{\begingroup\MakePrivateLetters\MHmarg}% \def\MHarg#1{{\ttfamily\char`\{#1\ttfamily\char`\}}\endgroup} \DeclareRobustCommand\arg{\begingroup\MakePrivateLetters\MHarg}% \def\MHcs#1{\texttt{\char`\\#1}\endgroup} \DeclareRobustCommand\cs{\begingroup\MakePrivateLetters\MHcs} \def\endverbatim{\if@newlist \leavevmode\fi\endtrivlist\vspace{-\baselineskip}} \expandafter\let\csname endverbatim*\endcsname =\endverbatim \let\MTtheindex\theindex \def\theindex{\MTtheindex\MakePrivateLetters} \usepackage[final,hyperindex=false]{hyperref} \renewcommand*\usage[1]{\textit{\hyperpage{#1}}} \OnlyDescription \begin{document} \DocInput{mathtools.dtx} \end{document} % % \fi % % \changes{v1.0}{2004/07/26}{Initial release} % % \GetFileInfo{mathtools.drv} % % \CheckSum{2311} % % \title{The \pkg{mathtools} package\thanks{This file has version number % \fileversion, last revised \filedate.}} % % \author{Morten H\o gholm} % \date{\filedate} % % \maketitle % % \begin{abstract} % The \pkg{mathtools} package is an extension package to % \pkg{amsmath}. There are two things on \pkg{mathtools}' agenda: % 1)~correct various bugs/defeciencies in \pkg{amsmath} until % these are fixed by the \AmS{} and 2)~provide useful tools % for mathematical typesetting, be it a small macro for % typesetting a prescript or an underbraket, or entirely new % display math constructs such as a \env{multlined} environment. % \end{abstract} % % \tableofcontents % % \section{Introduction} % % Although \pkg{amsmath} provides many handy tools for mathematical % typesetting, it is nonetheless a static package. This is not a bad % thing, because what it does, it mostly does quite well and having % a stable math typesetting package is ``a good thing.'' However, % \pkg{amsmath} does not fulfill all the needs of the mathematical % part of the \LaTeX{} community, resulting in many authors writing % small snippets of code for tweaking the mathematical layout. Some % of these snippets has also been posted to newsgroups and mailing % 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 me harvesting newsgroups for % code and/or you writing me 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 to me. I % can be reached at % \begin{quote}\email{mh.ctan@gmail.com}\end{quote} % This is of course also the address to use in case of bug reports. % % \section{Package loading} % % % The \pkg{mathtools} package requires \pkg{amsmath} but is able to % pass options to it as well. Thus a line like % \begin{verbatim} % \usepackage[fleqn,tbtags]{mathtools} % \end{verbatim} % is equivalent to % \begin{verbatim} % \usepackage[fleqn,tbtags]{amsmath} % \usepackage{mathtools} % \end{verbatim} % % % \subsection{Special \pkg{mathtools} options} % % \begin{codesyntax} % \SpecialOptIndex{fixamsmath}\opt{fixamsmath}\texttt{~~~~} % \SpecialOptIndex{donotfixamsmathbugs}\opt{donotfixamsmathbugs} % \end{codesyntax} % The option \opt{fixamsmath} (default) fixes two bugs in % \pkg{amsmath}.\footnote{See the online \LaTeX{} bugs database % \url{http://www.latex-project.org/cgi-bin/ltxbugs2html} under % \AmS\LaTeX{} problem reports 3591 and 3614.} Should you for some % reason not want to fix these bugs then just add the option % \opt{donotfixamsmathbugs} (if you can do it without typos). The % reason for this extremely long name is that I really don't see why % you wouldn't want these bugs to be fixed, so I've made it slightly % difficult not to fix them. % % \begin{codesyntax} % \SpecialOptIndex{allowspaces}\opt{allowspaces}\texttt{~~~~} % \SpecialOptIndex{disallowspaces}\opt{disallowspaces} % \end{codesyntax} % Sometimes \pkg{amsmath} gives you nasty surprises, as here where % things look seemingly innocent: % \begin{verbatim} % \[ % \begin{gathered} % [p] = 100 \\ % [v] = 200 % \end{gathered} % \] % \end{verbatim} % Without \pkg{mathtools} this will result in this output: % \[ % \begin{gathered}[c] % = 100 \\ % [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: % \[ % \begin{gathered}[c] % [p] = 100 \\ % [v] = 200 % \end{gathered} % \] % With the option \opt{disallowspaces} (default) \pkg{mathtools} % disallows spaces in front of optional arguments where it could % possibly cause problems just as \pkg{amsmath} does with |\\| % inside the display environments. This includes the environments % \env{gathered} (and also those shown in \S % \vref{subsec:gathered}), \env{aligned}, \env{multlined}, and the % extended \env{matrix}-environments (\S \vref{subsubsec:matrices}). % If you however want to preserve the more dangerous standard % optional spaces, simply choose the option \opt{allowspaces}. % % % \section{Tools for mathematical typesetting} % % \begin{codesyntax} % \SpecialUsageIndex{\mathtoolsset}\cs{mathtoolsset}\marg{key val list} % \end{codesyntax} % Many of the tools shown in this manual can be turned on and off be % setting a switch to either true or false. In all cases it is done % with the command \cs{mathtoolsset}. A typical use could be something like % \begin{verbatim} % \mathtoolsset{ % showonlyrefs, % mathic % or mathic = true % } % \end{verbatim} % More information on the keys later on. % % \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 % macros \pkg{mathtools} provides for this. % % \subsubsection{A complement to \texttt{\textbackslash smash}, % \texttt{\textbackslash llap}, and \texttt{\textbackslash rlap}} % % \begin{codesyntax} % \SpecialUsageIndex{\mathllap} % \cs{mathllap}\oarg{mathstyle}\marg{math}\texttt{~~} % \SpecialUsageIndex{\mathclap} % \cs{mathclap}\oarg{mathstyle}\marg{math}\\ % \SpecialUsageIndex{\mathrlap} % \cs{mathrlap}\oarg{mathstyle}\marg{math}\texttt{~~} % \SpecialUsageIndex{\clap} % \cs{clap}\marg{text}\\ % \SpecialUsageIndex{\mathmbox} % \cs{mathmbox}\marg{math}\phantom{\meta{mathstyle}}\texttt{~~~~} % \SpecialUsageIndex{\mathmakebox} % \cs{mathmakebox}\oarg{width}\oarg{pos}\marg{math} % \end{codesyntax} % In \cite{Perlis01}, Alexander R.~Perlis describes some simple yet % useful macros for use in math displays. For example the display % \begin{verbatim} % \[ % X = \sum_{1\le i\le j\le n} X_{ij} % \] % \end{verbatim} % \[ % X = \sum_{1\le i\le j\le n} X_{ij} % \] % contains a lot of excessive white space. The idea that comes to % mind is to fake the width of the subscript. The command % \cs{mathclap} puts its argument in a zero width box and centers % it, so it could possibly be of use here. % \begin{verbatim} % \[ % X = \sum_{\mathclap{1\le i\le j\le n}} X_{ij} % \] % \end{verbatim} % \[ % X = \sum_{\mathclap{1\le i\le j\le n}} X_{ij} % \] % For an in-depth discussion of % these macros I find it better to read the article; an online % version can be found at % \begin{quote} % \url{http://www.tug.org/TUGboat/Articles/tb22-4/tb72perlS.pdf} % \end{quote} % Note that the definitions shown in the article do not exactly % match the definitions in \pkg{mathtools}. Besides providing an % optional argument for specifying the desired math style, these % versions also work around a most unfortunate \TeX{} % ``feature.''\footnote{The faulty reboxing procedure.} The % \cs{smash} macro is fixed too. % % % \subsubsection{Forcing a cramped style} % % \begin{codesyntax} % \SpecialUsageIndex{\cramped} % \cs{cramped}\oarg{mathstyle}\marg{math} % \end{codesyntax} % \cttPosting{Michael Herschorn}{1992/07/21} % Let's look at another example where we have used \cs{mathclap}: % \begin{verbatim} % \begin{equation}\label{eq:mathclap} % \sum_{\mathclap{a^2