% \iffalse meta-comment
%
% Copyright (C) 1989-1992 by Frank Mittelbach.  All rights reserved.
% 
% This file is part of the doc package.
% 
% IMPORTANT NOTICE:
% 
% You are not allowed to change this file.  You may however copy
% this file to a file with a different name and then change the
% copy if you obey the restrictions on file changes described in
% readme.mz.
% 
% You are NOT ALLOWED to distribute this file alone.  You are NOT
% ALLOWED to take money for the distribution or use of this file
% (or a changed version) except for a nominal charge for copying
% etc.
% 
% You are allowed to distribute this file under the condition that
% it is distributed together with all files mentioned in
% readme.mz0.
% 
% If you receive only some of these files from someone, complain!
% 
% However, if these files are distributed by established suppliers
% as part of a complete TeX distribution, and the structure of the
% distribution would make it difficult to distribute the whole set
% of files, *those parties* are allowed to distribute only some of
% the files provided that it is made clear that the user will get
% a complete distribution-set upon request to that supplier (not
% me).  Notice that this permission is not granted to the end
% user.
% 
% 
% For error reports in case of UNCHANGED versions see readme.mz
% 
% 
% \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
%<*style>
\def\fileversion{v1.7k} 
\def\filedate{92/08/24}
\def\docdate {92/08/28}
%</style>
%\catcode`\<=12

% \CheckSum{1985}
%% \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.
%           

% Style-option `doc' to use with LaTeX v2.09
%% Copyright (C) 1989-1992 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.1a        13.5.88   \theindex and \endtheindex redefined.
%  1.1b        15.5.88   \bslash redefined.
%                        \verbatim changed so that `%'s will be ignored.
%  1.1c        19.5.88   Partly documented and \@temp... in
%                        \theindex replaced by private commands.
%                        Moreover, \pageshrink incorporated in the
%                        computation of the amount of free space on the
%                        page.
%  1.1d        3.6.88    Something goes wrong during the computation of
%                        \pageshrink, therefore a bit of empty space is
%                        inserted by
%                        hand, and some tracing information introduced.
%                        It can't stay like that!!
%  1.2a        23.9.88   Documentation of the macros in DOC-format,
%                        i.e. so that this file can document itself.
%  1.2b        7.10.88   Change of the index environment.
%  1.2c        10.10.88  Further Documentation.
%  1.2d        19.10.88  \the before \catcode eliminated. (thanks P.
%                        Breitenlohner)
%  1.3a        24.10.88  Scanning of macro names via \scanmacro
%                        introduced to produce index entries.
%  1.3b         16.1.89  Scanning of macro names via \scanmacro
%                        improved.
%                        At present only suitable for the makeindex
%                        program
%                        in conjunction with a special style file.
%                        Macro environment in `macro' environment
%                        renamed.
%  1.3c         30.1.89  Index environment removed. Will be developed in
%                        other style file.
%  1.4a         7.2.89   \SpecialEscapechar added (may change its name).
%  1.4b         7.3.89   \SpecialEscapechar reimplemented.
%  1.4c         9.3.89   \parts of \short@macro reimplemented because
%                        of some bugs in the macros and the makeindex
%                        program.
%                        Old definition of \b@slash used for \bslash.
%                        \b@slash removed.
%  1.4d         10.3.89  English documentation added.
%  1.4e         10.3.89  private names for private macros.
%                        \makespecialletters renamed to
%                        \MakePrivateLetters
%  1.4f         12.3.89  \short@macro changed (again)
%                        documentation update.
%  1.4g         13.3.89  \DoNotIndex macros changed.
%  1.4h         13.3.89  \DoNotIndex macros changed to version with
%                        \@elt
%  1.4i         15.3.89  documentation update
%  1.4j         15.3.89  \printindex inserted
%  1.4k         21.3.89  documentation update
%                        \PrintDescribe... and \Describe... added
%                        macro env. + \SpecialIndex changed to accept \
%  1.4l         29.3.89  macro env. changed once more (\macro@ added) to
%                        correct bug introduced in v1.4k
%                        \SpecialUsageIndex and \SpecialEnvIndex added.
%  1.4m          3.4.89  \OnlyDescription added, \MakePrivateLetters
%                        changed
%  1.4n         10.4.89  \MakePrivateLetters changed back to
%                        \makeatletter.
%                        \ifnot@excluded changed to allow other things
%                        than
%                        macro names in the exclude list (e.g. \abc*)
%  1.4o         14.4.89  Documentation update (Brian's correction)
%                        \EnableCrossrefs changed to disable
%                        \DisableCrossrefs
%  1.4p         15.4.89  Documentation update \Finale added,
%                        some changes to index.tex 
%  1.4q         19.4.89  Documentation update \verbatim changed (RmS)
%                        twocolumns env. added index.tex changed.
%  1.4r         22.4.89  Changed \macro@ to support \par and
%                        conditionals (might be wrong.)
%  1.4s         23.4.89  Getting nearer to the `final' version.
%                        \@sphack ...
%                        placed in several macros. Documentation update.
%                        Tried a \changes macro (somewhere in the middle
%                        of this file by using \glossary (might work!)
%  1.4t         24.4.89  Should change to 1.5? Index now uses multicols
%                        added \c@IndexColumns. Other changes forgotten.
%                        Some macro names renamed.
%  1.5a         26.4.89  Finally 1.5:  changes to \makelabel in macro
%                        env.
%  1.5b and higher...    are documented with the (undocumented) \changes
%                        feature.
%  \changes{v1.5f}{89/4/29}{Thanks to Brian who documented the
%                          {\tt\bslash changes} macro feature.}
%  \changes{v1.5g}{89/5/07}{MacroTopsep now called MacrocodeTopsep and
%                          new MacroTopsep added}
%  \changes{v1.5h}{89/05/17}{All lines shortened to <72 characters}
%  \changes{v1.5j}{89/06/09}{Corrections by Ron Whitney added}
%  \changes{v1.5q}{89/11/03}{`\ldots{}Listing macros renamed to
%                         `\ldots{}Input. Suggested by R. Wonneberger}
%  \changes{v1.5W}{90/02/05}{Counter codelineno renamed to CodelineNo}
%                        
%
%\fi
%
% \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{\cal,\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
%
% \makeatletter  ^^A hack so that this can be printed without multicols
% \newif \ifmulticols
% \ifhave@multicol \multicolstrue \fi
% \makeatother
% \title{The {\tt doc}--Option\thanks{%
%    This file has version number \fileversion{} dated \filedate{}.
%    The documentation was last revised on \docdate.
%       }}
% \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 {\tt newdoc},  and
%        documentation of post-v1.5q features added at v1.7a by Dave
%        Love (SERC Daresbury Lab).}\\
%         Gutenberg Universit\"at Mainz}
%
% \maketitle
%
% \begin{abstract}
%    This style option contains the definitions that are necessary to
%    format the documentation of style files.  The style file 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 {\sf doc} and integrates the features of {\sf
%    newdoc}. 
% \end{abstract}
%
% \ifmulticols
% \addtocontents{toc}{\protect\begin{multicols}{2}}
% \fi
%
% {\parskip 0pt                ^^A We have to reset \parskip
%                              ^^A (bug in \LaTeX)
% \tableofcontents
% }
%
% \changes{v1.7a}{92/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 {\tt doc.doc} documents changes which have occurred
% since the last published version \cite{art:doc} but which have been
% present in distributed versions of {\tt doc.sty} for some time.  It
% also integrates the (undocumented) features of the distributed {\tt
% 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 {\tt doc} files and {\tt doc}
% no longer has to be the last style option.  "\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 {\tt 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[{\tt \bslash par}] can now be used in "\DoNotIndex";
% \item[Checksum/character table support] for ensuring the
% integrity of distributions is added;
% \item[{\tt \bslash printindex}] becomes "\PrintIndex";
% \item[{\tt multicol.sty}] is no longer necessary to use {\tt 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 {\tt newdoc.sty} and that added after version 1.5k of
% {\tt 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 `General changes' glossary entry would come out after
%    macro names with a leading "!" and possibly a leading \verb+"+;
% \item If you have an old version of {\sf 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 {\sf makeindex} style files support
%    the inconsistent attribute specifications of older and newer
%    versions {\sf 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 style's `exported'
% definitions which they describe.  This could subsequently be
% included in the {\tt docstrip}ped {\tt .sty} file in a suitable form
% for use by smart editors in command completion, spelling checking
% etc., based on the style options of a document.  This would need
% agreement on a `suitable form'.
% \item Indexing of the modules used in {\tt docstrip}'s "%<"
% directives.  I'm not sure how to index directives containing
% module combinations;
% \item Writing out bibliographic information about the style;
% \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 style 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
% {\tt 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 {\sf doc} style option}
%
% Just like any other option, invoke it by including it amongst the
% style options in the optional parameter list for the
% \verb+\documentstyle+ command.  {\sf Doc}'s use of
% \verb+\reversemarginpars+ may make it incompatible with some style
% options.
% \changes{v1.7a}{92/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 {\tt doc}
% option one has to prepare a special driver file which produces the
% formatted document. This driver file has the following
% characteristics:
% 
% \noindent \verb+\documentstyle[+\meta{options}]^^A
%           \verb+{+\meta{document-style}\verb+}+\\[3pt]
% \hspace*{10pt}\meta{preamble}\\[3pt]
% \verb+\begin{document}+\\[3pt]
% \hspace*{10pt}\meta{special input commands}\\[3pt]
% \verb+\end{document}+
%
% The list of \meta{options} must contain the {\tt doc} option but it
% is not necessary any longer to put this option on the end of the
% list.
%
% The \meta{document-style} might be any document style, I normally
% use {\tt article}.
% 
% In the \meta{preamble} one should place declarations which
% manipulate the behavior of the {\tt doc} option like
% \verb+\DisableCrossrefs+ or \verb+\OnlyDescription+.
%
% \DescribeMacro\DocInput \DescribeMacro\IndexInput
% Finally the \meta{special input commands} part should contain one or
% more \verb+\DocInput+\meta{file name} and/or
% \verb+\IndexInput+\meta{file name} commands.  The
% \verb+\DocInput+ command is used for files prepared for the {\tt
% doc} option whereas \verb+\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 styles---for instance, each containing
% "\maketitle". 
%
% As an example, the driver file for the {\tt doc} option itself is
% derived from the following text.  This is meant to be extracted by
% the {\tt docstrip} program which will remove the leading "<+driver>"
% indicating the `module'; the line numbers are added by {\tt
% doc}'s formatting.
% \changes{v1.7a}{92/03/06}{Added docstrip-derivable driver file as
%                           example.}
% \changes{v1.7c}{92/04/01}{Expurgated ltugboat.sty from driver.}
%    \begin{macrocode}
%<+driver>\documentstyle[doc]{article}
%<+driver>% dimensions from ltugboat.sty:
%<+driver>\setlength\textwidth{31pc} \setlength\textheight{54pc}
%<+driver>\setlength{\parindent}{0pt} 
%<+driver>\setlength{\parskip}{2pt plus 1pt minus 1pt}
%<+driver>\setlength{\oddsidemargin}{8pc} 
%<+driver>\setlength{\marginparwidth}{8pc}
%<+driver>\setlength{\topmargin}{-2.5pc} 
%<+driver>\setlength{\headsep}{20pt}
%<+driver>\setlength{\columnsep}{1.5pc} 
%<+driver>\setlength{\columnwidth}{18.75pc}
%<+driver>\EnableCrossrefs         
%<+driver>%\DisableCrossrefs % Say \DisableCrossrefs if index is ready
%<+driver>\RecordChanges                  % Gather update information
%<+driver>\CodelineIndex                  % Index code by line number
%<+driver>%\OnlyDescription  % comment out for implementation details
%<+driver>%\OldMakeindex     % use if your MakeIndex is pre-v2.9
%<+driver>\begin{document}
%<+driver>   \DocInput{doc.doc}
%<+driver>\end{document}
%    \end{macrocode}
%^^A As an example this is the driver file for the {\tt doc} option
%^^A itself: 
%^^A\begin{verbatim}
%^^A\documentstyle[ltugboat,doc]{article}
%^^A
%^^A %  \DisableCrossrefs     % Say \DisableCrossrefs if the index
%^^A                          % is ready.
%^^A
%^^A    \RecordChanges        % Gather update-information
%^^A
%^^A %  \OnlyDescription      % Remove the comment char if you only want
%^^A                          % the description
%^^A
%^^A\SelfDocumenting          % Tugbot style macro (for doc)
%^^A
%^^A\begin{document}
%^^A
%^^A   \DocInput{doc.doc}
%^^A
%^^A\end{document}
%^^A\end{verbatim}
%
% \changes{v1.7a}{92/02/25}{Note on avoiding driver file}
% \subsection{Avoiding using a driver file}
%
% It is possible to dispense with a driver file at the expense of some
% flexibility using the following trick.\footnote{Due to David
% Carlisle, Manchester University.}  Before the documentation part of
% the file starts, include (without leading "%"s!)\ something like
% \begin{verbatim}
%\ifcat a\noexpand @\let\next\relax\else\def\next{%
%    \documentstyle[doc]{article}\MakePercentIgnore}\fi\next
%\end{verbatim}
% with any necessary extra style options included, of course.  Then
% the file can either be used directly as a style file as normal or
% have the documentation printed simply by using
% "latex"~\meta{filename}.  You can also arrange to have this process
% ask questions about whether to format only the usage section, for
% instance. 
%
% \subsection{General conventions}
%
% A \TeX{} file prepared to be used with the `doc' style option
% consists of `documentation parts' intermixed with `definition
% parts'.
%
% Every line of a `documentation part' starts with a percent sign
% (\verb+%+) in column one.  It may contain arbitrary \TeX{} or
% \LaTeX{} commands except that the character `\verb+%+' 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 \verb+^^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 style file in
% the \verb+\documentstyle+ 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 {\sf 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 \verb+%+
% and \verb+\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 {\sf macrocode} environment one can also use the {\sf
% 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 \verb+\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
% \verb+\DescribeMacro{\DescribeMacro}+ to make clear that this is the
% point where the usage of \verb+\DescribeMacro+ is explained.
%
% \DescribeMacro\DescribeEnv
% An analogous macro \verb+\DescribeEnv+ should be used to indicate
% that a \LaTeX{} environment is explained. It will produce a somewhat
% different index entry. Below I used \verb+\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 \verb+%+ sign in the first column of every
% row, the {\sf 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 {\sf verbatim} environment which
%                      can be used inside of other macros.}
% \DescribeEnv{verbatim*}
% The {\sf verbatim$*$} environment is changed in the same way.
% \changes{v1.7a}{92/02/26}{Documented `verb change.}
% \DescribeMacro\verb
% The "\verb" command is re-implemented to give an error report if a
% newline appears in its argument. 
% The {\sf verbatim} and {\sf 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 {\sf 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
%                {\sl 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}{92/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: \verb+\MacrocodeTopsep+ and
% \verb+\MacroTopsep+ are used to control the vertical spacing above
% and below the {\sf macrocode} and the {\sf macro}
% \DescribeMacro\MacroIndent
% environment, \verb+\MacroIndent+ is used to indent the lines of code
% and
% \DescribeMacro\MacroFont \label{sec:macrofont}
% \verb+\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 
% style file (like {\tt ltugboat.sty}) use the \verb+\DocstyleParms+
% command described below.
%
%
%
%
% \subsection{Formatting the margins}
%
% \DescribeMacro\PrintDescribeMacro
% \DescribeMacro\PrintDescribeEnv
% \DescribeMacro\PrintMacroName
% As mentioned earlier, some macros and the {\sf macro} environment
% print their arguments in the margin. This is actually done by three
% macros which are user
% definable.\footnote{You may place the changed definitions in a
%                     separate style
%                     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
%                     {\tt \bslash let}
%                     these macros equal {\tt \bslash @gobble}.
%                     The doc style option won't redefine any existing
%                     definitions of these macros.}
% They are named \verb+\PrintDescribeMacro+, \verb+\PrintDescribeEnv+
% and \verb+\PrintMacroName+ (called by the {\sf macro} 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 `\verb+\+' has got a
% special \verb+\catcode+. In this case one can use
% \verb+\SpecialEscapechar+ to indicate which character is actually
% used to play the r\^ole of the `\verb+\+'. A scheme like this is
% needed because the {\sf macrocode} environment and its counterpart
% {\sf 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 \verb+\catcode+$\,$s.  The argument to
% \verb+\SpecialEscapechar+ is a single-letter control sequence, that
% is, one has to use \verb+\|+ for example to denote that `\verb+|+'
% is used as an escape character. \verb+\SpecialEscapechar+ only
% changes the behavior of the next {\sf macrocode} or {\sf
% macrocode$*$} environment.
%
%  The actual index entries created will all be printed with \verb+\+
% 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 {\sf
% macrocode} or {\sf 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
% \verb+\DisableCrossrefs+ in the driver file. To turn it on again
% just use
% \verb+\EnableCrossrefs+.\footnote{Actually,
%          {\tt\bslash EnableCrossrefs}
%          changes things more drastically; any following
%          {\tt\bslash DisableCrossrefs}
%          which might be present in the source will be ignored.}
%
%
% \DescribeMacro\DoNotIndex
% But also finer control is provided. The \verb+\DoNotIndex+ macro
% takes a list of macro names separated by commas. Those names won't
% show up in the index. You might use several \verb+\DoNotIndex+
% commands: their lists will be concatenated.  In this article I used
% \verb+\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 {\sf 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 {\sf
% macrocode} environment in the {\sf 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.
%
%
% \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 {\sf
% 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 style file which might be read in before the doc style
% option.
%
%  To allow the user to change the specific characters recognized by
%  his or her index program all characters which have special meaning
%  in the {\sf 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 \verb+\catcode+ other than
% `letter' (11).
%
% \DescribeMacro{\actualchar}
% The \verb+\actualchar+ is used to separate the `key' and the actual
% index entry.
% \DescribeMacro{\quotechar}
% The \verb+\quotechar+ is used before a special index program
% character to suppress its special meaning.
% \DescribeMacro{\encapchar}
%  The \verb+\encapchar+ separates the indexing information from a
% letter string which {\sf makeindex} uses as a \TeX{} command to
% format the page number associated with a special entry.  It is used
% in this style to apply the \verb+\main+ and the \verb+\usage+
% commands.
% \DescribeMacro{\levelchar}
%  Additionally \verb+\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
% To produce a main index entry for a macro the
% \verb+\SpecialMainIndex+ macro\footnote{This macro is called by the
% {\sf macro} environment.} may be used.  It is called `special'
% because it has to print its argument verbatim.
% \DescribeMacro\SpecialIndex
% If you want a normal index entry for a macro name
% \verb+\SpecialIndex+ might be used.\footnote{This macro is called
% within the {\sf macrocode} environment when encountering a macro
% name.}
% \DescribeMacro\SpecialUsageIndex
% \DescribeMacro\SpecialEnvIndex
% To index the usage of a macro or an environment
% \verb+\SpecialUsageIndex+ and \verb+\SpecialEnvIndex+ may be used.
% \DescribeMacro\SortIndex
% Additionally a \verb+\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+\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 \verb+\verbatimchar+. It expands
% by default to \verb?+?  but if your code lines contain macros with
% `{\tt +}' 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 \verb+\verbatimchar+ globally or locally to
% overcome this problem.
%
% \DescribeMacro\*
% We also provide a \verb+\*+ 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 {\sf makeindex} prior to 2.9 had some bugs affecting
% {\sf 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
% style 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 {\sf makeindex}
% from one of the \TeX{} repositories.
%
%
% \subsection{Setting the index entries}
%
% \changes{v1.7a}{92/03/11}{Usage note on gind.ist.}
% After the first formatting pass through the {\tt .doc} file you need
% to sort the index entries written to the {\tt .idx} file using {\sf
% makeindex} or your favourite alternative.  You need a suitable style
% file for {\sf makeindex} (specified by the {\tt -s} switch).  A
% suitable one is supplied with {\sf doc}, called {\tt gind.ist}.
%
% \DescribeMacro\PrintIndex
% To read in and print the sorted index, just put the
% \verb+\PrintIndex+ command as the last (commented-out, and thus
% executed during the documentation pass through the file) command
% in your style 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 \verb+\StopEventually+ macro, in
% which case a \verb+\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 `{\sf
% IndexColumns}' and can therefore be changed with a
% \verb+\setcounter+ declaration.  Additionally one doesn't want to
% start a new page unnecessarily.  Therefore the {\sf theindex}
% environment is redefined.
% \DescribeMacro\IndexMin
% When the {\sf theindex} environment starts it will measure how much
% space is left on the current page. If this is more than
% \verb+\IndexMin+ then the index will start on this page. Otherwise
% \verb+\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
% \verb+\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 {\sf 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 \verb+\columnssep+
% etc.)\ is controlled by the \verb+\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}
%  \verb+\parindent+    & \IndexParms \the\parindent    &
%  \verb+\columnsep+    & \IndexParms \the\columnsep    \\
%  \verb+\parskip+      & \IndexParms \the\parskip           &
%  \verb+\rightskip+    & \IndexParms 
%                         \expandafter\dimenvalue\the\rightskip  \\
%  \verb+\mathsurround+ & \IndexParms \the\mathsurround  &
%  \verb+\parfillskip+  & \IndexParms 
%                         \expandafter\dimenvalue\the\parfillskip      
%  \end{tabular}
% \end{center}
% \DescribeMacro{\@idxitem}
% Additionally it defines \verb+\@idxitem+ (which will be used when an
% \verb+\item+ command is encountered) and selects \verb+\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
% \verb+\main+ macro (underlining its argument) and the numbers
% denoting the description are encapsulated by the \verb+\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 {\tt doc}
% style, you can either put your declarations in the driver file (that
% is after {\tt doc.sty} is read in) or use a separate style file for
% doing this work. In the latter case you can define the macro
% \verb+\DocstyleParms+ to contain all assignments.  This
% indirect approach is necessary if your style file might be read
% before the {\tt doc.sty}, when some of the registers are not
% allocated.  Its default definition is null.
%
% The doc style option 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}
%  \verb+\IndexMin+      & \the\IndexMin    &
%  \verb+\MacroTopsep+   & \the\MacroTopsep    \\
%  \verb+\marginparwidth+& \the\marginparwidth  &
%  \verb+\MacroIndent+   & \the\MacroIndent \\
%  \verb+\marginparpush+ & \the\marginparpush    &
%  \verb+\MacrocodeTopsep+   & \the\MacrocodeTopsep \\
%  \verb+\tolerance+     & \the\tolerance  
%  \end{tabular}
% \end{center}
%
%
% \subsection{Additional bells and whistles}
%
% We provide macros for logos such as \Web, \AmSTeX, \BibTeX,
% \SliTeX{} and \PlainTeX. Just type \verb+\Web+, \verb+\AmSTeX+,
% \verb+\BibTeX+, \verb+\SliTeX+ or \verb+\PlainTeX+, respectively.
% \LaTeX{} and \TeX{} are already defined in {\tt latex.tex}.
%
% \DescribeMacro\meta
% Another useful macro is \verb+\meta+ which has one argument and
% produces something like \meta{dimen parameter}.
%
% \DescribeMacro\OnlyDescription
% \DescribeMacro\StopEventually
% You can use the \verb+\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 \verb+\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 \verb+\OnlyDescription+ declaration is
% missing the \verb+\StopEventually+
% \DescribeMacro\Finale
% macro saves its argument in a macro called \verb+\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 \verb+\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 {\sf pagestyle} on the title page the
% \verb+\maketitle+ command issues a \verb+\thispagestyle{titlepage}+
% declaration which produces a {\sf plain} page if the {\sf titlepage}
% page style is undefined.  This allows style files like {\sf
% ltugboat.sty} to define their own page styles for title pages.
%
% \DescribeMacro\IndexInput \label{..Input}
% Last but not least I defined an \verb+\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 {\tt
% latex.tex} getting a verbatim copy with about 15 pages
% index.\footnote{It took quit a long time and the resulting {\tt .idx}
%                file was longer than the {\tt .dvi} file.
%                Actually too long to be handled by the {\sf 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 \verb+\changes+
% command may be placed amongst the description part of the changed
% code.  It takes three arguments, thus:
% \begin{quote}
% \verb+\changes{+\meta{version}\verb+}{+\meta{date}\verb+}{+^^A
% \meta{text}\verb+}+
% \end{quote}
% The changes may be used to produce an auxiliary file (\LaTeX's
% \verb+\glossary+ mechanism is used for this) which may be printed
% after suitable formatting. The \verb+\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 {\sf 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 {\sf makeindex}
% versions.
%
% \changes{v1.7a}{92/02/26}{Description of `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 \verb+\PrintChanges+ command as the last
% (commented-out, and thus executed during the documentation pass
% through the file) command in your style file.  Alternatively, this
% command may form one of the arguments of the \verb+\StopEventually+
% command, although a change history is probably {\em not\/} required
% if only the description is being printed.
% The command assumes that {\sf makeindex} or some other program
% has processed the {\tt.glo} file to generate a sorted {\tt.gls} file.
% You need a special {\sf makeindex} style file; a suitable one is
% supplied with {\sf doc}, called {\tt 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{verbatim}
%%% \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         \~}
%%%
%\end{verbatim}
% at the beginning of the file then character translation failures
% will be detected, provided of course, that the used {\tt doc} option
% 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 {\tt docstrip.tex} program.} at the beginning
% of the lines should be typed in, since only the {\tt doc} option
% should look at this command.
%
% Another problem of mailing files is possible truncation.  To
% detect these sort of errors we provide a \verb+\CheckSum+ macro.
% The check-sum of a file is simply the number of backslashes in the
% code, i.e.\ all lines between the {\sf macrocode} environments.  But
% don't be afraid: you don't have count the code-lines yourself; this
% is done by the {\tt doc} style option for you.  You simply have to
% use the \verb+\StopEventually+ (which starts looking for backslashes)
% and the \verb+\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}
%    \verb+%%   \CheckSum{+\meta{number}\verb+}+
% \end{quote}
% and that's all. If you precede it only with one percent then the
% line will not show up in {\tt docstrip} versions of the file.
% You should do so whenever you are using conditional code (see
% {\tt 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 \verb+\+ without
% being able to use the \verb+\verb+ command because the
% \verb+\catcode+$\,$s of the symbols are already firmly
% established.  In this instance we can use the command
% \verb+\bslash+ presupposing, of course, that the actual font in
% use at this point contains a `backslash' as a symbol.  Note that
% this definition of \verb+\bslash+ is expandable; it inserts a
% $"\"_{12}$.  This means that you have to \verb+\protect+
% it if it is used in `moving arguments'.
%
% \DescribeMacro\MakePrivateLetters
% \changes{v1.7a}{92/02/26}{Documented `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\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
% \verb+"+, but you may prefer "|" if you have \verb+"+ 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}.  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 {\sf
% verbatim} and {\sf 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.
%
% \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules
% \DescribeMacro\Module \DescribeMacro\AltMacroFont
% The `module' directives of the {\sf docstrip} system
% \cite{art:docstrip} are normally 
% recognised and invoke special formatting.  This can be turned on and
% off in the {\tt .doc} 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\tt\it
% small italic type\-writer\/} by default in the New Font
% Selection Scheme but just ordinary {\small\tt 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 style file and by default
% produces results like \Module{+foo|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}{92/03/11}{Added basic usage summary to spell it out.}
%
% To sum up, the basic structure of a {\tt .doc} 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 {\tt doc.doc} 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
% {\sf doc.doc} after its publication in {\sl TUGboat\/} have been never
% properly described. Beside this splendid work he kindly provided
% additional code (like ``docstrip'' module formatting) which I think
% every {\sf doc.doc} user will be grateful for.
%
%
% \StopEventually{
%  \begin{thebibliography}{1}
%    \bibitem{book:Buerger}  {\sc 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} {\sc D. E. Knuth}.
%      \newblock Literate Programming.
%      \newblock Computer Journal, Vol.~27, {\it pp}.~97--111, May 1984.
%    \bibitem{book:KnuthA} {\sc D. E. Knuth}.
%      \newblock Computers \& Typesetting (The \TeX book).
%      \newblock Addison-Wesley, Vol. A, 1986.
%    \bibitem{art:Chen} {\sc L. Lamport}.
%      \newblock MakeIndex: An Index Processor for \LaTeX.
%      \newblock 17 February 1987.
%      \newblock (Taken from the file {\tt makeindex.tex} provided with
%      the program source code.)
%    \bibitem{art:doc} {\sc Frank Mittelbach}.
%      \newblock The {\tt doc}-option.
%      \newblock {\sl TUGboat}, Vol.~10(2), {\it pp}.~245--273, July
%        1989.
%    \bibitem{art:docstrip} {\sc Frank Mittelbach, Denys Duchier and
%         Johannes Braams}. 
%      \newblock {\tt docstrip.doc} (to appear).
%      \newblock The file is part of the DOC package.
%    \bibitem{book:Raspe} {\sc 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} {\sc Rainer Sch\"opf}.
%      \newblock A New Implementation of \LaTeX's {\tt verbatim} and
%      {\tt verbatim*} Environments.
%      \newblock File {\tt 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 {\tt doc.sty} after
% processing with {\tt docstrip} to include the module {\bf style}
% indicated here.  (All code in this file not appropriate to {\tt
% doc.sty} has to be included explicitly by docstrip so that this {\tt
% .doc} file can be used as directly as a style 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}
%<*style>
%    \end{macrocode}
% As always, we begin by identifying the latest version of this file
% on the VDU and in the {\sf log} file. But only if the macros are
% unknown to the system.  
% \changes{v1.5i}{89/06/07}{Avoid reading the file twice.}
%    \begin{macrocode}
\@ifundefined{macro@cnt}{}{\endinput} \typeout{Style-Option: `doc'
\fileversion \@spaces\space\space <\filedate> (FMi)} \typeout{English
   Documentation \@spaces\@spaces\space <\docdate> (DLo, FMi, RMCS)}
%    \end{macrocode}
% \DescribeMacro\fileversion
% \DescribeMacro\filedate
% \DescribeMacro\docdate
% As you can see I used macros like \verb+\fileversion+ to denote the
% version number and the date. They are defined at the very beginning
% of the style file (without a surrounding {\sf 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}
%    \SortIndex{\string^\string^A}{\string\verb\verbatimchar
%                                  \string^\string^A\verbatimchar
%                                  \encapchar main}
% }
%
%
% \subsection{Macros surrounding the `definition parts'}
%
% \begin{macro}{\macrocode}
%    Parts of the macro definition will be surrounded by the
%    environment {\sf 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.
%    \verb+\macrocode+ is defined completely analogously to
%    \verb+\verbatim+, but because a few small changes were carried
%    out, almost all internal macros have got new names.  We start by
%    calling the macro \verb+\macro@code+, the macro which bears the
%    brunt of most of the work, such as \verb+\catcode+ reassignments,
%    etc.
% \changes{v1.5r}{89/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 \verb+\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 \verb+\catcode+
%    changes local.
% \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)}
% \changes{v1.5t}{89/11/07}{Common code moved to `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 {\sf 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 \verb+\@beginparpenalty+, in order
%    to prevent a page break before such an environment.
%    \begin{macrocode}
   \@beginparpenalty \predisplaypenalty
%    \end{macrocode}
%    We then start a \verb+\trivlist+, set \verb+\parskip+ back to
%    zero and start an empty \verb+\item+.
%    \begin{macrocode}
   \trivlist \parskip \z@ \item[]%
%    \end{macrocode}
%    Additionally, everything should be set in {\tt 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 {\tt\bslash item}. Otherwise a change to
%                       {\tt\bslash baselineskip} will affect the
%                       paragraph above.}
%    \begin{macrocode}
   \macro@font
%    \end{macrocode}
%    Because \verb+\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 \verb+\par+
%    used in \verb+\verbatim+ and should result in blank lines being
%    shown as blank lines.
% \changes{v1.5l}{89/09/10}{Code line numbers supported.}
% \changes{v1.5t}{89/11/07}{Call `leavevmode to get `everypar on
%                           blank lines.}
% \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `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 \verb+\par+\,?  We use the macro
%   \verb+\obeylines+ of \cite{book:KnuthA} which changes all \verb+^^M+
%    to \verb+\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 \verb+\catcode+ $12$.
%    \begin{macrocode}
   \obeylines \let\do\@makeother \catcode`\`\active \@noligs \dospecials
%    \end{macrocode}
% \changes{v1.5t}{89/11/07}{Common code added.}
% \changes{v1.5w}{90/02/05}{Skip of `@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 {\tt 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
%    \verb+\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}
%    \verb+\ifblank@line+ is the switch used in the definition above.
%    In the original {\sf verbatim} environment the \verb+\if@tempswa+
%    switch is used. This is dangerous because its value may change
%    while processing lines in the {\sf macrocode} environment.
%    \begin{macrocode}
\newif\ifblank@line
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\endmacrocode}
%    Because we have begun a {\sf trivlist} environment in the {\sf
%    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}{89/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 \verb+\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 \verb+\MacroFont+ macro.
%    If the new font selection scheme is in use we suppress changes
%    of math fonts thereby making doc much faster.
% \changes{v1.5x}{90/02/17}{`math@fontsfalse added for new font sel.}
% \changes{v1.7a}{92/03/13}{Added `reset@font for NFSS.}
%    \begin{macrocode}
\@ifundefined{MacroFont}{%
  \ifx\undefined\selectfont
    \def\MacroFont{\small\tt}\else
    \def\MacroFont{\math@fontsfalse\reset@font\small\tt}\fi
  }{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\AltMacroFont}
% \begin{macro}{\macro@font}
% \changes{v1.7a}{92/03/12}{Added to support distinction of modules.}
% \changes{v1.7c}{92/03/26}{Altered font change for OFSS.}
% 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}{%
  \ifx\undefined\selectfont
    \def\AltMacroFont{\small\tt}\else
    \def\AltMacroFont{\math@fontsfalse\small\reset@font\it\tt}\fi
  }{}
\let\macro@font=\MacroFont
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\check@module}
% \begin{macro}{\ifpm@module}
% \changes{v1.7a}{92/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 {\tt
% 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}{92/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}{92/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}{92/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}{92/03/12}{Added.}
% 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 "%".
%    \begin{macrocode}
\def\ch@angle{\if<\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}{92/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}
\def\ch@plus@etc<{\futurelet\next\check@plus@etc}
\def\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
    \else
      \let\next\pm@module
    \fi\fi\fi\fi
    \next}
%    \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 {\tt 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}{92/03/12}{Added.} 
% \changes{v1.7i}{92/07/11}{Support for fonts depending on nesting.}
%    \begin{macrocode}
\def\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}{92/03/12}{Added.}
% \changes{v1.7f}{92/05/16}{Take account of nested guards.}
% \changes{v1.7i}{92/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}{92/07/17}{Support for fonts depending on module
%                           nesting}
%    \begin{macrocode}
\def\star@module#1>{%
  \Module{#1}%
  \global \advance \guard@level\@ne
  \ifnum \guard@level>\c@StandardModuleDepth
    \global\let\macro@font=\AltMacroFont \macro@font
  \fi}
\def\slash@module#1>{%
  \Module{#1}%
  \global \advance \guard@level\m@ne
  \ifnum \guard@level=\c@StandardModuleDepth
    \global\let\macro@font\MacroFont  \macro@font
  \fi
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%  \begin{macro}{\c@StandardModuleDepth}
% \changes{v1.7i}{92/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 |%<*style>| 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}{92/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}{92/03/12}{Added.}
% \changes{v1.7d}{92/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.
%    \begin{macrocode}
\@ifundefined{Module}{%
  \ifx\undefined\selectfont
    \def\Module#1{{\mod@math@codes$\fam\sffam\langle #1\rangle$}}
%    \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 {\sf oldlfont} or not.  I expect there's a better
% way\ldots
%    \begin{macrocode}
  \else
    \expandafter\ifx\csname ds@oldlfont\endcsname\relax
      \def\Module#1{{\mod@math@codes$\langle\sfmath{#1}\rangle$}}
    \else
      \def\Module#1{{\mod@math@codes$\langle{\sfmath #1}\rangle$}}
    \fi
  \fi}{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\mod@math@codes}
% \changes{v1.7c}{92/03/26}{Added.}
% As well as `words', the module directive text might contain any of the
% characters "*/+-,&|!()" for the current version of {\sf 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
% \verb+"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}{\sfmath}
% \changes{v1.7c}{92/03/26}{Added.}
% \changes{v1.7d}{92/04/25}{Use sans font for modules.}
% If NFSS is in use we need a new math alphabet which uses a sans serif
% font.
%    \begin{macrocode}
\ifx\selectfont\undefined
\else
  \ifx\sfmath\undefined
    \newmathalphabet*{\sfmath}{\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 \verb+\DocstyleParms+ macro.
% \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
% \changes{v1.5y}{90/02/24}{Default changed.}
% \changes{v1.6b}{90/06/15}{`rm moved before `scriptsize to
%                           avoid unnecessary fontwarning.}
%    \begin{macrocode}
\newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt
\newdimen\MacroIndent    
\settowidth\MacroIndent{\rm\scriptsize 00\ }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
%
% \begin{macro}{\macrocode*}
% \begin{macro}{\endmacrocode*}
%    Just as in the {\sf verbatim} environment, there is also a `star'
%    variant of the {\sf 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
%    \verb+\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 \verb+\macrocode*+. We start with the macro
%    \verb+\macro@code+ which prepares everything and then call the
%    macro \verb+\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, \verb+\sxmacro@code+ and then \verb+\end{macrocode*}+
%    (the macro, not the string), will be executed, so that for a
%    happy ending we still need to define the macro
%    \verb+\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 \verb+\xmacro@code+ expects an
%    argument delimited by the string \verb*+%    \end{macrocode}+.  At
%    the moment that this macro is called, the \verb+\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 \verb+\catcode+$\,$s which are available
%    within the {\sf macrocode} environment.
%    \begin{macrocode*}
\catcode`\{=12 \catcode`\}=12
\catcode`\%=12 \catcode`\ =\active \catcode`\\=\active
!%    \end{macrocode*}
!    Next follows the actual definition of  \verb+\macro@code+;
!    notice the
!    use of the new escape character.  We manage to get the argument
!    surrounded by the string \verb+\end{macrocode}+, but at the end
!    however, in spite of the actual characters used during the
!    definition of
!    this macro, \verb+\end+ with the argument \verb+{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 \verb+\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 \verb+\catcode+ changes have been made local by
!    commencing a
!    new group, there now follows the matching \verb+\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}{90/01/28}{Macro added.}
% \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.}
% \begin{macro}{\DescribeEnv}
% \begin{macro}{\Describe@Env}
% \changes{v1.5v}{90/01/28}{Macro added.}
% \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.}
%    The \verb+\DescribeMacro+ and \verb+\DescribeEnv+ macros should
%    print their arguments in the margin and produce an index entry.
%    We simply use \verb+\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 {\sf macro} environment.} First we change
%    to horizontal mode if necessary. The \LaTeX{} macros
%    \verb+\@bsphack+ and \verb+\@esphack+ are used to make those
%    commands invisible (i.e.\ to normalize the surrounding space and
%    to make the \verb+\spacefactor+ transparent).
% \changes{v1.5v}{90/01/28}{`MakePrivateLetters added.}
%    \begin{macrocode}
\def\DescribeMacro{\leavevmode\@bsphack
%    \end{macrocode}
%    When documenting the code for the {\tt amstex.sty} option we
%    encountered a bug: the \verb+\catcode+ of \verb+@+ was active and
%    therefore couldn't be used in command names. So we first have to
%    make sure that we get all \verb+\catcode+s right by calling
%    \verb+\MakePrivateLetters+ inside a group. Then we call
%    \verb+\Describe@Macro+ to do the work.
%    \begin{macrocode}
   \begingroup\MakePrivateLetters\Describe@Macro}
\def\Describe@Macro#1{\endgroup
              \marginpar{\raggedleft\PrintDescribeMacro{#1}}%
%    \end{macrocode}
%    Note the use of \verb+\raggedleft+ to place the output flushed
%    right. Finally we call a macro which produces the actual index
%    entry and finish with \verb+\@esphack+ to leave no
%    trace.\footnote{The whole mechanism won't work because
%                    of the {\tt\bslash leavevmode} in front.
%                    As a temporary change {\tt\bslash ignorespaces}
%                    is added.}
%    \begin{macrocode}
              \SpecialUsageIndex{#1}\@esphack\ignorespaces}
%    \end{macrocode}
%    The \verb+\DescribeEnv+ macro is completely analogous.
% \changes{v1.5v}{90/01/28}{`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
%    \verb+\reversemarginpar+ declaration. (This means that the {\tt
%    doc.sty} can't be used with all style options.) We also make the
%    \verb+\marginparpush+ zero and \verb+\marginparwidth+ suitably
%    wide.
% \changes{v1.5d}{89/4/28}{marginparwith 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}{92/02/26}{Moved `bslash documentation to `user
%                           interface' part}
%    We start a new group in which to hide the alteration of
%    \verb+\catcode+$\,$s, and make \verb+|+ introduce commands,
%    whilst \verb+\+ becomes an `other' character.
%
%    \begin{macrocode}
{\catcode`\|=\z@ \catcode`\\=12
%    \end{macrocode}
%    Now we are able to define \verb+\bslash+ (globally) to generate a
%    backslash of \verb+\catcode+ `other'.  We then close this group,
%    restoring original \verb+\catcode+$\,$s.
%    \SpecialEscapechar{\|}
%    \begin{macrocode}
|gdef|bslash{\}}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\verbatim}
% \begin{macro}{\verbatim*}
% \changes{v1.7i}{92/07/12}{Added changed definition for verbatim!*.}
%    The {\sf verbatim} environment holds no secrets; it consists of
%    the normal \LaTeX{} environment.  We also set the
%    \verb+\@beginparpenalty+ and change to the font given by
%    \verb+\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 \verb+\@verbatim+ macro so that it
%    suppresses \verb+%+ characters at the beginning of the line.  The
%    first lines are copied literally from {\tt latex.tex}.
% \changes{v1.7i}{92/07/12}{Added `@@par to clear possible `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}
%    \verb+\@verbatim+ sets \verb+^^M+, the end of line character, to
%    be equal to \verb+\par+.  This control sequence is redefined
%    here; \verb+\@@par+ is the paragraph primitive of \TeX.
%    \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `par from
%                             verbatim.sty} 
%    \begin{macrocode}
 \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par
          \penalty\interlinepenalty
%    \end{macrocode}
%    We add a control sequence \verb+\check@percent+ to the definition
%    of \verb+\par+ whose task it is to check for a percent character.
%    \begin{macrocode}
   \check@percent}%
%    \end{macrocode}
%    The rest is again copied literally from {\tt latex.tex} (less
%    "\tt").
% \changes{v1.7a}{92/02/26}{Removed redundant `tt.}
%    \begin{macrocode}
 \obeylines \catcode`\`\active \@noligs \let\do\@makeother
 \dospecials}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\check@percent}
%    Finally we define \verb+\check@percent+.  Since this must compare
%    a character with a percent sign we must first (locally) change
%    percent's \verb+\catcode+ so that it is seen by \TeX.  The
%    definition itself is nearly trivial: grab the following
%    character, check if it is a \verb+%+, and insert it again if not.
%    At the end of the {\sf verbatim} environment this macro will peek
%    at the next input line. In that case the argument to
%    \verb+\check@percent+ might be a \verb+\par+ or a macro with
%    arguments. Therefore we make the definition \verb+\long+
%    (\verb+\par+ allowed) and use the normal \verb+\next+ mechanism
%    to reinsert the argument after the \verb+\fi+ if necessary.
%  \changes{v1.5i}{89/06/07}{Definition changed to `long'}
%  \changes{v1.5i}{89/06/07}{Macro `next' used to guard against
%                            macro with arguments}
%    There is a subtle problem here, the equal sign between
%    \verb+\next+ and \verb+#1+ is actually necessary. Do you see why?
%    The omission of this token once caused a funny error.
%  \changes{v1.5u}{89/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}{92/02/27}{Now warns about newlines (from
%                           newdoc with `@noligs added).}
% We re-define "\verb" to check for newlines in its argument since a
% missing delimiter is difficult to detect in {\sf doc} source.
% Although the code is somewhat different, the
% method follows \cite{art:verbatim}, which should be
% consulted for commentary.  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.  (There's no particular reason for
% using lower-casing here to
% splice in the relevant character, rather than the upper-casing used in
% the definition of "\SpecialEscapechar"
% (\S\ref{sect:specialescapechar}); remember that the case
% shift doesn't touch the control sequence tokens.)
% \changes{v1.7a}{92/02/28}{Added math math check (from verbatim.sty).}
%    \begin{macrocode}
\begingroup
  \lccode`\~=`\^^M
  \lowercase{%
    \gdef\verb{\relax
      \ifmmode \hbox \else \leavevmode\null \fi
      \bgroup
      \tt   \catcode`\`\active \@noligs
      \let~\verb@err
      \catcode`\^^M\active
      \let\do\@makeother \dospecials
      \@ifstar\@sverb{\@vobeyspaces \frenchspacing \@sverb}}}
\endgroup
\def\verb@err{\egroup\@latexerr{\string\verb\space
               command ended by end of line.}\@ehc}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@sverb}
% \changes{v1.7a}{92/02/27}{Added for `verb change.}
% \changes{v1.7a}{92/02/28}{Now same as in verbatim.sty.}
% See \cite{art:verbatim} for commentary.
%    \begin{macrocode}
\def\@sverb#1{%
  \catcode`#1\active  \lccode`\~`#1%
  \lowercase{\let~\egroup}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\macro}
% \begin{macro}{\m@cro@}
% \changes{v1.5v}{90/01/28}{`macro@ renamed to `m@cro@ since AmSTeX
%      defines another macro of the same name.}
% \begin{macro}{\macro@cnt}
% \begin{macro}{\macro@level}
%    \label{page:macro} The {\sf macro} environment is implemented as
%    a {\sf 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
%    \verb+\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 {\sf macro} environments.
% \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
%    \begin{macrocode}
\newcount\macro@cnt \macro@cnt=0
\newcount\macro@level \macro@level=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-\verb+\catcode+ them before scanning the argument. This is
%    done by the \verb+\MakePrivateLetters+ macro.  On toplevel we
%    start with \verb+\begingroup+ otherwise we simply re-catcode the
%    special letters and call \verb+\m@cro@+. Therefore the
%    \verb+\endgroup+ at the start of this macro will cancel the group
%    opened by the \verb+\begin+ macro if we are already inside a {\sf
%    macro} environment. This avoids problems with the save-stack on
%    small systems since then the \verb+\trivlist+ used later on will
%    not put anything onto this stack.
% \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
% \changes{v1.7a}{92/02/26}{Catcode backslash to other (from newdoc).}
%    \begin{macrocode}
\def\macro{%
   \ifnum\macro@level=\z@ \begingroup \fi
   \catcode`\\12
   \MakePrivateLetters \m@cro@}
%    \end{macrocode}
%    After scanning the argument we close the group to get the normal
%    \verb+\catcode+$\,$s back. Then we assign a special value to
%    \verb+\topsep+ and start a {\sf trivlist} environment.
%    Additionally we advance the \verb+\macro@level+ counter to keep
%    track of the number of nested {\sf macro} environments.
% \changes{v1.5f}{89/5/07}{MacroTopsep parameter added.}
% \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
%    \begin{macrocode}
\long\def\m@cro@#1{\endgroup \topsep\MacroTopsep \trivlist
   \advance\macro@level\@ne
%    \end{macrocode}
% We also save the name being described in \verb+\saved@macroname+ for
% use in conjunction with the \verb+\changes+ macro.
%    \begin{macrocode}
   \edef\saved@macroname{\string#1}%
%    \end{macrocode}
%    Now there follows a variation of \verb+\makelabel+ which is used
%    should the environment not be nested, or should it lie between
%    two successive \verb+\begin{macro}+ instructions or explanatory
%    text.  One can recognize this with the switch \verb+\if@inlabel+
%    which will be \verb+true+ in the case of successive \verb+\item+
%    commands.
%    \begin{macrocode}
  \def\makelabel##1{\llap{##1}}%
%    \end{macrocode}
%    If \verb+@inlabel+ is \verb+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 \verb+\makelabel+ needs to be redefined
%    in this case.
%    \begin{macrocode}
  \if@inlabel
%    \end{macrocode}
%    If \verb+\macro@cnt+ has the value $1$, then we redefine
%    \verb+\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 {\sf verbatim} environment. To produce the real
%    definition we save the value of \verb+\macro@cnt+ in
%    \verb+\count@+ and empty the temp macro \verb+\@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 \verb+\hbox{\strut}+ to the definition of \verb+\@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 \verb+\makelabel+ together.
% \changes{v1.5b}{89/04/27}{vbox to vtop changed in makelabel (test)}
% \changes{v1.5e}{89/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 {\sf macro} environment is always at least one
%    after this point, but its toplevel definition is zero. Provided
%    this environment has been used correctly, $\verb+\macro@cnt+=0$
%    should not occur when $\verb+@inlabel+=\sf 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 \verb+@inlabel+ is false we reset \verb+\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 \verb+\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 \verb+\par+ which is forbidden in the argument of other macros
%    if they are not defined as \verb+\long+, or it is something like
%    \verb+\iffalse+ or \verb+\else+, i.e.\ something which will be
%    misinterpreted when \TeX{} is skipping conditional text. In both
%    cases \verb+\item+ will bomb, so we protect the argument by using
%    \verb+\string+.
%    \begin{macrocode}
  \edef\@tempa{\noexpand\item[\noexpand\PrintMacroName{\string#1}]}%
  \@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 \verb+\index+, but rather a command
%    \verb+\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
%    \verb+\SpecialMainIndex+ for our installation).
% \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
%    \begin{macrocode}
  {\advance\c@CodelineNo\@ne\SpecialMainIndex{#1}\nobreak}%
%    \end{macrocode}
%    The \verb+\nobreak+ is needed to prevent a page break after the
%    \verb+\write+ produced by the \verb+\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 \verb+\par+ and the conditionals are uncritical.
%    \changes{v1.7a}{92/03/02}{Removed redundant code checking for
%                             `par.}^^A
%    \begin{macrocode}
  \DoNotIndex{#1}%
%    \end{macrocode}
%    Because the space symbol should be ignored between the
%    \verb+\begin{macro}{...}+ and the following text we must take
%    care of this with \verb+\ignorespaces+.
%    \begin{macrocode}
  \ignorespaces}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
%
% \begin{macro}{\endmacro}
%    When ending a {\sf macro} environment we have to cancel the
%    \verb+\endgroup+ generated by the \verb+\end+ macro as long as we
%    are still inside another {\sf macro} environment. Therefore
%    we check the value of the \verb+\macro@level+ counter. Of course
%    this counter also has to be decremented.
%    \SpecialIndex{\macro@cnt}
% \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
%    \begin{macrocode}
\def\endmacro{%
   \endtrivlist
   \ifnum\macro@level>\@ne \advance\macro@level\m@ne \begingroup \fi}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\MacroTopsep}
%    Here is the default value for the \verb+\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}{\PrintDescribeMacro}
% \begin{macro}{\PrintDescribeEnv}
%    The formatting of the macro name in the left margin is done by
%    these macros. We first set a \verb+\strut+ to get the height and
%    depth of the normal lines. Then we change to the
%    \verb+\MacroFont+ using \verb+\string+ to \verb+\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 \verb+\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
%    \verb+\string+.
%    \begin{macrocode}
\@ifundefined{PrintDescribeEnv}
   {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{}
%    \end{macrocode}
% \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
%  `\verb+\+') providing indexing has been turned on with "\PageIndex"
%  or "\CodelineIndex".  With the default definitions of
%  \verb+\SpecialMainIndex+, etc., the index file generated is
%  intended to be processed by Chen's {\sf makeindex} program
%  \cite{art:Chen}.
%
%
%  Of course, in {\em this\/} style 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 \verb+\+ 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 {\sf 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 \verb+\SpecialEscapechar+ is used to denote a special
%    escape character for the next {\sf macrocode} environment. It has
%    one argument---the new escape character given as a
%    `single-letter' control sequence.  Its main purpose is defining
%    \verb+\special@escape@char+ to produce the chosen escape
%    character \verb+\catcode+$\,$d to 12 and
%    \verb+\active@escape@char+ to produce the same character but with
%    \verb+\catcode+ 13.
%
%    The macro \verb+\special@escape@char+ is used to {\em print\/}
%    the escape character while \verb+\active@escape@char+ is needed
%    in the definition of \verb+\init@crossref+ to start the scanning
%    mechanism.
%
%    In the definition of \verb+\SpecialEscapechar+ we need an
%    arbitrary character with \verb+\catcode+ 13. We use `\~{}' and
%    ensure that it is active. The \verb+\begingroup+ is used to make
%    a possible change local to the expansion of
%    \verb+\SpecialEscapechar+.
% \changes{v1.7g}{92/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
%    \verb+\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 \verb+\active@escape@char+ we place an
%    \verb+\uppercase+ command. Recall that the expansion of
%    \verb+\uppercase+ changes characters according to their
%    \verb+\uccode+, but leaves their \verb+\catcode+$\,$s untouched
%    (cf.\ \TeX{}book page 41).
%    \begin{macrocode}
     \uppercase{\gdef\active@escape@char{~}}%
%    \end{macrocode}
%    The definition of \verb+\special@escape@char+ is easier, we use
%    \verb+\string+ to \verb+\catcode+ the argument of
%    \verb+\SpecialEscapechar+ to 12 and suppress the preceding
%    \verb+\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
%    \verb+\escapechar+ as well as the \verb+\uccode+ and
%    \verb+\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 \verb+\init@crossref+ should fulfill the
%    following tasks:
%    \begin{itemize}
%       \parindent4em
%       \item[1)]
%          \verb+\catcode+ all characters used in macro names to
%          11 (i.e.\ `letter').
%       \item[2)]
%          \verb+\catcode+ the `\verb+\+' character to 13
%          (i.e.\ `active').
%       \item[3a)]
%          \verb+\let+ the `\verb+\+' equal \verb+\scan@macro+
%          (i.e.\ start the macro scanning mechanism) if there is
%          no  special escape character (i.e.\ the
%          \verb+\special@escape@char+ is `\verb+\+').
%       \item[3b)]
%          Otherwise \verb+\let+ it equal \verb+\bslash+, i.e.\
%          produce a printable \verb+\+.
%       \item[4)]
%          Make the \meta{special escape character} active.
%       \item[5)]
%          \verb+\let+ the active version of the special escape
%          character
%          (i.e.\ the expansion of \verb+\active@escape@char+) equal
%          \verb+\scan@macro+.
%    \end{itemize}
%    The reader might ask why we bother to \verb+\catcode+ the
%    `\verb+\+' first to 12 (at the end of \verb+\macro@code+) then
%    re-\verb+\catcode+ it to 13 in order to produce a $\verb+\+_{12}$
%    in case 3b) above.  This is done because we have to ensure that
%    `\verb+\+' has \verb+\catcode+ 13 within the {\sf macrocode}
%    environment.  Otherwise the delimiter for the argument of
%    \verb+\xmacro@code+ would not be found (parameter matching
%    depends on \verb+\catcode+$\,$s).
%
%    Therefore we first re-\verb+\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 `\verb+@+' character as a
%    `letter' in macros, we normally have to change its
%    \verb+\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 \verb+\catcode+ switching.
%    \SpecialEscapechar\|
%    \begin{macrocode}
    |MakePrivateLetters
%    \end{macrocode}
%    Now we \verb+\catcode+ the special escape character to 13 and
%    \verb+\let+ it equal \verb+\scan@macro+, i.e.\ fulfill tasks 4)
%    and 5). Note the use of \verb+\expandafter+ to insert the chosen
%    escape character saved in \verb+\special@escape@char+ and
%    \verb+\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
%    \verb+\SpecialEscapechar+ is \verb+\\+, the second last line will
%    overwrite the previous definition of $\verb+\+_{13}$.  In this
%    way all tasks are fulfilled.
%
%    For happy documenting we give default values to
%    \verb+\special@escape@char+ and \verb+\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 \verb+@+ 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 `\verb+\+'.
%    \begin{macrocode}
\def\close@crossref{\SpecialEscapechar\\}
%    \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{Macros for scanning macro names}
%
% \begin{macro}{\scan@macro}
% \changes{v1.5k}{89/09/04}{Support for checksum added.}
% \begin{macro}{\macro@namepart}
%    The \verb+\init@crossref+ will have made \verb+\active+ our
%    \verb+\special@escape@char+, so that each
%    \verb+\active@escape@char+ will invoke \verb+\scan@macro+ when
%    within the {\sf 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 {\sf
%    macrocode} environments.
%    \begin{macrocode}
\def\scan@macro{%
%    \end{macrocode}
%    First we output the character which triggered this macro.  Its
%    version \verb+\catcode+$\,$d to 12 is saved in
%    \verb+\special@escape@char+. We also call \verb+\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 {\sf macrocode} environment contains, for example, the
%    command \verb+\\+, the second \verb+\+ 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
%    \verb+\macro@namepart+ so this is initially cleared; we then set
%    \verb+\next+ to the {\it first\/} character following the
%    \verb+\+ and call \verb+\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 \verb+\futurelet+ call until after the final
%    \verb+\fi+.  If, on the other hand, the scanning is disabled we
%    simply \verb+\let+ \verb+\next+ equal `empty'.
%    \begin{macrocode}
   \else \let\next\@empty \fi
%    \end{macrocode}
%    Now we invoke \verb+\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}
%    \verb+\ifscan@allowed+ is the switch used above to determine if
%    the \verb+\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 \verb+\DisableCrossrefs+ is in force).
%    \begin{macrocode}
\def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack}
%    \end{macrocode}
%    The macro \verb+\EnableCrossrefs+ will also disable any
%    \verb+\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 \verb+\next+), we can determine whether it's a `letter'
%    (which probably includes \verb+@+).
%
%    If it is, we let \verb+\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 \verb+\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}{89/4/27}{Corrected bad bug by putting the
%                         scan@allowedfalse macro before printing
%                         the argument.}
% \changes{v1.7a}{92/03/10}{Ensure character stored in `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 {\sf macrocode} environment.
%
%    First we take a look at the \verb+\index@excludelist+ to see
%    whether this macro name should produce an index entry.  This is
%    done by the \verb+\ifnot@excluded+ macro which assumes that the
%    macro name is saved in \verb+\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,
%    \verb+\string+ is used to normalize it. 
%    \begin{macrocode}
\def\short@macro#1{\begingroup
   \catcode`\&=11  \uccode`\&=\expandafter`\string#1%
   \uppercase{\def\macro@namepart{&}}%
   \endgroup
   \ifnot@excluded
%    \end{macrocode}
%    If necessary the index entry is produced by the macro
%    \verb+\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
%    \verb+\scan@allowedfalse+ and print the actual character. The
%    index entry was generated first to ensure that no page break
%    intervenes (recall that a \verb+^^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 \verb+\macro@switch+ won't be called) if
%    cross-referencing is globally disabled.
%    \begin{macrocode}
    \scan@allowedtrue }
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\produce@index}
% \changes{v1.4s}{89/04/23}{Added noexpand to all {\tt\protect\bslash
%                if} tests
%               to avoid garbage produced by new active chars}
% \changes{v1.4s}{89/04/23}{Used {\tt\protect\bslash string} for the
%                          same reason.}
% \changes{v1.5c}{89/4/27}{Corrected bad bug by placing the
%                         scan@allowedfalse macro into short@macro}
%    This macro is supposed to generate a suitable \verb+\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 \verb+^^M+).  Using the \verb+\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
%    `\verb+\+' in case there was none) the \verb+\it@is@a+ macro is
%    used to produce the actual \verb+\SortIndex+ call.
%    \begin{macrocode}
     \scan@allowedfalse \it@is@a\special@escape@char \else
%    \end{macrocode}
%    Next comes the test for a `\verb+\+' which must be the
%    $\verb+\+_{13}$ expanding to \verb+\bslash+.
%    \begin{macrocode}
     \if\noexpand#1\bslash \it@is@a\bslash \else
%    \end{macrocode}
%    Another possibility is \verb*+ +$_{13}$. Recall that \verb+\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 {\tt \bslash @noligs} some days ago
%                      and now {\tt `} 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 \verb+^^M+\@.  In this case
%    we don't test for character codes, since it is easier to look if
%    the character is equal to \verb+\par+. (We are inside the {\sf
%    macrocode} environment.)
%    \begin{macrocode}
         \ifx#1\par
%    \end{macrocode}
%    If we end up here we have just scanned a \verb+\^^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 \verb+\relax+ we do nothing. This can't happen
%    when the `doc' option is used in the way described here, but was
%    added to allow extensions like the {\tt idxverb} option.
%  \changes{v1.5t}{89/11/14}{Added `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 {\sf makeindex} program. You can't produce unbalanced index
%    entries\footnote{This is possible for \TeX{} if you use
%                     {\tt\string{$_{12}$ \rm or \tt\string}$_{12}$},
%                     but {\sf makeindex} will complain.}
%    and you have to double a percent character. To get around these
%    restrictions we use special macros to produce the \verb+\index+
%    calls.\footnote{Brian {\sc 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 \verb+\it@is@a+.)
%    \begin{macrocode}
                 \it@is@a{\string#1}%
%    \end{macrocode}
%    We now need a whole pile of \verb+\fi+$\,$s to match up with
%    the \verb+\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
%    \verb+@+ symbols, or anything else which has a \verb+\catcode+ of
%    11).
%
%    To do this we add the `letter' to the existing definition of
%    \verb+\macro@namepart+ (which you will recall was originally set
%    to \verb+\@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
%    \verb+\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 \verb+\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
%    \verb+\macro@finish+.
%    \begin{macrocode}
     \else \let\next\macro@finish \fi
%    \end{macrocode}
%    Here's where we invoke whatever macro was \verb+\let+ equal to
%    \verb+\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 \verb+\index+ command (provided
%    the command name is not on the list of exclusions).  The
%    `\verb+\+' is already typeset; therefore we only have to output
%    all `letters' saved in \verb+\macro@namepart+.
%    \begin{macrocode}
\def\macro@finish{%
  \macro@namepart
%    \end{macrocode}
%    Then we call \verb+\ifnot@excluded+ to decide whether we have to
%    produce an index entry. The construction with \verb+\@tempa+ is
%    needed because we want the expansion of \verb+\macro@namepart+ in
%    the \verb+\index+ command.\footnote{The {\tt \bslash index}
%    command will expand its argument in the {\tt\bslash output}
%    routine.  At this time {\tt\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 {\tt
%                          \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}\verb+,+\meta{macro name}\verb+,+
% \ldots\verb+,+
% \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
%    \verb+\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 \verb+\do@not@index+ macro \verb+\long+
%    since the user might want to exclude the \verb+\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}{92/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}{92/02/26}{Replaced with newdoc version.}
% \begin{macro}{\expanded@notin}
%    Now we take a look at the \verb+\index@excludelist+ to see
%    whether a macro name saved in \verb+\macro@namepart+ should
%    produce an index entry. This macro is a pseudo \verb+\if+; it
%    should expand to \verb+\iftrue+ or \verb+\iffalse+ depending on
%    the contents of \verb+\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 \verb+\scan@macro+.  As already mentioned, the definitions given
% here presuppose that the \verb+.idx+ file will be processed by
% Chen's {\sf 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
% `\verb+\+'; this is achieved by issuing an \verb+\index+ command
% which contains the `actual' operator for {\sf makeindex}.  The
% default value for the latter operator is `\verb+@+', but the latter
% character is so popular in \LaTeX\ style files that it is necessary
% to substitute another character.  This is indicated to {\sf
% makeindex} by means of an `index style file'; the character selected
% for this function is \verb+=+, 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 {\tt gind.ist} and is generated from this source by
% processing with {\tt docstrip} to extract the module {\bf gind}.  A
% similar style file {\tt gglo.ist} is supplied for sorting the change
% information in the glossary file and is extracted as module {\bf
% gglo}.  First of all we add some information to the front of the
% {\tt .ist} files.  \changes{v1.7a}{92/03/11}{Gglo.ist and gind.ist
% now derivable from doc.doc with docstrip.}
%    \begin{macrocode}
%</style>
%<+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>%% style option. 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 \verb+\actualchar+,
%    \verb+\quotechar+ and \verb+\levelchar+. Note, that our defaults
%    are not the ones used by the {\sf makeindex} program without a
%    style file.
%    \begin{macrocode}
%<*style>
\@ifundefined{actualchar}{\def\actualchar{=}}{}
\@ifundefined{quotechar}{\def\quotechar{!}}{}
\@ifundefined{levelchar}{\def\levelchar{>}}{}
%</style>
%<+gind|gglo>actual '='
%<+gind|gglo>quote '!'
%<+gind|gglo>level '>'
%<*style>
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\encapchar}
%    The {\sf makeindex} default for the \verb+\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+\verb*+ command used in the definitions below.
%    \begin{macrocode}
\@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\SpecialIndex}
%    The \verb+\SpecialIndex+ command creates index entries for
%    macros.  If the argument is \verb+\+$xyz$, the command produces
%    \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}|
%    given the above defined defaults for \verb+\actualchar+,
%    \verb+\quotechar+ and \verb+\verbatimchar+.  We first remove the
%    initial `\verb+\+' to get a better index.
% \changes{v1.5s}{89/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 \verb+\quotechar+ is placed
%    before the \verb+*+ to allow its use as a special {\sf makeindex}
%    character.  Again \verb+\@bsphack+ and \verb+\@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}{\SpecialUsageIndex}
%    The \verb+\SpecialMainIndex+ macro is used to cross-reference the
%    names introduced by the {\sf macro} environment.  The action is
%    as for \verb+\SpecialIndex+, except that {\sf makeindex} is
%    instructed to `encap'sulate the entry with the string
%    \verb+|main+ to cause it to generate a call of the \verb+\main+
%    macro.
% \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
%    \begin{macrocode}
\def\SpecialMainIndex#1{\@bsphack\special@index{\expandafter\@gobble
                                        \string#1\actualchar
                                        \string\verb
                                        \quotechar*\verbatimchar
                                        \string#1\verbatimchar
                                        \encapchar main}%
                        \@esphack}
%    \end{macrocode}
%    The \verb+\SpecialUsageIndex+ is literally the same---only we use
%    {\tt usage} instead of {\tt main}.
%    \begin{macrocode}
\def\SpecialUsageIndex#1{\@bsphack\index{\expandafter\@gobble\string#1%
    \actualchar\string\verb\quotechar*\verbatimchar
    \string#1\verbatimchar
    \encapchar usage}\@esphack}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
%
% \begin{macro}{\SpecialEnvIndex}
%    Indexing environments is done a little bit differently; we produce
%    two index entries with the \verb+\SpecialEnvIndex+ macro:
%    \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{\tt #1} (environment)\encapchar usage}%
%    \end{macrocode}
%    The second entry is sorted as a subitem under the key
%    `environments:'. 
%    \begin{macrocode}
    \index{environments:\levelchar{\tt #1}\encapchar usage}\@esphack}
%    \end{macrocode}
%    Because both entries correspond to `descriptions' of the
%    environment, we encapsulate the page numbers with the
%    \verb+\usage+ macro.
% \end{macro}
%
%
%
% \begin{macro}{\SortIndex}
%    This macro is used to generate the index entries for any
%    single-character command that \verb+\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 \verb+\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 \verb+\quotechar+.
% \changes{v1.5s}{89/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}{89/11/05}{Support for code line no. (Undoc)}
% \begin{macro}{\RightBraceIndex}
% \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
%    These two macros fix the problems with {\sf makeindex}.  Note the
%    `hack' with \verb+\iffalse}\fi+ to satisfy both \TeX{} and the
%    {\sf makeindex} program. When this is written to the {\tt .idx}
%    file \TeX{} will see both braces (so we get a balanced text).
%    {\sf makeindex} will also see balanced braces but when the actual
%    index entry is again processed by \TeX{} the brace in between
%    \verb+\iffalse+ \verb+\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}{89/11/05}{Support for code line no. (Undoc)}
% \changes{v1.7c}{92/03/25}{Default now for bug-fixed makeindex}
% By default we assume a version of {\sf 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}{92/03/26}{Replaced `NewMakeIndex.}
% \begin{macro}{\percentchar}
%    Here is one solution for the percent bug in {\sf makeindex}.  The
%    macro \verb+\percentchar+ denotes a \verb+%+$_{12}$.
%    Calling this from a style option 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 {\sf index} environment}
%
%\changes{v1.4r}{89/04/22}{twocols env. placed into separate file}
%\changes{v1.4?}{89/04/19}{use DEK's algorithm and implement
%                         a twocols env.}
%\changes{v1.4?}{89/04/16}{changes to the index env.}
%\changes{v1.5a}{89/04/26}{Now input multicol.sty instead of
%                         multcols.sty}
% \begin{macro}{\ifhave@multicol}
% \changes{v1.7a}{92/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 style file, if possible.  The last page will be
%    reformatted with balanced columns.  This requires the {\sf
%    multicols} environment which is described elsewhere.
% ^^A  described elsewhere (see page~\xrefto{mittelbachmulti}).
%    So that {\sf doc} can be run independently of {\tt multicol.sty}
%    we first check for its existence and set the "have@multicol" flag
%    appropriately for use below.
%    \begin{macrocode}
\newif\ifhave@multicol
\openin\@ne multicol.sty
\ifeof\@ne \else \have@multicoltrue \fi
\closein\@ne \relax
%    \end{macrocode}
%    On systems where it is impossible to determine the existence of a
%    file using the above method the docstrip program can be directed
%    to force using multicol by including the next line.
% \changes{v1.7i}{92/07/14}{Force use of multicol.sty if necessary.}
%    \begin{macrocode}
%<+multicol>\have@multicoltrue
%    \end{macrocode}
% \end{macro}
%    If we found {\tt 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}
\ifhave@multicol \input{multicol.sty} \fi
%    \end{macrocode}
%
% \begin{macro}{\IndexMin}
% \begin{macro}{\c@IndexColumns}
%    \changes{v1.4t}{89/04/24}{Counter added.}
%    If {\tt multicol} is in use,
%    when the index is started we compute the remaining space on the
%    current page; if it is greater than \verb+\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
%    \verb+\c@IndexColumns+ which can be changed with a
%    \verb+\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
%    \verb+\c@IndexColumns+ \LaTeX{} counter declared above to denote
%    the number of columns and insert the `index prologue' text (which
%    might contain a \verb+\section+ call, etc.). See the default
%    definition for an example.
%    \changes{v1.4t}{89/04/24}{Incorporated new multicols env.}
%    \changes{v1.5a}{89/04/26}{Call multicols first}
%    \changes{v1.6e}{91/04/03}{Turned into env definition.}
%    \changes{v1.7a}{92/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 \verb+\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}{89/04/24}{Incorporated new multicols env.}
%    At the end of the index, we have only to end the {\sf multicols}
%    environment.
%    \begin{macrocode}
    {\end{multicols}}
%    \end{macrocode}
%    If we can't use {\sf multicols} we warn the user and use an
%    environment that's basically the one from {\tt article.sty}.
%    \begin{macrocode}
\else
  \typeout{Can't find multicols.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 {\sf makeindex} declarations. We disable
% scanning of macro names inside the index with "\scan@allowedfalse\n"
% to avoid recursion.
%    \begin{macrocode}
%</style>
%<+gind>preamble
%<+gind>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
%<+gind>postamble
%<+gind>"\n\n \\end{theindex}\n"
%<*style>
%    \end{macrocode}
%
%
% \begin{macro}{\IndexPrologue}
% \begin{macro}{\index@prologue}
%    The \verb+\IndexPrologue+ macro is used to place a short message
%    into the document above the index.  It is implemented by
%    redefining \verb+\index@prologue+, a macro which holds the
%    default text.  We'd better make it a \verb+\long+ macro to allow
%    \verb+\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
%    style file. If not we define it.
%    \begin{macrocode}
\@ifundefined{index@prologue}
     {\def\index@prologue{\section*{Index}%
                 \markboth{Index}{Index}%
                 The italic numbers denote the pages where the
                 corresponding entry is described,
                 numbers underlined point to the definition,
                 all others indicate the places where it 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 \verb+\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 {\sf makeindex} program generates an \verb+\indexspace+
%    before each new alphabetic section commences. After this final
%    definition we end the \verb+\@ifundefined+ and the definition of
%    \verb+\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 \verb+\efill+ is intended to be used after
%    index items which have no following text (for example, ``{\it
%    see\/}'' entries).  It just ensures that the current line is
%    filled, preventing ``\verb+Underfull \hbox+'' messages.
%    \begin{macrocode}
\def\efill{\hfill\nopagebreak}%
%</style>
%<+gind|gglo>item_x1   "\\efill \n \\subitem "
%<+gglo>item_x2   "\\ "
%<+gind>item_x2   "\\efill \n \\subsubitem "
%<*style>
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\pfill}
% \begin{macro}{\dotfil}
% \begin{macro}{\dotfill}
%     The following definitions provide the \verb+\pfill+ command; if
%    this is specified in the index style file to {\sf 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}%
%</style>
%<+gind|gglo>delim_0   "\\pfill "
%<+gind|gglo>delim_1   "\\pfill "
%<+gind|gglo>delim_2   "\\pfill "
%<*style>
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
%
% \begin{macro}{\*}
%    Here is the definition for the \verb+\*+ 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 {\it defining\/} entry for a macro name is flagged with the
%    string {\tt\encapchar main}\footnote{With the current definition
%    of {\tt\bslash encapchar} substituted for {\tt\encapchar}} in the
%    \verb+\index+ command; {\sf makeindex} processes this so that the
%    \verb+\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 \verb+\usage+ macro is used to indicate entries describing
%    the usage of a macro. The corresponding page number(s) will be
%    set in {\it italics}.
%    \begin{macrocode}
\@ifundefined{usage}{\def\usage#1{{\it #1}}}{}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\PrintIndex}
% \changes{v1.5k}{89/09/04}{`printindex changed to `PrintIndex.}
% \changes{v1.7a}{92/02/26}{Documentation moved to interface section.}
% \begin{macro}{\printindex}
%    This is the same as "\printindex" in the {\sf makeidx} style.
%    \begin{macrocode}
\def\PrintIndex{\@input{\jobname.ind}}
%    \end{macrocode}
%    Since this macro was called \verb+\printindex+ in older versions
%    of {\tt doc.sty} we also provide the following definition.
%    \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}
% \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
% {\sf makeindex} appropriately.  Unfortunately the specification for
% this changed sometime between versions 2.4 and 2.11 of {\sf
% makeindex}.  We provide both ways of doing it but unfortunately this
% will always produce a warning message from {\sf makeindex}.  This is
% for older versions:
%  \changes{v1.7h}{92/07/01}{Turn off headings in gls file}
%    \begin{macrocode}
%</style>
%<+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   "{\\bf\\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   "{\\bf\\hfil "
%<+gind,gglo>heading_suffix   "\\hfil}\\nopagebreak\n"
%<+gind>headings_flag       1
%<+gglo>headings_flag       0
%<*style>
%    \end{macrocode}
%
%
%
% \subsection[Dealing with the change history]
%            {Dealing with the change history\footnotemark}
% \footnotetext{The whole section was proposed by Brian {\sc Hamilton
%               Kelly}. He also documented and debugged the macros as
%               well as many other parts of this style option.}
%
% To provide a change history log, the \verb+\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 {\sf
% 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}{89/04/26}{Documented {\tt\protect\bslash changes}
%                         command.}
% \changes{BHK}{89/04/26}{Changed definition of
%                         {\tt\protect\bslash protect}.}
%    The output of
%    the \verb+\changes+ command goes into the \meta{Glossary\_File}
%    and therefore uses the normal \verb+\glossaryentry+
%    commands.\footnote{Note that a recent change in \LaTeX{} 2.09
%    changed the command name in the {\tt.glo} file from {\tt\bslash
%    indexentry} to {\tt\bslash glossaryentry}.  It is therefore
%    necessary to have a special {\sf makeindex} style file called {\tt
%    gglo.ist} to process this file correctly.} Thus {\sf makeindex}
%    or a similar program can be used to process the output into a
%    sorted ``glossary''.  The \verb+\changes+ command commences by
%    taking the usual measures to hide its spacing, and then redefines
%    \verb+\protect+ for use within the argument of the generated
%    \verb+\indexentry+ command. 
%
%    We re-code nearly all chars found in \verb+\sanitize+ to letter
%    since the use of special style options which make some characters
%    active might upset the \verb+\changes+ command when writing its
%    entries to the file. However we have to leave \verb+%+ as comment
%    and \verb*+ + as \meta{space} otherwise chaos will happen.
%    And, of course the \verb+\+ should be available as escape
%    character.
% \changes{v1.5v}{90/01/28}{`Re-code a lot of chars.}
% \changes{v1.5m}{89/09/20}{`actualchar in second level removed.}
% \changes{v1.5o}{89/09/24}{New sorting.}
% \changes{v1.6c}{90/06/29}{Again new sorting.}
%    \begin{macrocode}
\def\changes{\@bsphack\begingroup\@sanitize
   \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
   \changes@}
\def\changes@#1#2#3{%
  \def\protect##1{\string##1\space}%
  \edef\@tempa{\noexpand\glossary{#1\levelchar
                                 \expandafter\@gobble
                                 \saved@macroname\actualchar
                                 \string\verb\quotechar*%
                                 \verbatimchar\saved@macroname
                                 \verbatimchar:\levelchar #3}}%
  \@tempa\endgroup\@esphack}
%    \end{macrocode}
% \begin{macro}{\saved@macroname}
% \changes{BHK}{89/04/26}{Provided for sorting outside
%                         {\sf macro} environment}
%    The entries are sorted for convenience by the name of the most
%    recently introduced macroname (i.e., that in the most recent
%    \verb+\begin{macro}+ command).  We therefore provide
%    \verb+\saved@macroname+ to record that argument, and provide a
%    default definition in case \verb+\changes+ is used outside a {\sf
%    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 \verb+"+.)
%    \changes{v1.7a}{92/03/02}{Changed string used for better sorting.}
%    \begin{macrocode}
\def\saved@macroname{"General"}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\RecordChanges}
% \changes{BHK}{89/04/26}{Renames former {\tt\protect\bslash
%                         PrintChanges} command.}
%    To cause the changes to be written (to a {\tt.glo}) file, we
%    define \verb+\RecordChanges+ to invoke \LaTeX's usual
%    \verb+\makeglossary+ command.
%    \begin{macrocode}
\let\RecordChanges\makeglossary
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% 
% \begin{macro}{\GlossaryMin}
%    \changes{BHK}{89/04/26}{Added to support
%                            {\tt\protect\bslash changes}.}
% \begin{macro}{\c@GlossaryColumns}
%    \changes{BHK}{89/04/26}{Added to support
%                            {\tt\protect\bslash changes}.}
%    The remaining macros are all analogues of those used for the {\sf
%    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 \verb+\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
%    \verb+\c@GlossaryColumns+ which can be changed with a
%    \verb+\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}{89/04/26}{Added to support
%                            {\tt\protect\bslash changes}.}
% \changes{v1.5p}{89/09/28}{Now call `multicols first.}
%    \changes{v1.6e}{91/04/03}{Turned into env definition.}
%    \changes{v1.7a}{92/03/10}{Changed to work without multicols if
%                              necessary.}
% \begin{macro}{\endglossary}
%    \changes{BHK}{89/04/26}{Added to support
%                            {\tt\protect\bslash changes}.}
%    The environment {\sf theglossary} is defined in the same manner
%    as the {\sf 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 {\sf makeindex} declarations with scanning
% disabled as for the index.
%    \begin{macrocode}
%</style>
%<+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 {\tt gind.ist} is necessary if you have an
% up-to-date \LaTeX. 
%    \begin{macrocode}
%<+gglo>keyword "\\glossaryentry"
%<*style>
%    \end{macrocode}
%
%
% \begin{macro}{\GlossaryPrologue}
%    \changes{BHK}{89/04/26}{Added to support
%                            {\tt\protect\bslash changes}.}
% \begin{macro}{\glossary@prologue}
%    \changes{BHK}{89/04/26}{Added to support
%                            {\tt\protect\bslash changes}.}
%    The \verb+\GlossaryPrologue+ macro is used to place a short
%    message above the glossary into the document.  It is implemented
%    by redefining \verb+\glossary@prologue+, a macro which holds the
%    default text.  We better make it a long macro to allow
%    \verb+\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
%    style 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}{89/04/26}{Added to support
%                            {\tt\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}{89/04/26}{Added to support
%                            {\tt\protect\bslash changes}.}
%    To read in and print the sorted change history, just put the
%    \verb+\PrintChanges+ command as the last (commented-out, and thus
%    executed during the documentation pass through the file) command
%    in your style file.  Alternatively, this command may form one of
%    the arguments of the \verb+\StopEventually+ command, although a
%    change history is probably {\em not\/} required if only the
%    description is being printed.
%
%    The command assumes that {\sf makeindex} or some other program
%    has processed the {\tt.glo} file to generate a sorted {\tt.gls}
%    file.
%    \begin{macrocode}
\def\PrintChanges{\@input{\jobname.gls}}
%    \end{macrocode}
% \end{macro}
%
%    
%
%
%
% \subsection{Bells and whistles}
%
% \begin{macro}{\StopEventually}
% \changes{v1.5k}{89/09/04}{Support for checksum.}
% \begin{macro}{\Finale}
% \changes{v1.5k}{89/09/04}{Support for checksum.}
% \changes{v1.5z}{90/04/22}{Define `Finale globally.}
% \begin{macro}{\OnlyDescription}
%    Here is the default definition for \verb+\StopEventually+, we
%    simply save its argument in the macro \verb+\Finale+.
%    \begin{macrocode}
\long\def\StopEventually#1{\@bsphack\gdef\Finale{#1%
%    \end{macrocode}
%    But \verb+\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 call \verb+\check@checksum+ at this
%    point. 
%    \begin{macrocode}
              \check@checksum}%
%    \end{macrocode}
%    On the other hand: \verb+\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
%    \verb+\init@checksum+. 
%    \begin{macrocode}
           \init@checksum
           \@esphack}
%    \end{macrocode}
%    When the user places an \verb+\OnlyDescription+ declaration in
%    the driver file the document should only be typeset up to
%    \verb+\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 \verb+\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}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\meta}
% \changes{v1.4t}{89/04/24}{Macro added.}
% \begin{macro}{\m@ta}
% \changes{v1.5w}{90/02/03}{Breaks at space allowed.}
% \changes{v1.6a}{90/05/24}{Extra space bug corrected.}
%    The \verb+\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. We therefore define \verb+\meta+ in a way that a
%    \verb*+ + is active when the argument is scanned. Words are then
%    scanned into \verb+\hbox+es. The active \verb*+ + will end the
%    preceding \verb+\hbox+ add an ordinary space and open a new
%    \verb+\hbox+. In this way breaks are only possible at spaces.  It
%    would be even better to forbid page breaks but this is not
%    possible in an all cases.
%    \begin{macrocode}
\begingroup
\obeyspaces%
\catcode`\^^M\active%
%    \end{macrocode}
%    We have to be careful to end all lines with a \verb+%+ sign in
%    this definition.
%    \begin{macrocode}
\gdef\meta{\begingroup\obeyspaces\catcode`\^^M\active%
\let^^M\do@space\let \do@space%
%    \end{macrocode}
%    To allow to break up words inside the \verb+\meta+ command we
%    redefine the \verb+\-+ command. It now has to end the last
%    open box, add a discretionary and start the next one for the
%    rest of the current word. See below for more details.
%
%    Finally we call \verb+\m@ta+ which
%    will scan the argument of \verb+\meta+.
%    \begin{macrocode}
\def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\it}%
\m@ta}%
\endgroup
%    \end{macrocode}
%    We start \verb+\m@ta+ by opening an \verb+\hbox+.
%    Inside this box there will be angle brackets and the argument
%    typeset in italic typeface. If there are no spaces or \verb+\-+ 
%    commands in this argument the result will be a single box. But
%    when a space is encountered (which has \verb+\catcode+ 13) then
%    it will expand into \verb+\do@space+ which will close the current
%    box, output a space (so that we have a legitimate break point, and
%    then opens an new box to catch the rest of the argument.
% \changes{v1.6d}{90/11/16}{`leavevmode added.}
%    \begin{macrocode}
\def\m@ta#1{\leavevmode\hbox\bgroup$\langle$\it#1\/$\rangle$\egroup
%    \end{macrocode}
%    Finally, we have to close the group which was started in
%    \verb+\meta+ 
%    to restore all our changes.
%    \begin{macrocode}
    \endgroup}
%    \end{macrocode}
%    The \verb+\do@space+ macro will produce the possible breakpoint
%    by ending the current box (\verb+\egroup+) and adding the
%    \verb+\space+ 
%    into the surrounding paragraph.
%    \begin{macrocode}
\def\do@space{\egroup\space
%    \end{macrocode}
%    Then we start a new box, switching again to italic to catch the
%    rest of the argument of \verb+\meta+. But we also have to make sure
%    that any space following  directly will be ignored. Therefore we
%    check the following token and discard it as long as it is a token
%    with the meaning \verb+\do@space+, i.e.\ a $\verb*+ +_{13}$ or a
%    $\verb+^^M+_{13}$.
%    \begin{macrocode}
    \hbox\bgroup\it\futurelet\next\sp@ce}
\def\sp@ce{\ifx\next\do@space\expandafter\sp@@ce\fi}
\def\sp@@ce#1{\futurelet\next\sp@ce}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\IndexInput}
%    This next macro may be used to read in a separate file (possibly
%    a style 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
%    \verb+\trivlist+ as is normally done by a
%    \verb+\begin{macrocode}+ command.
%    \begin{macrocode}
     \begingroup \macro@code
%    \end{macrocode}
%    We also make spacing behave as in the {\sf 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 \verb+\trivlist+.
% \changes{v1.5t}{89/11/07}{Call `endmacrocode instead of `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
%    \verb+\relax+. We must cancel anything that may have been put
%    into \verb+\@thanks+, etc., otherwise {\em all\/} titles will
%    carry forward any earlier such setting!
%  \changes{v1.5j}{89/06/09}{thispagestyle plain removed}
%    \begin{macrocode}
\def\maketitle{\par
      \begingroup \def \thefootnote {\fnsymbol {footnote}}%
      \setcounter {footnote}\z@
      \def \@makefnmark {\hbox to \z@{$^{\@thefnmark }$\hss }}%
      \if@twocolumn \twocolumn [\@maketitle ]%
      \else \newpage \global \@topnum \z@ \@maketitle \fi
%    \end{macrocode}
% \changes{v1.5k}{89/09/04}{Added {\tt\protect\bslash ps@titlepage}}
%    For special formatting requirements (such as in TUGboat), we use
%    pagestyle \verb+titlepage+ for this; this is later defined to be
%    \verb+plain+, unless already defined, as, for example, by
%    \verb+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}{89/09/04}{Added {\tt\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 style option such as {\sf
%    ltugboat} can define this macro in advance.  However, if no such
%    definition exists, we use pagestyle {\tt plain} for title pages.
%    \begin{macrocode}
\@ifundefined{ps@titlepage}
    {\let\ps@titlepage=\ps@plain}{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\MakeShortVerb}
% \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters
%                           `dospecials, `@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
% {\sf verbatim} and {\sf 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".
%    \begin{macrocode}
\def\MakeShortVerb#1{%
  \typeout{*** Made \expandafter\@gobble\string#1\space a short
           reference for \string\verb \on@line\space ***}%
  \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~%
    \gdef~{\verb~}}%
  \endgroup
%    \end{macrocode}
% Finally the character is made active.
%    \begin{macrocode}
  \global\catcode`#1\active}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\DeleteShortVerb}
% \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters
%                           `dospecials, `@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}{92/02/28}{Check for previous matched `MakeShortVerb
%                           to avoid error.}
%    \begin{macrocode}
\def\DeleteShortVerb#1{%
  \expandafter\ifx\csname cc\string#1\endcsname\relax
  \else
    \typeout{*** Deleted \expandafter\@gobble\string#1\space as short
             reference for \string\verb \on@line\space ***}%
    \rem@special{#1}%
    \global\catcode`#1\csname cc\string#1\endcsname
    \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}{\add@special}
% \changes{v1.7a}{92/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}{92/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}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\MakeShortverb}
% \begin{macro}{\DeleteShortverb}
% \changes{v1.7a}{92/02/27}{Added (from newdoc).}
% These commands from {\sf 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}{89/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}{89/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
         \errhelp\wrong@checksum
         \errmessage{Checksum not passed 
                    (\the\check@sum<>\the\bslash@cnt)}%
        \fi
     \fi
     \global\check@sum\z@}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\check@sum}
% \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
% \begin{macro}{\bslash@cnt}
% \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
% \begin{macro}{\wrong@checksum}
% \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
% We need to define the counter for the number of backslashes counted
% ("\bslash@cnt") and the value advertised by the file ("\check@sum")
% as well as a help message for when things go wrong.
%    \begin{macrocode}
\newcount\check@sum           \check@sum  = \z@
\newcount\bslash@cnt          \bslash@cnt = \z@
\newhelp\wrong@checksum
   {The currently documented file seems to be wrong.^^J%
    Try to get a correct version.}%
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\CheckSum}
% \changes{v1.5k}{89/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}{89/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}{89/09/20}{Macro added to check character translation
%                           problems.}
% \changes{v1.5q}{89/11/01}{Made character table more readable.}
% \changes{v1.5t}{89/11/07}{Make \string\~{} letter in chartable
%                           macros.} 
% \changes{v1.5u}{89/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
         \errhelp\wrong@table
         \errmessage{Character table corrupted}%
         \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}{92/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 {\sf macro}
% environment. 
% 
% 
% \begin{macro}{\codeline@index}
% Indexing by code line is controlled by the "codeline@index" switch.
% \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
% \changes{v1.7a}{92/02/24}{Documented code line no. support.}
%    \begin{macrocode}
\newif\ifcodeline@index \codeline@indexfalse
%    \end{macrocode}
% \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}{92/08/14}{Added `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}{89/11/14}{Added `PageIndex and `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}{89/09/10}{Counter added to support code line numbers.}
% \changes{v1.5y}{90/02/24}{Default changed.}
% \changes{v1.6b}{90/06/15}{`rm moved before `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}{92/02/25}{Existing definition not overwritten.}
% \changes{v1.7a}{92/03/12}{Use `reset@font for NFSS.}
% This provides a hook to control the format of line numbers which may
% be defined in a style file.
%    \begin{macrocode}
\@ifundefined{theCodelineNo}
  {\ifx\selectfont\undefined
     \def\theCodelineNo{\rm\scriptsize\arabic{CodelineNo}}%
   \else
     \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}%
   \fi}
  {} 
%    \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{Layout Parameters for documenting style files}
%
% \begin{macro}{\tolerance}
%    People documenting style files would probably rather have things
%    ``sticking out'' in overfull \verb+\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 \verb+\mathcode+ definitions allow the characters
% `\verb+\+'
% and `{\tt @}' to appear in \verb+\tt+ 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 {\tt\bslash mathcode} of
%                {\tt\bslash} was defined to be {\tt "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 {\tt\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 $\verb+\@abc+=1$.
%
% If an {\em old\/} version of the {\sf german} style option is in
% force, then the `\verb+"+' character is active and would upset the
% definition of the \meta{16-bit number} quantities below, therefore
% we change the \verb+\catcode+ of \verb+"+ inside a group, and use
% \verb+\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
%    \verb+\MacrocodeTopsep+ and \verb+\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 style
%    file (like {\tt ltugboat.sty} for example) since the registers are
%    undefined before {\tt doc.sty} is read in.  The default values
%    for the internal registers are scattered over this file.
% \changes{v1.5u}{89/11/14}{`DocStyleParms now empty}
%    \begin{macrocode}
\@ifundefined{DocstyleParms}{}{}
%    \end{macrocode}
%    Now we allow overwriting the values by calling
%    \verb+\DocstyleParms+.
%    \begin{macrocode}
\DocstyleParms     \let\DocstyleParms\relax
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\AmSTeX}
%   \changes{v1.5j}{89/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 style 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{$\cal A\kern-.2em\lower.376ex%
        \hbox{$\cal M$}\kern-.2em\cal S$-\TeX}}}{}
\@ifundefined{BibTeX}
   {\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em%
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{}
\@ifundefined{SliTeX}
   {\def\SliTeX{{\rm S\kern-.06emL\kern-.18em\raise.32ex\hbox
                {\sc i}\kern -.03em\TeX}}}{}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\PlainTeX}
% \changes{v1.5g}{89/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{{\sc Plain}\kern2pt\TeX}}{}
\@ifundefined{Web}{\def\Web{{\sc Web}}}{}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \subsection{Changing the {\tt\protect\bslash catcode} of \%}
%
% \begin{macro}{\MakePercentIgnore}
% \begin{macro}{\MakePercentComment}
%    And finally the most important bit: we change the \verb+\catcode+
%    of `\verb+%+' 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 \verb+\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
%    \verb+\DocInput+ macro which was introduced in version v1.5l
%    (or so) of
%    the {\tt doc} style option. In older versions
%    \verb+\MakePercentIgnore+ was placed at the very end of {\tt
%    doc.sty}.
%    \begin{macrocode}
\def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
%    \end{macrocode}
% \end{macro}
% We can now finish the {\tt docstrip} main module.
%    \begin{macrocode}
%</style>
%    \end{macrocode}
%
%
%  \begin{macro}{\on@line}
%    Finally something for people with an old \LaTeX:
% \changes{v1.7k}{92/08/24}{Macro and test added.}
%    \begin{macrocode}
\ifx\on@line\undefined
  \def\on@line{ on input line \the\inputlineno}
  \errhelp{Support for input line numbers has been added
           to latex.tex <dec91>.^^J^^J%
           Please update to a newer LaTeX release.}
  \errmessage{Obsolete LaTeX release (older than Dec.91)}
\fi
%    \end{macrocode}
%  \end{macro}
%
% \Finale
% \PrintIndex \PrintChanges
\endinput