| 1 |
%%% ==================================================================== |
| 2 |
%%% @LaTeX-file{ |
| 3 |
%%% filename = "technote.tex", |
| 4 |
%%% version = "2.0", |
| 5 |
%%% date = "1999/11/15", |
| 6 |
%%% time = "15:07:20 EST", |
| 7 |
%%% checksum = "58506 233 1647 12005", |
| 8 |
%%% author = "American Mathematical Society", |
| 9 |
%%% copyright = "Copyright 1995, 1999 American Mathematical Society, |
| 10 |
%%% all rights reserved. Copying of this file is |
| 11 |
%%% authorized only if either: |
| 12 |
%%% (1) you make absolutely no changes to your copy, |
| 13 |
%%% including name; OR |
| 14 |
%%% (2) if you do make changes, you first rename it |
| 15 |
%%% to some other name.", |
| 16 |
%%% address = "American Mathematical Society, |
| 17 |
%%% Technical Support, |
| 18 |
%%% Electronic Products and Services, |
| 19 |
%%% P. O. Box 6248, |
| 20 |
%%% Providence, RI 02940, |
| 21 |
%%% USA", |
| 22 |
%%% telephone = "401-455-4080 or (in the USA and Canada) |
| 23 |
%%% 800-321-4AMS (321-4267)", |
| 24 |
%%% FAX = "401-331-3842", |
| 25 |
%%% email = "[email protected] (Internet)", |
| 26 |
%%% supported = "yes", |
| 27 |
%%% keywords = "amsmath, latex", |
| 28 |
%%% abstract = "This is part of the AMS-\LaTeX{} distribution. It |
| 29 |
%%% is a document discussing some technical issues in the |
| 30 |
%%% contents and interface of AMS-\LaTeX{} packages." |
| 31 |
%%% docstring = "The checksum field above contains a CRC-16 checksum |
| 32 |
%%% as the first value, followed by the equivalent of |
| 33 |
%%% the standard UNIX wc (word count) utility output of |
| 34 |
%%% lines, words, and characters. This is produced by |
| 35 |
%%% Robert Solovay's checksum utility.", |
| 36 |
%%% } |
| 37 |
%%% ==================================================================== |
| 38 |
\NeedsTeXFormat{LaTeX2e}% LaTeX 2.09 can't be used (nor non-LaTeX) |
| 39 |
[1994/12/01]% LaTeX date must December 1994 or later |
| 40 |
\documentclass{amsdtx} |
| 41 |
|
| 42 |
\title{Technical notes on the \pkg{amsmath} package} |
| 43 |
\author{American Mathematical Society\\Michael Downes} |
| 44 |
\date{1999/10/29} |
| 45 |
|
| 46 |
\markboth |
| 47 |
{Technical notes on the \pkg{amsmath} package} |
| 48 |
{Technical notes on the \pkg{amsmath} package} |
| 49 |
\renewcommand{\sectionmark}[1]{} |
| 50 |
|
| 51 |
\providecommand{\etc}[1]{etc.} |
| 52 |
|
| 53 |
\providecommand{\begend}[1]{% |
| 54 |
{\ntt \symbol{92}begin\symbol{123}#1\symbol{125}} |
| 55 |
\ldots\ {\ntt\symbol{92}end\symbol{123}#1\symbol{125}}% |
| 56 |
} |
| 57 |
|
| 58 |
\MakeShortVerb{\|} |
| 59 |
|
| 60 |
\begin{document} |
| 61 |
\maketitle |
| 62 |
|
| 63 |
\section{Introduction} |
| 64 |
|
| 65 |
These notes are miscellaneous remarks on some technical questions |
| 66 |
applicable to version 2.0 of \amslatex/. |
| 67 |
|
| 68 |
\section{Deprecated and disallowed commands} |
| 69 |
|
| 70 |
Certain commands that were in the \pkg{amstex} package (the predecessor, |
| 71 |
in \amslatex/ 1.0 and 1.1, of the \pkg{amsmath} package) were moved into |
| 72 |
\pkg{amsxtra} because they seemed to be little-used relics: |
| 73 |
\cn{accentedsymbol}, \qq{sup accents} (\cn{sptilde}, \cn{sphat}, etc.). |
| 74 |
|
| 75 |
Certain other commands\mdash e.g., \cn{over}, \cn{pmatrix}, and |
| 76 |
\cn{cases}\mdash are changed by the \pkg{amsmath} package to produce |
| 77 |
warning messages or error messages, depending on their history; these |
| 78 |
are discussed in more detail in the following sections. |
| 79 |
|
| 80 |
\section{Why do \cn{matrix}, \cn{pmatrix}, and \cn{cases} stop working |
| 81 |
when I add the \pkg{amsmath} package?} |
| 82 |
|
| 83 |
If you used the \fn{plain.tex} versions of \cn{matrix}, \cn{pmatrix}, or |
| 84 |
\cn{cases} in a document and then later converted the document to use |
| 85 |
the \pkg{amsmath} package (or one of the AMS documentclasses, which |
| 86 |
automatically call the \pkg{amsmath} package internally), the instances |
| 87 |
of those commands will produce error messages. The problem is that when |
| 88 |
\latex/ was originally created, it adopted most of its mathematics |
| 89 |
features straight from \fn{plain.tex}. But in the case of \cn{matrix}, |
| 90 |
\cn{pmatrix}, \cn{cases} this was a mistake\mdash the \fn{plain.tex} |
| 91 |
syntax for them is decidedly non-\latex/ in style, for example the fact |
| 92 |
that they use \cs{cr} instead of \cn{\\} to mark line breaks, and they |
| 93 |
don't use \cn{begin} and \cn{end}. In basic \latex/ this mistake will be |
| 94 |
perpetuated at least until \latex/3 appears, in order to avoid breaking |
| 95 |
existing documents. But no existing documents that were written with the |
| 96 |
\pkg{amsmath} package have that syntactic problem, as \pkg{amsmath} |
| 97 |
provides proper \latex/-syntax versions of \cn{matrix} and the others. |
| 98 |
The possibility of optionally allowing the \fn{plain.tex} variants to |
| 99 |
make document conversion easier seems ill-advised since those variants |
| 100 |
are so blatantly wrong in a \latex/ context. The \env{array} environment |
| 101 |
ought to have been used instead. |
| 102 |
|
| 103 |
\section{Why do \cn{over}, \cn{atop}, \cn{above} [\dots{\ntt withdelims}] |
| 104 |
give a warning when I add the \pkg{amsmath} package?} |
| 105 |
|
| 106 |
Using the six generalized fraction commands \cn{over}, |
| 107 |
\cn{overwithdelims}, \cn{atop}, \cn{atopwithdelims}, \cn{above}, |
| 108 |
\cn{abovewithdelims} is not really a good idea in \latex/, for reasons |
| 109 |
explained below. I construe \latex/'s provision of \cs{frac}, and the |
| 110 |
lack of any mention in the \latex/ book of the primitive fraction |
| 111 |
commands, as an implicit injunction against their use, although I don't |
| 112 |
think Lamport actually spent a lot of time pondering the issue, and the |
| 113 |
basic \latex/ version of \cn{frac} provides access only to \cn{over}, |
| 114 |
not to \cn{atop}, \cn{above}, or the \verb'withdelims' variants. The |
| 115 |
\pkg{amsmath} package, however, provides a \cn{genfrac} command that |
| 116 |
gives user-level access to all six of the generalized fraction |
| 117 |
primitives in a way that conforms to the syntactic conventions followed |
| 118 |
by all other \latex/ commands. |
| 119 |
|
| 120 |
Not only is the unusual syntax of the \tex/ primitives rather out of |
| 121 |
place in \latex/, but furthermore that syntax seems to be responsible |
| 122 |
for one of the most significant flaws in \tex/'s mathematical |
| 123 |
typesetting capabilities: the fact that the current mathstyle at any |
| 124 |
given point in a math formula cannot be determined until the end of the |
| 125 |
formula, because of the possibility that a following generalized |
| 126 |
fraction command will change the mathstyle of the \emph{preceding} |
| 127 |
material. To cite two of the worst side effects: \cn{mathchoice} must |
| 128 |
actually typeset all four of its arguments, instead of being able to |
| 129 |
immediately select only one; and, were it possible to always know the |
| 130 |
current math style at a given point, math font selection would be |
| 131 |
greatly simplified and the upper limit of 16 different math font |
| 132 |
\cn{fam}s would never be a problem as \cn{text,script[script]font} |
| 133 |
assignments for any \cn{fam} could take immediate effect and therefore |
| 134 |
could be changed arbitrarily often within a single formula. More |
| 135 |
concretely, math font selection difficulties are responsible for many of |
| 136 |
the more convoluted passages in the source code of \latex/'s NFSS (that |
| 137 |
does font loading on demand) and of the \pkg{amsmath} package, and by |
| 138 |
extension it has historically been responsible for significant delays in |
| 139 |
making new features available to end users and for making those features |
| 140 |
more prone to bugs. |
| 141 |
|
| 142 |
There are additional bad consequences following from the syntax of those |
| 143 |
generalized fraction commands that only become evident when you do some |
| 144 |
writing of nontrivial macros for math use. For example, as things |
| 145 |
currently stand you cannot measure the size of any object in math |
| 146 |
without going through \cn{mathchoice} and \emph{leaving and reentering |
| 147 |
math mode} via \verb'\hbox{$' (which then introduces complications |
| 148 |
regarding \cn{everymath} and \cn{mathsurround}). And it seems that |
| 149 |
uncertainty about the current mathstyle is the only barrier to allowing |
| 150 |
the use of mu units with \cn{vrule}, to make vertical struts in |
| 151 |
constructing compound symbols or notation. And so on and so forth. |
| 152 |
|
| 153 |
\section{The \opt{fleqn} option and \cn{mathindent}} |
| 154 |
|
| 155 |
Strictly speaking, the \pkg{amsmath} package doesn't use \cn{mathindent} |
| 156 |
to control the left indent of displayed equations when the \opt{fleqn} |
| 157 |
option is in effect: it uses an internal parameter \cs{@mathmargin} |
| 158 |
instead. However, for compatibility with existing \latex/ documentation, |
| 159 |
\pkg{amsmath} turns \cn{mathindent} into an alias for \cs{@mathmargin}. |
| 160 |
There is a small risk here: In the plain \latex/ implementation, |
| 161 |
\cn{mathindent} is a dimen register, but with \pkg{amsmath} |
| 162 |
\cs{@mathmargin} is a skip register and, by association, so is |
| 163 |
\cn{mathindent}. If any package or documentclass uses \cn{mathindent} in |
| 164 |
a way that depends on it being a dimen register, when used in |
| 165 |
conjunction with the \pkg{amsmath} package it may be vulnerable to a |
| 166 |
well-known pitfall having to do with the primitive \tex/ lookahead for a |
| 167 |
\texttt{plus} or \texttt{minus} key word. However if the standard |
| 168 |
\latex/ commands \cn{setlength} and \cn{addtolength} are used to modify |
| 169 |
\cn{mathindent} then this problem will not arise. |
| 170 |
|
| 171 |
\section{Why can't I use abbreviations for \protect\begend{align}?} |
| 172 |
|
| 173 |
Authors often like to use abbreviations such as |\beq| |\eeq| for |
| 174 |
|\begin{equation}| |\end{equation}|. For some environments defined by |
| 175 |
the \pkg{amsmath} package, such as \env{align}, \env{gather}, |
| 176 |
\env{multline}, and others of the same general type, this does not work: |
| 177 |
An attempt to define |\bal| |\eal| as shorthand for |\begin{align}| |
| 178 |
|\end{align}| will fail with a puzzling error message. This has to do |
| 179 |
with unfortunately nontrivial technical complications: the given |
| 180 |
environments must read their contents as a delimited macro argument |
| 181 |
because they do multipass processing of the contents using algorithms |
| 182 |
inherited from Spivak's \fn{amstex.tex}. The obvious |
| 183 |
solution\mdash substitution of different algorithms that do box shuffling |
| 184 |
instead of token shuffling for the multipass calculations\mdash would |
| 185 |
require rewriting these display environments from the ground up; while |
| 186 |
that is a worthy goal, it was beyond the original scope of the |
| 187 |
\amslatex/ project. Work is under way on an auxiliary package called |
| 188 |
\pkg{breqn} that addresses not only this problem but a number of others; |
| 189 |
at the time of this writing, however [September 1999] it has only |
| 190 |
progressed as far as a beta release. |
| 191 |
|
| 192 |
Some workarounds: |
| 193 |
\begin{itemize} |
| 194 |
\item |\def\bal#1\eal{\begin{align}#1\end{align}}| |
| 195 |
\item Define |\newcommand{\env}[2]{\begin{#1}#2\end{#1}}| and then use |
| 196 |
|\env{align}{...}| |
| 197 |
\end{itemize} |
| 198 |
|
| 199 |
\section{The \pkg{upref} package} |
| 200 |
|
| 201 |
The reason for splitting out the \pkg{upref} package instead of |
| 202 |
automatically incorporating it in the \cls{amsart} and \cls{amsbook} |
| 203 |
classes is this: It involves low-level surgery on an important \latex/ |
| 204 |
command. This means that if ever this command changes in the future (as |
| 205 |
it did between versions 2.09 and 2e of \latex/) we have a maintenance |
| 206 |
problem. And the benefit that \pkg{upref} provides is something that |
| 207 |
most end users don't care much about. |
| 208 |
|
| 209 |
\section{The \pkg{amsintx} package} |
| 210 |
|
| 211 |
After a very preliminary trial release the \pkg{amsintx} package was |
| 212 |
withdrawn to await further development. It is still considered a worthy |
| 213 |
project but has simply not yet made it to the head of the priority queue |
| 214 |
in the AMS \latex/ development program, as it has had to contend with a |
| 215 |
number of other equally worthy projects for development time. |
| 216 |
|
| 217 |
\section{Hyphenation in the documentation} |
| 218 |
|
| 219 |
Hyphenation was allowed for certain long command names in |
| 220 |
\fn{amsldoc.tex}; this presented technical difficulties because \latex/ |
| 221 |
normally deactivates hyphenation for tt fonts. The method chosen to |
| 222 |
reinstate hyphenation was to turn off the encoding-specific function |
| 223 |
\cs{OT1+cmtt} that disables the \cs{hyphenchar} for tt fonts; see the |
| 224 |
definition of \cn{allowtthyphens} in \fn{amsdtx.dtx}. Then a list of all |
| 225 |
tt words in the document was gathered (from the \fn{.idx} file, produced |
| 226 |
by the \cn{cn}, \cn{fn}, \cn{pkg}, etc. commands) and \cn{showhyphens} |
| 227 |
was applied to this list. The result was another list in the resulting |
| 228 |
\tex/ log, containing those words in a form suitable for the argument of |
| 229 |
\cn{hyphenation}. That list was then edited by hand to overrule |
| 230 |
undesirable hyphenations; words with acceptable hyphenations were |
| 231 |
dropped from the list, as they don't need to be repeated there. |
| 232 |
|
| 233 |
\end{document} |