%%% ====================================================================
%%% @LaTeX-file{
%%%   filename  = "technote.tex",
%%%   version   = "1.2b",
%%%   date      = "29 October 1996",
%%%   time      = "11:39:02 EST",
%%%   checksum  = "60479 201 1425 10350",
%%%   author    = "American Mathematical Society",
%%%   copyright = "Copyright (C) 1995 American Mathematical Society,
%%%                all rights reserved.  Copying of this file is
%%%                authorized only if either:
%%%                (1) you make absolutely no changes to your copy,
%%%                including name; OR
%%%                (2) if you do make changes, you first rename it
%%%                to some other name.",
%%%   address   = "American Mathematical Society,
%%%                Technical Support,
%%%                Electronic Products and Services,
%%%                P. O. Box 6248,
%%%                Providence, RI 02940,
%%%                USA",
%%%   telephone = "401-455-4080 or (in the USA and Canada)
%%%                800-321-4AMS (321-4267)",
%%%   FAX       = "401-331-3842",
%%%   email     = "tech-support@ams.org (Internet)",
%%%   supported = "yes",
%%%   keywords  = "amslatex, ams-latex",
%%%   abstract  = "This is part of the AMS-\LaTeX{} distribution. It
%%%                is a document discussing some technical issues in the
%%%                contents and interface of AMS-\LaTeX{} packages."
%%%   docstring = "The checksum field above contains a CRC-16 checksum
%%%                as the first value, followed by the equivalent of
%%%                the standard UNIX wc (word count) utility output of
%%%                lines, words, and characters.  This is produced by
%%%                Robert Solovay's checksum utility.",
%%% }
%%% ====================================================================
\NeedsTeXFormat{LaTeX2e}% LaTeX 2.09 can't be used (nor non-LaTeX)
[1994/12/01]% LaTeX date must December 1994 or later
\documentclass{amsdtx}

\title{Technical notes on \amslatex/ version 1.2}
\author{American Mathematical Society\\Michael Downes}
\date{29 October 1996 \\
Version 1.02}

\markboth{Technical notes on \amslatex/ version 1.2}
  {Technical notes on \amslatex/ version 1.2}
\renewcommand{\sectionmark}[1]{}

\providecommand{\etc}[1]{etc.}

\MakeShortVerb{\|}

\begin{document}
\maketitle

\section{Introduction}

These notes are miscellaneous remarks on some technical questions that
arose during the creation of version 1.2 of \amslatex/ and subsequent
communications between users and AMS tech-support. We expect to add
more sections as further questions arise.

\section{Why can't I use abbreviations for the \env{equation}
environment?}

Many users have discovered to their dismay that when switching from
ordinary \latex/ to the \pkg{amsmath} package, they are no longer able
to use abbreviations such as |\beq| |\eeq| for |\begin{equation}|
|\end{equation}|. This has to do with unfortunately nontrivial technical
complications: the environments such as \env{align} must read their
contents as a delimited macro argument because they do multipass
processing of the contents using algorithms inherited from Spivak's
\fn{amstex.tex}. The obvious solution---substitution of different
algorithms that do box shuffling instead of token shuffling for the
multipass calculations---would require rewriting these display
environments from the ground up; while that is a worthy goal, it was
beyond the original scope of the \amslatex/ project. Some progress has
in fact been made on such a solution [time of writing: January 1995],
but not yet to the point of being ready for release.

Users have proposed two workarounds (September 1996):
\begin{itemize}
\item |\def\beq#1\eeq{\begin{equation}#1\end{equation}}| (Donald Arseneau)
\item Define |\newcommand{\env}[2]{\begin{#1}#2\end{#1}}| and then use
  |\env{equation}{...}| (Michael Skeide)
\end{itemize}

\section{The \pkg{upref} package}

The reason for splitting out the \pkg{upref} package instead of
automatically incorporating it in the \cls{amsart} and \cls{amsbook}
classes is this: It involves low-level surgery on an important \latex/
command. This means that if ever this command changes in the future (as
it did between versions 2.09 and 2e of \latex/) we have a maintenance
problem. And the benefit that \pkg{upref} provides is something that
most users don't care much about. It can be used for in-house AMS
production but it need not be inflicted on all users. Instead we leave
the choice to the individual user.

\section{The \pkg{amsintx} package}

The \pkg{amsintx} package is still in the experimental stage. The
variety of notation for integrals and sums is so great it's difficult to
pick one's way through all the complications.

\section{Deprecated and disallowed commands}

Certain commands were moved out of \pkg{amstex} into \pkg{amsxtra}
because they seemed to be little-used relics:
\cn{accentedsymbol}, `sup accents' (\cn{sptilde}, \cn{sphat}, etc.). The
primitive commands \cn{over}, \cn{atop}, \cn{above} were disallowed by
the \pkg{amsmath} package when it superseded \pkg{amstex} (see below).

\section{Hyphenation in the documentation}

Hyphenation was allowed for certain long command names in
\fn{amsldoc.tex}; this presented technical difficulties because \latex/
normally deactivates hyphenation for tt fonts. The method chosen to
reinstate hyphenation was to turn off the encoding-specific function
\cs{OT1+cmtt} that disables the \cs{hyphenchar} for tt fonts; see the
definition of \cn{allowtthyphens} in \fn{amsdtx.dtx}. Then a list of all
tt words in the document was gathered (from the \fn{.idx} file, produced
by the \cn{cn}, \cn{fn}, \cn{pkg}, etc. commands) and \cn{showhyphens}
was applied to this list. The result was another list in the resulting
\tex/ log, containing those words in a form suitable for the argument of
\cn{hyphenation}. That list was then edited by hand to overrule
undesirable hyphenations; words with acceptable hyphenations were
dropped from the list, as they don't need to be repeated there.

\section{Why did \cn{matrix}, \cn{pmatrix}, and \cn{cases} stop working
when I added the \pkg{amsmath} package?}

If you used the \fn{plain.tex} versions of \cn{matrix}, \cn{pmatrix}, or
\cn{cases} in a document and then later converted the document to use the
\pkg{amsmath} package (or one of the AMS documentclasses, which
automatically call the \pkg{amsmath} package internally), the instances
of those commands will produce error messages. The problem
is that when \latex/ was originally created, it adopted most of its
mathematics features straight from \fn{plain.tex}. But in the case of
\cn{matrix}, \cn{pmatrix}, \cn{cases} this was a mistake---the \fn{plain.tex}
syntax for them is decidedly non-\latex/ in style, for example the fact
that they use \cs{cr} instead of \cn{\\} to mark line breaks, and they
don't use \cn{begin} and \cn{end}. In basic \latex/ this mistake will be
perpetuated at least until \latex/3 appears, in order to avoid breaking
existing documents. But no existing documents that were written with the
\pkg{amsmath} package have that syntactic problem, as \pkg{amsmath}
provides proper \latex/-syntax versions of \cn{matrix} and the others.
The possibility of optionally allowing the \fn{plain.tex} variants to
make document conversion easier seems ill-advised since those variants
are so blatantly wrong in a \latex/ context.

\section{Why did \cn{over}, \cn{atop}, \cn{above} [\dots{\ntt withdelims}]
 stop working when I added the \pkg{amsmath} package?}

The six generalized fraction commands \cn{over}, \cn{overwithdelims},
\cn{atop}, \cn{atopwithdelims}, \cn{above}, \cn{abovewithdelims} are
expressly forbidden by the \pkg{amsmath} package; use of the recommended
forms \cn{frac} (and variants) is now required, instead of merely
recommended. (I tend to construe \latex/'s provision of \cs{frac}, and
the lack of any mention in the \latex/ book of the primitive fraction
commands, as an implicit injunction against their use, although I don't
think Lamport actually spent a lot of time pondering the issue, and the
basic \latex/ version of \cn{frac} provides access only to \cn{over},
not to \cn{atop}, \cn{above}, or the \verb'withdelims' variants.)

Not only is the unusual syntax of the \tex/ primitives rather out of
place in \latex/, but furthermore that syntax seems to be responsible
for one of the most significant flaws in \tex/'s mathematical
typesetting capabilities: the fact that the current mathstyle at any
given point in a math formula cannot be determined until the end of the
formula, because of the possibility that a following generalized
fraction command will change the mathstyle of the \emph{preceding}
material. To cite two of the worst side effects: \cn{mathchoice} must
actually typeset all four of its arguments, instead of being able to
immediately select only one; and, were it possible to always know the
current math style at a given point, math font selection would be
greatly simplified and the upper limit of 16 different math font
\cn{fam}s would never be a problem as \cn{text,script[script]font}
assignments for any \cn{fam} could take immediate effect and therefore
could be changed arbitrarily often within a single formula. More
concretely, math font selection difficulties are responsible for many of
the more convoluted passages in the source code of \latex/'s NFSS (that
does font loading on demand) and of the \pkg{amsmath} package, and by
extension it has historically been responsible for significant delays in
making new features available to end users and for making those features
more prone to bugs.

There are additional bad consequences following from the syntax of those
generalized fraction commands that only become evident when you do some
writing of nontrivial macros for math use. For example, as things
currently stand you cannot measure the size of any object in math
without going through \cn{mathchoice} and \emph{leaving and reentering
math mode} via \verb'\hbox{$' (which then introduces complications
regarding \cn{everymath} and \cn{mathsurround}). And it seems that
uncertainty about the current mathstyle is the only barrier to allowing
the use of mu units with \cn{vrule}, to make vertical struts in
constructing compound symbols or notation. And so on and so forth.

\end{document}
