%%% ====================================================================
%%%  @LaTeX-file{
%%%     filename        = "amstext.dtx",
%%%     version         = "1.2beta",
%%%     date            = "1994/12/13",
%%%     time            = "11:39:46 EST",
%%%     author          = "American Mathematical Society",
%%%     copyright       = "Copyright (C) 1994 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",
%%%     checksum        = "38673 282 1382 11263",
%%%     email           = "tech-support@math.ams.org (Internet)",
%%%     codetable       = "ISO/ASCII",
%%%     keywords        = "latex, amslatex, ams-latex",
%%%     supported       = "yes",
%%%     abstract        = "This is part of the AMS-\LaTeX{} distribution.
%%%                        It is a \LaTeX{} package that defines a
%%%                        \cn{\text} macro, which makes it easy to
%%%                        incorporate fragments of text inside a displayed
%%%                        equation or a sub or superscript. Font sizes
%%%                        are automatically scaled in sub/superscripts.",
%%%     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.",
%%%  }
%%% ====================================================================
% \iffalse
%<*driver>
\documentclass{amsdtx}
\usepackage{amstext}
\begin{document}
\title{The \pkg{amstext} package}
\author{Frank Mittelbach \and Rainer Sch\"opf}
\date{Version \fileversion, \filedate}
\hDocInput{amstext.dtx}
\end{document}
%</driver>
% \fi
%
% \maketitle
%
% \MakeShortVerb\|
%
% \section{Introduction}
%
%    This style file implements the \AmSTeX{} macro \verb+\text+ for use
%    with the new font selection scheme.  The \verb+\text+ macro is a
%    sophisticated command which allows the user to insert ``normal text''
%    into math formulas without worrying about correct sizes in sub- or
%    superscripts. It can also be used in ordinary text; there it
%    produces an unbreakable unit similar to \verb+\mbox+.
%
%    Here is an example demonstrating some of its features:
% \[
%^^A mathbin spacing is nonscript glue, disappears in superscript
%    x^{2\,\times\,\text{size of $y$}}
%    \leq
%    z_{i_{\text{upper bound of the array}}}
% \]
%    This was produced by
% \begin{verbatim}
% \[
%    x^{2\,\times\,\text{size of $y$}}
%    \leq
%    z_{i_{\text{upper bound of the array}}}
% \]
% \end{verbatim}
%
%    Additionally this style file redefines an internal \PlainTeX{}
%    macro called \verb+\mathhexbox+ so that commands like \verb+\dag+
%    or \verb+\P+ now correctly change sizes if used in math mode.
%
% \StopEventually{}
%    Package information.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{amstext}[1994/10/27 v1.2beta]
%    \end{macrocode}
%
% \section{The implementation}
%    We need a few tools from \fn{amsgen.sty}.
%    \begin{macrocode}
\RequirePackage{amsgen}[1994/09/01]
%    \end{macrocode}
%
% \begin{macro}{\text}
%    Now we come to the \verb+\text+ macro which is used to place
%    ordinary text inside of math formulas. We also allow it outside
%    math; in this case it is supposed to produce unbreakable text,
%    i.e.\ a \verb+\mbox+ in terms of \LaTeX{}.
%    \begin{macrocode}
\DeclareRobustCommand{\text}{%
  \ifmmode\expandafter\text@\else\expandafter\mbox\fi}
%    \end{macrocode}
%    At the present time (late 1994) the \LaTeX{} internal function
%    |\nfss@text| is used in |\ref|, in font commands like |\textbf|,
%    and in a few text symbol definitions like |\$| and |\pounds|. By
%    equating |\nfss@text| to |\text| we give it the ability of
%    |\text| to change sizes properly if used in a subscript.
%    \begin{macrocode}
\let\nfss@text\text
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\text@}
%    If \verb+\text+ is encountered inside math mode the macro
%    \verb+\text@+ is called.  It has one mandatory argument, the text
%    which should be produced.  Since we do not know in which math
%    style we are currently in we call \verb+\mathchoice+ to tyeset
%    our text in all four possible styles.
%    \begin{macrocode}
\def\text@#1{\mathchoice
%    \end{macrocode}
%    To save token space we call a macro \verb+\textdef@+ which takes
%    three arguments: the current math style, the corresponding size
%    macro and the text to typeset possibly with some additional
%    information for typesetting.
%    \begin{macrocode}
  {\textdef@\displaystyle\f@size{#1}}%
%    \end{macrocode}
%    The other three cases are similar except for the
%    \verb+\iffirstchoice+ switch which we set to false. This is
%    done to prevent \LaTeX{} macros like \verb+\ref+ or \verb+\index+
%    from writing their arguments more than once.
%    \begin{macrocode}
  {\textdef@\textstyle\tf@size{\firstchoice@false #1}}%
  {\textdef@\textstyle\sf@size{\firstchoice@false #1}}%
  {\textdef@\textstyle \ssf@size{\firstchoice@false #1}}%
%    \end{macrocode}
%    Here we need to check whether a math size-change occurred inside
%    the argument of \cn{text}. If so, restore
%    \begin{macrocode}
  \check@mathfonts
}
%    \end{macrocode}
%    The macros \verb+\tf@size+, \verb+\sf@size+ and \verb+\ssf@size+
%    hold the sizes which should be used when we are loading a new
%    font for use in \verb+\textfont+, \verb+\scriptfont+ and
%    \verb+\scriptscriptfont+.
% \end{macro}
%
% \begin{macro}{\textdef@}
%    To typeset the argument of \verb+\text+ correctly we have to make
%    several actions. We start by placing everything inside an
%    \verb+\hbox+.  But this is not enough: we need one extra level of
%    grouping.  These extra braces are necessary because of the new
%    font selection scheme which might produce an \verb+\aftergroup+
%    to globally restore some font values after the current group. To
%    prevent any damage by this mechanism we add the braces thereby
%    bringing the token inserted by \verb+\aftergroup+ inside the
%    \verb+\hbox+.\footnote{The mechanism will not produce a second
%    \cs{aftergroup}. For more details see the technical documentation
%    for NFSS2.}
%    \begin{macrocode}
\def\textdef@#1#2#3{\hbox{{%
%    \end{macrocode}
%    Since text typeset inside an \verb+\hbox+ always stays in the size
%    of the text surrounding the formula we have to adjust this for
%    script and scriptscript sizes.  For any math formula inside this
%    argument this will be achieved by setting \verb+\everymath+ to
%    the first argument of \verb+\textdef@+ since this argument
%    contains the math size in the current typeset case of
%    \verb+\mathchoice+.
%    Since \latex/ also knows about \verb+\parbox+$\,$es and the
%    \env{minipage} environment it might be neccessary to adjust
%    \verb+\everydisplay+ too but this has to be tested further.
%    \begin{macrocode}
                    \everymath{#1}%
%    \end{macrocode}
%    The next line of code changes locally (i.e.\ inside the current
%    \verb+\hbox+) the value of \verb+\f@size+. This macro holds the
%    size for typesetting ordinary text (e.g.\ loading or selecting a
%    new font via \verb+\selectfont+). By changing it to a smaller
%    value a following \verb+\selectfont+ will switch to the wanted
%    size.
%    \begin{macrocode}
                    \let\f@size#2\selectfont
%    \end{macrocode}
%    Now we simply call the third argument and close all open groups.
%    \begin{macrocode}
                    #3}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\iffirstchoice@}
%    Here is the switch that we use to decide if \verb+\ref+ etc.\
%    should print its warnings.  The default is true since
%    normally these warnings shouldn't be suppressed.
%    \begin{macrocode}
\newif\iffirstchoice@
\firstchoice@true
%    \end{macrocode}
% \end{macro}
%
% \subsection{Re-definition of \latex/ macros to work with \cn{text}}
%
% \begin{macro}{\stepcounter}
%    \begin{macrocode}
\def\stepcounter#1{%
  \iffirstchoice@
     \global\expandafter\advance\csname c@#1\endcsname \@ne
     \begingroup
         \let\@elt\@stpelt
         \csname cl@#1\endcsname
     \endgroup
  \fi}
%    \end{macrocode}
% \end{macro}
%
%    For \cn{ref}, \cn{pageref}, and indeed anything else that issues a
%    warning or error, \cn{text} will produce four copies of the
%    warning/error message. To suppress the last three copies, we change
%    \cs{GenericInfo}, \cs{GenericWarning}, \cs{GenericError}.
%
%    \begin{macrocode}
\toks@{\iffirstchoice@\else\@xp\@gobblefour\fi\protect}
\edef\GenericInfo{\the\toks@
  \@xp\@nx\csname GenericInfo \endcsname}
%
\edef\GenericWarning{\the\toks@
  \@xp\@nx\csname GenericWarning \endcsname}
%
\toks@{\iffirstchoice@\else
  \@xp\@xp\@xp\@gobblefour
  \@xp\@gobbletwo\fi\protect}
\edef\GenericError{\the\toks@
  \@xp\@nx\csname GenericError \endcsname}
%    \end{macrocode}
%
% \begin{macro}{\label}
%    Finally we must take care of defining labels only once.
%    \begin{macrocode}
\def\label#1{\@bsphack\iffirstchoice@\if@filesw {\let\thepage\relax
   \def\protect{\noexpand\noexpand\noexpand}%
\xdef\@gtempa{\write\@auxout{\string
      \newlabel{#1}{{\@currentlabel}{\thepage}}}}}\@gtempa
   \if@nobreak \ifvmode\nobreak\fi\fi\fi\fi\@esphack}
%    \end{macrocode}
% \end{macro}
%
%\subsection{Applications of \cn{text}}
%
% \begin{macro}{\mathhexbox}
%    We start with an re-definition of the \PlainTeX{} macro
%    \verb+\mathhexbox+.  I don't see any reason in using a new name
%    (M. Spivak in \AmSTeX{} uses \verb+\mathhexbox@+) since the new
%    definition is superior, has the same syntax and is used for the
%    same purpose.
%    \begin{macrocode}
\begingroup \catcode`\"=12
\gdef\mathhexbox#1#2#3{\text{$\m@th\mathchar"#1#2#3$}}
\endgroup
%    \end{macrocode}
%    This re-definition means that now symbols like \S,\P,\dag\ldots
%    which are defined via \verb+\mathhexbox+ in \PlainTeX{} or
%    elsewhere now correctly change sizes if they are used in math mode.
% \end{macro}
%
%    The usual \cs{endinput} to ensure that random garbage at the end of
%    the file doesn't get copied by \fn{docstrip}.
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
% \CheckSum{143}
% \Finale