% \iffalse meta-comment
%
% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file. 
% 
% This file is part of the LaTeX base system.
% -------------------------------------------
% 
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX 
% version 2005/12/01 or later.
% 
% This file has the LPPL maintenance status "maintained".
% 
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
% 
% The list of derived (unpacked) files belonging to the distribution 
% and covered by LPPL is defined by the unpacking scripts (with 
% extension .ins) which are part of the distribution.
% 
% \fi
% ^^A -*-LaTeX-*-
%
% ^^A These shouldn't come out in .ist files, hence the module
% ^^A comments, or in the printed version, hence temporary comment
% ^^A category for `<'
%\catcode`\<=14
%<+package|shortvrb>\NeedsTeXFormat{LaTeX2e}[1994/12/01]
%<+package> \ProvidesPackage{doc}
%<+shortvrb>\ProvidesPackage{shortvrb}
%<+package|shortvrb>  [2006/02/02 v2.1d
%<+package|shortvrb>   Standard LaTeX documentation package (FMi)]
%\catcode`\<=12
%
% \CheckSum{2171}
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%\iffalse    This is a METACOMMENT
%           Everything up to the next `\ fi' (without a blank) will
%           be ignored.  This is necessary because `%' may no longer
%           be a comment mark when this file is read in.
%           
%
%% Package `doc' to use with LaTeX 2e
%% Copyright (C) 1989-1999 Frank Mittelbach, all rights reserved.
%
%
% Version:     Date:     Changes:
%
%  1.0a        5.5.88    This is nothing but a collection of tests and
%                        hacks. It is certainly going to be greatly
%                        changed.
%                        Better not to use it!
%  1.5a and earlier...   are not longer recorded
%  1.5b and higher...    are documented with the (undocumented) \changes
%                        feature.
%\fi
%  \changes{v1.5f}{1989/4/29}{Thanks to Brian who documented the
%                          \cs{changes} macro feature.}
%  \changes{v1.5g}{1989/5/07}{MacroTopsep now called MacrocodeTopsep and
%                          new MacroTopsep added}
%  \changes{v1.5h}{1989/05/17}{All lines shortened to <72 characters}
%  \changes{v1.5j}{1989/06/09}{Corrections by Ron Whitney added}
%  \changes{v1.5q}{1989/11/03}{`\ldots{}Listing macros renamed to
%                         `\ldots{}Input. Suggested by R. Wonneberger}
%  \changes{v1.5w}{1990/02/05}{Counter codelineno renamed to CodelineNo}
%  \changes{v1.9a}{1993/12/02}{Upgrade for LaTeX2e}
%  \changes{v1.9d}{1993/12/20}{Protected changes entry.}
%  \changes{v1.0p}{1994/05/21}{Use new error commands}
%
%
% \hyphenation{make-index}
% 
% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
% \DoNotIndex{\@flushglue,\@gobble,\@input}
% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
% \DoNotIndex{\mathcal,\csname,\def,\documentstyle,\dospecials,\edef}
% \DoNotIndex{\egroup}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
% \DoNotIndex{\ifcase}
% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
% \DoNotIndex{\strutbox}
% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
% \DoNotIndex{\nopagebreak}
% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
% \DoNotIndex{\[,\{,\},\]}
% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
% \DoNotIndex{\baselineskip,\begin,\tw@}
% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
% \DoNotIndex{\bfdefault}
%
% \MakeShortVerb{\"}
% \setcounter{StandardModuleDepth}{1}
%
% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print
% \gdef\dimenvalue#1pt{$#1$pt}}  ^^A a register value with a - sign
%
% \newcommand{\DOC}{\texttt{doc}}
%
% \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}}
% \GetFileInfo{doc.sty}
%
% \title{The \DOC{} and \texttt{shortvrb} Packages\thanks
%    {This file has version number \fileversion{} dated \filedate{}.}}
% \author{Frank Mittelbach\thanks{Further commentary added at Royal
%        Military College of Science by B. Hamilton Kelly; English
%        translation of parts of the original German commentary
%        provided by Andrew Mills; fairly substantial additions,
%        particularly from \texttt{newdoc},  and
%        documentation of post-v1.5q features added at v1.7a by Dave
%        Love (SERC Daresbury Lab). Extraction of \texttt{shortvrb}
%        package added by Joachim Schrod (TU~Darmstadt).}\\
%         Gutenberg Universit\"at Mainz}
%
% \maketitle
%
% \begin{abstract}
%    This package contains the definitions that are necessary to
%    format the documentation of package files.  The package was
%    developed in Mainz in cooperation with the Royal Military College
%    of Science.  This is an update which documents various changes
%    and new features in \DOC{} and integrates the features of
%    \textsf{newdoc}.
% \end{abstract}
%
% \newif\ifmulticols
% \IfFileExists{multicol.sty}{\multicolstrue}{}
%
% \ifmulticols
% \addtocontents{toc}{\protect\begin{multicols}{2}}
% \fi
%
% {\parskip 0pt                ^^A We have to reset \parskip
%                              ^^A (bug in \LaTeX)
% \tableofcontents
% }
%
% \changes{v1.7a}{1992/02/25}{Miscellaneous small changes to the text}
%
% \ifmulticols
% \begin{multicols}{2}[\section*{Preface to version 1.7}]
% \else \section*{Preface to version 1.7} \fi
%
% This version of \texttt{doc.dtx} documents changes which have occurred
% since the last published version \cite{art:doc} but which have been
% present in distributed versions of \texttt{doc.sty} for some time.  It
% also integrates the (undocumented) features of the distributed
% \texttt{newdoc.sty}. 
%
% The following changes and additions have been made to the user
% interface since the published version~\cite{art:doc}.  See
% \S\ref{sec:interface} for more details. 
% \begin{description}
% \item[Driver mechanism] "\DocInput" is now used in the driver file
%    to input possibly multiple independent \DOC{} files and \DOC{} no
%    longer has to be the last package.  "\IndexListing" is replaced
%    by "\IndexInput"; 
% \item[Indexing] is controlled by "\PageIndex" and "\CodelineIndex",
%    one of which must be specified to produce an index---there is no
%    longer a "\makeindex" in the default "\DocstyleParms"; 
% \item[The \texttt{macro} environment] now takes as argument the
%    macro name {\em with\/} the backslash;
% \item[Verbatim text] Newlines are now forbidden inside "\verb" and
%    commands "\MakeShortVerb" and "\DeleteShortVerb" are provided for
%    verbatim shorthand; 
% \item[\texttt{\bslash par}] can now be used in "\DoNotIndex";
% \item[Checksum/character table support] for ensuring the integrity
%    of distributions is added;
% \item[\texttt{\bslash printindex}] becomes "\PrintIndex";
% \item[\texttt{multicol.sty}] is no longer necessary to use \DOC{} or
%    print the documentation (although it is recommended);
% \item[`Docstrip' modules] are recognised and formatted specially.
% \end{description}
%
% As well as adding some completely new stuff,
% the opportunity has been taken to add some commentary to the code
% formerly in \texttt{newdoc.sty} and that added after version 1.5k of
% \texttt{doc.sty}.  Since (as noted in the sections concerned) this
% commentary wasn't written by Frank Mittelbach but the code was, it is
% probably {\em not\/} true in this case that ``if the code and
% comments disagree both are probably wrong''!
%
% \subsection*{Bugs}
%
% There are some known bugs in this version:
% \begin{itemize}
% \item The "\DoNotIndex" command doesn't work for some single
%    character commands most noticeable "\%".
% \item The `General changes' glossary entry would come out after
%    macro names with a leading "!" and possibly a leading |"|;
% \item If you have an old version of \textsf{makeindex} long "\changes"
%    entries will come out strangely and you may find the section
%    header amalgamated with the first changes entry.  Try to get an
%    up-to-date one (see p.~\pageref{makeindex:version});
% \item Because the accompanying \textsf{makeindex} style files support
%    the inconsistent attribute specifications of older and newer
%    versions \textsf{makeindex} always complains about three `unknown
%    specifier's when sorting the index and changes entries.
% \item If "\MakeShortVerb" and "\DeleteShortVerb" are used with
%    single character arguments, e.g., "{|}" instead of "{\|}" chaos
%    may happen.
% \end{itemize}
% (Some `features' are documented below.)
%
% \subsection*{Wish list}
%
% \begin{itemize}
% \item Hooks to allow "\DescribeMacro" and "\DescribeEnv" to write
% out to a special file information about the package's `exported'
% definitions which they describe.  This could subsequently be
% included in the \texttt{docstrip}ped \texttt{.sty} file in a
% suitable form for use by smart editors in command completion,
% spelling checking etc., based on the packages used in a document.
% This would need agreement on a `suitable form'.  \item Indexing of
% the modules used in \texttt{docstrip}'s "%<" directives.  I'm not
% sure how to index directives containing module combinations; \item
% Writing out bibliographic information about the package; \item Allow
% turning off use of the special font for, say, the next guarded
% block.
% \end{itemize}
%
% \ifmulticols
% \end{multicols}
% 
% \begin{multicols}{2}[\medskip \rule{\textwidth}{.3pt}
%                      \section{Introduction}]
% \else
% \section{Introduction}
% \fi
%
% The \TeX{} macros which are described here allow definitions and
% documentation to be held in one and the same file.  This has the
% advantage that normally very complicated instructions are made
% simpler to understand by comments inside the definition. In addition
% to this, updates are easier and only one source file needs to be
% changed.  On the other hand, because of this, the package files are
% considerably longer: thus \TeX{} takes longer to load them.  If this
% is a problem, there is an easy remedy: one needs only to run the
% \texttt{docstrip.tex} program that removes nearly all lines that begin
% with a
% percent sign.
%
% The idea of integrated documentation was born with the development
% of the \TeX{} program; it was crystallized in Pascal with the \Web{}
% system.  The advantages of this method are plain to see (it's easy
% to make comparisons \cite{art:Knuthliterat}).  Since this
% development, systems similar to \Web{} have been developed for other
% programming languages. But for one of the most complicated
% programming languages (\TeX) the documentation has however been
% neglected.  The \TeX{} world seems to be divided between:---
% \begin{itemize} \item a couple of ``wizards'', who produce many
% lines of completely unreadable code ``off the cuff'', and \item many
% users who are amazed that it works just how they want it to do.  Or
% rather, who despair that certain macros refuse to do what is
% expected of them.\end{itemize}
%
% I do not think that the \Web{} system is {\em the\/} reference work;
% on the contrary, it is a prototype which suffices for the
% development of programs within the \TeX{} world.  It is sufficient,
% but not totally sufficient.\footnote{I know that this will be seen
% differently by a few people, but this product should not be seen as
% the finished product, at least as far as applications concerning
% \TeX{} are concerned.  The long-standing debate over `multiple
% change files' shows this well.} As a result of \Web, new programming
% perspectives have been demonstrated; unfortunately, though, they
% haven't been developed further for other programming languages.
%
% The method of documentation of \TeX{} macros which I have introduced
% here should also only be taken as a first sketch.  It is designed
% explicitly to run under \LaTeX{} alone.  Not because I was of the
% opinion that this was the best starting point, but because from this
% starting point it was the quickest to develop.\footnote{This
% argument is a bad one, however, it is all too often trotted out.} As
% a result of this design decision, I had to move away from the
% concept of modularization; this was certainly a step backward.
%
% I would be happy if this article could spark off discussion over
% \TeX\ documentation.  I can only advise anyone who thinks that they
% can cope without documentation to ``Stop Time'' until he or she
% completely understands the \AmSTeX{} source code.
%
%
%
%
%
% \subsection{Using the \DOC{} package}
%
% Just like any other package, invoke it by requesting it with a
% |\usepackage| command in the preamble. \textsf{Doc}'s use of
% |\reversemarginpars| may make it incompatible with some classes.
% \changes{v1.7a}{1992/02/25}{Altered usage info}
%
%
% \ifmulticols\end{multicols}\fi
%
%
% \section{The User Interface}\label{sec:interface}
% \subsection{The driver file}
%
% If one is going to document a set of macros with the \DOC{}
% package one has to prepare a special driver file which produces the
% formatted document. This driver file has the following
% characteristics:
% 
% \noindent |\documentclass[|\meta{options}]^^A
%           |{|\meta{document-class}|}|\\[1pt]
% |\usepackage{doc}|\\[3pt]
% \hspace*{10pt}\meta{preamble}\\[3pt]
% |\begin{document}|\\[3pt]
% \hspace*{10pt}\meta{special input commands}\\[3pt]
% |\end{document}|
%
% The \meta{document-class} might be any document class, I normally
% use \texttt{article}.
% 
% In the \meta{preamble} one should place declarations which
% manipulate the behavior of the \DOC{} package like
% |\DisableCrossrefs| or |\OnlyDescription|.
%
% \DescribeMacro\DocInput \DescribeMacro\IndexInput
% Finally the \meta{special input commands} part should contain one or
% more |\DocInput|\meta{file name} and/or
% |\IndexInput|\meta{file name} commands.  The
% |\DocInput| command is used for files prepared for the 
% \DOC{} package whereas |\IndexInput| can be used for all kinds of
% macro files.  See page \pageref{..Input} for more details of
% "\IndexInput".  Multiple "\DocInput"s can be used with a
% number of included files which are each self-contained
% self-documenting packages---for instance, each containing
% "\maketitle". 
%
% As an example, the driver file for the \DOC{} package itself is
% the following text surrounded by "%<*driver>" and "%</driver>".
% To produce the documentation you can simply run the \texttt{.dtx}
% file through \LaTeX{} in which case this code will be executed
% (loading the document class \texttt{ltxdoc}, etc.) or you can
% extract this into a separate file by using 
% the \texttt{docstrip} program.
% The line numbers below are added by
% \DOC{}'s formatting.  
% Note that the class \textsf{ltxdoc} has the \DOC{} package 
% preloaded.
% \changes{v1.7a}{1992/03/06}{Added
%                 docstrip-derivable driver file as example.}
% \changes{v1.7c}{1992/04/01}{Expurgated ltugboat.sty from driver.}
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}
\EnableCrossrefs         
 %\DisableCrossrefs % Say \DisableCrossrefs if index is ready
\CodelineIndex
\RecordChanges                  % Gather update information
 %\OnlyDescription  % comment out for implementation details
 %\OldMakeindex     % use if your MakeIndex is pre-v2.9
\setlength\hfuzz{15pt}  % dont make so many
\hbadness=7000          % over and under full box warnings
\begin{document}
   \DocInput{doc.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%
%
% \subsection{General conventions}
%
% A \TeX{} file prepared to be used with the `doc' package
% consists of `documentation parts' intermixed with `definition
% parts'.
%
% Every line of a `documentation part' starts with a percent sign
% (|%|) in column one.  It may contain arbitrary \TeX{} or
% \LaTeX{} commands except that the character `|%|' cannot be
% used as a comment character.
% \SortIndex{\string^\string^A}{\string\verb\verbatimchar
% \string^\string^A\verbatimchar \encapchar usage} To allow user
% comments, the |^^A| character is defined as a comment character
% later on.  Such `metacomments' may be also be included simply by
% surrounding them with "\iffalse" \ldots~"\fi".
%
% All other parts of the file are called `definition parts'.  They
% contain fractions of the macros described in the `documentation
% parts'.
%
% If the file is used to define new macros (e.g.\ as a package file in
% the |\usepackage| macro), the `documentation parts' are
% bypassed at high speed and the macro definitions are pasted
% together, even if they are split into several `definition parts'.
%
% \DescribeEnv{macrocode}
% On the other hand, if the documentation of these macros is to be
% produced, the `definition parts' should be typeset verbatim. To
% achieve this, these parts are surrounded by the \textsf{macrocode}
% environment.
% More exactly: before a `definition part' there should be a line
% containing\\
% \hspace*{\MacroIndent}\verb*+%    \begin{macrocode}+\\
% and after this part a line\\
% \hspace*{\MacroIndent}\verb*+%    \end{macrocode}+\\
% There must be {\em exactly\/} four spaces between the |%|
% and |\end{macrocode}| --- \TeX{} is looking for this string
% and not for the macro while processing a `definition part'.
%
% Inside a `definition part' all \TeX{} commands are allowed; even the
% percent sign could be used to suppress unwanted spaces etc.
%
% \DescribeEnv{macrocode*} Instead of the \textsf{macrocode}
% environment one can also use the \textsf{macrocode$*$} environment
% which produces the same results except that spaces are printed as
% \nopagebreak\verb*+ + characters.
%
%
%
% \subsection{Describing the usage of new macros}
%
% \DescribeMacro\DescribeMacro
% When you describe a new macro you may use |\DescribeMacro| to
% indicate that at this point the usage of a specific macro is
% explained. It takes one argument which will be printed in the margin
% and also produces a special index entry.  For example, I used
% |\DescribeMacro{\DescribeMacro}| to make clear that this is the
% point where the usage of |\DescribeMacro| is explained.
%
% \DescribeMacro\DescribeEnv
% An analogous macro |\DescribeEnv| should be used to indicate
% that a \LaTeX{} environment is explained. It will produce a somewhat
% different index entry. Below I used |\DescribeEnv{verbatim}|.
%
% \DescribeEnv{verbatim}
% It is often a good idea to include examples of the usage of new macros
% in the text. Because of the |%| sign in the first column of every
% row, the \textsf{verbatim} environment is slightly altered to suppress
% those
% characters.\footnote{These macros were written by Rainer
%                      Sch\"opf~\cite{art:verbatim}. He also
%                      provided a new \textsf{verbatim} environment
%                      which can be used inside of other macros.}
% \DescribeEnv{verbatim*}
% The \textsf{verbatim$*$} environment is changed in the same way.
% \changes{v1.7a}{1992/02/26}{Documented \cs{verb} change.}
% \DescribeMacro\verb
% The "\verb" command is re-implemented to give an error report if a
% newline appears in its argument. 
% The \textsf{verbatim} and \textsf{verbatim$*$} environments set text
% in the style defined by "\MacroFont"~(\S\ref{sec:macrofont}).
%
%
%
% \subsection{Describing the definition of new macros}
%
% \DescribeEnv{macro}
% To describe the definition of a new macro we use the \textsf{macro}
% environment. It has one argument: the name of the new
% macro.\footnote{This is a change to the style design I described in
%                ^^A \TUB ^^A removed in case ltugboat.sty not used
%                \textsl{TUGboat\/}\ 10\#1 (Jan.~89). We finally decided
%                that it would 
%                be better to use the macro name {\em with\/} the
%                backslash as an argument.}
% This argument is also used to print the name in the margin and to
% produce an index entry.
% Actually the index entries for usage and definition are different to
% allow an easy reference.
% This environment might be nested. In this case the
% labels in the margin are placed under each other.
% \changes{v1.7a}{1992/02/26}{Note on need for some text in macro env.}
% There should be some text---even  if it's just an empty
% "\mbox{}"---in this environment before "\begin{macrocode}" or the
% marginal label won't print in the right place. 
%
% \DescribeMacro\MacrocodeTopsep
% \DescribeMacro\MacroTopsep
% There also exist four style parameters: |\MacrocodeTopsep| and
% |\MacroTopsep| are used to control the vertical spacing above
% and below the \textsf{macrocode} and the \textsf{macro}
% \DescribeMacro\MacroIndent
% environment, |\MacroIndent| is used to indent the lines of code
% and
% \DescribeMacro\MacroFont \label{sec:macrofont}
% |\MacroFont| holds the font and a possible size change command
% for the code lines, the "verbatim"["*"] environment and the macro
% names printed in the margin.  If you want
% to change their default values in a 
% class file (like \texttt{ltugboat.cls}) use the |\DocstyleParms|
% command described below. Starting with release 2.0a it can now
% be changed directly as long as the redefinition happens before
% the |\begin{document}|.
%
%
%
%
% \subsection{Formatting the margins}
%
% \DescribeMacro\PrintDescribeMacro
% \DescribeMacro\PrintDescribeEnv
% \DescribeMacro\PrintMacroName
% \DescribeMacro\PrintEnvName
% As mentioned earlier, some macros and the \textsf{macro} environment
% print their arguments in the margin. This is actually done by four
% macros which are user
% definable.\footnote{You may place the changed definitions in a
%                     separate package
%                     file or at the beginning of the documentation
%                     file.
%                     For example, if you don't like any names in the
%                     margin
%                     but want a fine index you can simply
%                     \texttt{\bslash let}
%                     these macros equal \texttt{\bslash @gobble}.
%                     The doc package won't redefine any existing
%                     definitions of these macros.}
% They are named |\PrintDescribeMacro|, |\PrintDescribeEnv|,
% |\PrintMacroName| (called by the \textsf{macro} environment) and
% |\PrintEnvName| (called by the \textsf{environment} environment).
%
%
% \subsection{Using a special escape character}
%
% \DescribeMacro\SpecialEscapechar
% If one defines complicated macros it is sometimes necessary to
% introduce a new escape character because the `|\|' has got a
% special |\catcode|. In this case one can use
% |\SpecialEscapechar| to indicate which character is actually
% used to play the r\^ole of the `|\|'. A scheme like this is
% needed because the \textsf{macrocode} environment and its counterpart
% \textsf{macrocode$*$} produce an index entry for every occurrence of a
% macro name. They would be very confused if you didn't tell them that
% you'd changed |\catcode|$\,$s.  The argument to
% |\SpecialEscapechar| is a single-letter control sequence, that
% is, one has to use "\|" for example to denote that `\verb+|+'
% is used as an escape character. |\SpecialEscapechar| only
% changes the behavior of the next \textsf{macrocode} or 
% \textsf{macrocode$*$} environment.
%
%  The actual index entries created will all be printed with |\|
% rather than \verb+|+, but this probably reflects their usage, if not
% their definition, and anyway must be preferable to not having any
% entry at all.  The entries {\em could\/} be formatted appropriately,
% but the effort is hardly worth it, and the resulting index might be
% more confusing (it would certainly be longer!).
%
%
% \subsection{Cross-referencing all macros used}
%
% \DescribeMacro\DisableCrossrefs \DescribeMacro\EnableCrossrefs As
% already mentioned, every new macro name used within a
% \textsf{macrocode} or \textsf{macrocode$*$} environment will produce
% an index entry. In this way one can easily find out where a specific
% macro is used.  Since \TeX{} is considerably slower when it has to
% produce such a bulk of index entries one can turn off this feature
% by using |\DisableCrossrefs| in the driver file. To turn it on again
% just use |\EnableCrossrefs|.\footnote{Actually, \texttt{\bslash
% EnableCrossrefs} changes things more drastically; any following
% \texttt{\bslash DisableCrossrefs} which might be present in the
% source will be ignored.}
%
%
% \DescribeMacro\DoNotIndex
% But also finer control is provided. The |\DoNotIndex| macro
% takes a list of macro names separated by commas. Those names won't
% show up in the index. You might use several |\DoNotIndex|
% commands: their lists will be concatenated.  In this article I used
% |\DoNotIndex| for
% all macros which are already defined in \LaTeX.
%
% All three above declarations are local to the current group.
%
% Production (or not) of the index (via the "\makeindex" commend) is
% controlled by using or omitting the following declarations in the
% driver file preamble; if neither is used, no index is produced.
% \DescribeMacro\PageIndex Using "\PageIndex" makes all index
% entries refer to their page number; with
% \DescribeMacro\CodelineIndex "\CodelineIndex", index entries
% produced by "\DescribeMacro" and "\DescribeEnv" refer to page number
% but those produced by the \textsf{macro} environment refer to the
% code lines, which will be numbered automatically.\footnote{The line
% number is actually that of the first line of the first
% \textsf{macrocode} environment in the \textsf{macro} environment.}
% \DescribeMacro\theCodelineNo
% The style of this numbering can be controlled by defining the macro
% "\theCodelineNo".  Its default definition is to use scriptsize
% arabic numerals; a user-supplied definition won't be overwritten.
%
% \DescribeMacro\CodelineNumbered 
% When you don't wish to get an index but want your code lines
% numbered use "\CodelineNumbered" instead of "\CodelineIndex". This
% prevents the generation of an unnecessary ".idx" file.
% 
%
% \subsection{Producing the actual index entries}
%
% Several of the aforementioned macros will produce some sort of index
% entries. These entries have to be sorted by an external
% program---the current implementation assumes that the
% \textsf{makeindex} program by Chen~\cite{art:Chen} is used.
%
% But this isn't built in: one has only to redefine some of the
% following macros to be able to use any other index program.  All
% macros which are installation 
% dependent are defined in such a way that they won't overwrite a
% previous definition. Therefore it is safe to put the changed
% versions in a package file which might be read in before the doc
% package.
%
%  To allow the user to change the specific characters recognized by
%  his or her index program all characters which have special meaning
%  in the \textsf{makeindex} program are given symbolic
%  names.\footnote{I don't know if there exists a program which needs
%                  more command characters, but I hope not.}
% However, all characters used should be of |\catcode| other than
% `letter' (11).
%
% \DescribeMacro{\actualchar}
% The |\actualchar| is used to separate the `key' and the actual
% index entry.
% \DescribeMacro{\quotechar}
% The |\quotechar| is used before a special index program
% character to suppress its special meaning.
% \DescribeMacro{\encapchar}
%  The |\encapchar| separates the indexing information from a
% letter string which \textsf{makeindex} uses as a \TeX{} command to
% format the page number associated with a special entry.  It is used
% in this package to apply the |\main| and the |\usage|
% commands.
% \DescribeMacro{\levelchar}
%  Additionally |\levelchar| is used to separate `item',
% `subitem' and `subsubitem' entries.
%
% It is a good idea to stick to these symbolic names even if you know
% which index program is used. In this way your files will be
% portable.
%
% \DescribeMacro\SpecialMainIndex
% \DescribeMacro\SpecialMainEnvIndex
% To produce a main index entry for a macro the
% |\SpecialMainIndex| macro\footnote{This macro is called by the
% \textsf{macro} environment.} may be used.  It is called `special'
% because it has to print its argument verbatim.
% A similar macro, called |\SpecialMainEnvIndex| is used for indexing
% the main definition point of an 
% environment.\footnote{This macro is called by the
% \textsf{environment} environment.}
% \DescribeMacro\SpecialIndex
% If you want a normal index entry for a macro name
% |\SpecialIndex| might be used.\footnote{This macro is called
% within the \textsf{macrocode} environment when encountering a macro
% name.}
% \DescribeMacro\SpecialUsageIndex
% \DescribeMacro\SpecialEnvIndex
% To index the usage of a macro or an environment
% |\SpecialUsageIndex| and |\SpecialEnvIndex| may be used.
% \DescribeMacro\SortIndex
% Additionally a |\SortIndex| command is provided.  It takes two
% arguments---the sort key and the actual index entry.
%
% All these macros are normally used by other macros; you will need
% them only in an emergency.
%
% \DescribeMacro\verbatimchar
% But there is one characteristic worth mentioning: all macro names in
% the index are typeset with the |\verb*| command. Therefore one
% special character is needed to act as a delimiter for this command.
% To allow a change in this respect, again this character is
% referenced indirectly, by the macro |\verbatimchar|. It expands
% by default to \verb?+?  but if your code lines contain macros with
% `\texttt{+}' characters in their names (e.g.\ when you use \verb?\+?)
% you will end up with an index entry containing \verb?\verb+\++?
% which will be typeset as `\verb+\++' and not as `\verb?\+?'. In this
% case you should redefine |\verbatimchar| globally or locally to
% overcome this problem.
%
% \DescribeMacro\*
% We also provide a |\*| macro.  This is intended to be used for
% index entries like
% \begin{quote}
%    index entries \\
%    \hspace*{30pt} Special macros for \*
% \end{quote}
% Such an entry might be produced with the line:
%\begin{verbatim}
%   \index{index entries\levelchar Special macros for \*}
%\end{verbatim}
%
% \DescribeMacro\OldMakeindex
% Versions of \textsf{makeindex} prior to 2.9 had some bugs affecting
% \DOC{}.  One of these, 
% pertaining to the "%" character doesn't have a work-around
% appropriate for versions with and without the
% bug.\label{makeindex:version}  If
% you have an old version, invoke "\OldMakeindex" in a
% package file or the driver file to prevent problems with index entries
% such as "\%", although you'll probably normally want to turn off
% indexing of "\%" anyway.  Try to get an up-to-date \textsf{makeindex}
% from one of the \TeX{} repositories.
%
%
% \subsection{Setting the index entries}
%
% \changes{v1.7a}{1992/03/11}{Usage note on gind.ist.} After the first
% formatting pass through the \texttt{.dtx} file you need to sort the
% index entries written to the \texttt{.idx} file using
% \textsf{makeindex} or your favourite alternative.  You need a
% suitable style file for \textsf{makeindex} (specified by the
% \texttt{-s} switch).  A suitable one is supplied with \DOC{},
% called \texttt{gind.ist}.
%
% \DescribeMacro\PrintIndex
% To read in and print the sorted index, just put the
% |\PrintIndex| command as the last (commented-out, and thus
% executed during the documentation pass through the file) command
% in your package file.  Precede it by any bibliography commands
% necessary for your citations.
% Alternatively, it may be more convenient to put all such calls
% amongst the arguments of the |\StopEventually| macro, in
% which case a |\Finale| command should appear at the end of
% your file.
%
% \DescribeEnv{theindex}
% Contrary to standard \LaTeX, the index is typeset in three columns
% by default. This is controlled by the \LaTeX{} counter
% `\textsf{IndexColumns}' and can therefore be changed with a
% |\setcounter| declaration.  Additionally one doesn't want to
% start a new page unnecessarily.  Therefore the \textsf{theindex}
% environment is redefined.
% \DescribeMacro\IndexMin
% When the \textsf{theindex} environment starts it will measure how much
% space is left on the current page. If this is more than
% |\IndexMin| then the index will start on this page. Otherwise
% |\newpage| is called.
%
% Then a short introduction about the meaning of several index entries
% is typeset (still in onecolumn mode). Afterwards the actual index
% entries follow in multi-column mode.
% \DescribeMacro\IndexPrologue
% You can change this prologue with the help of the
% |\IndexPrologue| macro. Actually the section heading is also
% produced in this way, so you'd better write something like:
% \begin{verbatim}
%   \IndexPrologue{\section*{Index} The index entries underlined ...}
%\end{verbatim}
% When the \textsf{theindex} environment is finished the last page will
% be reformatted to produce balanced columns. This improves the layout
% and allows the next article to start on the same page.
% \DescribeMacro\IndexParms
% Formatting of the index columns (values for |\columnssep|
% etc.)\ is controlled by the |\IndexParms| macro. It assigns the
% following values:
% \SpecialUsageIndex{\parindent}\SpecialUsageIndex{\columnsep}^^A
% \SpecialUsageIndex{\parskip}\SpecialUsageIndex{\rightskip}^^A
% \SpecialUsageIndex{\mathsurround}\SpecialUsageIndex{\parfillskip}
% \begin{center}
%  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
%  |\parindent|    & \IndexParms \the\parindent    &
%  |\columnsep|    & \IndexParms \the\columnsep    \\
%  |\parskip|      & \IndexParms \the\parskip           &
%  |\rightskip|    & \IndexParms 
%                         \expandafter\dimenvalue\the\rightskip  \\
%  |\mathsurround| & \IndexParms \the\mathsurround  &
%  |\parfillskip|  & \IndexParms 
%                         \expandafter\dimenvalue\the\parfillskip      
%  \end{tabular}
% \end{center}
% \DescribeMacro{\@idxitem}
% Additionally it defines |\@idxitem| (which will be used when an
% |\item| command is encountered) and selects |\small| size.
% If you want to change any of these values you have to define them
% all.
%
% \DescribeMacro\main
% \DescribeMacro\usage
% The page numbers for main index entries are encapsulated by the
% |\main| macro (underlining its argument) and the numbers
% denoting the description are encapsulated by the |\usage| macro
% (which produces {\em italics}). As usual these commands are user
% definable.
%
%
% \subsection{Changing the default values of style parameters}
%
% \DescribeMacro\DocstyleParms If you want to overwrite some default
% settings made by the \DOC{} package, you can either put your
% declarations in the driver file (that is after \texttt{doc.sty} is
% read in) or use a separate package file for doing this work. In the
% latter case you can define the macro |\DocstyleParms| to contain all
% assignments.  This indirect approach is necessary if your package file
% might be read before the \texttt{doc.sty}, when some of the
% registers are not allocated.  Its default definition is null.
%
% The doc package currently assigns values to the following
% registers:
% \SpecialUsageIndex{\IndexMin}\SpecialUsageIndex{\MacrocodeTopsep}^^A
% \SpecialUsageIndex{\MacroTopsep}^^A
% \SpecialUsageIndex{\MacroIndent}\SpecialUsageIndex{\marginparpush}^^A
% \SpecialUsageIndex{\marginparwidth}\SpecialUsageIndex{\tolerance}
% \begin{center}
%  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
%  |\IndexMin|      & \the\IndexMin    &
%  |\MacroTopsep|   & \the\MacroTopsep    \\
%  |\marginparwidth|& \the\marginparwidth  &
%  |\MacroIndent|   & \the\MacroIndent \\
%  |\marginparpush| & \the\marginparpush    &
%  |\MacrocodeTopsep|   & \the\MacrocodeTopsep \\
%  |\tolerance|     & \the\tolerance  
%  \end{tabular}
% \end{center}
%
%
% \subsection{Short input of verbatim text pieces}
%
% \DescribeMacro\MakeShortVerb
% \DescribeMacro{\MakeShortVerb*} \DescribeMacro\DeleteShortVerb It is
% awkward to have to type, say, "\verb|"\ldots"|" continually when 
% quoting
% verbatim bits (like macro names) in the text, so an abbreviation
% mechanism is provided.  Pick a character \meta{c}---one which
% normally has catcode `other' unless you have very good reason not
% to---which you don't envisage using in the text, or not using often.
% (I like |"|, but you may prefer "|" if you have |"| active to do
% umlauts, for instance.)  Then if you say
% "\MakeShortVerb{\"\meta{c}"}" you can subsequently use
% \meta{c}\meta{text}\meta{c} as the equivalent of
% "\verb"\meta{c}\meta{text}\meta{c};  analogously, the "*"-form
% "\MakeShortVerb*{\"\meta{c}"}" gives you the equivalent of
% "\verb*"\meta{c}\meta{text}\meta{c}.  Use
% "\DeleteShortVerb{\"\meta{c}"}" if you subsequently want \meta{c} to
% revert to its previous meaning---you can always turn it on again
% after the unusual section.  The `short verb' commands make global
% changes.  The abbreviated "\verb" may not appear in the argument of
% another command just like "\verb".  However the `short verb'
% character may be used freely in the \textsf{verbatim} and
% \textsf{macrocode} environments without ill effect.
% "\DeleteShortVerb" is silently ignored if its argument does not
% currently represent a short verb character.  Both commands type a
% message to tell you the meaning of the character is being changed.
%
% Please remember that the command "\verb" cannot be used in arguments
% of other commands. Therefore abbreviation characters for "\verb"
% cannot be used there either.
%
% This feature is also available as a sole package, \texttt{shortvrb}.
%
%
% \subsection{Additional bells and whistles}
%
% We provide macros for logos such as \Web, \AmSTeX, \BibTeX,
% \SliTeX{} and \PlainTeX. Just type |\Web|, |\AmSTeX|,
% |\BibTeX|, |\SliTeX| or |\PlainTeX|, respectively.
% \LaTeX{} and \TeX{} are already defined in \texttt{latex.tex}.
%
% \DescribeMacro\meta
% Another useful macro is |\meta| which has one argument and
% produces something like \meta{dimen parameter}.
%
% \DescribeMacro\OnlyDescription
% \DescribeMacro\StopEventually
% You can use the |\OnlyDescription| declaration in the driver
% file to suppress the last part of your document (which presumably
% exhibits the code). To make this work
% you have to place the command |\StopEventually| at a suitable
% point in your file.  This macro has one argument in which you put
% all information you want to see printed if your document ends at
% this point (for example a bibliography which is normally printed at
% the very end). When the |\OnlyDescription| declaration is
% missing the |\StopEventually|
% \DescribeMacro\Finale
% macro saves its argument in a macro called |\Finale| which can
% afterwards be used to get things back (usually at the very end).
% Such a scheme makes changes in two places unnecessary.
%
% Thus you can use this feature to produce a local guide for the
% \TeX{} users which describes only the usage of macros (most of them
% won't be interested in your definitions anyway).  For the same
% reason the |\maketitle| \DescribeMacro\maketitle command is slightly
% changed to allow multiple titles in one document.  So you can make
% one driver file reading in several articles at once.
% \DescribeMacro{\ps@titlepage} To avoid an unwanted
% \textsf{pagestyle} on the title page the |\maketitle| command issues
% a |\thispagestyle{titlepage}| declaration which produces a
% \textsf{plain} page if the \textsf{titlepage} page style is
% undefined.  This allows class files like \textsf{ltugboat.cls} to
% define their own page styles for title pages.
%
% \DescribeMacro\AlsoImplementation
% Typesetting the whole document is the default. However, this default
% can also be explicitly selected using the declaration
% |\AlsoImplementation|. This overwrites any previous
% |\OnlyDescription| declaration. The \LaTeXe{} distribution, for
% example, is documented using the \texttt{ltxdoc} class which allows
% for a configuration file \texttt{ltxdoc.cfg}. In such a file one
% could then add the statement
% \begin{quote}
% |\AtBeginDocument{\AlsoImplementation}|
% \end{quote}
% to make sure that all documents will show the code part.
%
% \DescribeMacro\IndexInput \label{..Input} Last but not least I
% defined an |\IndexInput| macro which takes a file name as an
% argument and produces a verbatim listing of the file, indexing every
% command as it goes along.  This might be handy, if you want to learn
% something about macros without enough documentation.  I used this
% feature to cross-reference \texttt{latex.tex} getting a verbatim
% copy with about 15 pages index.\footnote{It took quite a long time
% and the resulting \texttt{.idx} file was longer than the
% \texttt{.dvi} file.  Actually too long to be handled by the
% \textsf{makeindex} program directly (on our MicroVAX) but the final
% result was worth the trouble.}
%
% \changes{v2.1d}{2006/02/02}{Corrected description of \cs{changes}
% macro.}
% \DescribeMacro\changes
% To maintain a change history within the file, the |\changes|
% command may be placed amongst the description part of the changed
% code.  It takes three arguments, thus:
% \begin{quote}
% |\changes{|\meta{version}|}{|\meta{date}|}{|^^A
% \meta{text}|}|
% \end{quote}
% The changes may be used to produce an auxiliary file (\LaTeX's
% |\glossary| mechanism is used for this) which may be printed
% after suitable formatting. The |\changes| macro generates the
% printed entry in such a change history; because old
% versions\footnote{Before 2.6.} of the \textsf{makeindex}
% program limit such fields to 64 characters, care should be taken
% not to exceed this limit when describing the change. The actual
% entry consists of the \meta{version}, the |\actualchar|, the current
% macro name, a colon, the |\levelchar|, and, finally, the \meta{text}.
% The result is a glossaryentry for the \meta{version}, with the name of
% the current macro as subitem.  Outside the |macro| environment, the
% text |\generalname| is used instead of the macro name.  When
% referring to macros in change descriptions it is conventional to use
% |\cs{|\meta{macroname}|}| rather than attempting to format it properly
% and using up valuable characters in the entry with old \textsf{makeindex}
% versions.
%
% \changes{v1.7a}{1992/02/26}{Description of \cs{RecordChanges} etc. 
% added
% to interface section.} \DescribeMacro\RecordChanges To cause the
% change information to be written out, include "\RecordChanges" in
% the driver file.  \DescribeMacro\PrintChanges To read in and print
% the sorted change history (in two columns), just put the
% |\PrintChanges| command as the last (commented-out, and thus
% executed during the documentation pass through the file) command in
% your package file.  Alternatively, this command may form one of the
% arguments of the |\StopEventually| command, although a change
% history is probably {\em not\/} required if only the description is
% being printed.  The command assumes that \textsf{makeindex} or some
% other program has processed the \texttt{.glo} file to generate a
% sorted \texttt{.gls} file.  You need a special \textsf{makeindex}
% style file; a suitable one is supplied with \DOC{}, called
% \texttt{gglo.ist}.  \DescribeMacro\GlossaryMin
% \DescribeMacro\GlossaryPrologue \DescribeMacro\GlossaryParms The
% "\GlossaryMin", "\GlossaryPrologue" and "\GlossaryParms" macros are
% analagous to the "\Index"\ldots\ versions.  (The \LaTeX{} `glossary'
% mechanism is used for the change entries.)
%
% \label{sec:checksum}
% \DescribeMacro\CharacterTable
% \DescribeMacro\CheckSum 
% To overcome some of the problems of sending files over the networks
% we developed two macros which should detect corrupted files. If one
% places the lines
% \begin{flushleft}
% \small\ttfamily        ^^A \ttfamily to get the blanks between "..."s
%                        ^^A right
%"%%\CharacterTable"\\
%"%% {Upper-case   "
%"\A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z"\\
%"%%  Lower-case   "
%"\a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z"\\
%"%%  Digits        \0\1\2\3\4\5\6\7\8\9"\\
%"%%  Exclamation   \!     Double quote  "\verb=\"= 
%"    Hash (number) \#"\\
%"%%  Dollar        \$     Percent       \%     Ampersand     \&"\\
%"%%  Acute accent  \'     Left paren    \(     Right paren   \)"\\
%"%%  Asterisk      \*     Plus          \+     Comma         \,"\\
%"%%  Minus         \-     Point         \.     Solidus       \/"\\
%"%%  Colon         \:     Semicolon     \;     Less than     \<"\\
%"%%  Equals        \=     Greater than  \>     Question mark \?"\\
%"%%  Commercial at \@     Left bracket  \[     Backslash     \\"\\
%"%%  Right bracket \]     Circumflex    \^     Underscore    \_"\\
%"%%  Grave accent  \`     Left brace    \{     Vertical bar  \|"\\
%"%%  Right brace   \}     Tilde         \~}"\\
%"%%"
%\end{flushleft}
% at the beginning of the file then character translation failures
% will be detected, provided of course, that the used \DOC{}
% package has a correct default table.  The percent
% signs\footnote{There are two percent signs in each line. This has
% the effect that these lines are not removed by the
% \texttt{docstrip.tex} program.} at the beginning of the lines should
% be typed in, since only the \DOC{} package should look at this
% command.
%
% Another problem of mailing files is possible truncation.  To detect
% these sort of errors we provide a |\CheckSum| macro.  The check-sum
% of a file is simply the number of backslashes in the code, i.e.\ all
% lines between the \textsf{macrocode} environments.  But don't be
% afraid: you don't have count the code-lines yourself; this is done
% by the \DOC{} package for you.  You simply have to use
% the |\StopEventually| (which starts looking for backslashes) and the
% |\Finale| command.  The latter will inform you either that your file
% has no check-sum (telling you the right number) or that your number
% is incorrect (this time telling you both the correct and the
% incorrect one).  Then you go to the top of your file inserting the
% line
% \begin{quote}
%    |%%   \CheckSum{|\meta{number}|}|
% \end{quote}
% and that's all. If you precede it only with one percent then the
% line will not show up in \texttt{docstrip} versions of the file.
% You should do so whenever you are using conditional code (see
% \texttt{docstrip} documentation) since then the check-sum will not
% reflect the number of backslashes in the stripped of versions.
%
% \DescribeMacro\bslash
% From time to time, it is necessary to print a |\| without
% being able to use the |\verb| command because the
% |\catcode|$\,$s of the symbols are already firmly
% established.  In this instance we can use the command
% |\bslash| presupposing, of course, that the actual font in
% use at this point contains a `backslash' as a symbol.  Note that
% this definition of |\bslash| is expandable; it inserts a
% $"\"_{12}$.  This means that you have to |\protect|
% it if it is used in `moving arguments'.
%
% \DescribeMacro\MakePrivateLetters
% \changes{v1.7a}{1992/02/26}{Documented \cs{MakePrivateLetters} in
%                           interface section}^^A
% If your macros "\catcode" anything other than "@" to `letter', you
% should redefine "\MakePrivateLetters" so that it also makes the
% relevant characters `letters' for the benefit of the indexing.  The
% default definition is just "\makeatletter".
%
% \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules
% \DescribeMacro\Module \DescribeMacro\AltMacroFont The `module'
% directives of the \textsf{docstrip} system \cite{art:docstrip} are
% normally recognised and invoke special formatting.  This can be
% turned on and off in the \texttt{.dtx} file or the driver file using
% "\CheckModules" and "\DontCheckModules".  If checking for module
% directives is on (the default) then code in the scope of the
% directives is set as determined by the hook "\AltMacroFont", which
% gives {\small\ttfamily\itshape small italic type\-writer\/} by
% default in the New Font Selection Scheme but just ordinary
% {\small\ttfamily small type\-writer} in the old one, where a font
% such as italic typewriter can't be used portably (plug for NFSS);
% you will need to override this if you don't have the italic
% typewriter font available.  Code is in such a scope if it's on a
% line beginning with "%<" or is between lines starting with
% "%<*"\meta{name list}">" and "%</"\meta{name list}">".  The
% directive is formatted by the macro "\Module" whose single argument
% is the text of the directive between, but not including, the angle
% brackets; this macro may be re-defined in the driver or package file
% and by default produces results like \Module{+foo\string|bar} with no
% following space.
%
% \DescribeMacro{StandardModuleDepth} Sometimes (as in this file) the
% whole code is surrounded by modules to produce several files from a
% single source. In this case it is clearly not appropriate to format
% all code lines in a special "\AltMacroFont". For this reason a
% counter "StandardModuleDepth" is provided which defines the level of
% module nesting which is still supposed to be formatted in
% "\MacroFont" rather then "\AltMacroFont". The default setting is
% "0", for this documentation it was set to
%\begin{verbatim}
%   \setcounter{StandardModuleDepth}{1}
%\end{verbatim}
% at the beginning of the file.
%
%
% \subsection{Basic usage summary}
% \changes{v1.7a}{1992/03/11}{Added basic usage summary to spell
%                             it out.}
%
% To sum up, the basic structure of a \texttt{.dtx} file without any
% refinements is like this: 
% \begin{verse}\small
% "% "\meta{waffle}\ldots\\
% \quad\ldots \\
% "% \DescribeMacro{\fred}"\\
% "% "\meta{description of fred's use}\\
% \quad\ldots\\
% "% \StopEventually{"\meta{finale code}"}"\\
% \quad\ldots\\
% "% \begin{macro}{\fred}"\\
% "% "\meta{commentary on macro fred}\\
% \verb*+%    \begin{macrocode}+\\
% \meta{code for macro fred}\\
% \verb*+%    \end{macrocode}+\\
% "% \end{macro}"\\
% \quad\ldots\\
% "% \Finale \PrintIndex \PrintChanges"
% \end{verse}
% For examples of the use of most---if not all---of the features
% described above consult the \texttt{doc.dtx} source itself. 
%
% \subsection{Acknowledgements}
%
% I would like to thank all folks at Mainz and at the Royal Military
% College of Science for their help in this project. Especially Brian
% and Rainer who pushed everything with their suggestions, bug fixes,
% etc.
%
% A big thank you to David Love who brought the documentation
% up-to-date again, after I neglected this file for more than two
% years. This was most certainly a tough job as many features added to
% \texttt{doc.dtx} after its publication in \textsl{TUGboat\/} have
% been never properly described. Beside this splendid work he kindly
% provided additional code (like ``docstrip'' module formatting) which
% I think every \textsf{doc.dtx} user will be grateful for.
%
%
% \StopEventually{
%  \begin{thebibliography}{1}
%    \bibitem{book:Buerger}  \textsc{G. A. B\"urger}.
%      \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldz\"uge
%                und lustige Abenteuer des Freyherrn v.\ M\"unchhausen.
%      \newblock London, 1786 \& 1788.
%    \bibitem{art:Knuthliterat} \textsc{D. E. Knuth}.
%      \newblock Literate Programming.
%      \newblock Computer Journal, Vol.~27, \textit{pp}.~97--111, 
%               May 1984.
%    \bibitem{book:KnuthA} \textsc{D. E. Knuth}.
%      \newblock Computers \& Typesetting (The \TeX book).
%      \newblock Addison-Wesley, Vol. A, 1986.
%    \bibitem{art:Chen} \textsc{L. Lamport}.
%      \newblock MakeIndex: An Index Processor for \LaTeX.
%      \newblock 17 February 1987.
%      \newblock (Taken from the file \texttt{makeindex.tex} provided
%                 with
%      the program source code.)
%    \bibitem{art:doc} \textsc{Frank Mittelbach}.
%      \newblock The \DOC{}-option.
%      \newblock \textsl{TUGboat}, Vol.~10(2), \textit{pp}.~245--273,
%        July 1989.
%    \bibitem{art:docstrip} \textsc{Frank Mittelbach, Denys Duchier and
%         Johannes Braams}. 
%      \newblock \texttt{docstrip.dtx} (to appear).
%      \newblock The file is part of the DOC package.
%    \bibitem{book:Raspe} \textsc{R. E. Raspe} (*1737, \dag 1797).
%      \newblock Baron M\"unchhausens narrative of his marvellous
%                travels and campaigns in Russia.
%      \newblock Oxford, 1785.
%    \bibitem{art:verbatim} \textsc{Rainer Sch\"opf}.
%      \newblock A New Implementation of \LaTeX's \texttt{verbatim} and
%      \texttt{verbatim*} Environments.
%      \newblock File \texttt{verbatim.doc}, version 1.4i.
%  \end{thebibliography}
%  ^^A\PrintIndex
%  ^^A\PrintChanges
%
%  \ifmulticols
%  \addtocontents{toc}{\protect\end{multicols}}
%  \fi
% 
% } ^^A end \StopEventually
%
%
% \section{The Description of Macros}
%
% Most of the following code is destined for \texttt{doc.sty} after
% processing with \texttt{docstrip} to include the module
% \textbf{style} indicated here.  (All code in this file not
% appropriate to \texttt{doc.sty} has to be included explicitly by
% docstrip so that this \texttt{.dtx} file can be used as directly as
% a package file rather than the stripped version.)  The usual font
% change for the conditionally-included lines between the
% \Module{*style} and \Module{/style} directives is suppressed since
% only the lines with an explicit directive are special in this file.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% Under \LaTeXe{} the test to avoid reading
% \DOC{} in twice is normally unnecessary. It was kept to only to
% stay compatible with \LaTeX209 styles that |\input| \DOC{}
% directly.
% \changes{v1.5i}{1989/06/07}{Avoid reading the file twice.}
%    \begin{macrocode}
\@ifundefined{macro@cnt}{}{\endinput}
%    \end{macrocode}
%
% \DescribeMacro\fileversion
% \DescribeMacro\filedate
% \DescribeMacro\docdate
% As you can see I used macros like |\fileversion| to denote the
% version number and the date. They are defined at the very beginning
% of the package file (without a surrounding \textsf{macrocode}
% environment), so I don't have to search for this place here when I
% change the version number.  You can see their actual outcome in a
% footnote to the title.
%
%
% The first thing that we do next is to get ourselves a new comment
% sign.  Because all sensible signs are already occupied, we will
% choose one that can only be entered indirectly:
% {\DoNotIndex{\^}^^A avoid misinterpretion !!!!! VERIFY  
%    \begin{macrocode}
\catcode`\^^A=14
%    \end{macrocode}
% We repeat this statement at the beginning of the document in case
% the \texttt{inputenc} package is used disabling it again.
% \changes{v2.0b}{1998/05/19}{Init docs private comment char at begin
%  of document again (pr2581)}
%    \begin{macrocode}
\AtBeginDocument{\catcode`\^^A=14\relax}
%    \end{macrocode}
%    \SortIndex{\string^\string^A}{\string\verb\verbatimchar
%                                  \string^\string^A\verbatimchar
%                                  \encapchar main}
% }
%
%
% \subsection{Options supported by \DOC{}}
%
%   Not options available at the moment
%
%    \begin{macrocode}
%    \end{macrocode}
%
%
% \subsection{Macros surrounding the `definition parts'}
%
% \begin{macro}{\macrocode}
%    Parts of the macro definition will be surrounded by the
%    environment \textsf{macrocode}.  Put more precisely, they will be
%    enclosed by a macro whose argument (the text to be set
%    `verbatim') is terminated by the string 
% \verb*+%    \end{macrocode}+.  Carefully note the number of spaces.
%    |\macrocode| is defined completely analogously to
%    |\verbatim|, but because a few small changes were carried
%    out, almost all internal macros have got new names.  We start by
%    calling the macro |\macro@code|, the macro which bears the
%    brunt of most of the work, such as |\catcode| reassignments,
%    etc.
% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)}
%    \begin{macrocode}
\def\macrocode{\macro@code
%    \end{macrocode}
%    Then we take care that all spaces have the same width, and that
%    they are not discarded.
%    \begin{macrocode}
   \frenchspacing \@vobeyspaces
%    \end{macrocode}
%    Before closing, we need to call |\xmacro@code|.  It is this
%    macro that expects an argument which is terminated by the above
%    string.  This way it is possible to keep the |\catcode|
%    changes local.
% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)}
% \changes{v1.5t}{1989/11/07}{Common code moved to \cs{macro@code}.}
%    \begin{macrocode}
   \xmacro@code}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\macro@code}
%    We will now begin with the macro that does the actual work:
%    \begin{macrocode}
\def\macro@code{%
%    \end{macrocode}
%    In theory it should consist of a \textsf{trivlist} environment, but
%    the empty space before and after the environment should not be
%    too large.
%    \begin{macrocode}
   \topsep \MacrocodeTopsep
%    \end{macrocode}
%    The next parameter we set is |\@beginparpenalty|, in order
%    to prevent a page break before such an environment.
%    \begin{macrocode}
   \@beginparpenalty \predisplaypenalty
%    \end{macrocode}
%    We then start a |\trivlist|, set |\parskip| back to
%    zero and start an empty |\item|.
% \changes{v1.9b}{1993/12/03}{Forcing any label from macro env.}
%    \begin{macrocode}
   \if@inlabel\leavevmode\fi
   \trivlist \parskip \z@ \item[]%
%    \end{macrocode}
%    Additionally, everything should be set in \texttt{typewriter} font.
%    Some people might prefer it somewhat differently; because of this
%    the font choice is
%    macro-driven.\footnote{The font change has to be placed
%                       {\em after\/}
%                       the \texttt{\bslash item}. Otherwise a change to
%                       \texttt{\bslash baselineskip} will affect the
%                       paragraph above.}
%    \begin{macrocode}
   \macro@font
%    \end{macrocode}
%    Because |\item| sets various parameters, we have found it
%    necessary to alter some of these retrospectively.
%    \begin{macrocode}
   \leftskip\@totalleftmargin \advance\leftskip\MacroIndent
   \rightskip\z@ \parindent\z@ \parfillskip\@flushglue
%    \end{macrocode}
%    The next line consists of the \LaTeX{} definition of |\par|
%    used in |\verbatim| and should result in blank lines being
%    shown as blank lines.
% \changes{v1.5l}{1989/09/10}{Code line numbers supported.}
% \changes{v1.5t}{1989/11/07}{Call \cs{leavevmode} to get \cs{everypar}
%                           on blank lines.}
% \changes{v1.7c}{1992/3/24}{Added \cs{interlinepenalty} to 
%                          \cs{par} from
%                          verbatim.sty}
%    \begin{macrocode}
   \blank@linefalse \def\par{\ifblank@line
                             \leavevmode\fi
                             \blank@linetrue\@@par
                             \penalty\interlinepenalty}
%    \end{macrocode}
%    What use is this definition of |\par|\,?  We use the macro
%   |\obeylines| of \cite{book:KnuthA} which changes all |^^M|
%    to |\par| so that each can control its own indentation.
%    Next we must also ensure that all special signs are normalized;
%    that is, they must be given |\catcode| $12$.
% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
%                           which handles more ligatures.}
%    \begin{macrocode}
   \obeylines
   \let\do\do@noligs \verbatim@nolig@list
   \let\do\@makeother \dospecials
%    \end{macrocode}
% \changes{v1.5t}{1989/11/07}{Common code added.}
% \changes{v1.5w}{1990/02/05}{Skip of \cs{@totalleftmargin} added.} If
% indexing by code lines is switched on the line number is incremented
% and set appropriately.  We also check whether the start of the next
% line indicates a \texttt{docstrip} module directive and process it
% appropriately if so using "\check@module".
%    \begin{macrocode}
   \global\@newlistfalse
   \global\@minipagefalse
   \ifcodeline@index
     \everypar{\global\advance\c@CodelineNo\@ne
               \llap{\theCodelineNo\ \hskip\@totalleftmargin}%
               \check@module}%
   \else \everypar{\check@module}%
   \fi
%    \end{macrocode}
%    We also initialize the cross-referencing feature by calling
%    |\init@crossref|. This will start the scanning mechanism
%    when encountering an escape character.
%    \begin{macrocode}
   \init@crossref}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\ifblank@line}
% \begin{macro}{\blank@linetrue}
% \begin{macro}{\blank@linefalse}
%    |\ifblank@line| is the switch used in the definition above.
%    In the original \textsf{verbatim} environment the |\if@tempswa|
%    switch is used. This is dangerous because its value may change
%    while processing lines in the \textsf{macrocode} environment.
%    \begin{macrocode}
\newif\ifblank@line
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\endmacrocode}
%    Because we have begun a \textsf{trivlist} environment in the
%    \textsf{macrocode} environment, we must also end it.  We must
%    also act on the value of the "pm@module" flag (see below) and
%    empty "\everypar".
% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)}
%    \begin{macrocode}
\def\endmacrocode{%
                 \ifpm@module \endgroup \pm@modulefalse \fi
                 \everypar{}%
                 \global\@inlabelfalse
                 \endtrivlist
%    \end{macrocode}
%    Additionally |\close@crossref| is used to do anything needed
%    to end the cross-referencing mechanism.
%    \begin{macrocode}
                 \close@crossref}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\MacroFont}
%    Here is the default definition for the |\MacroFont| macro.
%    With the new math font handling in NFSS2 it isn't any longer
%    correct to suppress the math font setup since this is now handled
%    differently. But to keep the font change fast we use only a
%    single |\selectfont| (in |\small|) and do the rest by hand.
% \changes{v1.5x}{1990/02/17}{\cs{math@fontsfalse} added for NFSS.}
% \changes{v1.7a}{1992/03/13}{Added \cs{reset@font} for NFSS.}
% \changes{v1.8c}{1993/10/25}{NFSS standard}
% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different
%                             math setup /pr1622}
%    \begin{macrocode}
\@ifundefined{MacroFont}{%
  \if@compatibility
%    \end{macrocode}
%    Despite the above statement we will call |\small| first if
%    somebody is using a \LaTeX2.09 document with doc. I wouldn't have
%    bothered since doc-sources should be up-to-date but since the
%    request came from someone called David Carlisle \ldots :-)
% \changes{v1.9y}{1996/01/26}{Support compat mode}
%    \begin{macrocode}
    \def\MacroFont{\small
                   \usefont\encodingdefault
                           \ttdefault
                           \mddefault
                           \updefault
                   }%
  \else
    \def\MacroFont{\fontencoding\encodingdefault
                   \fontfamily\ttdefault
                   \fontseries\mddefault
                   \fontshape\updefault
                   \small}%
  \fi
  }{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\AltMacroFont}
% \begin{macro}{\macro@font}
% \changes{v1.7a}{1992/03/12}{Added to support distinction of modules.}
% \changes{v1.7c}{1992/03/26}{Altered font change for OFSS.}
% \changes{v1.7m}{1992/10/11}{Use sltt as default.}
% \changes{v1.8c}{1993/10/25}{NFSS standard}
% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different
%                             math setup /pr1622}
% Although most of the macro code is set in "\MacroFont" we want to be
% able to switch to indicate module code set in "\AltMacroFont".
% "\macro@font" keeps track of which one we're using.  We can't do the
% same thing sensibly in OFSS as in NFSS.
%    \begin{macrocode}
\@ifundefined{AltMacroFont}{%
  \if@compatibility
%    \end{macrocode}
%    Again have |\small| first if we are in compat mode.
% \changes{v1.9y}{1996/01/26}{Support compat mode}
%    \begin{macrocode}
    \def\AltMacroFont{\small
                      \usefont\encodingdefault
                              \ttdefault
                              \mddefault
                              \sldefault
                      }%
  \else
    \def\AltMacroFont{\fontencoding\encodingdefault
                      \fontfamily\ttdefault
                      \fontseries\mddefault
                      \fontshape\sldefault
                      \small
                      }%
 \fi
  }{}
%    \end{macrocode}
%    To allow changing the "\MacroFont" in the preamble we defer
%    defining the internally used "\macro@font" until after the
%    preamble.
% \changes{v2.0a}{1998/05/16}{Support changing \cs{MacroFont} in 
%          preamble}
%    \begin{macrocode}
\AtBeginDocument{\let\macro@font\MacroFont}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\check@module}
% \begin{macro}{\ifpm@module}
% \changes{v1.7a}{1992/03/12}{Added.}
% This is inserted by "\everypar" at the start of each macrocode line to
% check whether it starts with module information.  (Such information is
% of the form "%<"\meta{switch}">", where the "%" must be at the
% start of the line and \meta{switch} comprises names with various
% possible separators and a possible leading "+", "-", "*" or "/"
% \cite{art:docstrip}.  All that concerns us here is what the first
% character of \meta{switch} is.)  First it checks the "pm@module" 
% flag in case the previous line had a non-block module
% directive i.e., not "%<*" or "%</"; if it did we need to close the
% group it started and unset the flag.  "\check@module" looks ahead at
% the next token and then calls "\ch@percent" to take action depending
% on whether or not it's a "%"; we don't want to expand the token at
% this stage.  This is all done conditionally so it can be turned off
% if it causes problems with code that wasn't designed to be
% \texttt{docstrip}ped.
%    \begin{macrocode}
\def\check@module{%
  \ifcheck@modules
    \ifpm@module \endgroup \pm@modulefalse \fi
    \expandafter\futurelet\expandafter\next\expandafter\ch@percent
  \fi}
\newif\ifpm@module
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\DontCheckModules}
% \begin{macro}{\CheckModules}
% \changes{v1.7a}{1992/03/12}{Added.}
% \begin{macro}{\ifcheck@modules}
% Here are two driver-file interface macros for turning the module
% checking on and off using the "check@modules" switch.
%    \begin{macrocode}
\def\DontCheckModules{\check@modulesfalse}
\def\CheckModules{\check@modulestrue}
\newif\ifcheck@modules  \check@modulestrue
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\ch@percent}
% \changes{v1.7a}{1992/03/12}{Added.}
% If the lookahead token in "\next" is $"%"_{12}$ we go on to check
% whether the following one is "<" and otherwise do nothing.  Note the
% "\expandafter" to get past the "\fi".
%    \begin{macrocode}
\def\ch@percent{%
  \if \percentchar\next
    \expandafter\check@angle
  \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\check@angle}
% \changes{v1.7a}{1992/03/12}{Added.}
% Before looking ahead for the "<" the "%" is gobbled by the
% argument here.
%    \begin{macrocode}
\def\check@angle#1{\futurelet\next\ch@angle}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ch@angle}
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.9k}{1994/02/22}{Have \texttt{<} active} 
%    If the current lookahead token is "<" we are defined to be
%    processing a module directive can go on to look for "+" etc.;
%    otherwise we must put back the gobbled "%". With \LaTeXe{}
%    \texttt{<} is active so we have to be a bit careful.
%    \begin{macrocode}
\begingroup
\catcode`\<\active
\gdef\ch@angle{\ifx<\next
    \expandafter\ch@plus@etc 
  \else \percentchar \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ch@plus@etc}
% \begin{macro}{\check@plus@etc}
% \changes{v1.7a}{1992/03/12}{Added.}
% We now have to decide what sort of a directive we're dealing with
% and do the right thing with it.
%    \begin{macrocode}
\gdef\ch@plus@etc<{\futurelet\next\check@plus@etc}
\gdef\check@plus@etc{%
    \if +\next
      \let\next\pm@module
    \else\if -\next
      \let\next\pm@module
    \else\if *\next
      \let\next\star@module
    \else\if /\next
      \let\next\slash@module
%    \end{macrocode}
%    At some point in the past the \texttt{docstrip} program was
%    partly rewritten and at that time it also got support for a very
%    special directive of the form |%<<| followed by an arbitrary
%    string. This is used for ``verbatim'' inclusion in case of
%    certain problem. We do not really attempt to pretty print that
%    case but we need at least account for it since otherwise we get
%    an error message since this is the only case where we will not
%    have a closing |>|.
% \changes{v2.0n}{2001/05/16}{Partly support docstrip's ``verbatim''
%    directive (pr/3331)}
%    \begin{macrocode}
    \else\ifx <\next
      \percentchar
    \else
      \let\next\pm@module
    \fi\fi\fi\fi\fi
    \next}
\endgroup
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\pm@module}
% If we're not dealing with a block
% directive ("*" or "/") i.e., it's a single special line, we set
% everything up to the next ">" appropriately and then change to the
% special macro font inside a group which will be ended at the start
% of the next line.  If the apparent module directive is missing the
% terminating ">" this will lose, but then so will the \texttt{docstrip}
% implementation.  An alternative strategy would be to have
% "\pm@module" make ">" active and clear a flag set here to indicate
% processing the directive.  Appropriate action could then be taken if
% the flag was found still to be set when processing the next line.
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.7i}{1992/07/11}{Support for fonts depending on nesting.}
%    \begin{macrocode}
\begingroup
\catcode`\~=\active
\lccode`\~=`\>
\lowercase{\gdef\pm@module#1~}{\pm@moduletrue
   \Module{#1}\begingroup 
%    \end{macrocode}
%    We switch to a special font as soon the nesting is higher than
%    the current value of "\c@StandardModuleDepth". We do a local
%    update to the "\guard@level" here which will be restored after
%    the current input line.
%    \begin{macrocode}
     \advance\guard@level\@ne
     \ifnum\guard@level>\c@StandardModuleDepth\AltMacroFont\fi
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\star@module}
% \begin{macro}{\slash@module}
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.7f}{1992/05/16}{Take account of nested guards.}
% \changes{v1.7i}{1992/07/11}{Add counter to determine when to switch to
%                           special font.}
% If the start or end of a module {\em block\/} is indicated, after
% setting the guard we have to check whether a change in the macrocode
% font should be done.  This will be the case if we are already inside
% a block or are ending the outermost block.  If so, we globally
% toggle the font for subsequent macrocode sections between the normal
% and special form, switching to the new one immediately.
% \changes{v1.7i}{1992/07/17}{Support for fonts depending on module
%                           nesting}
%    \begin{macrocode}
\lowercase{\gdef\star@module#1~}{%
  \Module{#1}%
  \global \advance \guard@level\@ne
  \ifnum \guard@level>\c@StandardModuleDepth
    \global\let\macro@font=\AltMacroFont \macro@font
  \fi}
\catcode`\>=\active
\gdef\slash@module#1>{%
  \Module{#1}%
  \global \advance \guard@level\m@ne
  \ifnum \guard@level=\c@StandardModuleDepth
    \global\let\macro@font\MacroFont  \macro@font
  \fi
}
\endgroup
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%  \begin{macro}{\c@StandardModuleDepth}
% \changes{v1.7i}{1992/07/11}{Counter added.}
%    Counter defining up to which level modules are considered part of
%    the main code. If, for  example, the whole code is surrounded by
%    a |%<*package>| module we better set this counter to |1| to avoid
%    getting the whole code be displayed in typewriter italic.
%    \begin{macrocode}
\newcounter{StandardModuleDepth}
%    \end{macrocode}
%  \end{macro}
%
%
% \begin{macro}{\guard@level}
% \changes{v1.7f}{1992/05/16}{Added.}
% We need a counter to keep track of the guard nesting.
%    \begin{macrocode}
\newcount \guard@level
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\Module}
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.7d}{1992/04/25}{Use sans font for modules.}
% This provides a hook to determine the way the module directive is
% set.  It gets as argument everything between the angle brackets.
% The default is to set the contents in sans serif text between
% $\langle\,\rangle$ with the special characters suitably "\mathcode"d
% by "\mod@math@codes".  (You can't just set it in a sans text font
% because normally "|" will print as an em-dash.)  This is done
% differently depending on whether we have the NFSS or the old one.  In
% the latter case we can easily change "\fam" appropriately.
% \changes{v1.8c}{1993/10/25}{NFSS standard}
%    \begin{macrocode}
\@ifundefined{Module}{%
%    \end{macrocode}
%    With NFSS what we probably {\em should\/} do is change to a new
%    "\mathversion" but I (Dave Love) haven't spotted an easy way to
%    do so correctly if the document uses a version other than
%    "normal".  (We need to know in what font to set the other
%    groups.)  This uses a new math alphabet rather than version and
%    consequently has to worry about whether we're using
%    \textsf{oldlfnt} or not.  I expect there's a better
% way\ldots
%    \begin{macrocode}
      \def\Module#1{\mod@math@codes$\langle\mathsf{#1}\rangle$}
  }{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\mod@math@codes}
% \changes{v1.7c}{1992/03/26}{Added.} As well as `words', the module
%    directive text might contain any of the characters "*/+-,&|!()"
%    for the current version of \textsf{docstrip}.  We only need
%    special action for two of them in the math code changing required
%    above: "|" is changed to a "\mathop" (it's normally |"026A|) and
%    "&" is also made a "\mathop", but in family 0.  Remember that "&"
%    will not have a special catcode when it's encountered.
%    \begin{macrocode}
\def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\mathsf}
% \changes{v1.7c}{1992/03/26}{Added.}
% \changes{v1.7d}{1992/04/25}{Use sans font for modules.}
% \changes{v1.7n}{1993/02/21}{\cs{sfmath} Renamed to \cs{mathsf}.}
% \changes{v1.8c}{1993/10/25}{NFSS standard}
% If NFSS is in use we need a new math alphabet which uses a sans serif
% font. To support both the release one and two of NFSS the alphabet
% was renamed to "\mathsf" which is defined in NFSS2. 
%    \begin{macrocode}
%\ifx\selectfont\undefined
%\else
%  \ifx\mathsf\undefined
%    \newmathalphabet*{\mathsf}{\sfdefault}{m}{n}\fi
%\fi
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\MacrocodeTopsep}
% \begin{macro}{\MacroIndent}
%    In the code above, we have used two registers. Therefore we have
%    to allocate them. The default values might be overwritten with
%    the help of the |\DocstyleParms| macro.
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
% \changes{v1.5y}{1990/02/24}{Default changed.}
% \changes{v1.6b}{1990/06/15}{\cs{rm} moved before \cs{scriptsize} to
%                           avoid unnecessary fontwarning.}
%    \begin{macrocode}
\newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt
\newdimen\MacroIndent    
\settowidth\MacroIndent{\rmfamily\scriptsize 00\ }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
%
% \begin{macro}{\macrocode*}
% \begin{macro}{\endmacrocode*}
%    Just as in the \textsf{verbatim} environment, there is also a
%    `star' variant of the \textsf{macrocode} environment in which a
%    space is shown by the symbol \verb*+ +.  Until this moment, I
%    have not yet used it (it will be used in the description of the
%    definition of |\xmacro@code| below) but it's exactly on this one
%    occasion {\em here\/} that you can't use it (cf.\ M\"unchhausens
%    Marsh problem)\footnote{Karl Friedrich Hieronymus Frhr.\ v.\
%    M\"unchhausen (*1720, \dag1797).  Several books were written
%    about fantastic adventures supposedly told by him (see
%    \cite{book:Raspe} or \cite{book:Buerger}). In one story he
%    escaped from the marsh by pulling himself out by his hair.}
%    directly. Because of this, on this one occasion we'll cheat
%    around the problem with an additional comment character.  But now
%    back to |\macrocode*|. We start with the macro |\macro@code|
%    which prepares everything and then call the macro |\sxmacro@code|
%    whose argument is terminated by the string 
%\verb*+%    \end{macrocode*}+.
%    \begin{macrocode}
\@namedef{macrocode*}{\macro@code\sxmacro@code}
%    \end{macrocode}
%    As we know, |\sxmacro@code| and then |\end{macrocode*}|
%    (the macro, not the string), will be executed, so that for a
%    happy ending we still need to define the macro
%    |\endmacrocode*|.
%    \begin{macrocode}
\expandafter\let\csname endmacrocode*\endcsname = \endmacrocode
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
%
%
%
%
% \begin{macro}{\xmacro@code}
\catcode`\!=\catcode`\%   ^^A In this section there must not be
                              ^^A any exclamation marks.
                              ^^A
%    As already mentioned, the macro |\xmacro@code| expects an
%    argument delimited by the string \verb*+%    \end{macrocode}+.  At
%    the moment that this macro is called, the |\catcode| of
%    \TeX's special characters are 12 (`other') or 13 (`active').
%    Because of this we need to utilize a different escape character
%    during the definition.  This happens locally.
%    \begin{macrocode*}
\begingroup
\catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@
%    \end{macrocode*}
%    Additionally, we need to ensure that the symbols in the above
%    string contain the |\catcode|$\,$s which are available
%    within the \textsf{macrocode} environment.
%    \begin{macrocode*}
\catcode`\{=12 \catcode`\}=12
\catcode`\%=12 \catcode`\ =\active \catcode`\\=\active
!%    \end{macrocode*}
!    Next follows the actual definition of  |\macro@code|;
!    notice the
!    use of the new escape character.  We manage to get the argument
!    surrounded by the string |\end{macrocode}|, but at the end
!    however, in spite of the actual characters used during the
!    definition of
!    this macro, |\end| with the argument |{macrocode}|
!    will be executed, to ensure a balanced environment.
!    \begin{macrocode*}
|gdef|xmacro@code#1%    \end{macrocode}[#1|end[macrocode]]
!%    \end{macrocode*}
! \begin{macro}{\sxmacro@code}
!    The definition of |\sxmacro@code| is completely analogous,
!    only
!    here a slightly different terminating string will be used.
!    Note that the space is not active in this environment.
!    \begin{macrocode}
|catcode`| =12
|gdef|sxmacro@code#1%    \end{macrocode*}[#1|end[macrocode*]]
!%    \end{macrocode}
!    because the |\catcode| changes have been made local by
!    commencing a
!    new group, there now follows the matching |\endgroup|
!    in a rather
!    unusual style of writing.
!    \begin{macrocode}
|endgroup
!%    \end{macrocode}
\catcode`\!=12
% \end{macro}
% \end{macro}
%
%
%
%
% \subsection{Macros for the `documentation parts'}
%
%
% \begin{macro}{\DescribeMacro}
% \begin{macro}{\Describe@Macro}
% \changes{v1.5v}{1990/01/28}{Macro added.}
% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary
%                             fix}
% \begin{macro}{\DescribeEnv}
% \begin{macro}{\Describe@Env}
% \changes{v1.5v}{1990/01/28}{Macro added.}
% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary
%                             fix}
%    The |\DescribeMacro| and |\DescribeEnv| macros should
%    print their arguments in the margin and produce an index entry.
%    We simply use |\marginpar| to get the desired result. This
%    is however not the best solution because the labels might be
%    slightly misplaced. One also might get a lot of `marginpar moved'
%    messages which are hard-wired into the \LaTeX{} output
%    routine.\footnote{It might be better to change these macros into
%    environments like the \textsf{macro} environment.} First we change
%    to horizontal mode if necessary. The \LaTeX{} macros
%    |\@bsphack| and |\@esphack| are used to make those
%    commands invisible (i.e.\ to normalize the surrounding space and
%    to make the |\spacefactor| transparent).
% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.}
%    \begin{macrocode}
\def\DescribeMacro{\leavevmode\@bsphack
%    \end{macrocode}
%    When documenting the code for the \texttt{amstex.sty} option we
%    encountered a bug: the |\catcode| of |@| was active and
%    therefore couldn't be used in command names. So we first have to
%    make sure that we get all |\catcode|s right by calling
%    |\MakePrivateLetters| inside a group. Then we call
%    |\Describe@Macro| to do the work.
% \changes{v2.0g}{1999/03/22}{Parse backslash as letter in argument
%        to \cs{DescribeMacro}.}
% \changes{v2.0h}{1999/03/25}{Correct errors introduced in v2.0g.}
%    \begin{macrocode}
   \begingroup\MakePrivateLetters\Describe@Macro}
\def\Describe@Macro#1{\endgroup
              \marginpar{\raggedleft\PrintDescribeMacro{#1}}%
%    \end{macrocode}
%    Note the use of |\raggedleft| to place the output flushed
%    right. Finally we call a macro which produces the actual index
%    entry and finish with |\@esphack| to leave no
%    trace.\footnote{The whole mechanism won't work because
%                    of the \texttt{\bslash leavevmode} in front.
%                    As a temporary change \texttt{\bslash ignorespaces}
%                    is added.}
%    \begin{macrocode}
              \SpecialUsageIndex{#1}\@esphack\ignorespaces}
%    \end{macrocode}
%    The |\DescribeEnv| macro is completely analogous.
% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.}
%    \begin{macrocode}
\def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters
  \Describe@Env}
\def\Describe@Env#1{\endgroup
              \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
              \SpecialEnvIndex{#1}\@esphack\ignorespaces}
%    \end{macrocode}
%    To put the labels in the left margin we have to use the
%    |\reversemarginpar| declaration. (This means that the
%    \texttt{doc.sty} can't be used with all classes or packages.) 
%    We also
%    make the |\marginparpush| zero and |\marginparwidth| suitably
%    wide.
% \changes{v1.5d}{1989/4/28}{\cs{marginparwidth} setting added.}
%    \begin{macrocode}
\reversemarginpar
\setlength\marginparpush{0pt}  \setlength\marginparwidth{8pc}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\bslash}
% \changes{v1.7a}{1992/02/26}{Moved \cs{bslash} documentation to `user
%                           interface' part}
%    We start a new group in which to hide the alteration of
%    |\catcode|$\,$s, and make \verb+|+ introduce commands,
%    whilst |\| becomes an `other' character.
%
%    \begin{macrocode}
{\catcode`\|=\z@ \catcode`\\=12
%    \end{macrocode}
%    Now we are able to define |\bslash| (globally) to generate a
%    backslash of |\catcode| `other'.  We then close this group,
%    restoring original |\catcode|$\,$s.
%    \SpecialEscapechar{\|}
%    \begin{macrocode}
|gdef|bslash{\}}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\verbatim}
% \begin{macro}{\verbatim*}
% \changes{v1.7i}{1992/07/12}{Added changed definition for verbatim!*.}
%    The \textsf{verbatim} environment holds no secrets; it consists of
%    the normal \LaTeX{} environment.  We also set the
%    |\@beginparpenalty| and change to the font given by
%    |\MacroFont|.
%    \begin{macrocode}
\def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim
              \MacroFont \frenchspacing \@vobeyspaces \@xverbatim}
%    \end{macrocode}
%    We deal in a similar way with the star form of this environment.
%    \begin{macrocode}
\@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim
              \MacroFont \@sxverbatim}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@verbatim}
%    Additionally we redefine the |\@verbatim| macro so that it
%    suppresses |%| characters at the beginning of the line.  The
%    first lines are copied literally from \texttt{latex.tex}.
% \changes{v1.7i}{1992/07/12}{Added \cs{@@par} to clear possible
%                             \cs{parshape}.}
%    \begin{macrocode}
\def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi
      \leftskip\@totalleftmargin\rightskip\z@
      \parindent\z@\parfillskip\@flushglue\parskip\z@
      \@@par
      \@tempswafalse
%    \end{macrocode}
%    |\@verbatim| sets |^^M|, the end of line character, to
%    be equal to |\par|.  This control sequence is redefined
%    here; |\@@par| is the paragraph primitive of \TeX.
%    \changes{v1.7c}{1992/3/24}{Added \cs{interlinepenalty} to
%                             \cs{par} from verbatim.sty}
%    \begin{macrocode}
 \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par
          \penalty\interlinepenalty
%    \end{macrocode}
%    We add a control sequence |\check@percent| to the definition
%    of |\par| whose task it is to check for a percent character.
%    \begin{macrocode}
   \check@percent}%
%    \end{macrocode}
%    The rest is again copied literally from \texttt{latex.tex} (less
%    "\tt").
% \changes{v1.7a}{1992/02/26}{Removed redundant \cs{tt}.}
% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
%                           which handles more ligatures.}
%    \begin{macrocode}
 \obeylines
 \let\do\do@noligs \verbatim@nolig@list
 \let\do\@makeother \dospecials}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\check@percent}
%    Finally we define |\check@percent|.  Since this must compare a
%    character with a percent sign we must first (locally) change
%    percent's |\catcode| so that it is seen by \TeX.  The definition
%    itself is nearly trivial: grab the following character, check if
%    it is a |%|, and insert it again if not.  At the end of the
%    \textsf{verbatim} environment this macro will peek at the next
%    input line. In that case the argument to |\check@percent| might
%    be a |\par| or a macro with arguments. Therefore we make the
%    definition |\long| (|\par| allowed) and use the normal |\next|
%    mechanism to reinsert the argument after the |\fi| if necessary.
%  \changes{v1.5i}{1989/06/07}{Definition changed to `long'}
%  \changes{v1.5i}{1989/06/07}{Macro \cs{next} used to guard against
%                            macro with arguments}
%    There is a subtle problem here, the equal sign between
%    |\next| and |#1| is actually necessary. Do you see why?
%    The omission of this token once caused a funny error.
%  \changes{v1.5u}{1989/11/14}{equal sign added.}
%    \begin{macrocode}
{\catcode`\%=12 
 \long\gdef\check@percent#1{\ifx #1%\let\next\@empty \else
                                    \let\next=#1\fi \next}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\verb}
% \changes{v1.7a}{1992/02/27}{Now warns about newlines (from
%                           newdoc with `@noligs added).}
% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX \cs{verb}}
% We re-define "\verb" to check for newlines in its argument since a
% missing delimiter is difficult to detect in \DOC{} source.
% The code is the saem as in latex.tex of September 19, 1993.
% Perhaps there should be a font-changing
% hook rather than just using "\tt", but if so it probably should be
% different from "\MacroFont" since that normally includes "\small"
% and would look wrong inline.
% \changes{v1.7a}{1992/02/28}{Added math mode check (from verbatim.sty)}
%    \begin{macrocode}
\def\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
  \bgroup \let\do\do@noligs \verbatim@nolig@list
    \ttfamily \verb@eol@error \let\do\@makeother \dospecials
    \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\verb@balance@group}
% \begin{macro}{\verb@egroup}
% \begin{macro}{\verb@eol@error}
% \changes{v1.8b}{1993/09/21}{Renamed \cs{verb@err} to
%                   \cs{verb@eol@error}, as in new LaTeX verbatim.}
%    \begin{macrocode}
\let\verb@balance@group\@empty

\def\verb@egroup{\global\let\verb@balance@group\@empty\egroup}

\begingroup
  \obeylines%
  \gdef\verb@eol@error{\obeylines%
    \def^^M{\verb@egroup\@latex@error{%
           Text for \noexpand\verb command ended by end of line}\@ehc}}%
\endgroup
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@sverb}
% \changes{v1.7a}{1992/02/27}{Added for \cs{verb} change.}
% \changes{v1.7a}{1992/02/28}{Now same as in verbatim.sty.}
% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
%                           which has better error trapping.}
% See \cite{art:verbatim} for commentary.
%    \begin{macrocode}
\def\@sverb#1{%
  \catcode`#1\active  \lccode`\~`#1%
  \gdef\verb@balance@group{\verb@egroup
     \@latex@error{Illegal use of \noexpand\verb command}\@ehc}%
  \aftergroup\verb@balance@group
  \lowercase{\let~\verb@egroup}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\verbatim@nolig@list}
% \begin{macro}{\do@noligs}
%     These macros replace the old "\@noligs" mechanism by an
%     extensible version to allow more ligatures to be added.
%    \begin{macrocode}
\def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-}
\def\do@noligs#1{%
  \catcode`#1\active
  \begingroup
     \lccode`\~=`#1\relax
     \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1}}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\macro}
% \begin{macro}{\m@cro@}
% \changes{v1.5v}{1990/01/28}{\cs{macro@} renamed to \cs{m@cro@}
%                  since AmSTeX
%      defines another macro of the same name.}
% \begin{macro}{\macro@cnt}
%    \label{page:macro} The \textsf{macro} environment is implemented as
%    a \textsf{trivlist} environment, whereby in order that the macro
%    names can be placed under one another in the margin
%    (corresponding to the macro's nesting depth), the macro
%    |\makelabel| must be altered.  In order to store the nesting
%    depth, we use a counter. We also need a counter to count the
%    number of nested \textsf{macro} environments.
% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
% \changes{v1.9k}{1994/02/22}{Fix probably no longer necessary} 
%    \begin{macrocode}
\newcount\macro@cnt \macro@cnt=0
%    \end{macrocode}
%    The environment takes an argument---the macro name to be
%    described.  Since this name may contain special `letters' we have
%    to re-|\catcode| them before scanning the argument. This is done
%    by the |\MakePrivateLetters| macro. 
% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
% \changes{v1.7a}{1992/02/26}{Catcode backslash to other (from newdoc).}
% \changes{v1.9k}{1994/02/22}{Don't omit extra group} 
%    \begin{macrocode}
\def\macro{\begingroup
   \catcode`\\12
   \MakePrivateLetters \m@cro@ \iftrue}
%    \end{macrocode}
%
% \begin{macro}{\environment}
% \changes{v1.8c}{1993/10/25}{Environment added}
%    The ``environment'' envrionment will be implemented just like the
%    ``macro'' environment flagging any differences in the code by
%    passing |\iffalse| or |\iftrue| to the |\m@cro@| environment
%    doing the actual work.
%    \begin{macrocode}
\def\environment{\begingroup
   \catcode`\\12
   \MakePrivateLetters \m@cro@ \iffalse}
%    \end{macrocode}
% \end{macro}
%
%    After scanning the argument we close the group to get the normal
%    |\catcode|$\,$s back. Then we assign a special value to
%    |\topsep| and start a \textsf{trivlist} environment.
% \changes{v1.5f}{1989/5/07}{MacroTopsep parameter added.}
% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
% \changes{v1.8c}{1993/10/25}{Support ``environment'' env}
% \changes{v1.9k}{1994/02/22}{Remove \cs{macro@level}} 
%    \begin{macrocode}
\long\def\m@cro@#1#2{\endgroup \topsep\MacroTopsep \trivlist
%    \end{macrocode}
% We also save the name being described in |\saved@macroname| for
% use in conjunction with the |\changes| macro.
%    \begin{macrocode}
   \edef\saved@macroname{\string#2}%
%    \end{macrocode}
%    Now there follows a variation of |\makelabel| which is used
%    should the environment not be nested, or should it lie between
%    two successive |\begin{macro}| instructions or explanatory
%    text.  One can recognize this with the switch |\if@inlabel|
%    which will be |true| in the case of successive |\item|
%    commands.
%    \begin{macrocode}
  \def\makelabel##1{\llap{##1}}%
%    \end{macrocode}
%    If |@inlabel| is |true| and if $\verb=\macro@cnt= > 0$
%    then the above definition needs to be changed, because in this
%    case \LaTeX{} would otherwise put the labels all on the same line
%    and this would lead to them being overprinted on top of each
%    other.  Because of this |\makelabel| needs to be redefined
%    in this case.
%    \begin{macrocode}
  \if@inlabel
%    \end{macrocode}
%    If |\macro@cnt| has the value $1$, then we redefine
%    |\makelabel| so that the label will be positioned in the
%    second line of the margin.  As a result of this, two macro names
%    appear correctly, one under the other.  It's important whilst
%    doing this that the generated label box is not allowed to have
%    more depth than a normal line since otherwise the distance
%    between the first two text lines of \TeX{} will be incorrectly
%    calculated. The definition should then look like:
%\begin{verbatim}
%     \def\makelabel##1{\llap{\vtop to \baselineskip
%          {\hbox{\strut}\hbox{##1}\vss}}}
%\end{verbatim}
%    Completely analogous to this is the case where labels need to be
%    placed one under the other.  The lines above are only an example
%    typeset with the \textsf{verbatim} environment. To produce the real
%    definition we save the value of |\macro@cnt| in
%    |\count@| and empty the temp macro |\@tempa| for later
%    use.
%    \begin{macrocode}
    \let\@tempa\@empty \count@\macro@cnt
%    \end{macrocode}
%    In the following loop we append for every already typeset label
%    an |\hbox{\strut}| to the definition of |\@tempa|.
%    \begin{macrocode}
    \loop \ifnum\count@>\z@
      \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat
%    \end{macrocode}
%    Now be put the definition of |\makelabel| together.
% \changes{v1.5b}{1989/04/27}{vbox to vtop changed in makelabel (test)}
% \changes{v1.5e}{1989/04/28}{ht strutbox changed to baselineskip
%                             (test)}
%    \begin{macrocode}
    \edef\makelabel##1{\llap{\vtop to\baselineskip
                               {\@tempa\hbox{##1}\vss}}}%
%    \end{macrocode}
%    Next we increment the value of the nesting depth counter.  This
%    value inside the \textsf{macro} environment is always at least one
%    after this point, but its toplevel definition is zero. Provided
%    this environment has been used correctly, $|\macro@cnt|=0$
%    should not occur when |@inlabel|=\textsf{true}.  It is
%    however possible if this environment is used within other list
%    environments (but this would have little point).
%    \begin{macrocode}
    \advance \macro@cnt \@ne
%    \end{macrocode}
%    If |@inlabel| is false we reset |\macro@cnt| assuming
%    that there is enough room to print the macro name without
%    shifting.
%    \begin{macrocode}
  \else  \macro@cnt\@ne  \fi
%    \end{macrocode}
%    Now the label will be produced using |\item|. The following
%    line is only a hack saving the day until a better solution is
%    implemented.  We have to face two problems: the argument might be
%    a |\par| which is forbidden in the argument of other macros
%    if they are not defined as |\long|, or it is something like
%    |\iffalse| or |\else|, i.e.\ something which will be
%    misinterpreted when \TeX{} is skipping conditional text. In both
%    cases |\item| will bomb, so we protect the argument by using
%    |\string|.
%    \begin{macrocode}
  \edef\@tempa{\noexpand\item[%
%    \end{macrocode}
%    Depending on whether we are inside a ``macro'' or ``environment''
%    environment we use |\PrintMacroName| or |\PrintEnvName| to
%    display the name.
%    \begin{macrocode}
     #1%
       \noexpand\PrintMacroName
     \else
       \noexpand\PrintEnvName
     \fi
     {\string#2}]}%
  \@tempa
%    \end{macrocode}
%    At this point we also produce an index entry.  Because it is not
%    known which index sorting program will be used, we do not use the
%    command |\index|, but rather a command
%    |\SpecialMainIndex| after advancing the counter for indexing
%    by line number.  This may be redefined by the user in
%    order to generate an index entry which will be understood by the
%    index program in use (note the definition of
%    |\SpecialMainIndex| for our installation).
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
% \changes{v1.9u}{1995/08/06}{Removed brace group which 
%           killed \cs{DoNotIndex}}
%    We advance the current codeline number and after producing an
%    index entry revert to the original value
%    \begin{macrocode}
  \global\advance\c@CodelineNo\@ne
%    \end{macrocode}
%    Again the macro to call depends on the environment we are
%    actually in.
%    \begin{macrocode}
   #1%
      \SpecialMainIndex{#2}\nobreak
      \DoNotIndex{#2}%
   \else
      \SpecialMainEnvIndex{#2}\nobreak
   \fi
  \global\advance\c@CodelineNo\m@ne
%    \end{macrocode}
%    The |\nobreak| is needed to prevent a page break after the
%    |\write| produced by the |\SpecialMainIndex| macro.  We
%    exclude the new macro in the cross-referencing feature, to
%    prevent spurious non-main entry references.  Regarding possibly
%    problematic arguments, the implementation takes
%    care of |\par| and the conditionals are uncritical.
%  \changes{v1.7a}{1992/03/02}{Removed redundant code checking for
%                             \cs{par}.}^^A
%
%    Because the space symbol should be ignored between the
%    |\begin{macro}{...}| and the following text we must take
%    care of this with |\ignorespaces|.
%    \begin{macrocode}
  \ignorespaces}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
%
% \begin{macro}{\endmacro}
% \begin{macro}{\endenvironment}
%     Older releases of this environment omit the |\endgroup| token,
%     when being nested. This was done to avoid unnessary stack usage.
%     However it does not work if \textsf{macro} and
%     \textsf{environment} environments are mixed, therefore we now
%     use a simpler approach.
% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
% \changes{v1.9k}{1994/02/22}{Don't checkfor nesting} 
%    \begin{macrocode}
\let\endmacro \endtrivlist
\let\endenvironment\endmacro
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
% \begin{macro}{\MacroTopsep}
%    Here is the default value for the |\MacroTopsep| parameter
%    used above.
%    \begin{macrocode}
\newskip\MacroTopsep     \MacroTopsep = 7pt plus 2pt minus 2pt
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
% \subsection{Formatting the margin}
%
% The following three macros should be user definable.
% Therefore we define those macros only if they have not already
% been defined.
%
% \begin{macro}{\PrintMacroName}
% \begin{macro}{\PrintEnvName}
% \begin{macro}{\PrintDescribeMacro}
% \begin{macro}{\PrintDescribeEnv}
%    The formatting of the macro name in the left margin is done by
%    these macros. We first set a |\strut| to get the height and
%    depth of the normal lines. Then we change to the
%    |\MacroFont| using |\string| to |\catcode| the
%    argument to other (assuming that it is a macro name). Finally we
%    print a space.  The font change remains local since this macro
%    will be called inside an |\hbox|.
%    \begin{macrocode}
\@ifundefined{PrintMacroName}
   {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{}
%    \end{macrocode}
%    We use the same formatting conventions when describing a macro.
%    \begin{macrocode}
\@ifundefined{PrintDescribeMacro}
   {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{}
%    \end{macrocode}
%    To format the name of a new environment there is no need to use
%    |\string|.
%    \begin{macrocode}
\@ifundefined{PrintDescribeEnv}
   {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{}
\@ifundefined{PrintEnvName}
   {\def\PrintEnvName#1{\strut \MacroFont #1\ }}{}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
%
% \subsection{Creating index entries by scanning `macrocode'}
%
%  The following macros ensure that index entries are created for each
%  occurrence of a \TeX-like command (something starting with
%  `|\|') providing indexing has been turned on with "\PageIndex"
%  or "\CodelineIndex".  With the default definitions of
%  |\SpecialMainIndex|, etc., the index file generated is
%  intended to be processed by Chen's \textsf{makeindex} program
%  \cite{art:Chen}.
%
%
%  Of course, in {\em this\/} package file itself we've sometimes had to
%  make \verb+|+ take the r\^ole of \TeX's escape character to
%  introduce command names at places where |\| has to belong to
%  some other category.  Therefore, we may also need to recognize
%  \verb+|+ as the introducer for a command when setting the text
%  inside the \textsf{macrocode} environment.  Other users may have the
%  need to make similar reassignments for their macros.
%
%
% \begin{macro}{\SpecialEscapechar}\label{sect:specialescapechar}
% \begin{macro}{\active@escape@char}
% \begin{macro}{\special@escape@char}
%    The macro |\SpecialEscapechar| is used to denote a special escape
%    character for the next \textsf{macrocode} environment. It has one
%    argument---the new escape character given as a `single-letter'
%    control sequence.  Its main purpose is defining
%    |\special@escape@char| to produce the chosen escape character
%    |\catcode|$\,$d to 12 and |\active@escape@char| to produce the
%    same character but with |\catcode| 13.
%
%    The macro |\special@escape@char| is used to {\em print\/}
%    the escape character while |\active@escape@char| is needed
%    in the definition of |\init@crossref| to start the scanning
%    mechanism.
%
%    In the definition of |\SpecialEscapechar| we need an
%    arbitrary character with |\catcode| 13. We use `\~{}' and
%    ensure that it is active. The |\begingroup| is used to make
%    a possible change local to the expansion of
%    |\SpecialEscapechar|.
% \changes{v1.7g}{1992/6/19}{Making tilde active moved outside
%    definition}
%    \begin{macrocode}
\begingroup
\catcode`\~\active
\gdef\SpecialEscapechar#1{%
    \begingroup
%    \end{macrocode}
%    Now we are ready for the definition of
%    |\active@escape@char|.  It's a little tricky: we first
%    define locally the uppercase code of `\~{}' to be the new escape
%    character.
%    \begin{macrocode}
     \uccode`\~`#1%
%    \end{macrocode}
%    Around the definition of |\active@escape@char| we place an
%    |\uppercase| command. Recall that the expansion of
%    |\uppercase| changes characters according to their
%    |\uccode|, but leaves their |\catcode|$\,$s untouched
%    (cf.\ \TeX{}book page 41).
%    \begin{macrocode}
     \uppercase{\gdef\active@escape@char{~}}%
%    \end{macrocode}
%    The definition of |\special@escape@char| is easier, we use
%    |\string| to |\catcode| the argument of
%    |\SpecialEscapechar| to 12 and suppress the preceding
%    |\escapechar|.
%    \begin{macrocode}
     \escapechar\m@ne  \xdef\special@escape@char{\string#1}%
%    \end{macrocode}
%    Now we close the group and end the definition: the value of
%    |\escapechar| as well as the |\uccode| and
%    |\catcode| of `\~{}' will be restored.
%    \begin{macrocode}
   \endgroup}
\endgroup
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
%
%
% \begin{macro}{\init@crossref}
%    The replacement text of |\init@crossref| should fulfill the
%    following tasks:
%    \begin{itemize}
%       \parindent4em
%       \item[1)]
%          |\catcode| all characters used in macro names to
%          11 (i.e.\ `letter').
%       \item[2)]
%          |\catcode| the `|\|' character to 13
%          (i.e.\ `active').
%       \item[3a)]
%          |\let| the `|\|' equal |\scan@macro|
%          (i.e.\ start the macro scanning mechanism) if there is
%          no  special escape character (i.e.\ the
%          |\special@escape@char| is `|\|').
%       \item[3b)]
%          Otherwise |\let| it equal |\bslash|, i.e.\
%          produce a printable |\|.
%       \item[4)]
%          Make the \meta{special escape character} active.
%       \item[5)]
%          |\let| the active version of the special escape
%          character
%          (i.e.\ the expansion of |\active@escape@char|) equal
%          |\scan@macro|.
%    \end{itemize}
%    The reader might ask why we bother to |\catcode| the
%    `|\|' first to 12 (at the end of |\macro@code|) then
%    re-|\catcode| it to 13 in order to produce a $|\|_{12}$
%    in case 3b) above.  This is done because we have to ensure that
%    `|\|' has |\catcode| 13 within the \textsf{macrocode}
%    environment.  Otherwise the delimiter for the argument of
%    |\xmacro@code| would not be found (parameter matching
%    depends on |\catcode|$\,$s).
%
%    Therefore we first re-|\catcode| some characters.
%    \begin{macrocode}
\begingroup   \catcode`\|=\z@  \catcode`\\=\active
%    \end{macrocode}
%    We carry out tasks 2) and 3b) first.
%    \SpecialEscapechar{\|}
%    \begin{macrocode}
|gdef|init@crossref{|catcode`|\|active   |let\|bslash
%    \end{macrocode}
%    Because of the popularity of the `|@|' character as a
%    `letter' in macros, we normally have to change its
%    |\catcode| here, and thus fulfill task 1).  But the macro
%    designer might use other characters as private letters as well,
%    so we use a macro to do the |\catcode| switching.
%    \SpecialEscapechar\|
%    \begin{macrocode}
    |MakePrivateLetters
%    \end{macrocode}
%    Now we |\catcode| the special escape character to 13 and
%    |\let| it equal |\scan@macro|, i.e.\ fulfill tasks 4)
%    and 5). Note the use of |\expandafter| to insert the chosen
%    escape character saved in |\special@escape@char| and
%    |\active@escape@char|.
%    \SpecialEscapechar\|
%    \begin{macrocode}
    |catcode|expandafter`|special@escape@char|active
    |expandafter|let|active@escape@char|scan@macro}
|endgroup
%    \end{macrocode}
%    If there is no special escape character, i.e.\ if
%    |\SpecialEscapechar| is |\\|, the second last line will
%    overwrite the previous definition of $|\|_{13}$.  In this
%    way all tasks are fulfilled.
%
%    For happy documenting we give default values to
%    |\special@escape@char| and |\active@escape@char| with
%    the following line:
%    \begin{macrocode}
\SpecialEscapechar{\\}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\MakePrivateLetters}
%    Here is the default definition of this command, which makes just
%    the |@| into a letter. The user may change it if he/she
%    needs more or other characters masquerading as letters.
%    \begin{macrocode}
\@ifundefined{MakePrivateLetters}
    {\let\MakePrivateLetters\makeatletter}{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\close@crossref}
%    At the end of a cross-referencing part we prepare ourselves for
%    the next one by setting the escape character to `|\|'.
%    \begin{macrocode}
\def\close@crossref{\SpecialEscapechar\\}
%    \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{Macros for scanning macro names}
%
% \begin{macro}{\scan@macro}
% \changes{v1.5k}{1989/09/04}{Support for checksum added.}
% \begin{macro}{\macro@namepart}
%    The |\init@crossref| will have made |\active| our
%    |\special@escape@char|, so that each
%    |\active@escape@char| will invoke |\scan@macro| when
%    within the \textsf{macrocode} environment.  By this means, we can
%    automatically add index entries for every \TeX-like command which
%    is met whilst setting (in verbatim) the contents of
%    \textsf{macrocode} environments.
%    \begin{macrocode}
\def\scan@macro{%
%    \end{macrocode}
%    First we output the character which triggered this macro.  Its
%    version |\catcode|$\,$d to 12 is saved in
%    |\special@escape@char|. We also call |\step@checksum|
%    to generate later on a proper check-sum (see section
%    \ref{sec:checksum} for details).
%    \begin{macrocode}
   \special@escape@char
   \step@checksum
%    \end{macrocode}
%    If the \textsf{macrocode} environment contains, for example, the
%    command |\\|, the second |\| should not start the
%    scanning mechanism. Therefore we use a switch to decide if
%    scanning of macro names is allowed.
%    \begin{macrocode}
   \ifscan@allowed
%    \end{macrocode}
%    The macro assembles the letters forming a \TeX\ command in
%    |\macro@namepart| so this is initially cleared; we then set
%    |\next| to the \textit{first\/} character following the
%    |\| and call |\macro@switch| to determine whether that
%    character is a letter or not.
%    \begin{macrocode}
      \let\macro@namepart\@empty
      \def\next{\futurelet\next\macro@switch}%
%    \end{macrocode}
%    As you recognize, we actually did something else, because we have
%    to defer the |\futurelet| call until after the final
%    |\fi|.  If, on the other hand, the scanning is disabled we
%    simply |\let| |\next| equal `empty'.
%    \begin{macrocode}
   \else \let\next\@empty \fi
%    \end{macrocode}
%    Now we invoke |\next| to carry out what's needed.
%    \begin{macrocode}
   \next}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\ifscan@allowed}
% \begin{macro}{\scan@allowedtrue}
% \begin{macro}{\scan@allowedfalse}
%    |\ifscan@allowed| is the switch used above to determine if
%    the |\active@escape@char|\SpecialIndex{\active@escape@char}
%    should start the macro scanning mechanism.
%    \begin{macrocode}
\newif\ifscan@allowed    \scan@allowedtrue
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\EnableCrossrefs}
% \begin{macro}{\DisableCrossrefs}
%    At this point we might define two macros which allow the user to
%    disable or enable the cross-referencing mechanism. Processing of
%    files will be faster if only main index entries are generated
%    (i.e., if |\DisableCrossrefs| is in force).
%    \begin{macrocode}
\def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack}
%    \end{macrocode}
%    The macro |\EnableCrossrefs| will also disable any
%    |\DisableCrossrefs| command encountered afterwards.
%    \begin{macrocode}
\def\EnableCrossrefs{\@bsphack\scan@allowedtrue
                     \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
%
% \begin{macro}{\macro@switch}
%    Now that we have the character which follows the escape character
%    (in |\next|), we can determine whether it's a `letter'
%    (which probably includes |@|).
%
%    If it is, we let |\next| invoke a macro which assembles the
%    full command name.
%    \begin{macrocode}
\def\macro@switch{\ifcat\noexpand\next a%
     \let\next\macro@name
%    \end{macrocode}
%    Otherwise, we have a `single-character' command name.  For all
%    those single-character names, we use |\short@macro| to
%    process them into suitable index entries.
%    \begin{macrocode}
     \else \let\next\short@macro  \fi
%    \end{macrocode}
%    Now that we know what macro to use to process the macro name, we
%    invoke it~\ldots
%    \begin{macrocode}
   \next}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\short@macro}
% \changes{v1.5c}{1989/4/27}{Corrected bad bug by putting the
%                         scan@allowedfalse macro before printing
%                         the argument.}
% \changes{v1.7a}{1992/03/10}{Ensure character stored in
%           \cs{macro@namepart} as `letter' so index exclusion works.}
%    This macro will be invoked (with a single character as parameter)
%    when a single-character macro name has been spotted whilst
%    scanning within the \textsf{macrocode} environment.
%
%    First we take a look at the |\index@excludelist| to see
%    whether this macro name should produce an index entry.  This is
%    done by the |\ifnot@excluded| macro which assumes that the
%    macro name is saved in |\macro@namepart|.  The character
%    mustn't be stored with a special category code or exclusion from
%    the index won't work, so we employ the case-changing trick used
%    elsewhere.  Since the argument might be an active character,
%    |\string| is used to normalize it. 
% \changes{v2.0e}{1998/12/28}{Correctly use the case-changing trick.} 
%    \begin{macrocode}
\begingroup
\catcode`\&=12
\gdef\short@macro#1{\begingroup
   \uccode`\&=\expandafter`\string#1%
   \uppercase{\def\x{\def\macro@namepart{&}}}%
   \expandafter\endgroup\x
   \ifnot@excluded
%    \end{macrocode}
%    If necessary the index entry is produced by the macro
%    |\produce@index|. Depending on the actual character seen,
%    this macro has to do different things, so we pass the character
%    as an argument.
%    \begin{macrocode}
     \produce@index{#1}\fi
%    \end{macrocode}
%    Then we disable the cross-referencing mechanism with
%    |\scan@allowedfalse| and print the actual character. The
%    index entry was generated first to ensure that no page break
%    intervenes (recall that a |^^M| will start a new line).
%    \begin{macrocode}
    \scan@allowedfalse#1%
%    \end{macrocode}
%    After typesetting the character we can safely enable the
%    cross-referencing feature again. Note that this macro won't be
%    called (since |\macro@switch| won't be called) if
%    cross-referencing is globally disabled.
%    \begin{macrocode}
    \scan@allowedtrue }
\endgroup
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\produce@index}
% \changes{v1.4s}{1989/04/23}{Added noexpand to all
%                           \cs{if} tests
%               to avoid garbage produced by new active chars}
% \changes{v1.4s}{1989/04/23}{Used \texttt{\protect\bslash string} for
%                          the same reason.}
% \changes{v1.5c}{1989/4/27}{Corrected bad bug by placing the
%                         scan@allowedfalse macro into short@macro}
%    This macro is supposed to generate a suitable |\SortIndex|
%    command for a given single-letter control sequence.  We test
%    first for the cases which involve active characters (i.e.\ the
%    backslash, the special escape character (if any), the space and
%    the |^^M|).  Using the |\if| test (testing for
%    character codes), we have to ensure that the argument isn't
%    expanded.
%    \begin{macrocode}
\def\produce@index#1{%
  \if\noexpand#1\special@escape@char
%    \end{macrocode}
%    If the character is the special escape character (or the
%    `|\|' in case there was none) the |\it@is@a| macro is
%    used to produce the actual |\SortIndex| call.
%    \begin{macrocode}
     \scan@allowedfalse \it@is@a\special@escape@char \else
%    \end{macrocode}
%    Next comes the test for a `|\|' which must be the
%    $|\|_{13}$ expanding to |\bslash|.
%    \begin{macrocode}
     \if\noexpand#1\bslash \it@is@a\bslash \else
%    \end{macrocode}
%    Another possibility is \verb*+ +$_{13}$. Recall that |\space|
%    produces a \verb*+ +$_{10}$.
%    \begin{macrocode}
       \if\noexpand#1\space \it@is@a\space \else
%    \end{macrocode}
%    The last\footnote{Well, it isn't the last active character after
%    all. I added \texttt{\bslash @noligs} some days ago and now
%    \texttt{`} too is active. So we have to make sure that such
%    characters don't get expanded in the index.} possibility of an
%    active character is |^^M|\@.  In this case we don't test for
%    character codes, since it is easier to look if the character is
%    equal to |\par|. (We are inside the \textsf{macrocode}
%    environment.)
%    \begin{macrocode}
         \ifx#1\par
%    \end{macrocode}
%    If we end up here we have just scanned a |\^^M| or something
%    similar. Since this will be treated like \verb*+\ + by \TeX{} we
%    produce a corresponding index entry.
%    \begin{macrocode}
         \it@is@a\space \else
%    \end{macrocode}
%    If it is the token |\relax| we do nothing. This can't happen
%    when the `doc' package is used in the way described here, but was
%    added to allow extensions like the \texttt{idxverb} option.
%  \changes{v1.5t}{1989/11/14}{Added \cs{relax} as a possible token to
%                           allow extensions.}
%    \begin{macrocode}
         \ifx#1\relax \else
%    \end{macrocode}
%    The next three branches are needed because of bugs in
%    our \textsf{makeindex} program. You can't produce unbalanced index
%    entries\footnote{This is possible for \TeX{} if you use
%                     \texttt{\string{$_{12}$ \rmfamily or 
%                     \ttfamily\string}$_{12}$},
%                     but \textsf{makeindex} will complain.}
%    and you have to double a percent character. To get around these
%    restrictions we use special macros to produce the |\index|
%    calls.\footnote{Brian \textsc{Hamilton Kelly} has written fixes for
%                  all three
%                  bugs. When they've found their way through all
%                    installations,
%                    the lines above will be removed. See 
%                    page~\pageref{bug:fixes} if you already have them.
%                    (I'm not sure which versions incorporate these, but
%                    2.11 is OK.  See also
%                    \pageref{makeindex:version}.)}
%    \begin{macrocode}
           \if\noexpand#1\bgroup \LeftBraceIndex \else
             \if\noexpand#1\egroup \RightBraceIndex \else
               \if\noexpand#1\percentchar \PercentIndex \else
%    \end{macrocode}
%    All remaining characters are used directly to produce their index
%    entries. This is possible even for the characters which have
%    special meanings in the index program, provided we quote the
%    characters.  (This is correctly done in |\it@is@a|.)
%    \begin{macrocode}
                 \it@is@a{\string#1}%
%    \end{macrocode}
%    We now need a whole pile of |\fi|$\,$s to match up with
%    the |\if|$\,$s.
%    \begin{macrocode}
       \fi \fi \fi \fi \fi \fi \fi \fi}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\macro@name}
%    We now come to the macro which assembles command names which
%    consist of one or more `letters' (which might well include
%    |@| symbols, or anything else which has a |\catcode| of
%    11).
%
%    To do this we add the `letter' to the existing definition of
%    |\macro@namepart| (which you will recall was originally set
%    to |\@empty|).
%    \begin{macrocode}
\def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}%
%    \end{macrocode}
%    Then we grab hold of the {\em next\/} single character and let
%    |\more@macroname| determine whether it belongs to the letter
%    string forming the command name or is a `non-letter'.
%    \begin{macrocode}
     \futurelet\next\more@macroname}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
% \begin{macro}{\more@macroname}
%
%    This causes another call of |\macro@name| to add in the next
%    character, if it is indeed a `letter'.
%    \begin{macrocode}
\def\more@macroname{\ifcat\noexpand\next a%
     \let\next\macro@name
%    \end{macrocode}
%    Otherwise, it finishes off the index entry by invoking
%    |\macro@finish|.
%    \begin{macrocode}
     \else \let\next\macro@finish \fi
%    \end{macrocode}
%    Here's where we invoke whatever macro was |\let| equal to
%    |\next|.
%    \begin{macrocode}
     \next}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
% \begin{macro}{\macro@finish}
%    When we've assembled the full `letter'-string which forms the
%    command name, we set the characters forming the entire command
%    name, and generate an appropriate |\index| command (provided
%    the command name is not on the list of exclusions).  The
%    `|\|' is already typeset; therefore we only have to output
%    all `letters' saved in |\macro@namepart|.
%    \begin{macrocode}
\def\macro@finish{%
  \macro@namepart
%    \end{macrocode}
%    Then we call |\ifnot@excluded| to decide whether we have to
%    produce an index entry. The construction with |\@tempa| is
%    needed because we want the expansion of |\macro@namepart| in
%    the |\index| command.\footnote{The \texttt{\bslash index}
%    command will expand its argument in the \texttt{\bslash output}
%    routine.  At this time \texttt{\bslash macro@namepart} might have a
%    new value.}
%    \begin{macrocode}
  \ifnot@excluded
     \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
     \@tempa  \fi}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
% \subsection[The index exclude list]{The index exclude
%             list\footnotemark}
%            \footnotetext{Warning: the incomplete commentary on
%            \texttt{\bslash DoNotIndex} and the macros it calls
%                          was written by Dave Love.}
%
%    The internal form of the index exclude list is
% \begin{quote}
% \meta{macro name}|,|\meta{macro name}|,|
% \ldots|,|
% \end{quote}
% where \meta{macro name} is a macro name like
% $"\"_{12}"p"{_{11}}"@"_{11}$ or $"\"_{12}"$"_{11}$.  Note that the "\"
% has category `other' and the other characters in the name are all
% `letter', regardless of their normal category. 
%
% \begin{macro}{\DoNotIndex}
%    This macro is used to suppress macro names in the index.  It
%    starts off with a new group because we have to change the
%    |\catcode|$\,$s of all characters which belong to `letters'
%    while macros are defined.
%    \begin{macrocode}
\def\DoNotIndex{\begingroup \MakePrivateLetters
    \catcode`\\12
%    \end{macrocode}
%    Then we call the macro which actually reads the argument given by
%    the user.
%    \begin{macrocode}
    \do@not@index}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\do@not@index}
%    We make the |\do@not@index| macro |\long|
%    since the user might want to exclude the |\par| 
%    macro.
%    \begin{macrocode}
\long\def\do@not@index#1{%
%    \end{macrocode}
%    It just adds to a token list after finishing the group in which
%    the catcodes were changed.
%    \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.}
%    \begin{macrocode}
    \endgroup
    \addto@hook\index@excludelist{#1,}}    
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\addto@hook}
% The code for adding tokens (the second argument) to a token list
% (the first argument) is taken from~\cite{art:verbatim}, but it needs
% to be "\long" in case "\par" is amongst the tokens.
%    \begin{macrocode}
\long\def\addto@hook#1#2{#1\expandafter{\the#1#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\index@excludelist}
% We need an initially-empty register for the excluded list.
%    \begin{macrocode}
\newtoks\index@excludelist
\index@excludelist{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ifnot@excluded}
%    \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.}
% \begin{macro}{\expanded@notin}
%    Now we take a look at the |\index@excludelist| to see
%    whether a macro name saved in |\macro@namepart| should
%    produce an index entry. This macro is a pseudo |\if|; it
%    should expand to |\iftrue| or |\iffalse| depending on
%    the contents of |\index@excludelist|.
%    \begin{macrocode}
\begingroup
%    \end{macrocode}
%    First we change "\catcode"s so that "\" is `other' and "|" a
%    temporary for the escape character. This is necessary since our
%    macro names are stored that way in the "\index@excludelist".
%    \begin{macrocode}
\catcode`\|=0%
\catcode`\\=12
%    \end{macrocode}
%    Then we define "\ifnot@excluded" to call "\expanded@notin" with
%    two arguments: the first is the string "\" followed by the
%    contents of "\macro@namepart" followed by a "," and the second is
%    "\the" followed by "\index@excludelist". To achieve the expansion
%    of "\macro@namepart", i.e.\ to pass its contents, we need a
%    suitable number of "\expandafter"s.
%    \SpecialEscapechar{\|}
%    \begin{macrocode}
|gdef|ifnot@excluded{|expandafter
     |expanded@notin|expandafter{|expandafter
     \|macro@namepart,}{|the|index@excludelist}}
|endgroup
%    \end{macrocode}
%    The macro "\expanded@notin" now does the dirty work. It first
%    defines a macro "\in@@" with a very special parameter text. If
%    you look closely "\in@@" has three arguments, the first one is
%    delimited by the first argument of "\expanded@notin" (i.e.\ by
%    the string starting with a "\" and ending with a "," above), the
%    second is undelimited (which means that it will get the next
%    token after our string, and the third is delimited again and will
%    get the rest up to the token "\in@@". In other words the token
%    "\in@@" is also used as a delimiter.
%    \begin{macrocode}
\def\expanded@notin#1#2{%
 \def\in@@##1#1##2##3\in@@{%
%    \end{macrocode}
%    Now the replacement text simply compares the second argument
%    (i.e.\ the undelimited one after our string) to the token
%    "\expanded@notin". This is an unclosed "\ifx" statement which
%    means that this macro behaves similar to a normal \TeX{}
%    conditional.
%    \begin{macrocode}
  \ifx\expanded@notin##2}%
%    \end{macrocode}
%    After all these preparations we call "\in@@". First we expand the
%    token after "\in@@" (which is "\the" from the second argument to
%    "\expanded@notin"). As a result we get the contents of the
%    "\index@excludelist" inserted after "\in@@". After this contents
%    we add once more the string we are looking for, then the token
%    "\expanded@notin" and finally the token "\in@@".
%    \begin{macrocode}
 \expandafter\in@@#2#1\expanded@notin\in@@}
%    \end{macrocode}
%    Now what happens when the macro "\in@@" above gets called? The
%    first argument to "\in@@" is delimited by our string. In other
%    words it will get everything from the contents of
%    "\index@excludelist" before this string. If the string is not in
%    "\index@excludelist" then it gets the whole contents, since after
%    it we had inserted the string one more. In this case the next
%    token is "\expanded@notin" which gets assigned to the second
%    argument and the third argument will be empty. If, on the other
%    hand, the string was inside "\index@excludelist" then the second
%    argument will not be the token "\expanded@notin" and the third
%    argument will be all the garbage up to "\in@@". Therefore testing
%    the se