From fed27f633aadbacbd3d1221da7993fed8d4efffe Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sun, 15 Sep 2019 03:00:57 +0000 Subject: CTAN sync 201909150300 --- macros/latex-dev/required/amsmath/technote.tex | 233 +++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 macros/latex-dev/required/amsmath/technote.tex (limited to 'macros/latex-dev/required/amsmath/technote.tex') diff --git a/macros/latex-dev/required/amsmath/technote.tex b/macros/latex-dev/required/amsmath/technote.tex new file mode 100644 index 0000000000..aede450621 --- /dev/null +++ b/macros/latex-dev/required/amsmath/technote.tex @@ -0,0 +1,233 @@ +%%% ==================================================================== +%%% @LaTeX-file{ +%%% filename = "technote.tex", +%%% version = "2.0", +%%% date = "1999/11/15", +%%% time = "15:07:20 EST", +%%% checksum = "58506 233 1647 12005", +%%% author = "American Mathematical Society", +%%% copyright = "Copyright 1995, 1999 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 = "amsmath, 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 the \pkg{amsmath} package} +\author{American Mathematical Society\\Michael Downes} +\date{1999/10/29} + +\markboth + {Technical notes on the \pkg{amsmath} package} + {Technical notes on the \pkg{amsmath} package} +\renewcommand{\sectionmark}[1]{} + +\providecommand{\etc}[1]{etc.} + +\providecommand{\begend}[1]{% + {\ntt \symbol{92}begin\symbol{123}#1\symbol{125}} + \ldots\ {\ntt\symbol{92}end\symbol{123}#1\symbol{125}}% +} + +\MakeShortVerb{\|} + +\begin{document} +\maketitle + +\section{Introduction} + +These notes are miscellaneous remarks on some technical questions +applicable to version 2.0 of \amslatex/. + +\section{Deprecated and disallowed commands} + +Certain commands that were in the \pkg{amstex} package (the predecessor, +in \amslatex/ 1.0 and 1.1, of the \pkg{amsmath} package) were moved into +\pkg{amsxtra} because they seemed to be little-used relics: +\cn{accentedsymbol}, \qq{sup accents} (\cn{sptilde}, \cn{sphat}, etc.). + +Certain other commands\mdash e.g., \cn{over}, \cn{pmatrix}, and +\cn{cases}\mdash are changed by the \pkg{amsmath} package to produce +warning messages or error messages, depending on their history; these +are discussed in more detail in the following sections. + +\section{Why do \cn{matrix}, \cn{pmatrix}, and \cn{cases} stop working +when I add 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\mdash 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. The \env{array} environment +ought to have been used instead. + +\section{Why do \cn{over}, \cn{atop}, \cn{above} [\dots{\ntt withdelims}] + give a warning when I add the \pkg{amsmath} package?} + +Using the six generalized fraction commands \cn{over}, +\cn{overwithdelims}, \cn{atop}, \cn{atopwithdelims}, \cn{above}, +\cn{abovewithdelims} is not really a good idea in \latex/, for reasons +explained below. I 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. The +\pkg{amsmath} package, however, provides a \cn{genfrac} command that +gives user-level access to all six of the generalized fraction +primitives in a way that conforms to the syntactic conventions followed +by all other \latex/ commands. + +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. + +\section{The \opt{fleqn} option and \cn{mathindent}} + +Strictly speaking, the \pkg{amsmath} package doesn't use \cn{mathindent} +to control the left indent of displayed equations when the \opt{fleqn} +option is in effect: it uses an internal parameter \cs{@mathmargin} +instead. However, for compatibility with existing \latex/ documentation, +\pkg{amsmath} turns \cn{mathindent} into an alias for \cs{@mathmargin}. +There is a small risk here: In the plain \latex/ implementation, +\cn{mathindent} is a dimen register, but with \pkg{amsmath} +\cs{@mathmargin} is a skip register and, by association, so is +\cn{mathindent}. If any package or documentclass uses \cn{mathindent} in +a way that depends on it being a dimen register, when used in +conjunction with the \pkg{amsmath} package it may be vulnerable to a +well-known pitfall having to do with the primitive \tex/ lookahead for a +\texttt{plus} or \texttt{minus} key word. However if the standard +\latex/ commands \cn{setlength} and \cn{addtolength} are used to modify +\cn{mathindent} then this problem will not arise. + +\section{Why can't I use abbreviations for \protect\begend{align}?} + +Authors often like to use abbreviations such as |\beq| |\eeq| for +|\begin{equation}| |\end{equation}|. For some environments defined by +the \pkg{amsmath} package, such as \env{align}, \env{gather}, +\env{multline}, and others of the same general type, this does not work: +An attempt to define |\bal| |\eal| as shorthand for |\begin{align}| +|\end{align}| will fail with a puzzling error message. This has to do +with unfortunately nontrivial technical complications: the given +environments 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\mdash substitution of different algorithms that do box shuffling +instead of token shuffling for the multipass calculations\mdash 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. Work is under way on an auxiliary package called +\pkg{breqn} that addresses not only this problem but a number of others; +at the time of this writing, however [September 1999] it has only +progressed as far as a beta release. + +Some workarounds: +\begin{itemize} +\item |\def\bal#1\eal{\begin{align}#1\end{align}}| +\item Define |\newcommand{\env}[2]{\begin{#1}#2\end{#1}}| and then use + |\env{align}{...}| +\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 end users don't care much about. + +\section{The \pkg{amsintx} package} + +After a very preliminary trial release the \pkg{amsintx} package was +withdrawn to await further development. It is still considered a worthy +project but has simply not yet made it to the head of the priority queue +in the AMS \latex/ development program, as it has had to contend with a +number of other equally worthy projects for development time. + +\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. + +\end{document} -- cgit v1.2.3