The amsldoc and amsdtx document classes

American Mathematical Society Michael Downes

Version 1.2b, 1995/02/23

1 Introduction

This file is the source for two documentclasses, amsldoc (used for the AMS-L^{A}TEX user’s guide) and amsdtx (used for printing AMS .dtx files). The generic book class is used as a base, but the amsdtx class is modified to serve as an article-type class. This affects the form of documentation files mainly in the use

of \maketitle and \chapter.

Standard starting pieces. (Note: the reason each \ProvidesClass command

Table 0.1. Features of the amsldoc and amsdtx classes

Command Name Purpose

\cn To print a user command name: \cn{title}; leading backslash can be optionally included for control symbols: \cn{\%}. The \cn command works properly even in macro arguments (compare to, e.g., \verb'\newif'). But beware of a fragile control symbol (are there any?) in a moving argument.

\cs ‘Control sequence’: to print an internal command

name, not intended for the end user

\env  To print an environment name: \env{table}
\pkg  To print a package name: \pkg{eufrak}
\cls  To print a class name: \cls{book}

\opt To print the name of a class or package option:

\opt{twocolumn}

\fn To print a file name or font name:

\fn{T1enc.def}, \fn{cmsy10}

\qc To quote a single character: \qc{\%}; this works properly for special characters, even in macro arguments, unlike e.g., \verb'%'

\latex/ etc. Convenient forms of \LaTeX, \TeX, \BibTeX, etc. that are easier to type and have a trailing slash to eliminate the following-space problem (without needing different markup in different contexts) is placed on a line by itself, with separate begin and end guards for docstripping, is to make automatic update of file date and version slightly easier and more robust.)

  \NeedsTeXFormat{LaTeX2e}

⟨∗amsldoc⟩

  \ProvidesClass{amsldoc}[1995/02/23 v1.2b]

⟨/amsldoc⟩

⟨∗amsdtx⟩

  \ProvidesClass{amsdtx}[1995/02/23 v1.2b]

⟨/amsdtx⟩

2 Implementation

Start with the generic book class as a base.

  \DeclareOption*{\PassOptionsToClass{\CurrentOption}{book}}
  \ProcessOptions
  \LoadClass{book}

Some functions to support \cn etc. For most of these commands we don’t really want them to be \long! (But rumor has it that the next release of L^{A}TEX will have an optional form for \newcommand to make non-long commands. [mjd,1994/10/19])

We use the name \bslchar instead of \bslash to avoid potential conflict with the doc package \bslash command. Unlike \bslash, \bslchar survives unlimited writing/expansion because it is a chardef.

  \chardef\bslchar=`\\ % p. 424, TeXbook
  \newcommand{\addbslash}{\expandafter\@addbslash\string}
  \def\@addbslash#1{\bslchar\@nobslash#1}
  \newcommand{\nobslash}{\expandafter\@nobslash\string}
  \def\@nobslash#1{\ifnum`#1=\bslchar\else#1\fi}

We define some macros to do automatic indexing of control sequences, environments, options, and file names.

  \newcommand{\autoindex}{\index}

To avoid font substitution warnings we make the tt font always print in the normal weight and shape.

  \newcommand{\ntt}{\normalfont\ttfamily}

\@boxorbreak Start up for a \cs or \cn command, adds an \hbox if in math, or an allowbreak penalty if the preceding item is not a space. (In case two such commands are used side-by-side.)

  \def\@boxorbreak{\leavevmode
    \ifmmode\hbox\else\ifdim\lastskip=\z@\penalty9999 \fi\fi}

Control sequence. The function \addbslash makes this command also usable for some special control sequences like \% \} \{: instead of writing \cs{%} which doesn’t work, you can write \cs{\%}.

  \DeclareRobustCommand{\cs}[1]{\@boxorbreak{\ntt\addbslash#1\@empty
    \autoindex{\nobslash#1@\string\cs{\string#1\@empty}}}}

Allow distinguishing non-private ‘command names’ that will be visible to the user from internal (mostly private) ‘control sequences’.

  \DeclareRobustCommand{\cn}[1]{\@boxorbreak{\ntt\addbslash#1\@empty

The \nobslash function here removes the leading backslash (for sorting purposes only) so that command names after sorting will be interspersed with regular words. The final \@empty is just to avoid bad errors if an empty argument is accidentally given; the printed results will be nonsense.

    \autoindex{\nobslash#1@\string\cn{\string#1\@empty}}}}

The following items should not normally appear in math mode so they don’t

need to call \@boxorbreak.

L^{A}TEX documentclass name.

  \DeclareRobustCommand{\cls}[1]{{\ntt#1}%
    \autoindex{#1@\string\cls{#1} class}}

L^{A}TEX package name.

  \DeclareRobustCommand{\pkg}[1]{{\ntt#1}%
    \autoindex{#1@\string\pkg{#1} package}}

L^{A}TEX option name.

  \DeclareRobustCommand{\opt}[1]{{\ntt#1}%
    \autoindex{#1@\string\opt{#1} option}}

Environment name.

  \DeclareRobustCommand{\env}[1]{{\ntt#1}%
    \autoindex{#1@\string\env{#1} environment}}

File name.

  \DeclareRobustCommand{\fn}[1]{{\ntt#1}%
     \autoindex{#1@\string\fn{#1}}}

BibTEX style.

  \DeclareRobustCommand{\bst}[1]{{\ntt#1}\autoindex{#1@{\string\ntt{}#1
    bibliography style}}}

To index a control sequence without printing it. Note non-long.

  \newcommand{\indexcs}[1]{\autoindex{#1@\string\cs{#1}}}

With long command names or file names we sometimes prefer to allow hyphenation in the tt font (in combination with suitable \hyphenation statements for individual documents). To make this work we must turn off the feature of L^{A}TEX that disables the hyphenchar of the tt fonts.

The method shown here depends on the assumption that OT1 encoding will be used for the tt fonts. An encoding-independent method would be more awkward: You’d have to explicitly load the relevant fonts, let’s say by using \AtBeginDocument, and undo the hyphenchar change individually for each font.

  \def\allowtthyphens{\input{OT1cmtt.fd}%
    \expandafter\let\csname OT1+cmtt\endcsname\@empty}

We allow some slop at the right margin because we have some long control sequence names and verbatim text to deal with. Also ignore underfull hboxes and vboxes unless they are really bad.

\hfuzz2pc
\vbadness9999 \hbadness5000
\def\AmS{{\protect\usefont{OMS}{cmsy}{m}{n}%
  A\kern-.1667em\lower.5ex\hbox{M}\kern-.125emS}}
\def\latex/{{\protect\LaTeX}}
\def\amslatex/{{\protect\AmS-\protect\LaTeX}}
\def\tex/{{\protect\TeX}}
\def\amstex/{{\protect\AmS-\protect\TeX}}
\def\bibtex/{{Bib\protect\TeX}}

\makeindex command is already used for other purposes.

\def\makeindx/{MakeIndex}

Don’t allow a break after the hyphen:

\def\xypic/{XY\mbox{-}pic}
\newcommand{\Textures}{\textit{Textures}}

‘Meta’ macro.

\def\<#1>{\textit{$\langle$#1\/$\rangle$}}
 Turn off \autoindex during \tableofcontents or similar.
\def\@starttoc#1{\begingroup
  \let\autoindex\@gobble
  \makeatletter
  \@input{\jobname.#1}\if@filesw
  \expandafter\newwrite\csname tf@#1\endcsname
             \immediate\openout
                 \csname tf@#1\endcsname \jobname.#1\relax
  \fi \global\@nobreakfalse \endgroup}

Make glossary commands a no-op for the moment. [mjd,1994/10/03] Provide a \secref command for section references.

⟨∗amsldoc⟩

\newcommand{\gloss}[1]{}
\newcommand{\secref}[1]{\S\ref{#1}}

⟨/amsldoc⟩

We can write \qc{\%} to quote a single character in situations where \verb"%" would not work, mainly when text is read as a macro argument (e.g., footnotes).

\newcommand{\qc}[1]{}% check for prior definition
\edef\qc#1{\noexpand\protect\expandafter\noexpand\csname qc \endcsname
  \noexpand\protect#1}

For this function the first argument is \protect and just needs to be discarded. The method for removing a leading backslash is to turn off \escapechar; this is 2. IMPLEMENTATION 5

more forgiving of variations like \qc{$}. If the argument is \ we print a cmtt visible-space character.

\@namedef{qc }#1#2{\begingroup\ntt
  \ifx\ #2\char`\ \else\escapechar\m@ne\string#2\fi\endgroup}

Declare a few character names to avoid e.g., indexing difficulties.

\DeclareRobustCommand{\qcat}{\qc\@}%
\DeclareRobustCommand{\qcamp}{\qc\&}%
\DeclareRobustCommand{\qcbang}{\qc\!}%

\arg Change \arg to print a macro argument number:

\DeclareRobustCommand{\arg}[1]{{\ntt\##1}}

We need to emulate the amsthm\qedsymbol for the AMS-L^{A}TEX user’s guide.

⟨∗amsldoc⟩

\newcommand{\openbox}{\leavevmode
  \hbox to.77778em{%
  \hfil\vrule
  \vbox to.675em{\hrule width.6em\vfil\hrule}%
  \vrule\hfil}}
\newcommand{\qedsymbol}{\openbox}

⟨/amsldoc⟩

Logical markup for e-mail address:

⟨amsldoc⟩\def\mail{\texttt}

Shorthand for indexing:

⟨∗amsldoc⟩

\def\*#1{\def\@tempa{#1}\def\@tempb{*}%
  \ifx\@tempa\@tempb \expandafter\index
  \else #1\index{#1}\fi}

⟨/amsldoc⟩

Non-indexed \cn (maybe call this \cn*?)

\def\ncn#1{{\let\index\@gobble\cn{#1}}}

Indexing difficulties with !, @.

\DeclareRobustCommand{\cnbang}{%
  \ncn{\!}\index{"!@{\ntt\bslchar\qcbang}}}
\DeclareRobustCommand{\cnat}{%
  \ncn{\!}\index{"@@{\ntt\bslchar\qcat}}}

Shorthand for a discouraged, but not forbidden, line break:

\def\5{\penalty500 }

Environment for error message examples. Use \meaning to allow reading the error message text as an ordinary brace-delimited arg but still be able to print embedded braces; and first change the backslash catcode to prevent extra spaces after control words.

⟨∗amsldoc⟩

\newenvironment{error}{%
  \begingroup\catcode`\\=12 \expandafter\endgroup\errora
}{%
  \endtrivlist
}
\newcommand{\errora}[1]{%
  \trivlist
  \item[\hskip\labelsep\errorbullet\enspace
    \ntt\frenchspacing\def\@tempa{#1}%
    \expandafter\strip@prefix\meaning\@tempa]\leavevmode\par
}

\errorbullet is just an attempt at a simple graphic device that doesn’t require any special fonts.

\newcommand{\errorbullet}{\rule[-.5pt]{2.5pt}{7.5pt}%
  \rule[-.5pt]{5pt}{2.5pt}\kern-2.5pt%
  \rule[4.5pt]{2.5pt}{2.5pt}}

⟨/amsldoc⟩

A couple of subheading commands:

\newcommand{\errexa}{\par\noindent\textit{Example}:\ }
\newcommand{\errexpl}{\par\noindent\textit{Explanation}:\ }

3 amsldoc style modifications for sectioning commands

The following section deals with book commands (part, chapter, frontmatter, …).

⟨∗amsldoc⟩

Modifications of sectioning commands from book.cls, mostly reducing font sizes and vertical spacing.

\renewcommand\frontmatter{\clearpage
            \@mainmatterfalse\pagenumbering{roman}}
\renewcommand\mainmatter{\clearpage
       \@mainmattertrue\pagenumbering{arabic}}
\renewcommand\backmatter{\clearpage \@mainmatterfalse}
\renewcommand\part{\clearpage
                 \thispagestyle{plain}%
                 \if@twocolumn
                     \onecolumn
                     \@tempswatrue
                   \else
                     \@tempswafalse
                 \fi
                 \hbox{}\vfil
                 \secdef\@part\@spart}
\def\@part[#1]#2{%
    \ifnum \c@secnumdepth >-2\relax
      \refstepcounter{part}%
      \addcontentsline{toc}{part}{\thepart\hspace{1em}#1}%

3. AMSLDOC STYLE MODIFICATIONS FOR SECTIONING COMMANDS 7

\else
 \addcontentsline{toc}{part}{#1}%
\fi
\markboth{}{}%
{\centering
\interlinepenalty \@M
\reset@font
\ifnum \c@secnumdepth >-2\relax
  \Large\bfseries \partname~\thepart
  \par
  \vskip 20\p@
\fi
\Large \bfseries #2\par}%
\@endpart}
\def\@spart#1{%
{\centering
\interlinepenalty \@M
\reset@font
\Large \bfseries #1\par}%
\@endpart}
\def\@endpart{\vfil\newpage
         \if@twoside
           \hbox{}%
           \thispagestyle{empty}%
           \newpage
         \fi
         \if@tempswa
           \twocolumn
         \fi}

⟨/amsldoc⟩

\renewcommand\chapter{\par \@afterindentfalse
               \secdef\@chapter\@schapter}
\def\@chapter[#1]#2{\ifnum \c@secnumdepth >\m@ne
                  \if@mainmatter
                    \refstepcounter{chapter}%
                    \typeout{\@chapapp\space\thechapter.}%
                    \addcontentsline{toc}{chapter}%
                              {\protect\numberline{\thechapter}#1}%
                  \else
                    \addcontentsline{toc}{chapter}{#1}\fi
               \else
                 \addcontentsline{toc}{chapter}{#1}
               \fi
               \chaptermark{#1}%
               \addtocontents{lof}{\protect\addvspace{10\p@}}%
               \addtocontents{lot}{\protect\addvspace{10\p@}}%
               \if@twocolumn
                 \@topnewpage[\@makechapterhead{#2}]%
               \else

                    \@makechapterhead{#2}%
                    \@afterheading
                  \fi}
\def\@makechapterhead#1{%
\vspace{1.5\baselineskip}%
{\parindent \z@ \raggedright \reset@font
  \ifnum \c@secnumdepth >\m@ne
    \large\bfseries \@chapapp\space\thechapter
    \par\nobreak
    \vskip.5\baselineskip\relax
  \fi
  #1\par\nobreak
  \vskip\baselineskip
}}
\def\@schapter#1{\if@twocolumn
                 \@topnewpage[\@makeschapterhead{#1}]%
               \else
                 \@makeschapterhead{#1}%
                 \@afterheading
               \fi}
\def\@makeschapterhead#1{%
\vspace*{1.5\baselineskip}%
{\parindent \z@ \raggedright
  \reset@font
  \large \bfseries  #1\par\nobreak
  \vskip\baselineskip
}}

Change running head font to \footnotesize, nonslanted.

⟨∗amsldoc⟩

\def\ps@headings{%
\let\@oddfoot\@empty\let\@evenfoot\@empty
\def\@evenhead{\thepage\hfil{\footnotesize\leftmark{}{}}}%
\def\@oddhead{{\footnotesize\rightmark{}{}}\hfil\thepage}%
\let\@mkboth\markboth
\def\chaptermark##1{%
  \markboth {\uppercase{\ifnum \c@secnumdepth >\m@ne
    \if@mainmatter
      \@chapapp\ \thechapter. \ \fi
    \fi
      ##1}}{}}%
\def\sectionmark##1{%
  \markright {\uppercase{\ifnum \c@secnumdepth >\z@
      \thesection. \ \fi
      ##1}}}}

⟨/amsldoc⟩

4 amsdtx style modifications for sectioning commands

These definitions for \maketitle are from article.cls.

4. AMSDTX STYLE MODIFICATIONS FOR SECTIONING COMMANDS 9

⟨∗amsdtx⟩

\renewcommand\maketitle{\par
\begingroup
  \renewcommand\thefootnote{\fnsymbol{footnote}}%
  \def\@makefnmark{\hbox to\z@{$\m@th^{\@thefnmark}$\hss}}%
  \long\def\@makefntext##1{\parindent 1em\noindent
          \hbox to1.8em{\hss$\m@th^{\@thefnmark}$}##1}%
  \if@twocolumn
    \ifnum \col@number=\@ne
      \@maketitle
    \else
      \twocolumn[\@maketitle]%
    \fi
  \else
    \newpage
    \global\@topnum\z@   % Prevents figures from going at top of page.
    \@maketitle
  \fi
  \thispagestyle{plain}\@thanks
\endgroup
\setcounter{footnote}{0}%
\let\thanks\relax
\let\maketitle\relax\let\@maketitle\relax
\gdef\@thanks{}\gdef\@author{}\gdef\@title{}}
%
\def\@maketitle{%
\newpage
\null
\vskip 2em%
\begin{center}%
  {\LARGE \@title \par}%
  \vskip 1.5em%
  {\large
    \lineskip .5em%
    \begin{tabular}[t]{c}%
      \@author
    \end{tabular}\par}%
  \vskip 1em%
  {\large \@date}%
\end{center}%
\par

Put the title into both running heads.

\uppercase\expandafter{\expandafter\toks@\expandafter{\@title}}%
\edef\@tempa{\noexpand\markboth{\the\toks@}{\the\toks@}}%
\@tempa
\vskip 1.5em}

⟨/amsdtx⟩

Edit the sectioning commands.

\renewcommand\section{\@startsection {section}{1}{\z@}%

                                 {-.6\baselineskip \@plus -3\p@}%
                                 {.4\baselineskip}
                                 {\reset@font\normalsize\bfseries}}
\renewcommand\subsection{\@startsection{subsection}{2}{\z@}%
                                   {-.3\baselineskip\@plus -2\p@}%
                                   {.2\baselineskip}%
                                   {\reset@font\normalsize\bfseries}}
\renewcommand\subsubsection{\@startsection{subsubsection}{3}{\z@}%
                                   {-.2\baselineskip\@plus -2\p@}%
                                   {.2\baselineskip}%
                                   {\reset@font\normalsize\bfseries}}

Change index environment to turn off \autoindex.

\renewenvironment{theindex}{%
\if@twocolumn \@restonecolfalse \else \@restonecoltrue \fi
\columnseprule \z@ \columnsep 35\p@
\let\autoindex\@gobble
⟨amsdtx⟩ \twocolumn[\section*{\indexname}]%
⟨amsldoc⟩ \twocolumn[\@makeschapterhead{\indexname}]%
\@mkboth{\uppercase{\indexname}}{\uppercase{\indexname}}%
\thispagestyle{plain}\parindent\z@
\parskip\z@ \@plus .3\p@\relax
\let\item\@idxitem
}{%
\if@restonecol\onecolumn\else\clearpage\fi
}
Take out \thechapter from \thesection.
⟨amsdtx⟩\renewcommand{\thesection}{\arabic{section}}

Change the style of captions slightly. Also incorporate some caption improvements from Donald Arseneau (comp.text.tex, 11 Oct 1994).

\long\def\@makecaption#1#2{%
\addvspace\abovecaptionskip
\begingroup
  \countdef\@parcycles=8 % local count register
  \@parcycles\z@
  \@setpar{\advance\@parcycles\@ne \ifnum\@parcycles>999
    \@@par\@parcycles\z@\fi
    \ifhmode \unskip\hskip\parfillskip\penalty-\@M\fi}%
  \@hangfrom{\textbf{#1.} }\vadjust{\penalty\m@ne}#2%
\endgroup
\ifhmode\unpenalty\fi\par
\ifnum\lastpenalty=\m@ne % only one line in the caption
  \unpenalty \setbox\@tempboxa\lastbox
  \nointerlineskip
  \hbox to\hsize{\hfill\unhbox\@tempboxa\unskip\hfill}%
\fi
\nobreak\vskip\belowcaptionskip
}

5. FLOAT PLACEMENT PARAMETERS 11

For table captions, assume top captions and so put space below the caption rather than above:

\renewenvironment{table}{%
  \belowcaptionskip\abovecaptionskip \abovecaptionskip\z@skip
  \@float{table}%
}{%
  \end@float
}
\renewenvironment{table*}{%
  \belowcaptionskip\abovecaptionskip \abovecaptionskip\z@skip
  \@dblfloat{table}%
}{%
  \end@dblfloat
}

5 Float placement parameters

These control the placing of floating objects like tables and figures. The values here, which are much more tolerant than the L^{A}TEX defaults, are more or less

copied from amsclass.dtx.
\setcounter{topnumber}{4}\setcounter{bottomnumber}{4}
\setcounter{totalnumber}{4}\setcounter{dbltopnumber}{4}
\renewcommand{\topfraction}{.97}\renewcommand{\bottomfraction}{.97}
\renewcommand{\textfraction}{.03}\renewcommand{\floatpagefraction}{.9}
\renewcommand{\dbltopfraction}{.97}
\renewcommand{\dblfloatpagefraction}{.9}
\setlength{\floatsep}{8pt plus6pt}
\setlength{\textfloatsep}{10pt plus8pt}
\setlength{\intextsep}{8pt plus6pt}
\setlength{\dblfloatsep}{8pt plus6pt}
\setlength{\dbltextfloatsep}{10pt plus8pt}
\setlength{\@fptop}{0pt}\setlength{\@fpsep}{8pt}%
\setlength{\@fpbot}{0pt plus 1fil}
\setlength{\@dblfptop}{0pt}\setlength{\@dblfpsep}{8pt}%
\setlength{\@dblfpbot}{0pt plus 1fil}
\pagestyle{headings}

Make |...| shorthand for verbatim fragments. In the case of the amsldoc class, we avoid requiring an extra package (doc or shortvrb), to reduce the possibility of package files not being found at run time.

⟨∗amsldoc⟩

\AtBeginDocument{\catcode`\|=\active }
\def\activevert{\verb|}
\expandafter\gdef\expandafter\dospecials\expandafter
  {\dospecials \do\|}%
\expandafter\gdef\expandafter\@sanitize\expandafter
  {\@sanitize \@makeother\|}
\begingroup\catcode`\|=\active \gdef|{\protect\activevert{}}\endgroup

⟨/amsldoc⟩

\arrayargpatch If the column-specs arg of array or tabular contains a vert bar character, and we have made vert bars active, it will cause trouble. The following command, used in the ctab environment, prevents the trouble.

\newcommand{\arrayargpatch}{%
\let\@oldarray\@array
\edef\@array[##1]##2{\catcode\number`\|=\number\catcode`\|
  \catcode\number`\@=\number\catcode`\@ \relax
  \let\noexpand\@array\noexpand\@oldarray
  \noexpand\@array[##1]{##2}}%
\catcode`\|=12 \catcode`\@=12 \relax
}

ctab An environment for centered tables.

\newenvironment{ctab}{%
\par\topsep\medskipamount
\trivlist\centering
\item[]%
\arrayargpatch
\begin{tabular}%
}{%
\end{tabular}%
\endtrivlist
}

Load doc package, reset \AltMacroFont to be the same as \MacroFont (when there are large sections of conditional code I think it looks better not to have it all slanted).

⟨∗amsdtx⟩

\RequirePackage{doc}
\def\AltMacroFont{\MacroFont}

Ordinary \DocInput doesn’t handle standardized file headers unless you enclose them in \iffalse … \fi which I don’t care to do. So instead here’s an alternate version of \DocInput, called \hDocInput.

\def\hDocInput#1{\MakePercentIgnore
\begingroup

Define active @ which should be the first non-percent, non-equal-sign character when a file header is present. (If a file header is not present, \hDocInput should not be used.)

\begingroup \lccode`\~=`\@
\lowercase{\endgroup\long\def ~}##1##{%
  \catcode`\==12 \skipfileheader{##1}}%
\catcode`\@=\active \catcode`\==14 % comment
\def\filename{#1}%
\@@input#1 \MakePercentComment}
\def\skipfileheader#1#2 {\endgroup
\hGetFileInfo#2 version = "??" date = "??"\@nil
\begingroup\catcode`\==9 \catcode`\ =9 \futurelet\0\endgroup
}

  \long\def\hGetFileInfo#1 version = "#2"#3 date = "#4"#5\@nil{%
    \def\fileversion{#2}\def\filedate{#4}}

⟨/amsdtx⟩

The usual \endinput to ensure that random garbage at the end of the file doesn’t get copied by docstrip.

  \endinput