path: root/macros/latex/required/amsmath/diffs-m.txt

diffs-m.txt [1999/12/15] American Mathematical Society

This is a synopsis of the principal differences between various versions
of the amsmath package and its companion packages.

A synopsis of changes in the "AMS-LaTeX" distribution is included at the
end of this file. See also diffs-c.txt in the amslatex/classes area.

Those upgrading from version 1.2 to version 2.0 will probably be
interested in the question:

  After I upgrade will anything fail in my pre-existing documents?

Certain of the bug fixes have the potential to affect the output of
existing documents in the following ways:

---Vertical spacing for some displayed equations will change because
"abovedisplayshortskip" is now applied when possible.

---Incorrect horizontal spacing for certain math constructs will change,
e.g., for \iint\nolimits or a subscript on a double-accented letter.

---The default subscript placement in displayed formulas for \varinjlim,
\varprojlim, \varliminf, \varlimsup is now below rather than to the
side. To get the old behavior, add \nolimits---e.g.,
\varliminf\nolimits_{...}.

---Ellipsis dots in text (\ldots or \dots) will now behave the same as
in standard LaTeX; the surrounding space may therefore change.

During regression testing we found some errors cropping up in documents
from incorrect usage that had not been caught with version 1.2. Although
these errors are relatively rare, documents containing such usage will
need to be corrected before they will run properly with version 2.0:

---Use of two mutually exclusive display structures for the same
display. In this example the outer \[ \] are redundant:

      \[
      \begin{align*}
      ...
      \end{align*}
      \]

---Inadequate argument markup for math accents:

      \hat \mathcal{C}

This should have been written with braces surrounding the argument of
the \hat command: \hat{\mathcal{C}}.

For documents where error messages crop up after the upgrade, there are
various possible approaches, including:

(a) Change instances of incorrect usage (if applicable).

(b) Put a copy of amsmath.sty version 1.2 into the home directory of the
document. Then it should continue to work the same as before.

(c) Use the snapshot package in combination with a shell script to
arrange that version 1.2 of amsmath is found instead of 2.0 when
processing the document. See ftp://ftp.ams.org/pub/tex/snapshot.*. This
approach requires a certain amount of technical knowledge.

(d) Downgrade to version 1.2 again.

========================================================================
Changes in amsmath 2.0 [November 1999]

---The AMS-LaTeX User's Guide (amsldoc.tex) has been turned into the
   AMSmath User's Guide by moving the amsthm documentation into a
   separate file (amsthdoc.tex) in the amslatex/classes area.

---Restored normal use of "shortskip" spacing in single equations.

[!! NOTE: This means that page breaks may change in existing documents.]

---Restored normal use of available shrink around binary operators in
   single equations.

---Fixed poor subscript placement for double-accented letters. Math
accent handling was reworked in the process in such a way that the
capitalized forms of the math accent commands are no longer necessary.
\hat{\hat{X}} will do proper alignment of the second accent. \Hat et
cetera are retained for compabitility reasons. (Thanks to Javier Bezos
for donating some code from his accents package.)

[!! NOTE: Improper math accent use will now produce wrong output.]

Suppose that we have \boldH defined in the preamble as
\newcommand{\boldH}{\mathbf{H}}. Then the following examples illustrate
recommended usage.

     \hat{\mathbf{H}}    OK
     \hat{\boldH}        OK
     \hat\boldH          Works OK, but deprecated by the LaTeX book
     \hat\mathbf{H}      Not OK! Output will be incorrect.

Since the output will be wrong, amsmath gives an error message when the
last variant is detected.

---The following kinds of mixed structures worked by happenstance with
   amsmath 1.2, although they should have produced an error message.
   With amsmath 2.0 they will produce an error or warning message.

   [!! NOTE: Potential error messages]

    % Outer \[ \] is redundant

    \[
    \begin{align*}
     ...
    \end{align*}
    \]

    % Outer \begin{equation*} ... \end{equation*} is redundant

    \begin{equation*}\begin{alignat*}{2}
    ...
    \end{alignat*}
    \end{equation*}

    % No printed material is allowed between \begin{equation} and
    % \begin{split}:

    \begin{equation*}\left \{
    \begin{split}
     ...
    \end{split}\right .
    \end{equation*}

---diff12.tex is replaced by diffs-m.txt and diffs-c.txt, with the
   latter moving to the amslatex/classes area.

---Added an "?" option which gives some information about the available
   documentation.

---The amsmath definitions for matrix, pmatrix, and cases are
   incompatible with the plain-TeX syntax for \pmatrix, \matrix, and
   \cases, which are used occasionally by some authors in LaTeX
   documents. In version 2.0 the error messages resulting from the
   plain-TeX syntax have been made more intelligible.

---If you need the boldsymbol facilities of the amsbsy package, use of
   the "bm" (boldmath) package is recommended instead for new documents.
   The amsbsy package is retained for compatibility with existing
   documents. If you have a recent version of LaTeX (1998 or newer) you
   already have the bm package; otherwise you may need to get it from
   CTAN. (It is not an AMS package.)

---\iint\nolimits: Fixed poor placement of subscript (also \iiint,
\idotsint, etc).

---\varinjlim, \varprojlim, \varliminf, \varlimsup: Default to
\displaylimits instead of nolimits.

---Fixed alignedat so that it doesn't take the first token of its
   contents and try to interpret it as a number.

---Leave text version of \dots and \ldots unchanged.

---Changed \numberwithin so it no longer assumes previous definition of
   \thesomething contained no prefixes.

---\mathbf{\Gamma}: Leave cap Greek letters alone instead of converting
   them from variable (fam 7) to fixed (fam 0). \mathbf{\gamma} still
   fails---but that's a math font problem.

---\mathindent is aliased to \@mathmargin so that when the fleqn option
   is used, users can reset it as the LaTeX book advertises.

---With the showkeys package: Corrected loss of marginal notes when
labels occurred inside an align environment.

---Carried over some tweaks (\bmod, \right/leftarrowfill) from the 1996
   version of plain.tex.

---Adjusted spacing of overarrow@ and underarrow@ to allow more room for
   larger cmsy arrowheads.

---Corrected spurious "overfull \hbox" warnings for \xrightarrow.

---Corrected poor spacing for \xleftarrow.

---Removed the \leavevmode in \smash which caused trouble for some
   applications (e.g., the crop package) that expected the original
   LaTeX definition.

---Changed \def to \newcommand/\newenvironment where appropriate.

---Use \sqrtsign instead of \@@sqrt (but include a backward
   compatibility hack for the latter).

---Left brace in \env{cases} environment would fail to work in
   certain circumstances: Fix by using \lbrace instead of \{.

---Use \ignorespacesafterend where applicable instead of
   \global\@ignoretrue.

---Protected commands in the definition of \theequation were
   incorrectly expanded by the subequations environment when copying
   the definition to \theparentequation: Fix by using \protected@edef.

---Spurious extra space following punctuation at that end of a display:
   In \math@cr, \math@cr@@, etc, use \iffalse{\fi instead of simply { to
   keep an unwanted mathord atom from being added at the end of the
   current math list; added \endmultline@math to work around a similar
   sort of problem specific to the `multline' environment.

---Various wrong results or no effect for \displaybreak inside "align",
   "alignat", etc. Resetting \dspbrk@level in the \everycr of
   \@display@init cleared most of these up.

---Changed \displaybreak to issue an error message if enclosed in boxing
   environment that will keep it from having any effect.

---Turned off \displaybreak during the measuring phase of multline.

---Fixed some numbering problems with multline and multline* and error
   for use of \tag.

---Use \@gtempa instead of \@tempa where assigned globally (standard
   save stack precaution).

---Save and restore \column@ to keep aligned from screwing up the column
   counting of a parent align environment. Made \column@ assignments
   uniformly global, except in a couple of places where the risk of side
   effects seemed too great.

---Error recovery for misspelled '\end{multline}' was not very helpful.
   Improve \collect@body along lines suggested by Hellström.

---Fixed up certain number placement problems with align

---Add \alignsafe@testopt to work around a LaTeX bug: when a nested
   alignment environment that takes an optional argument has an empty
   first cell (i.e., begins with an &) LaTeX's optional argument
   scanning screws up the alignment state.

---Add `mathdisplay' environment (internal use) to correct several
   problems of \[ \] and the `equation' environment arising from the
   previous implementation as a degenerate case of `gather'.

---It is possible now to use \eeq as an abbreviation for \end{equation}
(one of the consequences of the preceding change). But still not \eal
for \end{align} or certain other display structures.

---Reorganize `split' internal calling sequence to go along with the use
   of `mathdisplay' in \[ \] and `equation'.

---Suppression of LaTeX error messages during measuring phase made
   primitive TeX errors harder to understand; stop suppressing. (As a
   result, users will sometimes get redundant error messages now.)
   Remove obsolete Sb, Sp environments again.

---The file amsintx.dtx was removed from the distribution pending
   further development.

---Remove the \ifinany@ switch, use \spread@equation instead to achieve
   the same ends.

---Remove unbracefonts@ function, no longer needed after changes in
   math accent handling.

---Got rid of the special trap for '^x that had been carried over from
AMS-TeX.

---Made \overline, \doteq, \longrightarrow, etc, robust.

---Changed \relbar to use \std@minus---otherwise \underleftrightarrow
works poorly in a \DeclareMathOperator definition.

---Use \new@ifnextchar in matrix, pmatrix, cases so that \\<newline>[x]
doesn't trigger an error.

---Bug fix for nested use of \label inside minipage inside equation.

---Add minalignsep after every second column in aligned, for consistency
with align.

========================================================================
Changes in amsmath 1.2 [January 1995]

---Name change; relation to the "amsfonts" package

In version 1.1 of AMS-LaTeX, the name of this package was "amstex". The
new name is "amsmath". The amstex package automatically invoked the
amsfonts package as well; the amsmath package does not.

---Adapted for LaTeX2e

Old method of invocation:

  \documentstyle[amstex]{article}% LaTeX 2.09

New method of invocation:

  \documentclass{article}
  \usepackage{amsmath}

---Handling of options intlim, nosumlim, nonamelm, righttag, ctagsplt

Old usage:

  \documentstyle[amstex,righttag,intlim]

New usage:

  \usepackage[reqno,intlimits]{amsmath}

Several option names were changed (mainly, they are no longer restricted
to eight characters):

  intlim   -> intlimits
  nosumlim -> nosumlimits
  nonamelm -> nonamelimits
  righttag -> reqno         [for consistency with "leqno"]
  ctagsplt -> centertags

---Character @ is no longer used as a special command prefix

Certain commands in the amstex pkg started with "@" instead of "\". This
special usage has been discontinued, except for the amscd package, and
then only within the CD environment. Practically speaking, this means
primarily that it is no longer necessary to use doubled @@ to get a
single printed @ character (e.g., in e-mail addresses).

---The @, and @! micro-spacing commands are no longer provided

As a consequence of the @ character change, "@," and "@!" are no longer
recognized spacing commands. An \mspace command is provided that can be
used instead; see the AMSmath User's Guide.

---Extensible arrow commands @>>> and @<<<

The commands @>>> and @<<< are no longer available [except in the CD
environment of the amscd package]; alternative commands \xleftarrow and
\xrightarrow are provided by the amsmath package. The sub and
superscripts are given through an optional resp. mandatory argument, for
example

  X\xleftarrow{b}Y                  % superscript "b" only
  X\xrightarrow[\alpha]{\beta}Y     % sub alpha, sup beta

---The command \bold has been superseded by the command \mathbf, as the
latter is now the standard name provided by LaTeX for this purpose.

---The commands \newsymbol, \frak, \Bbb are no longer available because
the amsfonts package is not loaded by amsmath. In any case those
commands now have new names---\frak -> \mathfrak, \Bbb -> \mathbb, etc.
See the amsfonts documentation for further details.

---The amsmath package provides \lvert and \rvert to use for vert-bar
symbols when they act as delimiters (compare \langle, \rangle for
angle-bracket delimiters). Commands \lVert and \rVert are likewise
provided instead of \| for paired-delimiter use of the double-vert
symbol. Use of | and \| for paired delimiters can lead to incorrect
spacing in rare cases. Further discussion is found in the AMS-LaTeX
user's guide (amsldoc.tex).

---The ~ command is now left unchanged by amsmath; the change
that makes it remove a redundant preceding or following space character
is now done only by AMS documentclasses (in version 1.1 this was done by
the amstex package).

---The following rarely used commands are removed to the amsxtra
package: \accentedsymbol, \sphat, \spcheck, \sptilde, \spdot, \spddot,
\spdddot, \spbreve, \@))), \@(((.

---The six generalized fraction commands \over, \overwithdelims, \atop,
\atopwithdelims, \above, \abovewithdelims are deprecated and produce
warning messages. Their functionality can be obtained through \frac,
\binom, and \genfrac instead. See amsldoc.tex and technote.tex for
further details.

---The \fracwithdelims command is gone, as \genfrac provides
equivalent functionality (and a little more).

---The optional argument of \frac that allowed changing the thickness of
the fraction line is gone. That functionality is now provided only
through \genfrac: the need to change the line thickness is so rare in
practice that it seems better not to burden the ubiquitous \frac command
with the somewhat time-consuming look-ahead process required for an
optional argument. I.e., this change will contribute in a small way to
making your documents run faster.

---The commands \lcfrac and \rcfrac for left or right alignment of
continued fraction numerators are gone; they are replaced by an optional
argument of the \cfrac command.

---A new command \DeclareMathOperator is provided for defining new
operator names:

\DeclareMathOperator{\Tr}{Tr}
\DeclareMathOperator*{\xlim}{x-lim}

The * form makes the operator name produce limit-style sub and
superscripts, like \max or \lim. This is now the preferred method,
instead of using the old command \operatorname (which is, however,
retained for now). The command \operatornamewithlimits has been renamed
\operatorname*. These commands now can also be obtained through a
separate package amsopn, so it's not necessary to load the entire
amsmath package just to get that feature.

---Environments "Sb", "Sp" retired.

The environments Sb and Sp for multiline subscripts have been replaced
by a single command \substack, used as follows:

\sum_{\substack{first line\\second line}}

This command can be used equally well in a subscript or superscript, and
provides better vertical positioning (as compared to Sb, Sp) if a
multiline subscript is placed on the side, as perhaps for an integral.
There is also a slightly generalized alternative, an environment
subarray that allows you to specify either centering or left alignment
for the contents:

\sum_{\begin{subarray}{l}first line\\second line\end{subarray}}

---New command \nobreakdash

A command \nobreakdash is provided to suppress the possibility of a
linebreak after the following hyphen or dash. For example, if you write
"$p$\nobreakdash-adic" then a linebreak will never be taken between the
hyphen and the "adic".

---The placement of equation numbers has been substantially improved for
align, gather, and split. Numbers will now never overlap on top of the
equation body (as far as we can ascertain), and they are much less
likely to be shifted up or down unnecessarily when there is actually
adequate space to leave the number in the normal place. In a few
remaining cases, an equation number will be shifted unnecessarily
because technical complications make accurate measurement of the
available room too difficult; for those cases a \raisetag command is
provided that allows you to manually adjust the vertical position of the
equation number.

---The [xx]align[at] family of environments has been thoroughly revised:
now the xalignat environment is gone, as its function has been merged
into the align environment (it's no longer necessary to specify how many
side-by-side structures, as was required for xalignat, because align
automatically handles any number of them). Similarly, the xxalignat
environment has been replaced by an environment flalign that doesn't
require you to specify how many side-by-side structures will be needed.
Certain numbering problems (presence of an equation number when it
should be absent, or vice versa) have also been cleared up.

(Thanks to David M. Jones for his substantial [volunteer] work behind
this change and the preceding one.)

---The alignedat environment was changed to take two arguments rather
than one: a mandatory argument (as formerly) specifying the number of
align structures, and a new optional one specifying the placement of the
environment (parallel to the optional argument of aligned). However,
aligned is simpler to use, allowing any number of aligned structures
automatically, and therefore the use of alignedat is deprecated.

---The seldom-used command \oldnos is gone; if you need it, you should
consult the LaTeX documentation on using fonts (e.g., fntguide.tex) to
find out how to construct an equivalent command.

---A new subequations environment causes all numbered equation
environments within its scope to be numbered (4.9a) (4.9b) (4.9c) etc.,
if the preceding numbered equation was 4.8. A \label command immediately
after \begin{subequations} will produce a \ref of the parent number
`4.9', not `4.9a'. The counters used by the subequations environment are
parentequation and equation and standard uses of \addtocounter,
\setcounter, etc., are possible with those counter names.

---The amsmath package (unlike amstex) respects the setting provided by
the documentclass for putting equation numbers on the right or the left.
[Technical note: a documentclass that has leqno as the default should
explicitly pass that option to the amsmath package with
\PassOptionsToPackage in order for it to be effective.]

---The fleqn option for left-aligned instead of centered equations is
now supported (thanks to David M. Jones).

************************************************************************
The remainder of this file discusses some changes that do not directly
pertain to the amsmath package but to the parent distribution known as
"AMS-LaTeX".

========================================================================
Changes in AMS-LaTeX 2.0

---The AMS-LaTeX User's Guide (amsldoc.tex) is split up into amsldoc.tex
and amsthdoc.tex, with the latter moving into the "classes" area.

---The file amslatex.faq was split into amsmath.faq and amsclass.faq.

---The file amslatex.bug was done away with; most of the information was
merged into diffs-m.txt, diffs-c.txt, amsmath.faq, and amsclass.faq.

========================================================================
Changes in AMS-LaTeX 1.2

---Adapted for LaTeX2e

AMS-LaTeX 1.0 and 1.1 were designed to work with LaTeX 2.09, which
became obsolete in 1994 with the appearance of "LaTeX2e". AMS-LaTeX 1.2
has been extensively adapted to take advantage of various features of
LaTeX2e. It is no longer a separate TeX format---i.e., it does not need
to be invoked by a separate "amslatex" command.

---LaTeX 2.09 font commands (\bf, \it, etc)

Pre-existing documents will for the most part continue to work fine
without requiring any changes. However, depending on the installation
options used for your copy of AMS-LaTeX 1.1 you may need to update the
options list of the \documentstyle command by adding newlfont, for
example:

  \documentstyle[newlfont]{amsart}

---The packages amsfonts, amssymb were moved to the AMSFonts
distribution. They used to be included in the AMS-LaTeX distribution for
pragmatic reasons but their natural home is with the AMSFonts
distribution.

---Package amstex renamed to amsmath

The amstex package has been renamed amsmath. The old name `amstex' came
from the fact that version 1.0 was a more or less straight port into
LaTeX of selected portions from the macro package AmS-TeX written by
Michael Spivak, but the historical origins of the package are likely of
less interest to the general usership---especially looking to the
future---than a straightforward declaration in the name `amsmath' of the
sort of features that are provided.

Another important reason for the name change was to make possible some
progress that would be out of the question (because of the impact on
existing documents) if the name `amstex' were retained. For example,
unlike amstex, amsmath doesn't automatically load the amsfonts package,
as that package was moved out to the AMSFonts distribution as described
above. If this change were not accompanied by a name change, many
existing documents would have to be updated by hand (adding
\usepackage{amsfonts}) in order to run without error. A frozen version
of amstex.sty is provided for processing pre-existing documents; it
won't have active maintainence henceforth except for bug fixes. For new
documents, authors should use the amsmath package.

Therefore, "\usepackage{amstex}" is incorrect usage---do not rely on the
1994 edition of `The LaTeX Companion' in this respect (unless you obtain
the errata for Chapter 8).

---New documentclass amsproc

A new documentclass amsproc was added for collections of articles, such as
the proceedings of a conference.