trunk/Master/texmf-dist/source/latex/base

git-svn-id: svn://tug.org/texlive/trunk@151 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 4894 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/base/doc.dtx b/Master/texmf-dist/source/latex/base/doc.dtx
new file mode 100644
index 00000000000..cb658e0c800
--- /dev/null
+++ b/Master/texmf-dist/source/latex/base/doc.dtx
@@ -0,0 +1,4894 @@
+% \iffalse meta-comment
+%
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004
+% 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.3
+% 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.3 or later is part of all distributions of LaTeX 
+% version 2003/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>  [2004/02/09 v2.1b
+%<+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.}
+%
+% \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 encloses the
+% \meta{date} in parentheses and appends the \meta{text} to form 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.  When
+% referring to macros in change descriptions it is conventional to use
+% "`"\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 seconded argument, as done in the definition of "\in@@" will
+%    tell us  whether or not the string is in "\index@includelist" and
+%    this was exactly what we wanted. (Deep breath.) You got
+%    that?\footnote{\TeX{}book page 125. The code described above is
+%    originally due to Michael Spivak who used a similar method within
+%    the \AmSTeX{} macros.}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+%
+%
+%
+% \subsection{Macros for generating index entries}
+%
+% Here we provide default definitions for the macros invoked to create
+% index entries; these are either invoked explicitly, or automatically
+% by |\scan@macro|.  As already mentioned, the definitions given
+% here presuppose that the |.idx| file will be processed by
+% Chen's \textsf{makeindex} program --- they may be redefined for use
+% with the user's favourite such program.
+%
+% To assist the reader in locating items in the index, all such
+% entries are sorted alphabetically {\em ignoring\/} the initial
+% `|\|'; this is achieved by issuing an |\index| command which
+% contains the `actual' operator for \textsf{makeindex}.  The default
+% value for the latter operator is `|@|', but the latter character is
+% so popular in \LaTeX\ package files that it is necessary to substitute
+% another character.  This is indicated to \textsf{makeindex} by means
+% of an `index style file'; the character selected for this function
+% is |=|, and therefore this character too must be specially treated
+% when it is met in a \TeX\ command.  A suitable index style file is
+% provided amongst the supporting files for this style file in
+% \texttt{gind.ist} and is generated from this source by processing
+% with \texttt{docstrip} to extract the module \textbf{gind}.  A
+% similar style file \texttt{gglo.ist} is supplied for sorting the
+% change information in the glossary file and is extracted as module
+% \textbf{gglo}.  First of all we add some information to the front of
+% the \texttt{.ist} files.  \changes{v1.7a}{1992/03/11}{glo.ist and
+% gind.ist now derivable from doc.dtx with docstrip.}
+%    \begin{macrocode}
+%</package>
+%<+gind|gglo>%% This is a MAKEINDEX style file which should be used to
+%<+gind>%% generate the formatted index for use with the doc
+%<+gglo>%% generate the formatted change history for use with the doc
+%<+gind|gglo>%% package. The TeX commands used below are defined in
+%<+gind|gglo>%% doc.sty.  The commands for MAKEINDEX like `level'
+%<+gind|gglo>%% `item_x1' are described in `` Makeindex, A General
+%<+gind|gglo>%% Purpose, Formatter-Independent Index Processor'' by
+%<+gind|gglo>%% Pehong Chen. 
+%<+gind|gglo>
+%    \end{macrocode}
+%
+% \begin{macro}{\actualchar}
+% \begin{macro}{\quotechar}
+% \begin{macro}{\levelchar}
+%    First come the definitions of |\actualchar|,
+%    |\quotechar| and |\levelchar|. Note, that our defaults
+%    are not the ones used by the \textsf{makeindex} program without a
+%    style file.
+%    \begin{macrocode}
+%<*package>
+\@ifundefined{actualchar}{\def\actualchar{=}}{}
+\@ifundefined{quotechar}{\def\quotechar{!}}{}
+\@ifundefined{levelchar}{\def\levelchar{>}}{}
+%</package>
+%<+gind|gglo>actual '='
+%<+gind|gglo>quote '!'
+%<+gind|gglo>level '>'
+%<*package>
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\encapchar}
+%    The \textsf{makeindex} default for the |\encapchar| isn't
+%    changed.
+%    \begin{macrocode}
+\@ifundefined{encapchar}{\def\encapchar{|}}{}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\verbatimchar}
+%    We also need a special character to be used as a delimiter for
+%    the |\verb*| command used in the definitions below.
+%    \begin{macrocode}
+\@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\SpecialIndex}
+%    The |\SpecialIndex| command creates index entries for
+%    macros.  If the argument is |\|$xyz$, the command produces
+%    \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}|
+%    given the above defined defaults for |\actualchar|,
+%    |\quotechar| and |\verbatimchar|.  We first remove the
+%    initial `|\|' to get a better index.
+% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
+%    \begin{macrocode}
+\def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble
+                                      \string#1\actualchar
+%    \end{macrocode}
+%    Then follows the actual entry. A |\quotechar| is placed
+%    before the |*| to allow its use as a special \textsf{makeindex}
+%    character.  Again |\@bsphack| and |\@esphack| are used
+%    to make the macros invisible.
+%    \begin{macrocode}
+      \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}%
+    \@esphack}
+%    \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\SpecialMainIndex}
+% \begin{macro}{\SpecialMainEnvIndex}
+% \begin{macro}{\SpecialUsageIndex}
+%    The |\SpecialMainIndex| macro is used to cross-reference the
+%    names introduced by the \textsf{macro} environment.  The action is
+%    as for |\SpecialIndex|, except that \textsf{makeindex} is
+%    instructed to `encap'sulate the entry with the string
+%    \verb=|main= to cause it to generate a call of the |\main|
+%    macro.
+% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
+% \changes{v2.0c}{1998/08/22}{Correctly handle single character
+%                   control sequences like \cs{<}.}
+%
+%    |\SpecialMainIndex| passes the macro name to be indexed on to the
+%    macro |\SpecialIndex@|.
+%    \begin{macrocode}
+\def\SpecialMainIndex#1{\@bsphack\SpecialIndex@{#1}{\encapchar main}%
+                        \@esphack}
+%    \end{macrocode}
+%
+% \begin{macro}{\SpecialIndex@}
+% \changes{v2.0c}{1998/08/22}{Macro added.}
+% \changes{v2.0f}{1999/02/27}{Temp fix to allow strange code in arg 1 
+%                             (PR 2968)}
+%    The macro |\SpecialIndex@| does the real work for |\SpecialMainIndex|
+%    and |\SpecialUsageIndex|. It takes two arguments: the macro to be
+%    indexed (as a control sequence or list of character tokens) and the
+%    additional text for the index.
+% \changes{v2.0g}{1999/03/22}{Correct so-called temp fix. I'm not going to
+%                   explain this.}
+%    \begin{macrocode}
+\begingroup       
+ \catcode`\|=0                                                         
+ \catcode`\\=12                                                        
+ |gdef|@SpecialIndexHelper@#1#2|@nil{% 
+   |if |noexpand#1\%                                           
+     |gdef|@gtempa{#2}%                                         
+   |else                                                       
+     |begingroup                                               
+       |escapechar|m@ne                                        
+       |expandafter|gdef|expandafter|@gtempa|expandafter{|string#1#2}%
+     |endgroup                                                 
+   |fi}                                                        
+|endgroup                                                      
+\def\SpecialIndex@#1#2{%
+%    \end{macrocode}
+%    The first thing it does is to convert the macro into a list of
+%    characters. Note that a character token list remains (mostly) unchanged.
+%    \begin{macrocode}
+   \@SpecialIndexHelper@#1\@nil
+%    \end{macrocode}
+%    The macro name \verb*|\ | has to handled in a special way. The reason
+%    is that the space token is skipped when \TeX\ is scanning macro
+%    parameters, so that the trick used below will not work.
+%    So, we check whether the replacement text of |\@tempa| starts with
+%    a space token and write the appropriate index entry.
+%    \begin{macrocode}
+   \def\@tempb{ }%
+   \ifcat \@tempb\@gtempa
+      \special@index{\quotechar\space\actualchar
+                     \string\verb\quotechar*\verbatimchar
+                     \quotechar\bslash\quotechar\space\verbatimchar#2}%
+   \else
+%    \end{macrocode}
+%    Having handled this special case we have to distinguish control
+%    sequences consisting of one or more
+%    letters and those that consists of exactly one nonletter. As character
+%    tokens in the replacement text of the macro |\@gtempa| have all
+%    category code $12$ (other), this is difficult. For simplicity, we treat
+%    all single character control sequences alike, irregardless of whether
+%    the character is a letter or not. This has the advantage that it works
+%    even for strange settings of the category codes.
+%
+%    We define a utility macro |\@tempb| with two arguments, the second
+%    delimited by |\relax|.
+%    It will be called later so that the first argument is the first character
+%    of the macro name, and the second argument receives the rest of the
+%    characters. So we distinguish the two cases above by checking whether
+%    the second argument is empty.
+%    \begin{macrocode}
+     \def\@tempb##1##2\relax{\ifx\relax##2\relax
+%    \end{macrocode}
+%    If so, we define the helper macro |\@tempc| in a way that it
+%    adds quotechars in critical places.
+%    \begin{macrocode}
+          \def\@tempc{\special@index{\quotechar##1\actualchar
+                      \string\verb\quotechar*\verbatimchar
+                      \quotechar\bslash\quotechar##1\verbatimchar#2}}%
+%    \end{macrocode}
+%    Otherwise we write the characters as in |\SpecialIndex|.
+%    \begin{macrocode}
+        \else
+          \def\@tempc{\special@index{##1##2\actualchar
+                       \string\verb\quotechar*\verbatimchar
+                       \bslash##1##2\verbatimchar#2}}%
+        \fi}%
+%    \end{macrocode}
+%    Now pass the list of characters to \@tempb and call \@tempc to do the
+%    work.
+%    \begin{macrocode}
+     \expandafter\@tempb\@gtempa\relax
+     \@tempc
+   \fi}
+%    \end{macrocode}
+% \end{macro}
+%
+%    Slightly simpler is the main entry for environments
+% \changes{v1.9e}{1994/02/03}{use \cs{ttfamily} with \cs{string}}
+% \changes{v1.9f}{1994/02/07}{should have used \cs{noexpand}, sigh}
+% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}}
+% \changes{v1.9j}{1994/02/16}{Back to string:-)}
+% \changes{v1.9s}{1994/10/14}{Added missing percent and changed to
+%                             \cs{ttfamily}}
+% \changes{v2.0d}{1998/12/20}{Correctly handle second index entry
+%    by using \cs{special@index} not \cs{index} (PR/2928).}
+% \changes{v2.0e}{1998/12/28}{Use \cs{string}, not \cs{protect} in argument to
+%             \cs{special@index}.}
+% \changes{v2.1b}{2004/02/09}{environment names incorrectly sorted in
+%           index (pr/3615)}
+%    \begin{macrocode}
+\def\SpecialMainEnvIndex#1{\@bsphack\special@index{%
+                                      #1\actualchar
+                                      {\string\ttfamily\space#1} 
+                                         (environment)%
+                                      \encapchar main}%
+    \special@index{environments:\levelchar#1\actualchar{%
+                   \string\ttfamily\space#1}\encapchar 
+           main}\@esphack}
+%    \end{macrocode}
+%    The |\SpecialUsageIndex| is similar to |\SpecialMainIndex|, except
+%    that it uses the standard |\index| command.
+%    \texttt{usage} instead of \texttt{main}.
+%    \begin{macrocode}
+\def\SpecialUsageIndex#1{\@bsphack
+   {\let\special@index\index\SpecialIndex@{#1}{\encapchar usage}}%
+   \@esphack}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+% \begin{macro}{\SpecialEnvIndex}
+%    Indexing environments is done a little bit differently; we produce
+%    two index entries with the |\SpecialEnvIndex| macro:
+% \changes{v1.9e}{1994/02/03}{The index needs protecting}
+% \changes{v1.9g}{1994/02/08}{should have used \cs{noexpand}, sigh}
+% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}}
+%    \begin{macrocode}
+\def\SpecialEnvIndex#1{\@bsphack
+%    \end{macrocode}
+%    First we sort the environment under its own name stating in the
+%    actual entry that this is an environment.
+%    \begin{macrocode}
+    \index{#1\actualchar{\protect\ttfamily#1} 
+           (environment)\encapchar usage}%
+%    \end{macrocode}
+%    The second entry is sorted as a subitem under the key
+%    `environments:'. 
+% \changes{v2.1b}{2004/02/09}{environment names incorrectly sorted in
+%           index (pr/3615)}
+%    \begin{macrocode}
+    \index{environments:#1\actualchar\levelchar{\protect\ttfamily#1}\encapchar 
+           usage}\@esphack}
+%    \end{macrocode}
+%    Because both entries correspond to `descriptions' of the
+%    environment, we encapsulate the page numbers with the
+%    |\usage| macro.
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\SortIndex}
+%    This macro is used to generate the index entries for any
+%    single-character command that |\scan@macro| encounters.  The
+%    first parameter specifies the lexical order for the character,
+%    whilst the second gives the actual characters to be printed in
+%    the entry. It can also be used directly to generate index entries
+%    which differ in sort key and actual entry.
+%    \begin{macrocode}
+\def\SortIndex#1#2{\index{#1\actualchar#2}}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\it@is@a}
+%    This macro is supposed to produce a correct |\SortIndex|
+%    entry for a given character. Since this character might be
+%    recognised as a `command' character by the index program used,
+%    all characters are quoted with the |\quotechar|.
+% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
+%    \begin{macrocode}
+\def\it@is@a#1{\special@index{\quotechar #1\actualchar
+                          \string\verb\quotechar*\verbatimchar
+                          \quotechar\bslash\quotechar#1\verbatimchar}}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\LeftBraceIndex}
+% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
+% \begin{macro}{\RightBraceIndex}
+% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} These
+%    two macros fix the problems with \textsf{makeindex}.  Note the
+%    `hack' with |\iffalse}\fi| to satisfy both \TeX{} and the
+%    \textsf{makeindex} program. When this is written to the
+%    \texttt{.idx} file \TeX{} will see both braces (so we get a
+%    balanced text).  \textsf{makeindex} will also see balanced braces
+%    but when the actual index entry is again processed by \TeX{} the
+%    brace in between |\iffalse| |\fi| will vanish.
+%    \begin{macrocode}
+\@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{%
+   \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar
+          \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{}
+
+\@ifundefined{RightBraceIndex}{\def\RightBraceIndex{%
+ \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb
+           \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\PercentIndex}
+% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
+% \changes{v1.7c}{1992/03/25}{Default now for bug-fixed makeindex}
+% By default we assume a version of \textsf{makeindex} without the
+% percent bug is being used.
+%    \begin{macrocode}
+\@ifundefined{PercentIndex}
+  {\def\PercentIndex{\it@is@a\percentchar}}{}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\OldMakeindex}
+% \changes{v1.7c}{1992/03/26}{Replaced \cs{NewMakeIndex}.}
+% \begin{macro}{\percentchar}
+%    Here is one solution for the percent bug in \textsf{makeindex}.
+%    The macro |\percentchar| denotes a |%|$_{12}$.  Calling this from
+%    a package or the driver file sets things up
+%    appropriately.\label{bug:fixes}
+%    \begin{macrocode}
+\def\OldMakeindex{\def\PercentIndex{%
+    \special@index{\quotechar\percentchar\actualchar\string\verb
+           \quotechar*\verbatimchar\quotechar\bslash
+           \percentchar\percentchar\verbatimchar}}}
+{\catcode`\%=12 \gdef\percentchar{%}}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+%
+%
+% \subsection{Redefining the \textsf{index} environment}
+%
+%\changes{v1.4r}{1989/04/22}{twocols env. placed into separate file}
+%\changes{v1.4?}{1989/04/19}{use DEK's algorithm and implement
+%                         a twocols env.}
+%\changes{v1.4?}{1989/04/16}{changes to the index env.}
+%\changes{v1.5a}{1989/04/26}{Now input multicol.sty instead of
+%                         multcols.sty}
+% \begin{macro}{\ifhave@multicol}
+% \changes{v1.7a}{1992/03/04}{Added to support avoiding multicol.sty} By
+%    default the index is set in three columns, and will start on the
+%    same page as, and underneath, the last part of the text of the
+%    documented package file, if possible.  The last page will be
+%    reformatted with balanced columns.  This requires the
+%    \textsf{multicols} environment which is described elsewhere.  So
+%    that \DOC{} can be run independently of
+%    \texttt{multicol.sty} we first check for its existence and set
+%    the "have@multicol" flag appropriately for use below.
+%  \changes{v1.9a}{1993/12/02}{Use \cs{IfFileExists}}
+%  \changes{v1.9m}{1994/04/28}{Use \cs{RequirePackage} to load multicol}
+%    \begin{macrocode}
+\newif\ifhave@multicol
+%    \end{macrocode}
+%    If we found \texttt{multicol.sty} we use it.  It would be nice to
+%    delay this (and the re-definition of "theindex") until we knew
+%    whether an index was actually required \ldots
+%    \begin{macrocode}
+\IfFileExists{multicol.sty}{\have@multicoltrue
+                            \RequirePackage{multicol}%
+                           }{}
+%    \end{macrocode}
+% \end{macro}
+
+%
+% \begin{macro}{\IndexMin}
+% \begin{macro}{\c@IndexColumns}
+%    \changes{v1.4t}{1989/04/24}{Counter added.}
+%    If \texttt{multicol} is in use,
+%    when the index is started we compute the remaining space on the
+%    current page; if it is greater than |\IndexMin|, the first
+%    part of the index will then be placed in the available space.
+%    The number of columns set is controlled by the counter
+%    |\c@IndexColumns| which can be changed with a
+%    |\setcounter| declaration.
+%    \begin{macrocode}
+\newdimen\IndexMin         \IndexMin       = 80pt
+\newcount\c@IndexColumns   \c@IndexColumns = 3
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\theindex}
+%    Now we start the multi-column mechanism, if appropriate. We use the
+%    \LaTeX{} counter |\c@IndexColumns|  declared above to denote
+%    the number of columns and insert the `index prologue' text (which
+%    might contain a |\section| call, etc.). See the default
+%    definition for an example.
+%    \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.}
+%    \changes{v1.5a}{1989/04/26}{Call multicols first}
+%    \changes{v1.6e}{1991/04/03}{Turned into env definition.}
+%    \changes{v1.7a}{1992/03/04}{Include test for multicols.}
+%    \begin{macrocode}
+\ifhave@multicol
+  \renewenvironment{theindex}
+    {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]%
+%    \end{macrocode}
+%    Then we make a few last minute assignments to read the individual
+%    index |\item|$\,$s and finish off by ignoring any initial
+%    space.
+%    \begin{macrocode}
+      \IndexParms \let\item\@idxitem \ignorespaces}%
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\endtheindex}
+%    \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.}
+%    At the end of the index, we have only to end the \textsf{multicols}
+%    environment.
+%    \begin{macrocode}
+    {\end{multicols}}
+%    \end{macrocode}
+%    If we can't use \textsf{multicols} we warn the user and use an
+%    environment that's basically the one from \texttt{article.sty}.
+%    \begin{macrocode}
+\else
+  \typeout{Can't find multicol.sty -- will use normal index layout if
+     necessary.}
+  \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi
+    \columnseprule \z@  \columnsep 35\p@
+    \twocolumn[\index@prologue]%
+    \IndexParms \let\item\@idxitem \ignorespaces}
+  \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi}
+\fi
+%    \end{macrocode}
+% \end{macro}
+% Here are the necessary \textsf{makeindex} declarations. We disable
+% scanning of macro names inside the index with "\scan@allowedfalse\n"
+% to avoid recursion.
+%    \begin{macrocode}
+%</package>
+%<+gind>preamble
+%<+gind>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
+%<+gind>postamble
+%<+gind>"\n\n \\end{theindex}\n"
+%<*package>
+%    \end{macrocode}
+%
+%
+% \begin{macro}{\IndexPrologue}
+% \begin{macro}{\index@prologue}
+% \changes{v1.9w}{1995/12/27}{Text changed}
+% \changes{v1.9x}{1996/01/11}{Text depends on code lines used}
+%    The |\IndexPrologue| macro is used to place a short message
+%    into the document above the index.  It is implemented by
+%    redefining |\index@prologue|, a macro which holds the
+%    default text.  We'd better make it a |\long| macro to allow
+%    |\par| commands in its argument.
+%    \begin{macrocode}
+\long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack}
+%    \end{macrocode}
+%    Now we test whether the default is already defined by another
+%    package file. If not we define it.
+% \changes{v2.0j}{2000/05/22}{Less obscure wording? (CAR pr/3202)}
+%    \begin{macrocode}
+\@ifundefined{index@prologue}
+     {\def\index@prologue{\section*{Index}%
+                 \markboth{Index}{Index}%
+                 Numbers written in italic refer to the page 
+                 where the corresponding entry is described;
+                 numbers underlined refer to the 
+                 \ifcodeline@index
+                   code line of the
+                 \fi
+                 definition; numbers in roman refer to the 
+                 \ifcodeline@index
+                   code lines
+                 \else
+                   pages
+                 \fi
+                 where the entry is used.
+                 }}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\IndexParms}
+%    These are some last-minute assignments for formatting the index
+%    entries. They are defined in a separate macro so that a user can
+%    substitute different definitions.  We start by defining the
+%    various parameters controlling leading and the separation between
+%    the two columns.  The entire index is set in |\small| size.
+%    \begin{macrocode}
+\@ifundefined{IndexParms}
+    {\def\IndexParms{%
+       \parindent \z@
+       \columnsep 15pt
+       \parskip 0pt plus 1pt
+       \rightskip 15pt
+       \mathsurround \z@
+       \parfillskip=-15pt
+        \small
+%    \end{macrocode}
+% \begin{macro}{\@idxitem}
+% \begin{macro}{\subitem}
+% \begin{macro}{\subsubitem}
+%    Index items are formatted with hanging indentation for any items
+%    which may require more than one line.
+%    \begin{macrocode}
+       \def\@idxitem{\par\hangindent 30pt}%
+%    \end{macrocode}
+%    Any sub-item in the index is formatted with a 15pt indentation
+%    under its main heading.
+%    \begin{macrocode}
+       \def\subitem{\@idxitem\hspace*{15pt}}%
+%    \end{macrocode}
+%    Whilst sub-sub-items go in a further 10pt.
+%    \begin{macrocode}
+       \def\subsubitem{\@idxitem\hspace*{25pt}}%
+%    \end{macrocode}
+% \begin{macro}{\indexspace}
+%    The \textsf{makeindex} program generates an |\indexspace|
+%    before each new alphabetic section commences. After this final
+%    definition we end the |\@ifundefined| and the definition of
+%    |\IndexParms|.
+%    \begin{macrocode}
+       \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}%
+      }}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\efill}
+%    This definition of |\efill| is intended to be used after index
+%    items which have no following text (for example, ``\textit{
+%    see\/}'' entries).  It just ensures that the current line is
+%    filled, preventing ``|Underfull \hbox|'' messages.
+%    \begin{macrocode}
+\def\efill{\hfill\nopagebreak}%
+%</package>
+%<+gind|gglo>item_x1   "\\efill \n \\subitem "
+%<+gglo>item_x2   "\\ "
+%<+gind>item_x2   "\\efill \n \\subsubitem "
+%<*package>
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\pfill}
+% \begin{macro}{\dotfil}
+% \begin{macro}{\dotfill}
+%     The following definitions provide the |\pfill| command; if
+%    this is specified in the index style file to \textsf{makeindex} as
+%    the delimiter to appear after index items, then the intervening
+%    space before the referenced page numbers will be filled with
+%    dots, with a little white space interpolated at each end of the
+%    dots.  If the line is broken the dots will show up on both lines.
+%    \begin{macrocode}
+\def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus  1fill}%
+\def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil}%
+\def\pfill{\unskip~\dotfill\penalty500\strut\nobreak
+               \dotfil~\ignorespaces}%
+%</package>
+%<+gind|gglo>delim_0   "\\pfill "
+%<+gind|gglo>delim_1   "\\pfill "
+%<+gind|gglo>delim_2   "\\pfill "
+%<*package>
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\*}
+%    Here is the definition for the |\*| macro. It isn't used in
+%    this set of macros.
+%    \begin{macrocode}
+\def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\main}
+%    The \textit{defining\/} entry for a macro name is flagged with
+%    the string \texttt{\encapchar main}\footnote{With the current
+%    definition of \texttt{\bslash encapchar} substituted for
+%    \texttt{\encapchar}} in the |\index| command; \textsf{makeindex}
+%    processes this so that the |\main| macro will be invoked to
+%    underline the page number(s) on which the {\em definition\/} of
+%    the macro will be found.
+%    \begin{macrocode}
+\@ifundefined{main}{\def\main#1{\underline{#1}}}{}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\usage}
+%    The |\usage| macro is used to indicate entries describing
+%    the usage of a macro. The corresponding page number(s) will be
+%    set in \textit{italics}.
+%    \begin{macrocode}
+\@ifundefined{usage}{\def\usage#1{\textit{#1}}}{}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\PrintIndex}
+% \changes{v1.5k}{1989/09/04}{\cs{printindex} changed to
+%                             \cs{PrintIndex}}
+% \changes{v1.7a}{1992/02/26}{Documentation moved to interface section.}
+% \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.}
+% \changes{v1.9w}{1995/12/29}{Turn the cmd into a noop after use.}
+%    This is the same as "\printindex" in the \textsf{makeidx} package.
+%    \begin{macrocode}
+\def\PrintIndex{\@input@{\jobname.ind}%
+                \global\let\PrintIndex\@empty}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\printindex}
+%    Since the above macro was called |\printindex| in older versions
+%    of \texttt{doc.sty} the following definition was provided up to
+%    version 1.9y.
+% \changes{v1.9z}{1996/04/17}{Commented out}
+%    \begin{macrocode}
+%\def\printindex{\typeout{\string\printindex\space is obsolete!}%
+%                \typeout{Please use \string\PrintIndex\space
+%                         if you are a macro implementor^^J
+%                         or get a newer version of the documented 
+%                         software if you are a user}%
+%                \PrintIndex}
+%    \end{macrocode}
+% \end{macro}
+%
+% We want headings in the index (and changes list) according to the
+% initial character of the next block of entries and have to instruct
+% \textsf{makeindex} appropriately.  Unfortunately the specification
+% for this changed sometime between versions 2.4 and 2.11 of
+% \textsf{makeindex}.  We provide both ways of doing it but
+% unfortunately this will always produce a warning message from
+% \textsf{makeindex}.  This is for older versions:
+% \changes{v1.7h}{1992/07/01}{Turn off headings in gls file}
+%    \begin{macrocode}
+%</package>
+%<+gind,gglo>% The next lines will produce some warnings when
+%<+gind,gglo>% running Makeindex as they try to cover two different
+%<+gind,gglo>% versions of the program:
+%<+gind,gglo>lethead_prefix   "{\\bfseries\\hfil "
+%<+gind,gglo>lethead_suffix   "\\hfil}\\nopagebreak\n"
+%<+gind>lethead_flag       1
+%<+gglo>lethead_flag       0
+%    \end{macrocode}
+% This works for newer ones:
+%    \begin{macrocode}
+%<+gind,gglo>heading_prefix   "{\\bfseries\\hfil "
+%<+gind,gglo>heading_suffix   "\\hfil}\\nopagebreak\n"
+%<+gind>headings_flag       1
+%<+gglo>headings_flag       0
+%<*package>
+%    \end{macrocode}
+%
+%
+%
+% \subsection[Dealing with the change history]
+%            {Dealing with the change history\footnotemark}
+% \footnotetext{The whole section was proposed by Brian \textsc{Hamilton
+%               Kelly}. He also documented and debugged the macros as
+%               well as many other parts of this package.}
+%
+% To provide a change history log, the |\changes| command has
+% been introduced.  This takes three arguments, respectively, the
+% version number of the file, the date of the change, and some detail
+% regarding what change has been made.  The first of these arguments
+% is otherwise ignored, but the others are written out and may be used
+% to generate a history of changes, to be printed at the end of the
+% document.  However, note that older versions of Chen's standard
+% \textsf{makeindex}
+% program limit any textual field to just 64 characters; therefore,
+% is important that the number of characters in the second and third
+% parameters should not exceed 61 altogether (to allow for the
+% parentheses placed around the date).
+%
+% \begin{macro}{\changes}
+% \changes{BHK}{1989/04/26}{Documented \texttt{\protect\bslash changes}
+%                         command.}
+% \changes{BHK}{1989/04/26}{Changed definition of
+%    \texttt{\protect\bslash protect}.} The output of the |\changes|
+%    command goes into the \meta{Glossary\_File} and therefore uses
+%    the normal |\glossaryentry| commands.\footnote{Note that a recent
+%    change in \LaTeX{} 2.09 changed the command name in the
+%    \texttt{.glo} file from \texttt{\bslash indexentry} to
+%    \texttt{\bslash glossaryentry}.  It is therefore necessary to
+%    have a special \textsf{makeindex} style file called
+%    \texttt{gglo.ist} to process this file correctly.} Thus
+%    \textsf{makeindex} or a similar program can be used to process
+%    the output into a sorted ``glossary''.  The |\changes| command
+%    commences by taking the usual measures to hide its spacing, and
+%    then redefines |\protect| for use within the argument of the
+%    generated |\indexentry| command.
+%
+%    We re-code nearly all chars found in |\sanitize| to letter
+%    since the use of special package which make some characters
+%    active might upset the |\changes| command when writing its
+%    entries to the file. However we have to leave |%| as comment
+%    and \verb*+ + as \meta{space} otherwise chaos will happen.
+%    And, of course the |\| should be available as escape
+%    character.
+% \changes{v1.5v}{1990/01/28}{`Re-code a lot of chars.}
+% \changes{v1.5m}{1989/09/20}{\cs{actualchar} in second level removed.}
+% \changes{v1.5o}{1989/09/24}{New sorting.}
+% \changes{v1.6c}{1990/06/29}{Again new sorting.}
+% \changes{v1.9u}{1995/08/06}{Use \cs{protected@edef}}
+%    \begin{macrocode}
+\def\changes{\@bsphack\begingroup\@sanitize
+   \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
+   \changes@}
+\def\changes@#1#2#3{%
+  \protected@edef\@tempa{\noexpand\glossary{#1\levelchar
+%    \end{macrocode}
+% \changes{v1.9u}{1995/08/06}{Use value of \cs{saved@macroname} to
+%          find out about change entries at outer level}
+%    If the macro "\saved@macroname" doesn't contain any macro name
+%    (ie is empty) the current changes entry was done at top-level.
+%    In this case we preceed it by "\generalname".
+%    \begin{macrocode}
+                                 \ifx\saved@macroname\@empty
+                                   \space
+                                   \actualchar
+                                   \generalname
+                                 \else
+                                   \expandafter\@gobble
+                                   \saved@macroname
+                                   \actualchar
+                                   \string\verb\quotechar*%
+                                   \verbatimchar\saved@macroname
+                                   \verbatimchar
+                                 \fi
+                                 :\levelchar #3}}%
+  \@tempa\endgroup\@esphack}
+%    \end{macrocode}
+%
+% \begin{macro}{\saved@macroname}
+% \changes{BHK}{1989/04/26}{Provided for sorting outside \textsf{macro}
+%    environment} The entries are sorted for convenience by the name
+%    of the most recently introduced macroname (i.e., that in the most
+%    recent |\begin{macro}| command).  We therefore provide
+%    |\saved@macroname| to record that argument, and provide a default
+%    definition in case |\changes| is used outside a \textsf{macro}
+%    environment.  (This is a {\em wicked\/} hack to get such entries
+%    at the beginning of the sorted list!  It works providing no macro
+%    names start with "!" or |"|.)  \changes{v1.7a}{1992/03/02}{Changed
+%    string used for better sorting.}
+% \changes{v1.9u}{1995/08/06}{Now empty by default}
+%    \begin{macrocode}
+\def\saved@macroname{}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\generalname}
+% \changes{v1.9u}{1995/08/06}{Macro added}
+%    This macro holds the string placed before changes entries on
+%    top-level.
+%    \begin{macrocode}
+\def\generalname{General}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\RecordChanges}
+% \changes{BHK}{1989/04/26}{Renames former \texttt{\protect\bslash
+%                         PrintChanges} command.}
+%    To cause the changes to be written (to a \texttt{.glo}) file, we
+%    define |\RecordChanges| to invoke \LaTeX's usual
+%    |\makeglossary| command.
+%    \begin{macrocode}
+\let\RecordChanges\makeglossary
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% 
+% \begin{macro}{\GlossaryMin}
+%    \changes{BHK}{1989/04/26}{Added to support
+%                            \texttt{\protect\bslash changes}.}
+% \begin{macro}{\c@GlossaryColumns}
+%    \changes{BHK}{1989/04/26}{Added to support \texttt{\protect\bslash
+%    changes}.} The remaining macros are all analogues of those used
+%    for the \textsf{theindex} environment.  When the glossary is
+%    started we compute the space which remains at the bottom of the
+%    current page; if this is greater than |\GlossaryMin| then the
+%    first part of the glossary will be placed in the available space.
+%    The number of columns set are controlled by the counter
+%    |\c@GlossaryColumns| which can be changed with a |\setcounter|
+%    declaration.
+%    \begin{macrocode}
+\newdimen\GlossaryMin         \GlossaryMin       = 80pt
+\newcount\c@GlossaryColumns   \c@GlossaryColumns = 2
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\theglossary}
+%  \changes{BHK}{1989/04/26}{Added to support
+%                            \texttt{\protect\bslash changes}.}
+% \changes{v1.5p}{1989/09/28}{Now call \cs{multicols} first.}
+%    \changes{v1.6e}{1991/04/03}{Turned into env definition.}
+%    \changes{v1.7a}{1992/03/10}{Changed to work without multicols if
+%                              necessary.}
+% \begin{macro}{\endglossary}
+%    \changes{BHK}{1989/04/26}{Added to support
+%                            \texttt{\protect\bslash changes}.}
+%    The environment \textsf{theglossary} is defined in the same manner
+%    as the \textsf{theindex} environment.
+%    \begin{macrocode}
+\ifhave@multicol
+  \newenvironment{theglossary}{%
+    \begin{multicols}\c@GlossaryColumns
+                     [\glossary@prologue][\GlossaryMin]%
+    \GlossaryParms \let\item\@idxitem \ignorespaces}%
+   {\end{multicols}}
+\else
+  \newenvironment{theglossary}{%
+      \@restonecoltrue\if@twocolumn\@restonecolfalse\fi
+      \columnseprule \z@  \columnsep 35\p@
+      \twocolumn[\glossary@prologue]%
+      \GlossaryParms \let\item\@idxitem \ignorespaces}
+    {\if@restonecol\onecolumn\else\clearpage\fi}
+\fi
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% Here are the necessary \textsf{makeindex} declarations with scanning
+% disabled as for the index.
+%    \begin{macrocode}
+%</package>
+%<+gglo>preamble
+%<+gglo>"\n \\begin{theglossary} \n
+%<+gglo>    \\makeatletter\\scan@allowedfalse\n"
+%<+gglo>postamble
+%<+gglo>"\n\n \\end{theglossary}\n"
+%    \end{macrocode}
+% This difference from \texttt{gind.ist} is necessary if you have an
+% up-to-date \LaTeX. 
+%    \begin{macrocode}
+%<+gglo>keyword "\\glossaryentry"
+%<*package>
+%    \end{macrocode}
+%
+%
+% \begin{macro}{\GlossaryPrologue}
+%    \changes{BHK}{1989/04/26}{Added to support
+%                            \texttt{\protect\bslash changes}.}
+% \begin{macro}{\glossary@prologue}
+%    \changes{BHK}{1989/04/26}{Added to support
+%                            \texttt{\protect\bslash changes}.}
+%    The |\GlossaryPrologue| macro is used to place a short
+%    message above the glossary into the document.  It is implemented
+%    by redefining |\glossary@prologue|, a macro which holds the
+%    default text.  We better make it a long macro to allow
+%    |\par| commands in its argument.
+%    \begin{macrocode}
+\long\def\GlossaryPrologue#1{\@bsphack
+                             \def\glossary@prologue{#1}%
+                             \@esphack}
+%    \end{macrocode}
+%    Now we test whether the default is already defined by another
+%    package file. If not we define it.
+%    \begin{macrocode}
+\@ifundefined{glossary@prologue}
+     {\def\glossary@prologue{\section*{{Change History}}%
+                 \markboth{{Change History}}{{Change History}}%
+                 }}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\GlossaryParms}
+%    \changes{BHK}{1989/04/26}{Added to support
+%                            \texttt{\protect\bslash changes}.}
+% Unless the user specifies otherwise, we set the change history
+% using the same parameters as for the index.
+%    \begin{macrocode}
+\@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms}{}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\PrintChanges}
+%    \changes{BHK}{1989/04/26}{Added to support
+%                            \texttt{\protect\bslash changes}.}
+%    To read in and print the sorted change history, 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.
+% \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.}
+% \changes{v1.9w}{1995/12/29}{Turn the cmd into a noop after use.}
+%    \begin{macrocode}
+\def\PrintChanges{\@input@{\jobname.gls}%
+                  \global\let\PrintChanges\@empty}
+%    \end{macrocode}
+% \end{macro}
+%
+%    
+%
+%
+%
+% \subsection{Bells and whistles}
+%
+% \begin{macro}{\StopEventually}
+% \changes{v1.5k}{1989/09/04}{Support for checksum.}
+% \begin{macro}{\Finale}
+% \changes{v1.5k}{1989/09/04}{Support for checksum.}
+% \changes{v1.5z}{1990/04/22}{Define \cs{Finale} globally.}
+% \begin{macro}{\AlsoImplementation}
+% \changes{v1.9w}{1995/12/27}{Macro added}
+% \begin{macro}{\OnlyDescription}
+%    If |\AlsoImplementation| is in force the whole documentation 
+%    including the code part will be typeset. This is the default.
+%    \begin{macrocode}
+\newcommand\AlsoImplementation{%
+%    \end{macrocode}
+%    To make this happen we have to define
+%    |\StopEventually| in a way that its argument is typeset at the
+%    very end or more exactly at |\Finale|. For this we
+%    save its argument in the macro |\Finale|.
+%    \begin{macrocode}
+   \long\def\StopEventually##1{\@bsphack\gdef\Finale{##1%
+%    \end{macrocode}
+%    But |\Finale| will be called at the very end of a file. This
+%    is exactly the point were we want to know if the file is
+%    uncorrupted. Therefore we also call |\check@checksum| at this
+%    point. 
+%    \begin{macrocode}
+                  \check@checksum}%
+%    \end{macrocode}
+%    On the other hand: |\StopEventually| is more or less a
+%    dividing point between description and code. So we start to look
+%    for the check-sum of the documented file by calling
+%    |\init@checksum|. 
+%    \begin{macrocode}
+              \init@checksum
+              \@esphack}%
+         }
+%    \end{macrocode}
+%
+%    Since |\AlsoImplementation| should be the default we execute it
+%    and thus |\StopEventually| gets the desired meaning.
+%    \begin{macrocode}
+\AlsoImplementation
+%    \end{macrocode}
+%    When the user places an |\OnlyDescription| declaration in
+%    the driver file the document should only be typeset up to
+%    |\StopEventually|. We therefore have to redefine this macro.
+%    \begin{macrocode}
+\def\OnlyDescription{\@bsphack\long\def\StopEventually##1{%
+%    \end{macrocode}
+%    In this case the argument of |\StopEventually| should be set
+%    and afterwards \TeX{} should stop reading from this file.
+%    Therefore we finish this macro with
+%    \begin{macrocode}
+           ##1\endinput}\@esphack}
+%    \end{macrocode}
+%    If no |\StopEventually| command is given we silently ignore a
+%    |\Finale| issued.
+% \changes{v1.9n}{1994/04/28}{Ignore \cs{Finale} if no
+%                  \cs{StopEventually} is given}
+%    \begin{macrocode}
+\let\Finale\relax
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\meta}
+% \changes{v1.4t}{1989/04/24}{Macro added.}
+% \changes{v1.5w}{1990/02/03}{Breaks at space allowed.}
+% \changes{v1.6a}{1990/05/24}{Extra space bug corrected.}
+%    The |\meta| macro is a bit tricky. We want to allow line
+%    breaks at blanks in the argument but we don't want a break
+%    in between. In the past this was done by defining |\meta| in a way that a
+%    \verb*+ + is active when the argument is scanned. Words are then
+%    scanned into |\hbox|es. The active \verb*+ + will end the
+%    preceding |\hbox| add an ordinary space and open a new
+%    |\hbox|. In this way breaks are only possible at spaces.  The
+%    disadvantage of this method was that |\meta| was neither robust
+%    nor could it be |\protect|ed. The new implementation  fixes this
+%    problem by defining |\meta| in a radically different way: we
+%    prevent hypenation by defining a |\language| which has no
+%    patterns associated with it and use this to typeset the words
+%    within the angle brackets.
+% \changes{v2.0i}{2000/05/21}{New implementation (pr/3170)}
+%    \begin{macrocode}
+\ifx\l@nohyphenation\undefined
+  \newlanguage\l@nohyphenation
+\fi
+%    \end{macrocode}
+%    
+%    \begin{macrocode}
+\DeclareRobustCommand\meta[1]{%
+%    \end{macrocode}
+%    Since the old implementation of |\meta| could be used in math we
+%    better ensure that this is possible with the new one as
+%    well. So we use |\ensuremath| around |\langle| and
+%    |\rangle|. However this is not enough: if |\meta@font@select|
+%    below expands to |\itshape| it will fail if used in math
+%    mode. For this reason we hide the whole thing inside an
+%    |\nfss@text| box in that case.
+% \changes{v2.0l}{2000/06/10}{Fixing changes for (pr/3170)}
+%    \begin{macrocode}
+     \ensuremath\langle
+     \ifmmode \expandafter \nfss@text \fi
+     {%
+      \meta@font@select
+%    \end{macrocode}
+%    Need to keep track of what we changed just in case the user
+%    changes font inside the argument so we store the font explicitly.
+% \changes{v2.0m}{2000/07/04}{More fixing changes for (pr/3170)}
+%    \begin{macrocode}
+      \edef\meta@hyphen@restore
+        {\hyphenchar\the\font\the\hyphenchar\font}%
+      \hyphenchar\font\m@ne
+      \language\l@nohyphenation
+      #1\/%
+      \meta@hyphen@restore
+     }\ensuremath\rangle
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\meta@font@select}
+% \changes{v2.0k}{2000/05/26}{Macro added (pr/3170)}
+%    Maske font used inside |\meta| customizable.
+%    \begin{macrocode}
+\def\meta@font@select{\itshape}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\IndexInput}
+%    This next macro may be used to read in a separate file (possibly
+%    a package file that is {\em not\/} documented by this means) and
+%    set it verbatim, whilst scanning for macro names and indexing the
+%    latter.  This could be a useful first pass in preparing to
+%    generate documentation for the file read.
+%    \begin{macrocode}
+\def\IndexInput#1{%
+%    \end{macrocode}
+%     We commence by setting up a group, and initializing a
+%    |\trivlist| as is normally done by a
+%    |\begin{macrocode}| command.
+%    \begin{macrocode}
+     \begingroup \macro@code
+%    \end{macrocode}
+%    We also make spacing behave as in the \textsf{macrocode}
+%    environment, because otherwise all the spaces will be shown
+%    explicitly.
+%    \begin{macrocode}
+   \frenchspacing \@vobeyspaces
+%    \end{macrocode}
+%    Then it only remains to read in the specified file, and finish
+%    off the |\trivlist|.
+% \changes{v1.5t}{1989/11/07}{Call \cs{endmacrocode} instead 
+%                             of \cs{endtrivlist}.}
+%    \begin{macrocode}
+     \input{#1}\endmacrocode
+%    \end{macrocode}
+%    Of course, we need to finish off the group as well.
+%    \begin{macrocode}
+     \endgroup}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\maketitle}
+%    The macro to generate titles is easily altered in order that it
+%    can be used more than once (an article with many titles).  In the
+%    original, diverse macros were concealed after use with
+%    |\relax|. We must cancel anything that may have been put
+%    into |\@thanks|, etc., otherwise {\em all\/} titles will
+%    carry forward any earlier such setting!
+%  \changes{v1.5j}{1989/06/09}{thispagestyle plain removed}
+%  \changes{v1.9r}{1994/06/09}{Added new definitions of
+%                 \cs{@makefnmark} and \cs{@makefntext}}
+%    \begin{macrocode}
+\def\maketitle{\par
+      \begingroup \def \thefootnote {\fnsymbol {footnote}}%
+      \setcounter {footnote}\z@
+      \def\@makefnmark{\hbox to\z@{$\m@th^{\@thefnmark}$\hss}}%
+      \long\def\@makefntext##1{\parindent 1em\noindent
+            \hbox to1.8em{\hss$\m@th^{\@thefnmark}$}##1}%
+      \if@twocolumn \twocolumn [\@maketitle ]%
+      \else \newpage \global \@topnum \z@ \@maketitle \fi
+%    \end{macrocode}
+% \changes{v1.5k}{1989/09/04}{Added \cs{ps@titlepage}}
+%    For special formatting requirements (such as in TUGboat), we use
+%    pagestyle |titlepage| for this; this is later defined to be
+%    |plain|, unless already defined, as, for example, by
+%    |ltugboat.sty|.
+%    \begin{macrocode}
+       \thispagestyle{titlepage}\@thanks \endgroup
+%    \end{macrocode}
+%    If the driver file documents many files, we don't want parts of a
+%    title of one to propagate to the next, so we have to cancel
+%    these:
+%    \begin{macrocode}
+      \setcounter {footnote}\z@
+      \gdef\@date{\today}\gdef\@thanks{}%
+      \gdef\@author{}\gdef\@title{}}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\ps@titlepage}
+% \changes{v1.5k}{1989/09/04}{Added \texttt{\protect\bslash
+%    ps@titlepage}} When a number of articles are concatenated into a
+%    journal, for example, it is not usual for the title pages of such
+%    documents to be formatted differently.  Therefore, a class
+%    such as \textsf{ltugboat} can define this macro in advance.
+%    However, if no such definition exists, we use pagestyle
+%    \texttt{plain} for title pages.
+%    \begin{macrocode}
+\@ifundefined{ps@titlepage}
+    {\let\ps@titlepage=\ps@plain}{}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\MakeShortVerb}
+% \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters
+%                           \cs{dospecials}, \cs{@sanitize}).}
+% This arranges an abbreviation for "\verb" such that if you say
+% "\MakeShortVerb{\"\meta{c}"}" subsequently using
+% \meta{c}\meta{text}\meta{c} is equivalent to
+% "\verb"\meta{c}\meta{text}\meta{c}.\footnote{Warning:
+% the commentary in the rest of this section was written by Dave
+% Love.}  In addition, the fact 
+% that \meta{c} is made active is recorded for the benefit of the
+% \textsf{verbatim} and \textsf{macrocode} environments.
+% Note particularly that the definitions below are global.
+% The first thing we do (it needn't be first) is to record
+% the---presumably new---special character in "\dospecials" and
+% "\@sanitize" using "\add@special".
+%
+% \changes{v1.9e.2}{1994/02/07}{-js: Check if \protect\meta{c} is
+%                              already an
+%                              abbreviation for \cs{verb}.}
+% Some unwary user might issue "\MakeShortVerb" for a second time, we
+% better protect against this. We assume that this happened if a
+% control sequence "\cc\"\meta{c} is bound, the probability that this
+% name is used by another module is low. We will output a warning
+% below, so that a possible error might be noticed by the programmer
+% if he reads the "LOG" file. (Should have used module internal names,
+% 'though.)
+%
+% \begin{macro}{\MakeShortVerb*}
+% \changes{v2.1a}{2003/12/09}{(HjG) Added \texttt{*} form}
+% This arranges an abbreviation for "\verb*" such that if you say
+% "\MakeShortVerb*{\"\meta{c}"}" subsequently using
+% \meta{c}\meta{text}\meta{c} is equivalent to
+% "\verb*"\meta{c}\meta{text}\meta{c}.
+%    \begin{macrocode}
+%</package>
+%<*package|shortvrb>
+\def\MakeShortVerb{%
+  \@ifstar
+    {\def\@shortvrbdef{\verb*}\@MakeShortVerb}%
+    {\def\@shortvrbdef{\verb}\@MakeShortVerb}}
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
+\def\@MakeShortVerb#1{%
+  \expandafter\ifx\csname cc\string#1\endcsname\relax
+%    \end{macrocode}
+% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}}
+%    \begin{macrocode}
+    \@shortvrbinfo{Made }{#1}\@shortvrbdef
+    \add@special{#1}%
+%    \end{macrocode}
+% Then the character's current catcode is stored in "\cc\"\meta{c}.
+%    \begin{macrocode}
+    \expandafter
+    \xdef\csname cc\string#1\endcsname{\the\catcode`#1}%
+%    \end{macrocode}
+% The character is spliced into the definition using the same trick as
+% used in "\verb" (for instance), having activated "~" in a group.
+%    \begin{macrocode}
+    \begingroup
+      \catcode`\~\active  \lccode`\~`#1%
+      \lowercase{%
+%    \end{macrocode}
+% The character's old meaning is recorded in "\ac\"\meta{c} prior to
+% assigning it a new one.
+%    \begin{macrocode}
+      \global\expandafter\let
+         \csname ac\string#1\endcsname~%
+      \expandafter\gdef\expandafter~\expandafter{\@shortvrbdef~}}%
+    \endgroup
+%    \end{macrocode}
+% Finally the character is made active.
+%    \begin{macrocode}
+    \global\catcode`#1\active
+%    \end{macrocode}
+% If we suspect that \meta{c} is already a short reference, we tell
+% the user. Now he or she is responsible if anything goes wrong\,\dots
+%    \begin{macrocode}
+  \else
+%    \end{macrocode}
+% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}}
+%    \begin{macrocode}
+    \@shortvrbinfo\@empty{#1 already}{\@empty\verb(*)}%
+  \fi}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\DeleteShortVerb}
+% \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters
+%                           \cs{dospecials}, \cs{@sanitize}).}
+% Here's the means of undoing a "\MakeShortVerb", for instance in a
+% region where you need to use the character outside a verbatim
+% environment.  It arranges for "\dospecials" and "\@sanitize" to be
+% altered appropriately, restores the saved catcode and, if necessary,
+% the character's meaning (as stored by 
+% "\MakeShortVerb").  If the catcode wasn't stored in
+% "\cc\"\meta{c} (by "\MakeShortVerb") the command is silently
+% ignored. 
+% \changes{v1.7a}{1992/02/28}{Check for previous matched
+%                           \cs{MakeShortVerb}
+%                           to avoid error.}
+%    \begin{macrocode}
+\def\DeleteShortVerb#1{%
+  \expandafter\ifx\csname cc\string#1\endcsname\relax
+%    \end{macrocode}
+% \changes{v2.1a}{2003/12/10}{(HjG) Notify user
+%             if it's not a short verb character}
+%    \begin{macrocode}
+    \@shortvrbinfo\@empty{#1 not}{\@empty\verb(*)}%
+  \else
+%    \end{macrocode}
+% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}}
+%    \begin{macrocode}
+    \@shortvrbinfo{Deleted }{#1 as}{\@empty\verb(*)}%
+    \rem@special{#1}%
+    \global\catcode`#1\csname cc\string#1\endcsname
+%    \end{macrocode}
+% \changes{v1.9e.2}{1994/02/07}{-js: Reset `cc`\protect\meta{c} in
+%                       in \cs{DeleteShortVerb}}
+% We must not forget to reset "\cc\"\meta{c}, otherwise the check in
+% "\MakeShortVerb" for a repeated definition will not work.
+%    \begin{macrocode}
+    \global \expandafter\let \csname cc\string#1\endcsname \relax
+    \ifnum\catcode`#1=\active
+      \begingroup
+        \catcode`\~\active   \lccode`\~`#1%
+        \lowercase{%
+          \global\expandafter\let\expandafter~%
+          \csname ac\string#1\endcsname}%
+      \endgroup \fi \fi}
+%    \end{macrocode}
+% \end{macro}
+%
+%  \begin{macro}{\@shortvrbinfo}
+% \changes{v1.9v}{1995/11/03}{(DPC) Macro added}
+% \changes{v2.1a}{2003/12/10}{(HjG) Third argument added
+%             on behalf of \cmd{\MakeShortVerb*}}
+% Helper function for info messages.
+%    \begin{macrocode}
+\def\@shortvrbinfo#1#2#3{%
+%<shortvrb>  \PackageInfo{shortvrb}{%
+%<!shortvrb>  \PackageInfo{doc}{%
+     #1\expandafter\@gobble\string#2 a short reference
+                                          for \expandafter\string#3}}
+%    \end{macrocode}
+%  \end{macro}
+%
+% \begin{macro}{\add@special}
+% \changes{v1.7a}{1992/02/27}{Added for short verb facility.}
+% This helper macro adds its argument to the
+% "\dospecials" macro which is conventionally used by verbatim macros
+% to alter the catcodes of the currently active characters.  We need
+% to add "\do\"\meta{c} to the expansion of "\dospecials" after
+% removing the character if it was already there to avoid multiple
+% copies building up should "\MakeShortVerb" not be balanced by
+% "\DeleteShortVerb" (in case anything that uses "\dospecials" cares
+% about repetitions).
+%    \begin{macrocode}
+\def\add@special#1{%
+  \rem@special{#1}%
+  \expandafter\gdef\expandafter\dospecials\expandafter
+    {\dospecials \do #1}%
+%    \end{macrocode}
+% Similarly we have to add "\@makeother\"\meta{c} to "\@sanitize"
+% (which is used in things like "\index" to re-catcode all special
+% characters except braces).
+%    \begin{macrocode}
+  \expandafter\gdef\expandafter\@sanitize\expandafter
+    {\@sanitize \@makeother #1}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\rem@special}
+% \changes{v1.7a}{1992/02/27}{Added for short verb facility.}
+% The inverse of "\add@special" is slightly trickier.  "\do" is
+% re-defined to expand to nothing if its argument is the character of
+% interest, otherwise to expand simply to the argument.  We can then
+% re-define "\dospecials" to be the expansion of itself.  The space
+% after "=`##1" prevents an expansion to "\relax"!
+%    \begin{macrocode}
+\def\rem@special#1{%
+  \def\do##1{%
+    \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}%
+  \xdef\dospecials{\dospecials}%
+%    \end{macrocode}
+% Fixing "\@sanitize" is the same except that we need to re-define
+% "\@makeother" which obviously needs to be done in a group. 
+%    \begin{macrocode}
+  \begingroup
+    \def\@makeother##1{%
+      \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}%
+    \xdef\@sanitize{\@sanitize}%
+  \endgroup}
+%</package|shortvrb>
+%<*package>
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\MakeShortverb}
+% \begin{macro}{\DeleteShortverb}
+% \changes{v1.7a}{1992/02/27}{Added (from newdoc).}
+% These commands from \textsf{newdoc} are now obsolete.
+%    \begin{macrocode}
+\def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb
+                         syntax, this is obsolete ***}\MakeShortVerb}
+\def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb
+                         syntax, this is obsolete ***}\DeleteShortVerb}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsection[Providing a checksum and character table]
+%        {Providing a checksum and character table\footnotemark}
+%        \footnotetext{Warning: the commentary in this section was
+%                      written by Dave Love. }
+%
+% 
+% \begin{macro}{\init@checksum}
+% The checksum mechanism works by counting backslashes in the
+% macrocode.  This initialises the count (when called from
+% "\StopEventually"). 
+% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
+%    \begin{macrocode}
+\def\init@checksum{\relax
+    \global\bslash@cnt\z@}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\check@checksum}
+% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
+% This reports the sum compared with the value ("\bslash@cnt") the
+% file advertises.  It's called from "\Finale" (if that hasn't been
+% re-defined). 
+%    \begin{macrocode}
+\def\check@checksum{\relax
+     \ifnum\check@sum=\z@
+       \typeout{**********************************}%
+       \typeout{* This macro file has no checksum!}%
+       \typeout{* The checksum should be \the\bslash@cnt!}%
+       \typeout{**********************************}%
+     \else
+       \ifnum\check@sum=\bslash@cnt
+         \typeout{*******************}%
+         \typeout{* Checksum passed *}%
+         \typeout{*******************}%
+       \else
+         \PackageError{doc}{Checksum not passed 
+                    (\the\check@sum<>\the\bslash@cnt)}%
+          {The file currently documented seems to be wrong.^^J%
+           Try to get a correct version.}%
+       \fi
+     \fi
+     \global\check@sum\z@}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\check@sum}
+% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
+% \begin{macro}{\bslash@cnt}
+% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
+% We need to define counters, "\bslash@cnt" for the number of
+% backslashes counted and "\check@sum" for the value advertised by the
+% file.
+%    \begin{macrocode}
+\newcount\check@sum           \check@sum  = \z@
+\newcount\bslash@cnt          \bslash@cnt = \z@
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\CheckSum}
+% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
+% This is the interface to setting "\check@sum".
+%    \begin{macrocode}
+\def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\step@checksum}
+% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
+% This advances the count when a backslash is encountered in the
+% macrocode. 
+%    \begin{macrocode}
+\def\step@checksum{\global\advance\bslash@cnt\@ne}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\CharacterTable}
+%    The user interface to the character table-checking does some
+%    "\catcode"ing and then compares the following table with the
+%    stored version. We need to have "@" of type ``other'' within the
+%    table since this is the way it is usually returned when reading
+%    in a normal document. To nevertheless have a private letter we
+%    use "~" for this purpose. "~" does no harm as a ``letter'' as it
+%    comes last in the table and therefore will not gobble following
+%    space.
+% \changes{v1.5m}{1989/09/20}{Macro added to check character translation
+%                           problems.}
+% \changes{v1.5q}{1989/11/01}{Made character table more readable.}
+% \changes{v1.5t}{1989/11/07}{Make \string\~{} letter in chartable
+%                           macros.}
+% \changes{v1.5u}{1989/11/14}{Made @ other in default table.}
+%    \begin{macrocode}
+\def\CharacterTable{\begingroup \CharTableChanges \character@table}
+%    \end{macrocode}
+% \end{macro}
+% \def\MakePrivateLetters{\catcode`\~=11\makeatletter}
+% \begin{macro}{\character@table}
+% This does the work of comparing the tables and reporting the result.
+% Note that the following code is enclosed in a group
+% with "~" catcoded to letter.
+%    \begin{macrocode}
+\begingroup
+  \catcode`\~=11
+  \gdef\character@table#1{\def\used~table{#1}%
+      \ifx\used~table\default~table
+           \typeout{***************************}%
+           \typeout{* Character table correct *}%
+           \typeout{***************************}%
+      \else
+         \PackageError{doc}{Character table corrupted}
+                           {\the\wrong@table}
+         \show\default~table
+         \show\used~table
+      \fi
+      \endgroup}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\CharTableChanges}
+%    When the character table is read in we need to scan it with a
+%    fixed set of "\catcode"s. The reference table below  was defined by
+%    assuming the normal "\catcode"s of \TeX{}, i.e.\ "@" is of type
+%    other and the only token of type ``letter'' are the usual letters
+%    of the alphabet. If, for some reason, other characters are made
+%    ``letters'' then their "\catcode"s need to be restored before
+%    checking the table. Otherwise spaces in the table are gobbled and
+%    we get the information that the tables are different, even if
+%    they are actually equal. For this reason "\CharTableChanges" can
+%    be set up to locally restore the "\catcode"s of such ``letters''
+%    to ``other''.
+%    \begin{macrocode}
+  \global\let\CharTableChanges\@empty
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\default~table}
+% Here's what the table {\em should\/} look like (modulo spaces).
+%    \begin{macrocode}
+  \makeatother
+  \gdef\default~table
+     {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         \~}
+\endgroup
+%    \end{macrocode}
+% \end{macro}
+% \let\MakePrivateLetters=\makeatletter
+% 
+% \begin{macro}{\wrong@table}
+% \changes{v1.7a}{1992/02/28}{Moved to where the catcodes are right
+%                           so it works.}
+% We need a help message in case of problems.
+%    \begin{macrocode}
+  \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J
+            I now \string\show\space you both tables for comparison.}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection[Attaching line numbers to code lines]
+%            {Attaching line numbers to code lines\footnotemark}
+%            \footnotetext{Warning: the commentary was written by Dave
+%            Love.}
+%
+%
+% The code in this section allows index entries to refer to code line
+% numbers---the number of the first line of macrocode in the
+% \textsf{macro} environment.
+% 
+% 
+% \begin{macro}{\codeline@index}
+% Indexing by code line is controlled by the "codeline@index" switch.
+% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
+% \changes{v1.7a}{1992/02/24}{Documented code line no. support.}
+% \begin{macro}{\CodelineNumbered}
+% \changes{v1.8a}{1993/05/19}{Macro added}
+%    \begin{macrocode}
+\newif\ifcodeline@index \codeline@indexfalse
+\let\CodelineNumbered\codeline@indextrue
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\codeline@wrindex}
+%    The code index entries are written out by "\special@index".  If
+%    indexing is by code line this is "\let" to "\codeline@wrindex";
+%    if indexing is by page it is just "\index".  However, if
+%    "\nofiles" is given, we omit writing such an index entry at all.
+% \changes{v1.7j}{1992/08/14}{Added \cs{if@filesw}.}
+%    \begin{macrocode}
+\def\codeline@wrindex#1{\if@filesw
+        \immediate\write\@indexfile
+            {\string\indexentry{#1}%
+            {\number\c@CodelineNo}}\fi}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\special@index}
+% By default no index entries are written out.
+%    \begin{macrocode}
+\let\special@index = \@gobble
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\CodelineIndex}
+% \changes{v1.5u}{1989/11/14}{Added \cs{PageIndex} and
+%                  \cs{CodelineIndex} (Undoc)}
+% This switches on use of the index file with "\makeindex", sets the
+% switch to indicate code line numbering and defines "\special@index"
+% appropriately. 
+%    \begin{macrocode}
+\def\CodelineIndex{\makeindex 
+                   \codeline@indextrue
+                   \let\special@index\codeline@wrindex}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\PageIndex}
+% "\PageIndex" is similar.
+%    \begin{macrocode}
+\def\PageIndex{\makeindex 
+               \codeline@indexfalse
+               \let\special@index\index}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\c@CodelineNo}
+% \changes{v1.5l}{1989/09/10}{Counter added to support code line
+%                             numbers}
+% \changes{v1.5y}{1990/02/24}{Default changed.}
+% \changes{v1.6b}{1990/06/15}{\cs{rm} moved before \cs{scriptsize} to
+%                           avoid unnecessary fontwarning.}
+% We need a counter to keep track of the line number.
+%    \begin{macrocode}
+\newcount\c@CodelineNo  \c@CodelineNo\z@
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\theCodelineNo}
+% \changes{v1.7a}{1992/02/25}{Existing definition not overwritten.}
+% \changes{v1.7a}{1992/03/12}{Use \cs{reset@font} for NFSS.}
+% This provides a hook to control the format of line numbers which may
+% be defined in a class file.
+%    \begin{macrocode}
+\@ifundefined{theCodelineNo}
+  {\ifx\selectfont\undefined
+     \def\theCodelineNo{\rmfamily\scriptsize\arabic{CodelineNo}}%
+   \else
+     \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}%
+   \fi}
+  {}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
+% \subsection{Layout Parameters for documenting package files}
+%
+% \begin{macro}{\tolerance}
+%    People documenting package files would probably rather have things
+%    ``sticking out'' in overfull |\hbox|es and poorish spacing,
+%    because they probably don't want to spend a lot of time on making
+%    all the line breaks perfect!
+%    \begin{macrocode}
+       \tolerance=1000\relax
+%    \end{macrocode}
+% \end{macro}
+%
+% \DeleteShortVerb{\"}
+%
+% The following |\mathcode| definitions allow the characters
+% `|\|'
+% and `\texttt{@}' to appear in |\ttfamily| font when invoked in math 
+% mode;\footnote{You may wonder why the definitions state that both
+%                characters belong to the {\em variable family\/}
+%                (i.e.\ the number 7 in front). The reason is this:
+%                Originally the \texttt{\bslash mathcode} of
+%                \texttt{\bslash} was defined to be \texttt{"075C},
+%                i.e.\ ordinary character number 92 (hex 5C) in
+%                math family number 7 which is the typewriter family in
+%                standard \LaTeX.
+%                But this file should not depend on this specific
+%                setting, so I changed these 
+%                \texttt{\bslash mathcode}$\,$s
+%                to work with any family assignments. For an example
+%                see the article about the new font selection scheme.}
+% particularly for something like $|\@abc|=1$.
+%
+% If an {\em old\/} version of the \textsf{german} package is in
+% force, then the `|"|' character is active and would upset the
+% definition of the \meta{16-bit number} quantities below, therefore
+% we change the |\catcode| of |"| inside a group, and use
+% |\global|.
+%    \begin{macrocode}
+{ \catcode`\"=12
+  \global\mathcode`\\="705C \global\mathcode`\@="7040 }
+%    \end{macrocode}
+% \MakeShortVerb{\"}
+%
+% \begin{macro}{\DocstyleParms}
+%    This macro can be used, for example, to assign new values to
+%    |\MacrocodeTopsep| and |\MacroIndent| and some other internal
+%    registers.  If it is already defined, the default definition
+%    won't be carried out. Note that it is necessary to assign new
+%    values via this macro if it should be done in a class file (like
+%    \texttt{ltugboat.cls} for example) since the registers are
+%    undefined before \texttt{doc.sty} is read in.  The default values
+%    for the internal registers are scattered over this file.
+% \changes{v1.5u}{1989/11/14}{\cs{DocStyleParms} now empty}
+%    \begin{macrocode}
+\@ifundefined{DocstyleParms}{}{}
+%    \end{macrocode}
+%    Now we allow overwriting the values by calling
+%    |\DocstyleParms|.
+%    \begin{macrocode}
+\DocstyleParms     \let\DocstyleParms\relax
+%    \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\AmSTeX}
+%   \changes{v1.5j}{1989/06/09}{Macro AmsTeX renamed to AmSTeX}
+% \begin{macro}{\BibTeX}
+% \begin{macro}{\SliTeX}
+%    Here are a few definitions which can usefully be employed when
+%    documenting package files: now we can readily refer to \AmSTeX,
+%    \BibTeX\ and \SliTeX, as well as the usual \TeX\ and \LaTeX.
+%    \begin{macrocode}
+\@ifundefined{AmSTeX}
+   {\def\AmSTeX{\leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex%
+        \hbox{$\mathcal M$}\kern-.2em\mathcal S$-\TeX}}}{}
+\@ifundefined{BibTeX}
+   {\def\BibTeX{{\rmfamily B\kern-.05em%
+    \textsc{i\kern-.025em b}\kern-.08em%
+    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{}
+\@ifundefined{SliTeX}
+   {\def\SliTeX{{\rmfamily S\kern-.06emL\kern-.18em\raise.32ex\hbox
+                {\scshape i}\kern -.03em\TeX}}}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\PlainTeX}
+% \changes{v1.5g}{1989/05/07}{space between plain and TeX changed.}
+% \begin{macro}{\Web}
+%     There's even a \PlainTeX{} and a \Web.
+%    \begin{macrocode}
+\@ifundefined{PlainTeX}{\def\PlainTeX{\textsc{Plain}\kern2pt\TeX}}{}
+\@ifundefined{Web}{\def\Web{\textsc{Web}}}{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsection{Changing the \texttt{\protect\bslash catcode} of \%}
+%
+% \begin{macro}{\MakePercentIgnore}
+% \begin{macro}{\MakePercentComment}
+%    And finally the most important bit: we change the |\catcode|
+%    of `|%|' so that it is ignored (which is how we are able to
+%    produce this document!). We provide two commands to do the actual
+%    switching.
+%^^A The |\MakePercentIgnore| is then called as the
+%^^A last command in this file.
+%    \begin{macrocode}
+\def\MakePercentIgnore{\catcode`\%9\relax}
+\def\MakePercentComment{\catcode`\%14\relax}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\DocInput}
+%    The two macros above are now used to define the |\DocInput| macro
+%    which was introduced in version v1.5l (or so) of the \DOC{}
+%    package. In older versions |\MakePercentIgnore| was placed
+%    at the very end of \texttt{doc.sty}.
+%    \begin{macrocode}
+\def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{GetFileInfo}
+%
+% \begin{macro}{\GetFileInfo}
+% \changes{v1.9o}{1994/05/08}{Macro added}
+% \changes{v1.9z}{1997/02/05}{Missing percent latex/2404}
+%    Define |\filedate| and friends from info in the
+%    |\ProvidesPackage| etc.\ commands.
+%    \begin{macrocode}
+\def\GetFileInfo#1{%
+  \def\filename{#1}%
+  \def\@tempb##1 ##2 ##3\relax##4\relax{%
+    \def\filedate{##1}%
+    \def\fileversion{##2}%
+    \def\fileinfo{##3}}%
+  \edef\@tempa{\csname ver@#1\endcsname}%
+  \expandafter\@tempb\@tempa\relax? ? \relax\relax}
+%    \end{macrocode}
+% \end{macro}
+%
+% We can now finish the \texttt{docstrip} main module.
+%    \begin{macrocode}
+%</package>
+%    \end{macrocode}
+%
+%
+% \Finale
+% \PrintIndex \PrintChanges
+\endinput