path: root/macros/latex/base/doc.dtx

% \iffalse meta-comment
%
% Copyright (C) 1993-2024
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the LaTeX base system.
% -------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
%
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
%
% \fi
% ^^A -*-LaTeX-*-
%
% ^^A These shouldn't come out in .ist files, hence the module
% ^^A comments, or in the printed version, hence temporary comment
% ^^A category for `<'
%\catcode`\<=14
%<+package|shortvrb>\NeedsTeXFormat{LaTeX2e}[1994/12/01]
%<+package>
% Any rollback request before 2016-02-15 we try to fullfil with the 2016 version:
%<+package>\DeclareRelease{}{1994-06-01}
%<+package>                      {doc-2016-02-15.sty}
%<+package>\DeclareRelease{v2.1g}{2016-02-15}
%<+package>                      {doc-2016-02-15.sty}
%<+package>\DeclareRelease{v2}{2021-06-01}
%<+package>                   {doc-2021-06-01.sty}
%<+package>\DeclareCurrentRelease{v3}{2022-06-01}
%<+package>
%<+package>\ProvidesPackage{doc}
%<+shortvrb>\ProvidesPackage{shortvrb}
%<+package|shortvrb>  [2024/04/26 v3.0p
%<+package|shortvrb>   Standard LaTeX documentation package V3 (FMi)]
%\catcode`\<=12
%
%%
%\iffalse    This is a METACOMMENT
%           Everything up to the next `\ fi' (without a blank) will
%           be ignored.  This is necessary because `%' may no longer
%           be a comment mark when this file is read in.
%
%
%% Package `doc' to use with LaTeX 2e
%% Copyright (C) 1989-2023 Frank Mittelbach, all rights reserved.
%
%
% Version:     Date:     Changes:
%
%  1.0a        5.5.88    This is nothing but a collection of tests and
%                        hacks. It is certainly going to be greatly
%                        changed.
%                        Better not to use it!
%  1.5a and earlier...   are not longer recorded
%  1.5b and higher...    are documented with the (undocumented) \changes
%                        feature.
%\fi
%  \changes{v1.5f}{1989/04/29}{Thanks to Brian who documented the
%                          \cs{changes} macro feature.}
%  \changes{v1.5g}{1989/05/07}{MacroTopsep now called MacrocodeTopsep and
%                          new MacroTopsep added}
%  \changes{v1.5h}{1989/05/17}{All lines shortened to <72 characters}
%  \changes{v1.5j}{1989/06/09}{Corrections by Ron Whitney added}
%  \changes{v1.5q}{1989/11/03}{`\ldots{}Listing macros renamed to
%                         `\ldots{}Input. Suggested by R. Wonneberger}
%  \changes{v1.5w}{1990/02/05}{Counter codelineno renamed to CodelineNo}
%  \changes{v1.9a}{1993/12/02}{Upgrade for LaTeX2e}
%  \changes{v1.9d}{1993/12/20}{Protected changes entry.}
%  \changes{v1.0p}{1994/05/21}{Use new error commands}
%  \changes{v3.0m}{2022/11/13}{Redefinitions of \cs{verb} removed as
%     no longer needed (gh/953)}
%
%
% \hyphenation{make-index}
%
% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
% \DoNotIndex{\@flushglue,\@gobble,\@input}
% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
% \DoNotIndex{\mathcal,\csname,\def,\documentstyle,\dospecials,\edef}
% \DoNotIndex{\egroup}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
% \DoNotIndex{\ifcase}
% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
% \DoNotIndex{\strutbox}
% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
% \DoNotIndex{\nopagebreak}
% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
% \DoNotIndex{\[,\{,\},\]}
% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
% \DoNotIndex{\baselineskip,\begin,\tw@}
% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
% \DoNotIndex{\bfdefault}
%
% \MakeShortVerb{\|}
% \setcounter{StandardModuleDepth}{1}
%
% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print a
% \gdef\dimenvalue#1pt{$#1$pt}}  ^^A register value with a - sign
%
% \newcommand{\DOC}{\texttt{doc}\xspace}
%
% \changes{v3.0j}{2022/06/02}{Use \cs{providecommand} to define \cs{pkg}}
% \providecommand\env{\texttt}
% \providecommand\opt{\texttt}
% \providecommand\cls{\texttt}
% \providecommand\pkg{\texttt}
% \providecommand\prg{\textsf}
%
% \newcommand\DOX{\env{DoX}\xspace}
% \newcommand\api{\textsc{api}\xspace}
%
% \newcommand\fmi[1]{\par\textbf{TODO: }\textit{#1}\par}
%
% \newcommand\NewIn[1]{\leavevmode
%         \marginpar{\hfill\fbox{\fbox{New in #1}}\hspace*{1em}}\ignorespaces}
%
%
%\RenewDocElement[macrolike = true ,
%		 toplevel  = false,
%                idxtype   = ,
%                idxgroup  = LaTeX commands\actualchar\LaTeX{} commands ,
%                printtype =
%               ]{Macro}{macro}
%
%\RenewDocElement[macrolike = false ,
%		 toplevel  = false,
%                idxtype   = env.  ,
%                idxgroup  = Package environments,
%                printtype = \textit{env.}
%               ]{Env}{environment}
%
%
%\NewDocElement[macrolike = true ,
%               toplevel  = false,
%               idxtype   = ,
%               idxgroup  = Package commands,
%               printtype =
%               ]{InterfaceMacro}{imacro}
%
%\NewDocElement[macrolike = true ,
%		 toplevel  = false,
%                idxtype   = ,
%                idxgroup  = Package commands (obsolete),
%                printtype =
%               ]{ObsoleteInterfaceMacro}{omacro}
%
%\NewDocElement[macrolike = false ,
%		 toplevel  = false,
%                idxtype   =  counter  ,
%                idxgroup  = LaTeX counters\actualchar \LaTeX{} counters ,
%                printtype = \textit{counter}
%               ]{LaTeXCounter}{lcounter}
%
%\NewDocElement[macrolike = true ,
%		 toplevel  = false,
%                idxtype   =  counter  ,
%                idxgroup  = TeX counters\actualchar \protect\TeX{} counters ,
%                printtype = \textit{counter}
%               ]{TeXCounter}{tcounter}
%
%
%\NewDocElement[macrolike = true ,
%		 toplevel  = false,
%                idxtype   =  skip  ,
%                idxgroup  = LaTeX length\actualchar \LaTeX{} length (skip) ,
%                printtype = \textit{skip}
%               ]{LaTeXSkip}{lskip}
%
%\NewDocElement[macrolike = true ,
%		 toplevel  = false,
%                idxtype   =  dimen  ,
%                idxgroup  = LaTeX length\actualchar \LaTeX{} length (dimen) ,
%                printtype = \textit{dimen}
%               ]{LaTeXDimen}{ldimen}
%
%\NewDocElement[macrolike = false ,
%		 toplevel  = false,
%                idxtype   = option  ,
%                idxgroup  = Package options ,
%                printtype = \textit{option}
%               ]{Option}{option}
%
% \renewcommand\code[1]{\mbox{$\ell$-#1}}
% \renewcommand\main[1]{\underline{\mbox{$\ell$-#1}}}
% \setcounter{IndexColumns}{2}
%
%
% \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}}
% \GetFileInfo{doc.sty}
%
% \CheckSum{0}
%
% \title{The \DOC{} and \texttt{shortvrb} Packages\thanks
%    {This file has version number \fileversion{} dated \filedate{}.}}
% \author{Frank Mittelbach\thanks{Further commentary added at Royal
%        Military College of Science by B. Hamilton Kelly; English
%        translation of parts of the original German commentary
%        provided by Andrew Mills; fairly substantial additions,
%        particularly from \texttt{newdoc},  and
%        documentation of post-v1.5q features added at v1.7a by Dave
%        Love (SERC Daresbury Lab).}~\thanks
%        {Extraction of \texttt{shortvrb}
%        package added by Joachim Schrod (TU~Darmstadt).}~\thanks
%        {Version~3 now integrates code from Didier Verna's
%        \DOX package and some of his documentation was
%        reused (a.k.a.\ stolen).}}
% \date{Printed \today}
%
% \MaintainedByLaTeXTeam{latex}
%
% \maketitle
%
% \begin{abstract}
%    Roughly 30 years ago (version 1.0 was dated 1988/05/05) I wrote
%    the first version of the \DOC package, a package to provide code
%    documentation for \TeX{} code. Since then it has been used all
%    over the place to document the \LaTeX{} kernel and most of the
%    packages that are nowadays available. The core code of version 2
%    (which is the current version) exists since 1998, i.e., for 20
%    years.
%
%    If I would restart from scratch I would do a lot of things
%    differently these days and in fact several other people have
%    tried to come up with better solutions. However, as the saying
%    goes, a bad standard is better than none, \DOC has prevailed and
%    changing it now in incompatible ways is probably not really
%    helpful.
%
%    So this is version 3 of the package with some smaller extensions
%    that are upwards compatible but hopefully serve well. Most
%    important modifications are the integration of the
%    \pkg{hypdoc} package to enable links within the document (in
%    particular from the index) if so desired. Also integrated are the
%    ideas from the \DOX package by Didier Verna (although I
%    offer a different interface that imho fits better with the rest
%    of \DOC's interfaces). Finally I updated a few odds and ends.
% \end{abstract}
%
%
% \newpage
%
% \addtocontents{toc}{\protect\begin{multicols}{2}}
%
% ^^A{\parskip 0pt                ^^A We have to reset \parskip
%                              ^^A (bug in \LaTeX)
% \tableofcontents
% ^^A}
%
% \changes{v1.7a}{1992/02/25}{Miscellaneous small changes to the text}
% \changes{v3.0a}{2018/03/04}{Integrated DoX package}
% \changes{v3.0a}{2018/03/04}{Interfaced hypdoc package}
%
%
%
% \section{Introduction}
%
% This is a new version of the \DOC package, written roughly 30 years
% after the initial release. As the package has been used for so long
% (and largely unchanged)
% it is absolutely important to preserve existing interfaces, even if
% we can agree that they could have been done better.
%
% So this is a light-weight change, basically adding hyperlink support
% and adding a way to provide generally \DOC elements (not just macros
% and environments) and try to do this properly (which wasn't the case
% for environments either in the past). The ideas for this have been
% stolen from the \DOX package by Didier Verna even though I
% didn't keep his interfaces.
%
% Most of the documentation below is from the earlier release  which
% accounts for some inconsistencies in presentation, mea culpa.
%
%
% \section{The User Interface}\label{sec:interface}
% \subsection{The driver file}
%
% If one is going to document a set of macros with the \DOC{}
% package one has to prepare a special driver file which produces the
% formatted document. This driver file has the following
% characteristics:
% \begin{quote}
% \noindent |\documentclass|\oarg{options}^^A
%           \marg{document-class}\\[1pt]
% |\usepackage{doc}|\\[3pt]
% \hspace*{10pt}\meta{preamble}\\[3pt]
% |\begin{document}|\\[3pt]
% \hspace*{10pt}\meta{special input commands}\\[3pt]
% |\end{document}|
% \end{quote}
% The \meta{document-class} might be any document class, I usually
% use \texttt{article}.
%
% In the \meta{preamble} one should place declarations which
% manipulate the behavior of the \DOC{} package like
% |\DisableCrossrefs| or |\OnlyDescription|.
%
%
% \DescribeInterfaceMacro\DocInput \DescribeInterfaceMacro\IndexInput
% Finally
% the \meta{special input commands} part should contain one or
% more |\DocInput|\marg{file name} and/or
% |\IndexInput|\marg{file name} commands.  The
% |\DocInput| command is used for files prepared for the
% \DOC{} package whereas |\IndexInput| can be used for all kinds of
% macro files.  See page \pageref{..Input} for more details of
% |\IndexInput|.  Multiple |\DocInput|s can be used with a
% number of included files which are each self-contained
% self-documenting packages---for instance, each containing
% |\maketitle|.
%
% As an example, the driver file for the \DOC{} package itself is
% the following text surrounded by |%<*driver>| and |%</driver>|.
% To produce the documentation you can simply run the \texttt{.dtx}
% file through \LaTeX{} in which case this code will be executed
% (loading the document class \texttt{ltxdoc}, etc.) or you can
% extract this into a separate file by using
% the \texttt{docstrip} program.
% The line numbers below are added by
% \DOC{}'s formatting.
% Note that the class \cls{ltxdoc} has the \DOC{} package
% preloaded.
% \changes{v1.7a}{1992/03/06}{Added
%                 docstrip-derivable driver file as example.}
% \changes{v1.7c}{1992/04/01}{Expurgated ltugboat.sty from driver.}
%    \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}

\usepackage[T1]{fontenc}
\usepackage{xspace}          

\OnlyDescription

\EnableCrossrefs
 %\DisableCrossrefs     % Say \DisableCrossrefs if index is ready
\CodelineIndex
\RecordChanges          % Gather update information
\SetupDoc{reportchangedates}
 %\OnlyDescription      % comment out for implementation details
\setlength\hfuzz{15pt}  % don't show so many
\hbadness=7000          % over- and underfull box warnings
\begin{document}
   \DocInput{doc.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%
% \RecordIndexType{\CodelineIndex}{InterfaceMacro}
% \RecordIndexType{\DisableCrossrefs}{InterfaceMacro}
% \RecordIndexType{\DocInput}{InterfaceMacro}
% \RecordIndexType{\EnableCrossrefs}{InterfaceMacro}
% \RecordIndexType{\OnlyDescription}{InterfaceMacro}
% \RecordIndexType{\RecordChanges}{InterfaceMacro}
% \RecordIndexType{\hbadness}{TeXCounter}
% \RecordIndexType{\hfuzz}{LaTeXDimen}
%
%
% \subsection{Package options}
%
% \NewIn{v3}
% Starting with version~3 the \DOC package now offers a small number
% of package options to modify its overall behavior. These are:
% \DescribeOption[noprint]{multicol}
% \DescribeOption[noprint]{nomulticol}
% \DescribeOption[noprint]{hyperref}
% \DescribeOption[noprint]{nohyperref}
% \DescribeOption[noprint]{debugshow}
% \DescribeOption[noprint]{noindex}
% \DescribeOption[noprint]{noprint}
% \DescribeOption[noprint]{reportchangedates}
% \begin{description}
% \item[\opt{hyperref}, \opt{nohyperref}] Boolean (default \texttt{true}). Load the
%    \pkg{hyperref} package and make index references to code lines
%    and pages and other items clickable links. \opt{nohyperref} is
%    the complementary key.
%
% \item[\opt{multicol}, \opt{nomulticol}] Boolean (default \texttt{true}). Load the
%    \pkg{multicol} package for use in typesetting the index and the
%    list of changes. \opt{nomulticol} is
%    the complementary key.
%
% \item[\opt{debugshow}] Boolean (default \texttt{false}). Provide
%    various tracing information at the terminal and in the transcript
%    file. In particular show which elements are indexed.
%
% \item[\opt{noindex}] Boolean (default \texttt{false}). If set, all
%    automatic indexing is suppressed. This option can also be used on
%    individual elements as described below.
%
% \item[\opt{noprint}] Boolean (default \texttt{false}). If set, then
%    printing of element names in the margin will be suppressed. This
%    option can also be used on individual elements as described
%    below.
% \item[\opt{reportchangedates}] Boolean (default \texttt{false}). If
%    set, then change entries list the date after the version number in
%    the change log.
% \end{description}
%
% \DescribeInterfaceMacro{\SetupDoc} Instead of providing options to the \DOC
%    package you can call \cs{SetupDoc} and provide them there. This
%    allows, for example,  to change default values in case \DOC was already
%    loaded earlier.
%
%
%
% \subsection{General conventions}
%
% A \TeX{} file prepared to be used with the `doc' package
% consists of `documentation parts' intermixed with `definition
% parts'.
%
% Every line of a `documentation part' starts with a percent sign
% (|%|) in column one.  It may contain arbitrary \TeX{} or
% \LaTeX{} commands except that the character `|%|' cannot be
% used as a comment character.
% \SortIndex{\string^\string^A}{\string\verb\verbatimchar
% \string^\string^A\verbatimchar \encapchar usage}^^A
% \SortIndex{\string^\string^X}{\string\verb\verbatimchar
% \string^\string^X\verbatimchar \encapchar usage}
% To allow user
% comments, the characters |^^A| and |^^X| are both defined as a comment character
% later on.\footnote{In version 2 it was only
%    \texttt{\string^\string^A}, but many keyboards combine
%    \texttt{\string^} and \texttt{A} and automatically turn it into
%    ``Ä''; so \texttt{\string^\string^X} was added as an
%    alternative in version 3.}
% Such `metacomments' may be also be included simply by
% surrounding them with |\iffalse| \ldots~|\fi|.
%
% All other parts of the file are called `definition parts'.  They
% contain fractions of the macros described in the `documentation
% parts'.
%
% If the file is used to define new macros (e.g.\ as a package file in
% the |\usepackage| macro), the `documentation parts' are
% bypassed at high speed and the macro definitions are pasted
% together, even if they are split into several `definition parts'.
%
% \DescribeEnv{macrocode}
% On the other hand, if the documentation of these macros is to be
% produced, the `definition parts' should be typeset verbatim. To
% achieve this, these parts are surrounded by the \env{macrocode}
% environment.
% More exactly: before a `definition part' there should be a line
% containing
% \begin{flushleft}
%   \hspace*{\MacroIndent}\verb*+%    \begin{macrocode}+
% \end{flushleft}
% and after this part a line
% \begin{flushleft}
%   \hspace*{\MacroIndent}\verb*+%    \end{macrocode}+
% \end{flushleft}
% There must be {\em exactly\/} four spaces between the |%|
% and |\end{macrocode}| --- \TeX{} is looking for this string
% and not for the macro while processing a `definition part'.
%
% Inside a `definition part' all \TeX{} commands are allowed; even the
% percent sign could be used to suppress unwanted spaces etc.
%
% \DescribeEnv{macrocode*} Instead of the \env{macrocode}
% environment one can also use the \env{macrocode$*$} environment
% which produces the same results except that spaces are printed as
% \nopagebreak\verb*+ + characters.
%
%
%
% \subsection{Describing the usage of macros and environments}
%
% \DescribeInterfaceMacro\DescribeMacro
% When you describe a new macro you may use |\DescribeMacro| to
% indicate that at this point the usage of a specific macro is
% explained. It takes one argument which will be printed in the margin
% and also produces a special index entry.  For example, I used
% |\DescribeMacro{\DescribeMacro}| to make clear that this is the
% point where the usage of |\DescribeMacro| is explained.
%
% As the argument to |\DescribeMacro| is a command name, many people
% got used to using the (incorrect) short form, i.e., omitting the
% braces around the argument as in |\DescribeMacro\foo|. This does
% work as long as the macro name consists only of ``letters''.
% However, if the name contains special characters that are normally
% not of type ``letter'' (such as |@|, or in case of \pkg{expl3} |_|
% and |:|) this will fail dramatically. |\DescribeMacro| would then
% receive only a partial command name (up to the first ``non-letter'')
% e.g., |\DescribeMacro\foo@bar| would be equivalent to
% |\DescribeMacro{\foo} @bar| and you can guess that this can
% resulting in both incorrect output and possibly low-level error
% messages.
%
% \DescribeInterfaceMacro\DescribeEnv
% An analogous macro |\DescribeEnv| should be used to indicate that a
% \LaTeX{} environment is explained. It will produce a somewhat
% different index entry and a slightly different display in the
% margin. Below I used |\DescribeEnv{verbatim}|.
%
%
% \NewIn{v3}
% Starting with version~3 the \cs{Describe...} commands accept an
% optional argument in which you can specify either \opt{noindex}
% or \opt{noprint} to suppress indexing or printing for that
% particular instance. Using both would be possible too, but pointless
% as then the commands wouldn't do anything any more.
%
%
% \subsection{Describing the definition of macros and environments}
%
% \DescribeEnv{macro}
% To describe the definition of a (new) macro we use the \env{macro}
% environment. It has one argument: the name of the new
% macro.\footnote{This is a change to the style design I described in
%                ^^A \TUB ^^A removed in case ltugboat.sty not used
%                \textsl{TUGboat\/}\ 10\#1 (Jan.~89). We finally decided
%                that it would
%                be better to use the macro name {\em with\/} the
%                backslash as an argument.}
% This argument is also used to print the name in the margin and to
% produce an index entry.
% Actually the index entries for usage and definition are different to
% allow an easy reference.
% This environment might be nested. In this case the
% labels in the margin are placed under each other.
% \changes{v1.7a}{1992/02/26}{Note on need for some text in macro env.}
% There should be some text---even  if it's just an empty
% |\mbox{}|---in this environment before |\begin{macrocode}| or the
% marginal label won't print in the right place.
%
% \NewIn{v3}
% In fact it is now allowed to specify several macros in the argument,
% separated by commas. This is a short form for starting several
% \env{macro} environments in direct succession. Of course, you
% should then have also only one matching |\end{macro}|.
%
% \DescribeLaTeXSkip\MacrocodeTopsep
% \DescribeLaTeXSkip\MacroTopsep
% There also exist four style parameters: |\MacrocodeTopsep| and
% |\MacroTopsep| are used to control the vertical spacing above
% and below the \env{macrocode} and the \env{macro}
% \DescribeLaTeXDimen\MacroIndent
% environment, |\MacroIndent| is used to indent the lines of code
% and
% \DescribeInterfaceMacro\MacroFont \label{sec:macrofont}
% |\MacroFont| holds the font and a possible size change command
% for the code lines, the |verbatim|[|*|] environment and the macro
% names printed in the margin.  If you want
% to change their default values in a
% class file (like \texttt{ltugboat.cls}) use the |\DocstyleParms|
% command described below. Starting with release 2.0a it can now
% be changed directly as long as the redefinition happens before
% the |\begin{document}| (if you change it later you might see strange
% typesetting effects if you are unlucky).
%
% |\MacroFont| does not alter the font of
% |\verb| or |\verb*| because it is often used to make the font size of
% the code displays smaller, which would look odd if used within a
% paragraph. If you decide to use a different font family and want to
% use the same family with
% |\verb| you need to alter the font setup for |\ttfamily| in addition
% to |\MacroFont|.
%
% \DescribeEnv{environment}
% For documenting the definition of environments one can use the
% environment \texttt{environment} which works like the \texttt{macro}
% environment, except that it expects an \meta{env-name}
% (without a backslash)
% as its argument and internally provides different index
% entries suitable for environments.
% Nowadays you can alternatively specify a comma-separated list of environments.
%
% \NewIn{v3}
% Starting with version~3 these environments accept an optional
% argument in which you can specify \opt{noindex} or \opt{noprint} or
% both to suppress indexing or printing for that particular
% instance. If any such setting is made on the environment level it
% overwrites whatever default was given when the \DOC element was
% defined or when the package was loaded.
%
%
%
%
% \subsection{Formatting names in the margin}
%
% \DescribeInterfaceMacro\PrintDescribeMacro
% \DescribeInterfaceMacro\PrintDescribeEnv
% \DescribeInterfaceMacro\PrintMacroName
% \DescribeInterfaceMacro\PrintEnvName
% As mentioned earlier, some macros and environment
% print their arguments in the margin. The actual formatting is done by four
% macros which are user
% definable.\footnote{You may place the changed definitions in a
%                     separate package
%                     file or at the beginning of the documentation
%                     file.
%                     For example, if you don't like any names in the
%                     margin
%                     but want a fine index you can simply redefine them
% accept their argument and do nothing with it.}
% They are named |\PrintDescribeMacro| and |\PrintDescribeEnv| (defining
% how |\DescribeMacro| and |\DescribeEnv| behave) and
% |\PrintMacroName| and
% |\PrintEnvName| (called by the \env{macro} and \env{environment}
% environments, respectively).
%
%
% \subsection{Providing further documentation items}
%
% Out of the box the \DOC package offers the above commands and
% environments to document macros and environments.
% \NewIn{v3}
% With version 3
% this has now been extended in a generic fashion so that you can
% easily provide your own items, such as counters, length register,
% options etc.
%
% \DescribeInterfaceMacro{\NewDocElement}
% The general syntax for providing a new \DOC element is
% \begin{quote}
%   \cs{NewDocElement}\oarg{options}\marg{element-name}\marg{env-name}
% \end{quote}
% By convention the \meta{element-name} has the first letter
% uppercased as in \texttt{Env} or \texttt{Macro}.
%
% Such a declaration will define for you
% \begin{itemize}
% \item the command |\Describe|\meta{element-name} which has the
%    syntax
%    \begin{quote}
%      |\Describe|\meta{element-name}\oarg{options}\marg{element}
%    \end{quote}
%
% \item the environment \meta{env-name} which has the syntax
%    \begin{quote}
%      \cs{begin}\marg{env-name}\oarg{options}\marg{element}
%    \end{quote}
%
% \item the display command |\PrintDescribe|\meta{element-name} with
%    the syntax
%    \begin{quote}
%      |\PrintDescribe|\meta{element-name}\marg{element}
%    \end{quote}
%
% \item and the
% |\Print|\meta{element-name}|Name|  display command for the
% environment.
% \end{itemize}
% If any of the commands or the environment is already defined (which
% especially with the \meta{env-name} is a danger) then you will
% receive an error telling you so.
%
% \DescribeInterfaceMacro{\RenewDocElement}
% If you want to modify an existing \DOC element use
% |\RenewDocElement| instead.
%
% For example, the already provided ``\texttt{Env}'' \DOC element could have been
% defined simply by making the declaration
%   |\NewDocElement{Env}{environment}|
% though that's not quite what has been done, as we will see later.
%
% \DescribeInterfaceMacro{\ProvideDocElement}
% This declaration does nothing when the doc element is already
% declared, otherwise it works like \cs{NewDocElement}. It can be
% useful if you have many documentation files that you may want to
% process individually as well as together.
%
% \DescribeOption[noprint]{macrolike}
% \DescribeOption[noprint]{envlike}
% \DescribeOption[noprint]{toplevel}
% \DescribeOption[noprint]{notoplevel}
% \DescribeOption[noprint]{idxtype}
% \DescribeOption[noprint]{printtype}
% \DescribeOption[noprint]{idxgroup}
% The \meta{options} are keyword/value and define further details on
% how that \DOC element should behave. They are:
% \begin{description}
% \item[\opt{macrolike}] Boolean (default \opt{false}). Does this \DOC
%   element starts with a backslash?
%
% \item[\opt{envlike}] Boolean. Complementary option to
%   \opt{macrolike}.
%
% \item[\opt{toplevel}] Boolean (default \opt{true}). Should all
%   a top-level index entry be made? If set to \texttt{false} then
%   either no index entries are produced or only grouped index entries
%   (see \opt{idxgroup} for details).
%
% \item[\opt{notoplevel}] Boolean.  Complementary option to
%   \opt{toplevel}.
%
% \item[\opt{idxtype}] String (default \meta{env-name}). What to put
%   (in parentheses if non-empty) at the end of a top-level index entry.
%
% \item[\opt{printtype}] String (default \meta{env-name}). What to put
%   (in parentheses if non-empty) after an element name in the margin.
%
% \item[\opt{idxgroup}] String (default
%   \meta{env-name}\texttt{s}). Name of the top-level index entry if
%   entries are grouped. They are only grouped if this option is
%   non-empty.
%
% \item[\opt{noindex}] Boolean (default \texttt{false}).  If set this
%   will suppress indexing for elements of this type. This setting
%   overwrite any global setting of \opt{noindex}.
%
% \item[\opt{noprint}] Boolean (default \texttt{false}).  If set this
%   will suppress printing the element name in the margin. This setting
%   overwrite any global setting of \opt{noprint}.
% \end{description}
% As usual giving a boolean option without a value sets it to
% \texttt{true}.




% \subsection{Displaying sample code verbatim}
%
% \DescribeEnv{verbatim}
% It is often a good idea to include examples of the usage of new macros
% in the text. Because of the |%| sign in the first column of every
% row, the \env{verbatim} environment is slightly altered to suppress
% those
% characters.\footnote{These macros were written by Rainer
%                      Schöpf~\cite{art:verbatim}. He also
%                      provided a new \env{verbatim} environment
%                      which can be used inside of other macros.}
% \DescribeEnv{verbatim*}
% The \env{verbatim$*$} environment is changed in the same way.
% \changes{v1.7a}{1992/02/26}{Documented \cs{verb} change.}
% \DescribeInterfaceMacro\verb
% The |\verb| command is re-implemented to give an error report if a
% newline appears in its argument.
% The \env{verbatim} and \env{verbatim$*$} environments set text
% in the style defined by |\MacroFont|~(\S\ref{sec:macrofont}).
%
%

% \subsection{Using a special escape character}
%
% \DescribeInterfaceMacro\SpecialEscapechar
% If one defines complicated macros it is sometimes necessary to
% introduce a new escape character because the `|\|' has got a
% special |\catcode|. In this case one can use
% |\SpecialEscapechar| to indicate which character is actually
% used to play the r\^ole of the `|\|'. A scheme like this is
% needed because the \env{macrocode} environment and its counterpart
% \env{macrocode$*$} produce an index entry for every occurrence of a
% macro name. They would be very confused if you didn't tell them that
% you'd changed |\catcode|$\,$s.  The argument to
% |\SpecialEscapechar| is a single-letter control sequence, that
% is, one has to use \verb=\|= for example to denote that `\verb+|+'
% is used as an escape character. |\SpecialEscapechar| only
% changes the behavior of the next \env{macrocode} or
% \env{macrocode$*$} environment.
%
%  The actual index entries created will all be printed with |\|
% rather than \verb+|+, but this probably reflects their usage, if not
% their definition, and anyway must be preferable to not having any
% entry at all.  The entries {\em could\/} be formatted appropriately,
% but the effort is hardly worth it, and the resulting index might be
% more confusing (it would certainly be longer!).
%
%
% \subsection{Cross-referencing all macros used}
%
% \DescribeInterfaceMacro\DisableCrossrefs \DescribeInterfaceMacro\EnableCrossrefs As
% already mentioned, every macro name used within a
% \env{macrocode} or \env{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\footnote{This
% comment was written about 30 years ago. \TeX{} is still considerably
% slower but while it took minutes to process a large document (such
% as the \LaTeX{} kernel documentation) it takes seconds or less these
% days. Thus \cs{DisableCrossrefs} isn't really that necessary these
% days.}  when it has to produce such a bulk of index entries one can
% turn off this feature by using |\DisableCrossrefs| in the driver
% file. To turn it on again just use
% |\EnableCrossrefs|.\footnote{Actually, \cs{EnableCrossrefs} changes
% things more drastically; any following call to \cs{DisableCrossrefs}
% which might be present in the source will be ignored.}
%
%
% \DescribeInterfaceMacro\DoNotIndex
% But also finer control is provided. The |\DoNotIndex| macro
% takes a list of macro names separated by commas. Those names won't
% show up in the index. You might use several |\DoNotIndex|
% commands: their lists will be concatenated.  In this article I used
% |\DoNotIndex| for
% all macros which are already defined in \LaTeX.
%
% All three above declarations are local to the current group.
%
% Production (or not) of the index (via the |\makeindex| commend) is
% controlled by using or omitting the following declarations in the
% driver file preamble; if neither is used, no index is produced.
% \DescribeInterfaceMacro\PageIndex Using |\PageIndex| makes all index
% entries refer to their page number; with
% \DescribeInterfaceMacro\CodelineIndex |\CodelineIndex|, index entries
% produced by |\DescribeMacro| and |\DescribeEnv| and possibly further
% |\Describe...| commands refer to a page number
% but those produced by the \env{macro} environment (or other \DOC
% element environments) refer to the
% code lines, which will be numbered automatically.\footnote{The line
% number is actually that of the first line of the first
% \env{macrocode} environment in the \env{macro} environment.}
% \DescribeInterfaceMacro\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.
%
% \DescribeInterfaceMacro\CodelineNumbered
% When you don't wish to get an index but want your code lines
% numbered use |\CodelineNumbered| instead of |\CodelineIndex|. This
% prevents the generation of an unnecessary |.idx| file.
%
%
% \subsection{Producing the actual index entries}
%
% Several of the aforementioned macros will produce some sort of index
% entries. These entries have to be sorted by an external
% program---the current implementation assumes that the
% \prg{makeindex} program by Chen~\cite{art:Chen} is used.
%
% But this isn't built in: one has only to redefine some of the
% following macros to be able to use any other index program.  All
% macros which are installation
% dependent are defined in such a way that they won't overwrite a
% previous definition. Therefore it is safe to put the changed
% versions in a package file which might be read in before the doc
% package.
%
%  To allow the user to change the specific characters recognized by
%  his or her index program all characters which have special meaning
%  in the \prg{makeindex} program are given symbolic
%  names.\footnote{I don't know if there exists a program which needs
%                  more command characters, but I hope not.}
% However, all characters used should be of |\catcode| other than
% `letter' (11).
%
% \DescribeInterfaceMacro{\actualchar}
% The |\actualchar| is used to separate the `key' and the actual
% index entry.
% \DescribeInterfaceMacro{\quotechar}
% The |\quotechar| is used before a special index program
% character to suppress its special meaning.
% \DescribeInterfaceMacro{\encapchar}
%  The |\encapchar| separates the indexing information from a
% letter string which \prg{makeindex} uses as a \TeX{} command to
% format the page number associated with a special entry.  It is used
% in this package to apply the |\main| and the |\usage|
% commands.
% \DescribeInterfaceMacro{\levelchar}
%  Additionally |\levelchar| is used to separate `item',
% `subitem' and `subsubitem' entries.
%
% It is a good idea to stick to these symbolic names even if you know
% which index program is used. In this way your files will be
% portable.
%
% \fmi{describe old \cs{SpecialMainIndex} and \cs{SpecialUsageIndex}}
%
% \DescribeInterfaceMacro\SpecialMainMacroIndex
% \DescribeInterfaceMacro\SpecialMainEnvIndex
% To produce a main index entry for a macro the
% |\SpecialMainMacroIndex| macro\footnote{This macro is called by the
% \env{macro} environment.} may be used.  It is called `special'
% because it has to print its argument verbatim.
% A similar macro, called |\SpecialMainEnvIndex| is used for indexing
% the main definition point of an
% environment.\footnote{This macro is called by the
% \env{environment} environment.}
%
% \DescribeInterfaceMacro\SpecialMacroIndex
% \DescribeInterfaceMacro\SpecialEnvIndex
% To index the usage of a macro or an environment
% |\SpecialMacroIndex| and |\SpecialEnvIndex| may be used.
%
% All these macros are normally used by other macros; you will need
% them only in an emergency.
%
% \NewIn{v3}
% If further code elements are declared with
% |\NewDocElement|\marg{name}\texttt{...} then this sets up
% additional indexing commands, e.g.,
% \cs{SpecialMain\meta{name}Index}.
%
% \DescribeInterfaceMacro\SpecialIndex
% The \env{macrocode} environment is automatically indexing macros
% (normally by code line number). You can (with care) also do this
% manually by
% |\SpecialIndex|. However, note that if |\CodelineIndex| is used
% this will generate an entry referring to the last code line which is
% usually not what you want. It does, however, make some sense if you
% always refer to pages only, i.e., if you use |\PageIndex|.
%
% \DescribeInterfaceMacro\SpecialShortIndex
% \NewIn{v3}
% For single character macros, e.g., |\{|, doesn't always work
% correctly.
% For this reason there is now also
% a special variant the can produce correct index entries for them.
%
% \DescribeInterfaceMacro\SortIndex
% Additionally a |\SortIndex| command is provided.  It takes two
% arguments---the sort key and the actual index entry.
%
% \DescribeInterfaceMacro\verbatimchar
% But there is one characteristic worth mentioning: all macro names in
% the index are typeset with the |\verb*| command. Therefore one
% special character is needed to act as a delimiter for this command.
% To allow a change in this respect, again this character is
% referenced indirectly, by the macro |\verbatimchar|. It expands
% by default to \verb?+?  but if your code lines contain macros with
% `\texttt{+}' characters in their names (e.g.\ when you use \verb?\+?)
% then that caused a problem because you ended up with an
% index entry containing \verb?\verb+\++?
% which will be typeset as `\verb+\++' and not as `\verb?\+?'.
% \NewIn{v3}
% In version 3 this is now automatically taken care of (with the help
% of the |\SpecialShortIndex| command).
%
% \DescribeInterfaceMacro\*
% We also provide a |\*| macro.  This is intended to be used for
% index entries like
% \begin{quote}
%    index entries \\
%    \hspace*{30pt} Special macros for \*
% \end{quote}
% Such an entry might be produced with the line:
%\begin{verbatim}
%   \index{index entries\levelchar Special macros for \*}
%\end{verbatim}
%
%
% \subsection{Setting the index entries}
%
% \changes{v1.7a}{1992/03/11}{Usage note on gind.ist.} After the first
% formatting pass through the \texttt{.dtx} file you need to sort the
% index entries written to the \texttt{.idx} file using
% \prg{makeindex} or your favorite alternative.  You need a
% suitable style file for \prg{makeindex} (specified by the
% \texttt{-s} switch).  A suitable one is supplied with \DOC{},
% called \texttt{gind.ist}.
%
% \DescribeInterfaceMacro\PrintIndex
% To read in and print the sorted index, just put the
% |\PrintIndex| command as the last (commented-out, and thus
% executed during the documentation pass through the file) command
% in your package file.  Precede it by any bibliography commands
% necessary for your citations.
% Alternatively, it may be more convenient to put all such calls
% amongst the arguments of the |\MaybeStop| macro, in
% which case a |\Finale| command should appear at the end of
% your file.
%
% \DescribeEnv{theindex}
% Contrary to standard \LaTeX, the index is typeset in three columns
% by default.
% \DescribeLaTeXCounter{IndexColumns}
% This is controlled by the \LaTeX{} counter
% `\textsf{IndexColumns}' and can therefore be changed with a
% |\setcounter| declaration.  Additionally one doesn't want to
% start a new page unnecessarily.  Therefore the \env{theindex}
% environment is redefined.
% \DescribeLaTeXDimen\IndexMin
% When the \env{theindex} environment starts it will measure how much
% space is left on the current page. If this is more than
% |\IndexMin| then the index will start on this page. Otherwise
% |\newpage| is called.
%
% Then a short introduction about the meaning of several index entries
% is typeset (still in onecolumn mode). Afterwards the actual index
% entries follow in multi-column mode.
% \DescribeInterfaceMacro\IndexPrologue
% You can change this prologue with the help of the
% |\IndexPrologue| macro. Actually the section heading is also
% produced in this way, so you'd better write something like:
% \begin{verbatim}
%   \IndexPrologue{\section*{Index} The index entries underlined ...}
%\end{verbatim}
% When the \env{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.
% \DescribeInterfaceMacro\IndexParms
% Formatting of the index columns (values for |\columnssep|
% etc.)\ is controlled by the |\IndexParms| macro. It assigns the
% following values:
% \SpecialLaTeXDimenIndex{\parindent}\SpecialLaTeXDimenIndex{\columnsep}^^A
% \SpecialLaTeXSkipIndex{\parskip}\SpecialLaTeXSkipIndex{\rightskip}^^A
% \SpecialLaTeXDimenIndex{\mathsurround}\SpecialLaTeXSkipIndex{\parfillskip}
% \begin{center}
%  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
%  |\parindent|    & \IndexParms \the\parindent    &
%  |\columnsep|    & \IndexParms \the\columnsep    \\
%  |\parskip|      & \IndexParms \the\parskip           &
%  |\rightskip|    & \IndexParms
%                         \expandafter\dimenvalue\the\rightskip  \\
%  |\mathsurround| & \IndexParms \the\mathsurround  &
%  |\parfillskip|  & \IndexParms
%                         \expandafter\dimenvalue\the\parfillskip
%  \end{tabular}
% \end{center}
% \DescribeInterfaceMacro{\@idxitem}
% Additionally it defines |\@idxitem| (which will be used when an
% |\item| command is encountered) and selects |\small| size.
% If you want to change any of these values you have to define them
% all.
%
% \DescribeInterfaceMacro\main
% \DescribeInterfaceMacro\usage
% \DescribeInterfaceMacro\code
% The page numbers for main index entries are encapsulated by the
% |\main| macro (underlining its argument) and the numbers
% denoting the description are encapsulated by the |\usage| macro
% (which produces \textit{italics}). |\code| encapsulates page or code
%    line numbers in entries generated by parsing the code inside
%    \env{macrocode} environments. As usual these commands are user
% definable.
%
%
% \subsection{Changing the default values of style parameters}
%
% \DescribeInterfaceMacro\DocstyleParms If you want to overwrite some default
% settings made by the \DOC{} package, you can either put your
% declarations in the driver file (that is after \texttt{doc.sty} is
% read in) or use a separate package file for doing this work. In the
% latter case you can define the macro |\DocstyleParms| to contain all
% assignments.  This indirect approach is necessary if your package file
% might be read before the \texttt{doc.sty}, when some of the
% registers are not allocated.  Its default definition is null.
%
% The doc package currently assigns values to the following
% registers:
% \SpecialLaTeXDimenIndex{\IndexMin}^^A
% \SpecialLaTeXSkipIndex{\MacrocodeTopsep}^^A
% \SpecialLaTeXSkipIndex{\MacroTopsep}^^A
% \SpecialLaTeXDimenIndex{\MacroIndent}^^A
% \SpecialLaTeXDimenIndex{\marginparpush}^^A
% \SpecialLaTeXDimenIndex{\marginparwidth}^^A
% \SpecialTeXCounterIndex{\tolerance}
% \begin{center}
%  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
%  |\IndexMin|      & \the\IndexMin    &
%  |\MacroTopsep|   & \the\MacroTopsep    \\
%  |\marginparwidth|& \the\marginparwidth  &
%  |\MacroIndent|   & \the\MacroIndent \\
%  |\marginparpush| & \the\marginparpush    &
%  |\MacrocodeTopsep|   & \the\MacrocodeTopsep \\
%  |\tolerance|     & \the\tolerance
%  \end{tabular}
% \end{center}
%
%
% \subsection{Short input of verbatim text pieces}
%
% \DescribeInterfaceMacro\MakeShortVerb
% \DescribeInterfaceMacro{\MakeShortVerb*} \DescribeInterfaceMacro\DeleteShortVerb It is
% awkward to have to type, say, \verb"\verb|"\ldots\verb"|" continually when
% quoting
% verbatim bits (like macro names) in the text, so an abbreviation
% mechanism is provided.  Pick a character \meta{c}---one which
% normally has catcode `other' unless you have very good reason not
% to---which you don't envisage using in the text, or not using often.
% (I like |"|, but you may prefer \verb"|" if you have |"| active to do
% umlauts, for instance.)  Then if you say
% |\MakeShortVerb{\|\meta{c}|}| you can subsequently use
% \meta{c}\meta{text}\meta{c} as the equivalent of
% |\verb|\meta{c}\meta{text}\meta{c};  analogously, the |*|-form
% |\MakeShortVerb*{\|\meta{c}|}| gives you the equivalent of
% |\verb*|\meta{c}\meta{text}\meta{c}.  Use
% |\DeleteShortVerb{\|\meta{c}|}| if you subsequently want \meta{c} to
% revert to its previous meaning---you can always turn it on again
% after the unusual section.  The `short verb' commands make global
% changes.  The abbreviated |\verb| may not appear in the argument of
% another command just like |\verb|.  However the `short verb'
% character may be used freely in the \env{verbatim} and
% \env{macrocode} environments without ill effect.
% |\DeleteShortVerb| is silently ignored if its argument does not
% currently represent a short verb character.  Both commands type a
% message to tell you the meaning of the character is being changed.
%
% Please remember that the command |\verb| cannot be used in arguments
% of other commands. Therefore abbreviation characters for |\verb|
% cannot be used there either.
%
% This feature is also available as a sole package, \texttt{shortvrb}.
%
%
% \subsection{Additional bells and whistles}
%
% We provide macros for logos such as \Web, \AmSTeX, \BibTeX,
% \SliTeX{} and \PlainTeX. Just type |\Web|, |\AmSTeX|,
% |\BibTeX|, |\SliTeX| or |\PlainTeX|, respectively.
% \LaTeX{} and \TeX{} are already defined in \texttt{latex.tex}.
%
% \DescribeInterfaceMacro\meta
% Another useful macro is |\meta| which has one argument and
% produces something like \meta{dimen parameter}.
%
% \DescribeInterfaceMacro\OnlyDescription
% \DescribeInterfaceMacro\MaybeStop
% \DescribeObsoleteInterfaceMacro\StopEventually
% You can use the |\OnlyDescription| declaration in the driver
% file to suppress the last part of your document (which presumably
% exhibits the code). To make this work
% \NewIn{v3}
% you have to place the command |\MaybeStop| at a suitable
% point in your file.  This macro\footnote{For about 30 years this
%    macro was called \cs{StopEventually} which was due to a ``false
%    friend'' misunderstanding. In the German language the word
%    ``eventuell'' mean roughly ``perhaps'' which isn't quite the same
%    as ``eventually''. But given that this is now used for so long
%    and all over the place we can't drop the old name. So it is still
%    there to allow processing all the existing documentation.}
% has one argument in which you put
% all information you want to see printed if your document ends at
% this point (for example a bibliography which is normally printed at
% the very end). When the |\OnlyDescription| declaration is
% missing the |\MaybeStop|
% \DescribeInterfaceMacro\Finale
% macro saves its argument in a macro called |\Finale| which can
% afterwards be used to get things back (usually at the very end).
% Such a scheme makes changes in two places unnecessary.
%
% Thus you can use this feature to produce a local guide for the
% \TeX{} users which describes only the usage of macros (most of them
% won't be interested in your definitions anyway).  For the same
% reason the |\maketitle| \DescribeInterfaceMacro\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.
% \DescribeInterfaceMacro{\ps@titlepage} To avoid an unwanted
% \textsf{pagestyle} on the title page the |\maketitle| command issues
% a |\thispagestyle{titlepage}| declaration which produces a
% \textsf{plain} page if the \textsf{titlepage} page style is
% undefined.  This allows class files like \cls{ltugboat.cls} to
% define their own page styles for title pages.
%
% \DescribeInterfaceMacro\AlsoImplementation
% Typesetting the whole document is the default. However, this default
% can also be explicitly selected using the declaration
% |\AlsoImplementation|. This overwrites any previous
% |\OnlyDescription| declaration. The \LaTeXe{} distribution, for
% example, is documented using the \texttt{ltxdoc} class which allows
% for a configuration file \texttt{ltxdoc.cfg}. In such a file one
% could then add the statement
% \begin{quote}
% |\AtBeginDocument{\AlsoImplementation}|
% \end{quote}
% to make sure that all documents will show the code part.
%
% \DescribeInterfaceMacro\IndexInput \label{..Input} Last but not least I
% defined an |\IndexInput| macro which takes a file name as an
% argument and produces a verbatim listing of the file, indexing every
% command as it goes along.  This might be handy, if you want to learn
% something about macros without enough documentation.  I used this
% feature to cross-reference \texttt{latex.tex} getting a verbatim
% copy with about 15 pages index.\footnote{It took quite a long time
% and the resulting \texttt{.idx} file was longer than the
% \texttt{.dvi} file.  Actually too long to be handled by the
% \prg{makeindex} program directly (on our MicroVAX) but the final
% result was worth the trouble.}
%
% \changes{v2.1d}{2006/02/02}{Corrected description of \cs{changes}
% macro.}
% \DescribeInterfaceMacro\changes
% To maintain a change history within the file, the |\changes|
% command may be placed amongst the description part of the changed
% code.  It takes three arguments, thus:
% \begin{quote}
% |\changes{|\meta{version}|}{|\meta{date}|}{|^^A
% \meta{text}|}|
% \end{quote}
% The changes may be used to produce an auxiliary file (\LaTeX's
% |\glossary| mechanism is used for this) which may be printed
% after suitable formatting. The |\changes| macro generates the
% printed entry in such a change history; because old
% versions\footnote{Before 2.6.} of the \prg{makeindex}
% program limit such fields to 64 characters, care should be taken
% not to exceed this limit when describing the change. The actual
% entry consists of the \meta{version}, the |\actualchar|, the current
% macro name, a colon, the |\levelchar|, and, finally, the \meta{text}.
% The result is a glossary entry for the \meta{version}, with the name of
% the current macro as subitem.  Outside the |macro| environment, the
% text |\generalname| is used instead of the macro name.  When
% referring to macros in change descriptions it is conventional to use
% |\cs{|\meta{macroname}|}| rather than attempting to format it properly
% and using up valuable characters in the entry with old \prg{makeindex}
% versions.
%
% Note that in the history listing, the entry is shown with the page number
% that corresponds to its place in the source, e.g., general changes put at the
% very beginning of the file will show up with page number ``1'', change entries
% placed elsewhere might have different numbers (not necessarily always
% very useful unless you are careful).
%
%
% \changes{v1.7a}{1992/02/26}{Description of \cs{RecordChanges} etc.
% added
% to interface section.} \DescribeInterfaceMacro\RecordChanges To cause the
% change information to be written out, include |\RecordChanges| in
% the driver file.  \DescribeInterfaceMacro\PrintChanges To read in and print
% the sorted change history (in two columns), just put the
% |\PrintChanges| command as the last (commented-out, and thus
% executed during the documentation pass through the file) command in
% your package file.  Alternatively, this command may form one of the
% arguments of the |\MaybeStop| command, although a change
% history is probably {\em not\/} required if only the description is
% being printed.  The command assumes that \prg{makeindex} or some
% other program has processed the \texttt{.glo} file to generate a
% sorted \texttt{.gls} file.  You need a special \prg{makeindex}
% style file; a suitable one is supplied with \DOC{}, called
% \texttt{gglo.ist}.
%
% \DescribeLaTeXDimen\GlossaryMin
% \DescribeInterfaceMacro\GlossaryPrologue
% \DescribeInterfaceMacro\GlossaryParms
% \DescribeLaTeXCounter{GlossaryColumns}
%  The
% |\GlossaryMin|, |\GlossaryPrologue| and |\GlossaryParms| macros and
% the counter \texttt{GlossaryColumns} are
% analogous to the |\Index|\ldots\ versions.  (The \LaTeX{} `glossary'
% mechanism is used for the change entries.)
%
%
% \DescribeInterfaceMacro\bslash
% From time to time, it is necessary to print a |\| without
% being able to use the |\verb| command because the
% |\catcode|$\,$s of the symbols are already firmly
% established.  In this instance we can use the command
% |\bslash| presupposing, of course, that the actual font in
% use at this point contains a `backslash' as a symbol.  Note that
% this definition of |\bslash| is expandable; it inserts a
% $|\|_{12}$.  This means that you have to |\protect|
% it if it is used in `moving arguments'.
%
% \DescribeInterfaceMacro\MakePrivateLetters
% \changes{v1.7a}{1992/02/26}{Documented \cs{MakePrivateLetters} in
%                           interface section}^^A
% If your macros |\catcode| anything other than |@| to `letter', you
% should redefine |\MakePrivateLetters| so that it also makes the
% relevant characters `letters' for the benefit of the indexing.  The
% default definition is just |\makeatletter|.
%
% \DescribeInterfaceMacro\DontCheckModules \DescribeInterfaceMacro\CheckModules
% \DescribeInterfaceMacro\Module \DescribeInterfaceMacro\AltMacroFont The `module'
% directives of the \prg{docstrip} system \cite{art:docstrip} are
% normally recognized and invoke special formatting.  This can be
% turned on and off in the \texttt{.dtx} file or the driver file using
% |\CheckModules| and |\DontCheckModules|.  If checking for module
% directives is on (the default) then code in the scope of the
% directives is set as determined by the hook |\AltMacroFont|, which
% gives {\small\ttfamily\itshape small italic type\-writer\/} by
% default in the New Font Selection Scheme but just ordinary
% {\small\ttfamily small type\-writer} in the old one, where a font
% such as italic typewriter can't be used portably (plug for NFSS);
% you will need to override this if you don't have the italic
% typewriter font available.  Code is in such a scope if it's on a
% line beginning with |%<| or is between lines starting with
% |%<*|\meta{name list}|>| and |%</|\meta{name list}|>|.  The
% directive is formatted by the macro |\Module| whose single argument
% is the text of the directive between, but not including, the angle
% brackets; this macro may be re-defined in the driver or package file
% and by default produces results like \Module{+foo\string|bar} with no
% following space.
%
% \DescribeLaTeXCounter{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.
%
%
% \section{Examples and basic usage summary}
%
% \subsection{Basic usage summary}
% \changes{v1.7a}{1992/03/11}{Added basic usage summary to spell
%                             it out.}
%
% To sum up, the basic structure of a \texttt{.dtx} file without any
% refinements is like this:
% \begin{verse}\small
% |% |\meta{waffle}\ldots\\
% \quad\ldots \\
% |% \DescribeMacro{\fred}|\\
% |% |\meta{description of fred's use}\\
% \quad\ldots\\
% |% \MaybeStop{|\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 further examples of the use of most---if not all---of the features
% described above, consult the \texttt{doc.dtx} source itself.
%
%
%
% \subsection{Examples}
%
% The default setup includes definitions for the \DOC elements
% ``macro'' and ``environment''. They correspond to the following
% declarations:
%\begin{verbatim}
% \NewDocElement[macrolike = true ,
%                 idxtype   = ,
%                 idxgroup  = ,
%                 printtype =
%                ]{Macro}{macro}
%
% \NewDocElement[macrolike = false ,
%                 idxtype   = env.  ,
%                 idxgroup  = environments ,
%                 printtype = \textit{env.}
%                ]{Env}{environment}
%\end{verbatim}
%
% To showcase the new features of \DOC version 3 to some extend, the
% current documentation is done by redefining these declarations and
% also adding a few additional declarations on top.
%
% For any internal command we document we use \texttt{Macro} and put
% all of them under the heading ``\LaTeX{} commands'' (note the use of \cs{actualchar}):
%\begin{verbatim}
%\RenewDocElement[macrolike = true ,
%                toplevel  = false,
%                idxtype   = ,
%                idxgroup  = LaTeX commands\actualchar\LaTeX{} commands ,
%                printtype =
%               ]{Macro}{macro}
%\end{verbatim}
%
% We only have package environments so we use \texttt{Env} for those
% and group them as well:
%\begin{verbatim}
%\RenewDocElement[macrolike = false ,
%                toplevel  = false,
%                idxtype   = env.  ,
%                idxgroup  = Package environments,
%                printtype = \textit{env.}
%               ]{Env}{environment}
%\end{verbatim}
%
%
% All the interface commands are also grouped together under the label
% ``Package commands'', we use \texttt{InterfaceMacro} for them:
%\begin{verbatim}
%\NewDocElement[macrolike = true ,
%                toplevel  = false,
%                idxtype   = ,
%                idxgroup  = Package commands,
%                printtype =
%               ]{InterfaceMacro}{imacro}
%\end{verbatim}
%
% And since we also have a few obsolete interfaces we add yet another category:
%\begin{verbatim}
%\NewDocElement[macrolike = true ,
%                toplevel  = false,
%                idxtype   = ,
%                idxgroup  = Package commands (obsolete),
%                printtype =
%               ]{ObsoleteInterfaceMacro}{omacro}
%\end{verbatim}
%
% Another type of category are the package keys:
%\begin{verbatim}
%\NewDocElement[macrolike = false ,
%                toplevel  = false,
%                idxtype   = key  ,
%                idxgroup  = Package keys ,
%                printtype = \textit{key}
%               ]{Key}{key} 
%\end{verbatim}
%
% Finally we have \TeX{} counters (with a backslash in front) and
% \LaTeX{} counters (no backslash) and the two types of \LaTeX{}
% length registers:
%\begin{verbatim}
%\NewDocElement[macrolike = true ,
%                toplevel  = false,
%                idxtype   =  counter  ,
%                idxgroup  = TeX counters\actualchar \protect\TeX{} counters ,
%                printtype = \textit{counter}
%               ]{TeXCounter}{tcounter}
%
%\NewDocElement[macrolike = false ,
%                toplevel  = false,
%                idxtype   =  counter  ,
%                idxgroup  = LaTeX counters\actualchar \LaTeX{} counters ,
%                printtype = \textit{counter}
%               ]{LaTeXCounter}{lcounter}
%
%\NewDocElement[macrolike = true ,
%                toplevel  = false,
%                idxtype   =  skip  ,
%                idxgroup  = LaTeX length\actualchar \LaTeX{} length (skip) ,
%                printtype = \textit{skip}
%               ]{LaTeXSkip}{lskip}
%
%\NewDocElement[macrolike = true ,
%                toplevel  = false,
%                idxtype   =  dimen  ,
%                idxgroup  = LaTeX length\actualchar \LaTeX{} length (dimen) ,
%                printtype = \textit{dimen}
%               ]{LaTeXDimen}{ldimen}
%
%\end{verbatim}
%
% And we modify the appearance of the index: just 2 columns not 3 and
% all the code-line entries get prefixed with an ``$\ell$'' (for line)
% so that they can easily be distinguished from page index entries.
%\begin{verbatim}
% \renewcommand\code[1]{\mbox{$\ell$-#1}}
% \renewcommand\main[1]{\underline{\mbox{$\ell$-#1}}}
% \setcounter{IndexColumns}{2}
%\end{verbatim}
%
%
%
% \section{Incompatibilities between version 2 and 3}
%
% The basic approach when developing version~3 was to provide a very
% high level of compatibility with version~2 so that nearly all
% older documents should work out of the box without the need for
% any adjustments.
%
% But as with any change there are situations where that change can
% result in some sort of incompatibility, e.g., if a newly introduce
% command name was already been defined in the user document then
% there will be a conflict that is nearly impossible to avoid
% 100\%.
%
% As mentioned earlier, \DOC now supports options on several commands
% and environments and as a result it is necessary to use braces
% around the argument for \cs{DescribeMaro} if the ``macro to be
% described'' uses private letters such as |@| or |_| as part of its
% name. That was always the official syntax but in the past you could
% get away with leaving out the braces more often than you can now.
%
% The old \DOC documentation also claimed that redefinitions of things
% like \cs{PrintDescribeMacro} could be done before loading the
% package (and not only afterwards) and \DOC would in that case not
% change those commands. As the setup mechanisms are now much more
% powerful and general such an approach is not really good. So with
% \DOC version~3 modifications have to be done after the \DOC package
% got loaded and the last modification will always win.
%
% I'm temped to drop compatibility with \LaTeX~2.09  (but so far I
% have left it in).
%
% In the past it was possible to use macros declared with \cs{outer}
% in the argument of \verb=\begin{macro}= or \cs{DoNotIndex} even
% though \cs{outer} is not a concept supported in \LaTeX{}. This is no
% longer possible. More exactly, it is no longer possible to prevent
% them from being indexed (as \cs{DoNotIndex} can't be used), but you
% can pass them to the \env{macro} environment as follows:
%\begin{verbatim}
%     \begin{macro}[outer]{\foo}
%\end{verbatim}
% if \cs{foo} is a macro declared with \cs{outer}. The technical
% reason for this change is that in the past various other commands,
% such as |\{| or |\}| did not work properly in these arguments when
% they where passed as ``strings'' and not as single macro tokens. But
% by switching to macro tokens we can't have \cs{outer} macros because
% their feature is to be not allowed in arguments. So what happens
% above when you use \texttt{[outer]} is that the argument is read as
% a string with four character tokens so that it is not recognized as
% being \cs{outer}.
%
%
% \section{Old interfaces no longer really needed}
%
% Thirty years is a long time in the life of computer programs, so
% there are a good number of interfaces within \DOC that are really
% only of historical interest (or when processing equally old sources).
% We list them here, but in general we suggest that for new
% documentation they should not be used.
%
%
% \subsection{\prg{makeindex} bugs}
%
% \DescribeObsoleteInterfaceMacro\OldMakeindex
% Versions of \prg{makeindex} prior to 2.9 had some bugs affecting
% \DOC{}.  One of these,
% pertaining to the |%| character doesn't have a work-around
% appropriate for versions with and without the
% bug.\label{makeindex:version}  If
% you really still have an old version, invoke |\OldMakeindex| in a
% package file or the driver file to prevent problems with index entries
% such as |\%|, although you'll probably normally want to turn off
% indexing of |\%| anyway.  Try to get an up-to-date \prg{makeindex}
% from one of the \TeX{} repositories.
%
% \subsection{File transmission issues}
%
% In the early days of the Internet file transmission issues have been
% a serious problem. There was a famous gateway in Rochester, UK that
% handled the traffic from the European continent to the UK and that
% consisted of two IBM machines running with different codepages (that
% had non-reversible differences). As a result ``strange'' \TeX{}
% characters got replaced with something else with the result that the
% files became unusable.
%
% To guard against this problem (or rather to detect it if something
% got broken in transfer I added code to \DOC to check a static
% character table and also to have a very simple checksum feature
% (counting backslashes).
%
% These days the \cs{CheckSum} is of little value (and a lot of pain
% for the developer) and character scrambling doesn't happen any more
% so the \cs{CharacterTable} is essentially useless. Thus neither
% should be used in new developments.
%
% \label{sec:checksum}
% \DescribeObsoleteInterfaceMacro\CharacterTable
% \DescribeObsoleteInterfaceMacro\CheckSum
% To overcome some of the problems of sending files over the networks
% we developed two macros which should detect corrupted files. If one
% places the lines
% \begin{flushleft}
% \small\ttfamily        ^^A \ttfamily to get the blanks between "..."s
%                        ^^A right
%|%%\CharacterTable|\\
%|%% {Upper-case   |
%|\A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z|\\
%|%%  Lower-case   |
%|\a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z|\\
%|%%  Digits        \0\1\2\3\4\5\6\7\8\9|\\
%|%%  Exclamation   \!     Double quote  "|
%|    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  |\verb=|=\\
%|%%  Right brace   \}     Tilde         \~}|\\
%|%%|
%\end{flushleft}
% at the beginning of the file then character translation failures
% will be detected, provided of course, that the used \DOC{}
% package has a correct default table.  The percent
% signs\footnote{There are two percent signs in each line. This has
% the effect that these lines are not removed by the
% \texttt{docstrip.tex} program.} at the beginning of the lines should
% be typed in, since only the \DOC{} package should look at this
% command.
%
%
% Another problem of mailing files is possible truncation.  To detect
% these sort of errors we provide a |\CheckSum| macro.  The check-sum
% of a file is simply the number of backslashes in the code, i.e.\ all
% lines between the \env{macrocode} environments.  But don't be
% afraid: you don't have count the code-lines yourself; this is done
% by the \DOC{} package for you.  You simply have add
% \begin{quote}
%    |%   \CheckSum{0}|
% \end{quote}
% near the beginning of the file and use the |\MaybeStop| (which
% starts looking for backslashes) and the |\Finale| command.  The
% latter will inform you either that your file has no check-sum
% (telling you the right number) or that your number is incorrect if
% you put in anything other than zero but guessed wrong (this time
% telling you both the correct and the incorrect one).  Then you go to
% the top of your file again and change the line to the right number,
% i.e.,  line
% \begin{quote}
%    |%   \CheckSum{|\meta{number}|}|
% \end{quote}
% and that's all.
%
% While |\CharacterTable| and |\CheckSum| have been important features
% in the early days of the public internet when \DOC{} was written as
% the mail gateways back then were rather unreliable and often mangled
% files they are these days more a nuisance than any help. They are
% therefore now fully optional and no longer recommended for use with
% new files.
%
%



% ^^A =============================================================



% \begin{multicols}{2}[\medskip \noindent\rule{\textwidth}{.3pt}
%                      \section{Introduction to previous releases}]
%
% \begin{quote}
%   \textbf{Original abstract:}
%    This package contains the definitions that are necessary to
%    format the documentation of package files.  The package was
%    developed in Mainz in cooperation with the Royal Military College
%    of Science.  This is an update which documents various changes
%    and new features in \DOC{} and integrates the features of
%    \env{newdoc}.
% \end{quote}
%
% The \TeX{} macros which are described here allow definitions and
% documentation to be held in one and the same file.  This has the
% advantage that normally very complicated instructions are made
% simpler to understand by comments inside the definition. In addition
% to this, updates are easier and only one source file needs to be
% changed.  On the other hand, because of this, the package files are
% considerably longer: thus \TeX{} takes longer to load them.  If this
% is a problem, there is an easy remedy: one needs only to run the
% \texttt{docstrip.tex} program that removes nearly all lines that begin
% with a
% percent sign.
%
% The idea of integrated documentation was born with the development
% of the \TeX{} program; it was crystallized in Pascal with the \Web{}
% system.  The advantages of this method are plain to see (it's easy
% to make comparisons \cite{art:Knuthliterat}).  Since this
% development, systems similar to \Web{} have been developed for other
% programming languages. But for one of the most complicated
% programming languages (\TeX) the documentation has however been
% neglected.  The \TeX{} world seems to be divided between:---
% \begin{itemize} \item a couple of ``wizards'', who produce many
% lines of completely unreadable code ``off the cuff'', and \item many
% users who are amazed that it works just how they want it to do.  Or
% rather, who despair that certain macros refuse to do what is
% expected of them.\end{itemize}
%
% I do not think that the \Web{} system is {\em the\/} reference work;
% on the contrary, it is a prototype which suffices for the
% development of programs within the \TeX{} world.  It is sufficient,
% but not totally sufficient.\footnote{I know that this will be seen
% differently by a few people, but this product should not be seen as
% the finished product, at least as far as applications concerning
% \TeX{} are concerned.  The long-standing debate over `multiple
% change files' shows this well.} As a result of \Web, new programming
% perspectives have been demonstrated; unfortunately, though, they
% haven't been developed further for other programming languages.
%
% The method of documentation of \TeX{} macros which I have introduced
% here should also only be taken as a first sketch.  It is designed
% explicitly to run under \LaTeX{} alone.  Not because I was of the
% opinion that this was the best starting point, but because from this
% starting point it was the quickest to develop.\footnote{This
% argument is a bad one, however, it is all too often trotted out.} As
% a result of this design decision, I had to move away from the
% concept of modularization; this was certainly a step backward.
%
% I would be happy if this article could spark off discussion over
% \TeX\ documentation.  I can only advise anyone who thinks that they
% can cope without documentation to ``Stop Time'' until he or she
% completely understands the \AmSTeX{} source code.
%
% \subsection*{Using the \DOC{} package}
%
% Just like any other package, invoke it by requesting it with a
% |\usepackage| command in the preamble. \DOC's use of
% |\reversemarginpars| may make it incompatible with some classes.
% \changes{v1.7a}{1992/02/25}{Altered usage info}
%
%
% \end{multicols}
%
%
%
%
% \begin{multicols}{2}[\subsection*{Preface to version 1.7 (from
%    around 1992)}]
%
% This version of \texttt{doc.dtx} documents changes which have occurred
% since the last published version \cite{art:doc} but which have been
% present in distributed versions of \texttt{doc.sty} for some time.  It
% also integrates the (undocumented) features of the distributed
% \texttt{newdoc.sty}.
%
% The following changes and additions have been made to the user
% interface since the published version~\cite{art:doc}.  See
% \S\ref{sec:interface} for more details.
% \begin{description}
% \item[Driver mechanism] |\DocInput| is now used in the driver file
%    to input possibly multiple independent \DOC{} files and \DOC{} no
%    longer has to be the last package.  |\IndexListing| is replaced
%    by |\IndexInput|;
% \item[Indexing] is controlled by |\PageIndex| and |\CodelineIndex|,
%    one of which must be specified to produce an index---there is no
%    longer a |\makeindex| in the default |\DocstyleParms|;
% \item[The \texttt{macro} environment] now takes as argument the
%    macro name {\em with\/} the backslash;
% \item[Verbatim text] Newlines are now forbidden inside |\verb| and
%    commands |\MakeShortVerb| and |\DeleteShortVerb| are provided for
%    verbatim shorthand;
% \item[\texttt{\bslash par}] can now be used in |\DoNotIndex|;
% \item[Checksum/character table support] for ensuring the integrity
%    of distributions is added;
% \item[\texttt{\bslash printindex}] becomes |\PrintIndex|;
% \item[\texttt{multicol.sty}] is no longer necessary to use \DOC{} or
%    print the documentation (although it is recommended);
% \item[`Docstrip' modules] are recognized 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 \pkg{newdoc} and that added after version 1.5k of
% \DOC.  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''!
%
% \subsubsection*{Bugs}
%
% There are some known bugs in this version:
% \begin{itemize}
% \item The |\DoNotIndex| command doesn't work for some single
%    character commands most noticeable |\%|.
% \item The `General changes' glossary entry would come out after
%    macro names with a leading |!| and possibly a leading |"|;
% \item If you have an old version of \prg{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 \prg{makeindex} style files support
%    the inconsistent attribute specifications of older and newer
%    versions \prg{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., \verb"{|}" instead of \verb"{\|}" chaos
%    may happen.
% \end{itemize}
% (Some `features' are documented below.)
%
% \subsubsection*{Wish list}
%
% \begin{itemize}
% \item Hooks to allow |\DescribeMacro| and |\DescribeEnv| to write
% out to a special file information about the package's `exported'
% definitions which they describe.  This could subsequently be
% included in the \texttt{docstrip}ped \texttt{.sty} file in a
% suitable form for use by smart editors in command completion,
% spelling checking etc., based on the packages used in a document.
% This would need agreement on a `suitable form'.  \item Indexing of
% the modules used in \texttt{docstrip}'s |%<| directives.  I'm not
% sure how to index directives containing module combinations; \item
% Writing out bibliographic information about the package; \item Allow
% turning off use of the special font for, say, the next guarded
% block.
% \end{itemize}
%
%
% \end{multicols}


% \subsection*{Acknowledgements}
%
% I would like to thank all folks at Mainz and at the Royal Military
% College of Science for their help in this project. Especially Brian
% and Rainer who pushed everything with their suggestions, bug fixes,
% etc.
%
% A big thank you to David Love who brought the documentation
% up-to-date again, after I neglected this file for more than two
% years. This was most certainly a tough job as many features added to
% \texttt{doc.dtx} after its publication in \textsl{TUGboat\/} have
% been never properly described. Beside this splendid work he kindly
% provided additional code (like ``docstrip'' module formatting) which
% I think every \DOC user will be grateful for.
%
%
% \MaybeStop{
%  \begin{thebibliography}{1}
%    \bibitem{book:Buerger}  \textsc{G. A. B\"urger}.
%      \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldzüge
%                und lustige Abenteuer des Freyherrn v.\ Münchhausen.
%      \newblock London, 1786 \& 1788.
%    \bibitem{art:Knuthliterat} \textsc{D. E. Knuth}.
%      \newblock Literate Programming.
%      \newblock Computer Journal, Vol.~27, \textit{pp}.~97--111,
%               May 1984.
%    \bibitem{book:KnuthA} \textsc{D. E. Knuth}.
%      \newblock Computers \& Typesetting (The \TeX book).
%      \newblock Addison-Wesley, Vol. A, 1986.
%    \bibitem{art:Chen} \textsc{L. Lamport}.
%      \newblock MakeIndex: An Index Processor for \LaTeX.
%      \newblock 17 February 1987.
%      \newblock (Taken from the file \texttt{makeindex.tex} provided
%                 with
%      the program source code.)
%    \bibitem{art:doc} \textsc{Frank Mittelbach}.
%      \newblock The \DOC{}-option.
%      \newblock \textsl{TUGboat}, Vol.~10(2), \textit{pp}.~245--273,
%        July 1989.
%    \bibitem{art:docstrip} \textsc{Frank Mittelbach, Denys Duchier and
%         Johannes Braams}.
%      \newblock \texttt{docstrip.dtx}.
%      \newblock The file is part of core \LaTeX{}.
%    \bibitem{book:Raspe} \textsc{R. E. Raspe} (*1737, \dag 1797).
%      \newblock Baron Münchhausens narrative of his marvelous
%                travels and campaigns in Russia.
%      \newblock Oxford, 1785.
%    \bibitem{art:verbatim} \textsc{Rainer Schöpf}.
%      \newblock A New Implementation of \LaTeX's \texttt{verbatim} and
%      \texttt{verbatim*} Environments.
%      \newblock File \texttt{verbatim.doc}, version 1.4i.
%  \end{thebibliography}
%
%  \addtocontents{toc}{\protect\end{multicols}}
%
%  \PrintIndex
%
% } ^^A end \MaybeStop
%
%
% \section{The Description of Macros}
%
% Most of the following code is destined for \texttt{doc.sty} after
% processing with \texttt{docstrip} to include the module
% \textbf{style} indicated here.  (All code in this file not
% appropriate to \texttt{doc.sty} has to be included explicitly by
% docstrip so that this \texttt{.dtx} file can be used as directly as
% a package file rather than the stripped version.)  The usual font
% change for the conditionally-included lines between the
% \Module{*style} and \Module{/style} directives is suppressed since
% only the lines with an explicit directive are special in this file.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% Under \LaTeXe{} the test to avoid reading
% \DOC{} in twice is normally unnecessary. It was kept to only to
% stay compatible with \LaTeX209 styles that |\input| \DOC{}
% directly.
% \changes{v1.5i}{1989/06/07}{Avoid reading the file twice.}
%    \begin{macrocode}
\@ifundefined{macro@cnt}{}{\endinput}
%    \end{macrocode}
%
% \DescribeObsoleteInterfaceMacro\fileversion
% \DescribeObsoleteInterfaceMacro\filedate
% \DescribeObsoleteInterfaceMacro\docdate
% As you can see I used macros like |\fileversion| to denote the
% version number and the date. They are defined at the very beginning
% of the package file (without a surrounding \env{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 two alternative comment
% signs.  Because all sensible signs are already occupied, we will
% choose some that can only be entered indirectly:
% {\DoNotIndex{\^}^^A avoid misinterpretation !!!!! VERIFY
%    \begin{macrocode}
\catcode`\^^A=14
\catcode`\^^X=14
%    \end{macrocode}
% We repeat this statement at the beginning of the document in case
% the \texttt{inputenc} package is used disabling it again.
% \changes{v2.0b}{1998/05/19}{Init docs private comment char at begin
%  of document again (pr2581)}
%    \begin{macrocode}
\AtBeginDocument{\catcode`\^^A=14\relax\catcode`\^^X=14\relax}
%    \end{macrocode}
%    \SortIndex{\string^\string^A}{\string\verb\verbatimchar
%                                  \string^\string^A\verbatimchar
%                                  \encapchar main}^^A
%    \SortIndex{\string^\string^X}{\string\verb\verbatimchar
%                                  \string^\string^X\verbatimchar
%                                  \encapchar main}
% }
%
%
% \subsection{Keys supported by \DOC{}}
%
%    In the past this used \pkg{kvoptions} but this will be
%    replaced by using \texttt{l3keys} at some point in the future.
%    Right now this is only a lightweight shift---the code could and
%    should be altered further.
%    \fmi{cleanup replacement of kvoptions}
%
% Some keys are available as options for use in \cs{usepackage} some are
% for the generated item \api's:
% \changes{v3.0k}{2022/06/22}{Use \cs{DeclareKeys}}
% \changes{v3.0h}{2022/06/01}{fix choice key name (gh/750)}
% \changes{v3.0h}{2022/06/01}{fix default key name (gh/750)}
%    \begin{macrocode}
\DeclareKeys
  {
    noprint           .if    = {doc@noprint},
    noindex           .if    = {doc@noindex},
    hyperref          .if    = {doc@hyperref},
    nohyperref        .ifnot = {doc@hyperref},
    multicol          .if    = {doc@multicol},
    nomulticol        .ifnot = {doc@multicol},
    debugshow         .if    = {doc@debugshow},
    reportchangedates .if    = {doc@reportchangedates},
    toplevel          .if    = {doc@toplevel},
    notoplevel        .ifnot = {doc@toplevel},
    macrolike         .if    = {doc@macrolike},
    envlike           .ifnot = {doc@macrolike},
    idxtype           .store = \doc@idxtype,
    idxgroup          .store = \doc@idxgroup,
    printtype         .store = \doc@printtype,
    outer             .if    = {doc@outer},
  }
%    \end{macrocode}
%
% Setting these options to true initially.
%    \begin{macrocode}
\doc@hyperreftrue
\doc@multicoltrue
\doc@topleveltrue
%    \end{macrocode}
%
% \subsection{Processing the package keys}
%
%    \begin{macrocode}
\ProcessKeyOptions
%    \end{macrocode}
%
%
% \begin{macro}{\ifscan@allowed}
% \begin{macro}{\scan@allowedtrue}
% \begin{macro}{\scan@allowedfalse}
%    |\ifscan@allowed| is the switch used to determine if
%    the |\active@escape@char|\SpecialIndex{\active@escape@char}
%    should start the macro scanning mechanism.
%    \begin{macrocode}
\newif\ifscan@allowed    \scan@allowedtrue
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%  \begin{imacro}{\SetupDoc}
%
%    We need to save the default value for some options because \DOC elements
%    can locally set them.
% \fmi{Use 2e interface for \cs{keys\_set:nn} when available}
%    \begin{macrocode}
\def\SetupDoc#1{%
  \csname keys_set:nn\endcsname{doc}{#1}%
    \edef\doc@noprintdefault{\ifdoc@noprint true\else false\fi}%
  \ifdoc@noindex
%    \end{macrocode}
%    If we do not index by default then we should also turn off
%    \cs{scan@allowed}.
%    \begin{macrocode}
    \def\doc@noindexdefault{true}%
    \scan@allowedfalse
  \else
    \def\doc@noindexdefault{false}%
  \fi
}
%    \end{macrocode}
%  \end{imacro}
%
%    \begin{macrocode}
\SetupDoc{}              % just save the default values
%    \end{macrocode}
%
%
%
% \subsection{Macros surrounding the `definition parts'}
%
% \begin{environment}{macrocode}
%    Parts of the macro definition will be surrounded by the
%    environment \env{macrocode}.  Put more precisely, they will be
%    enclosed by a macro whose argument (the text to be set
%    `verbatim') is terminated by the string
% \verb*+%    \end{macrocode}+.  Carefully note the number of spaces.
%    |\macrocode| is defined completely analogously to
%    |\verbatim|, but because a few small changes were carried
%    out, almost all internal macros have got new names.  We start by
%    calling the macro |\macro@code|, the macro which bears the
%    brunt of most of the work, such as |\catcode| reassignments,
%    etc.
% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)}
%    \begin{macrocode}
\def\macrocode{\macro@code
%    \end{macrocode}
%    Then we take care that all spaces have the same width, and that
%    they are not discarded.
%    \begin{macrocode}
   \frenchspacing \@vobeyspaces
%    \end{macrocode}
%    Before closing, we need to call |\xmacro@code|.  It is this
%    macro that expects an argument which is terminated by the above
%    string.  This way it is possible to keep the |\catcode|
%    changes local.
% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)}
% \changes{v1.5t}{1989/11/07}{Common code moved to \cs{macro@code}.}
%    \begin{macrocode}
   \xmacro@code}
%    \end{macrocode}
% \end{environment}
%
%
% \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 \env{trivlist} environment, but
%    the empty space before and after the environment should not be
%    too large.
%    \begin{macrocode}
   \topsep \MacrocodeTopsep
%    \end{macrocode}
%    The next parameter we set is |\@beginparpenalty|, in order
%    to prevent a page break before such an environment.
%    \begin{macrocode}
   \@beginparpenalty \predisplaypenalty
%    \end{macrocode}
%    We then start a |\trivlist|, set |\parskip| back to
%    zero and start an empty |\item|.
% \changes{v1.9b}{1993/12/03}{Forcing any label from macro env.}
%    \begin{macrocode}
   \if@inlabel\leavevmode\fi
   \trivlist \parskip \z@ \item[]%
%    \end{macrocode}
%    The \cs{item} command sets the \cs{@labels} box but that box is
%    never typeset (as \cs{everypar} that normally does this gets
%    redefined later). That is normally not an issue, but produces a
%    problem when typesetting in mixed directions, (e.g., in
%    Japanese), so we explicitly clear it for that use case.
%  \changes{v2.1m}{2020/06/15}{Void \cs{@labels} for vertical
%    typesetting (gh/344)}
%    \begin{macrocode}
   \global\setbox\@labels\box\voidb@x
%    \end{macrocode}
%    Additionally, everything should be set in \texttt{typewriter} font.
%    Some people might prefer it somewhat differently; because of this
%    the font choice is
%    macro-driven.\footnote{The font change has to be placed
%                       {\em after\/}
%                       the \texttt{\bslash item}. Otherwise a change to
%                       \texttt{\bslash baselineskip} will affect the
%                       paragraph above.}
%    \begin{macrocode}
   \macro@font
%    \end{macrocode}
%    Because |\item| sets various parameters, we have found it
%    necessary to alter some of these retrospectively.
%    \begin{macrocode}
   \leftskip\@totalleftmargin \advance\leftskip\MacroIndent
   \rightskip\z@ \parindent\z@ \parfillskip\@flushglue
%    \end{macrocode}
%    The next line consists of the \LaTeX{} definition of |\par|
%    used in |\verbatim| and should result in blank lines being
%    shown as blank lines.
% \changes{v1.5l}{1989/09/10}{Code line numbers supported.}
% \changes{v1.5t}{1989/11/07}{Call \cs{leavevmode} to get \cs{everypar}
%                           on blank lines.}
% \changes{v1.7c}{1992/03/24}{Added \cs{interlinepenalty} to
%                          \cs{par} from
%                          verbatim.sty}
%    \begin{macrocode}
   \blank@linefalse \def\par{\ifblank@line
                             \leavevmode\fi
                             \blank@linetrue\@@par
                             \penalty\interlinepenalty}
%    \end{macrocode}
%    What use is this definition of |\par|\,?  We use the macro
%   |\obeylines| of \cite{book:KnuthA} which changes all |^^M|
%    to |\par| so that each can control its own indentation.
%    Next we must also ensure that all special signs are normalized;
%    that is, they must be given |\catcode| $12$.
% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
%                           which handles more ligatures.}
%  \changes{v3.0o}{2023/12/30}{Use \cs{@noligs} from the \LaTeX\
%            kernel, so that the \texttt{upquote} package can
%            add its patch (gh/1230)}
%    \begin{macrocode}
   \obeylines
   \@noligs
   \let\do\@makeother \dospecials
%    \end{macrocode}
% \changes{v1.5t}{1989/11/07}{Common code added.}
% \changes{v1.5w}{1990/02/05}{Skip of \cs{@totalleftmargin} added.} If
% indexing by code lines is switched on the line number is incremented
% and set appropriately.  We also check whether the start of the next
% line indicates a \texttt{docstrip} module directive and process it
% appropriately if so using |\check@module|.
%    \begin{macrocode}
   \global\@newlistfalse
   \global\@minipagefalse
   \ifcodeline@index
     \everypar{\global\advance\c@CodelineNo\@ne
               \llap{\theCodelineNo\ \hskip\@totalleftmargin}%
               \check@module}%
   \else \everypar{\check@module}%
   \fi
%    \end{macrocode}
%    We also initialize the cross-referencing feature by calling
%    |\init@crossref|. This will start the scanning mechanism
%    when encountering an escape character.
%    \begin{macrocode}
   \init@crossref}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\ifblank@line}
% \begin{macro}{\blank@linetrue}
% \begin{macro}{\blank@linefalse}
%    |\ifblank@line| is the switch used in the definition above.
%    In the original \env{verbatim} environment the |\if@tempswa|
%    switch is used. This is dangerous because its value may change
%    while processing lines in the \env{macrocode} environment.
%    \begin{macrocode}
\newif\ifblank@line
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\endmacrocode}
%    Because we have begun a \env{trivlist} environment in the
%    \env{macrocode} environment, we must also end it.  We must
%    also act on the value of the |pm@module| flag (see below) and
%    empty |\everypar|.
% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)}
%    \begin{macrocode}
\def\endmacrocode{%
                 \ifpm@module \endgroup \pm@modulefalse \fi
                 \everypar{}%
                 \global\@inlabelfalse
                 \endtrivlist
%    \end{macrocode}
%    Additionally |\close@crossref| is used to do anything needed
%    to end the cross-referencing mechanism.
%    \begin{macrocode}
                 \close@crossref}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{imacro}{\MacroFont}
%    Here is the default definition for the |\MacroFont| macro.
%    With the new math font handling in NFSS2 it isn't any longer
%    correct to suppress the math font setup since this is now handled
%    differently. But to keep the font change fast we use only a
%    single |\selectfont| (in |\small|) and do the rest by hand.
% \changes{v1.5x}{1990/02/17}{\cs{math@fontsfalse} added for NFSS.}
% \changes{v1.7a}{1992/03/13}{Added \cs{reset@font} for NFSS.}
% \changes{v1.8c}{1993/10/25}{NFSS standard}
% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different
%                             math setup /pr1622)}
%    \begin{macrocode}
\@ifundefined{MacroFont}{%
  \if@compatibility
%    \end{macrocode}
%    Despite the above statement we will call |\small| first if
%    somebody is using a \LaTeX2.09 document with doc. I wouldn't have
%    bothered since doc-sources should be up-to-date but since the
%    request came from someone called David Carlisle \ldots :-)
% \changes{v1.9y}{1996/01/26}{Support compat mode}
% \changes{v2.1l}{2019/12/16}{Use \cs{shapedefault} not
%    \cs{updefault} for extended NFSS}
%    \begin{macrocode}
    \def\MacroFont{\small
                   \usefont\encodingdefault
                           \ttdefault
                           \mddefault
                           \shapedefault
                   }%
  \else
    \def\MacroFont{\fontencoding\encodingdefault
                   \fontfamily\ttdefault
                   \fontseries\mddefault
                   \fontshape\shapedefault
                   \small}%
  \fi
  }{}
%    \end{macrocode}
% \end{imacro}
%
% \begin{imacro}{\AltMacroFont}
% \begin{macro}{\macro@font}
% \changes{v1.7a}{1992/03/12}{Added to support distinction of modules.}
% \changes{v1.7c}{1992/03/26}{Altered font change for OFSS.}
% \changes{v1.7m}{1992/10/11}{Use sltt as default.}
% \changes{v1.8c}{1993/10/25}{NFSS standard}
% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different
%                             math setup /pr1622)}
% Although most of the macro code is set in |\MacroFont| we want to be
% able to switch to indicate module code set in |\AltMacroFont|.
% |\macro@font| keeps track of which one we're using.  We can't do the
% same thing sensibly in OFSS as in NFSS.
%    \begin{macrocode}
\@ifundefined{AltMacroFont}{%
  \if@compatibility
%    \end{macrocode}
%    Again have |\small| first if we are in compat mode.
% \changes{v1.9y}{1996/01/26}{Support compat mode}
%    \begin{macrocode}
    \def\AltMacroFont{\small
                      \usefont\encodingdefault
                              \ttdefault
                              \mddefault
                              \sldefault
                      }%
  \else
    \def\AltMacroFont{\fontencoding\encodingdefault
                      \fontfamily\ttdefault
                      \fontseries\mddefault
                      \fontshape\sldefault
                      \small
                      }%
 \fi
  }{}
%    \end{macrocode}
%    To allow changing the |\MacroFont| in the preamble we defer
%    defining the internally used |\macro@font| until after the
%    preamble.
% \changes{v2.0a}{1998/05/16}{Support changing \cs{MacroFont} in
%          preamble}
%    \begin{macrocode}
\AtBeginDocument{\let\macro@font\MacroFont}
%    \end{macrocode}
% \end{macro}
% \end{imacro}
%
% \begin{macro}{\check@module}
% \begin{macro}{\ifpm@module}
% \changes{v1.7a}{1992/03/12}{Added.}
% This is inserted by |\everypar| at the start of each macrocode line to
% check whether it starts with module information.  (Such information is
% of the form |%<|\meta{switch}|>|, where the |%| must be at the
% start of the line and \meta{switch} comprises names with various
% possible separators and a possible leading |+|, |-|, |*| or |/|
% \cite{art:docstrip}.  All that concerns us here is what the first
% character of \meta{switch} is.)  First it checks the |pm@module|
% flag in case the previous line had a non-block module
% directive i.e., not |%<*| or |%</|; if it did we need to close the
% group it started and unset the flag.  |\check@module| looks ahead at
% the next token and then calls |\ch@percent| to take action depending
% on whether or not it's a |%|; we don't want to expand the token at
% this stage.  This is all done conditionally so it can be turned off
% if it causes problems with code that wasn't designed to be
% \texttt{docstrip}ped.
%    \begin{macrocode}
\def\check@module{%
  \ifcheck@modules
    \ifpm@module \endgroup \pm@modulefalse \fi
    \expandafter\futurelet\expandafter\next\expandafter\ch@percent
  \fi}
\newif\ifpm@module
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{imacro}{\DontCheckModules}
% \begin{imacro}{\CheckModules}
% \changes{v1.7a}{1992/03/12}{Added.}
% \begin{macro}{\ifcheck@modules}
% Here are two driver-file interface macros for turning the module
% checking on and off using the |check@modules| switch.
%    \begin{macrocode}
\def\DontCheckModules{\check@modulesfalse}
\def\CheckModules{\check@modulestrue}
\newif\ifcheck@modules  \check@modulestrue
%    \end{macrocode}
% \end{macro}
% \end{imacro}
% \end{imacro}
%
%
% \begin{macro}{\ch@percent}
% \changes{v1.7a}{1992/03/12}{Added.}
% If the lookahead token in |\next| is $|%|_{12}$ we go on to check
% whether the following one is |<| and otherwise do nothing.  Note the
% |\expandafter| to get past the |\fi|.
%    \begin{macrocode}
\def\ch@percent{%
  \if \percentchar\next
    \expandafter\check@angle
  \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\check@angle}
% \changes{v1.7a}{1992/03/12}{Added.}
% Before looking ahead for the |<| the |%| is gobbled by the
% argument here.
%    \begin{macrocode}
\def\check@angle#1{\futurelet\next\ch@angle}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ch@angle}
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.9k}{1994/02/22}{Have \texttt{<} active}
%    If the current lookahead token is |<| we are defined to be
%    processing a module directive can go on to look for |+| etc.;
%    otherwise we must put back the gobbled |%|. With \LaTeXe{}
%    \texttt{<} is active so we have to be a bit careful.
%    \begin{macrocode}
\begingroup
\catcode`\<\active
\gdef\ch@angle{\ifx<\next
    \expandafter\ch@plus@etc
  \else \percentchar \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ch@plus@etc}
% \begin{macro}{\check@plus@etc}
% \changes{v1.7a}{1992/03/12}{Added.}
% We now have to decide what sort of a directive we're dealing with
% and do the right thing with it.
%    \begin{macrocode}
\gdef\ch@plus@etc<{\futurelet\next\check@plus@etc}
\gdef\check@plus@etc{%
    \if +\next
      \let\next\pm@module
    \else\if -\next
      \let\next\pm@module
    \else\if *\next
      \let\next\star@module
    \else\if /\next
      \let\next\slash@module
%    \end{macrocode}
%    At some point in the past the \texttt{docstrip} program was
%    partly rewritten and at that time it also got support for a very
%    special directive of the form |%<<| followed by an arbitrary
%    string. This is used for ``verbatim'' inclusion in case of
%    certain problem. We do not really attempt to pretty print that
%    case but we need at least account for it since otherwise we get
%    an error message since this is the only case where we will not
%    have a closing |>|.
% \changes{v2.0n}{2001/05/16}{Partly support docstrip's ``verbatim''
%    directive (pr/3331)}
%    \begin{macrocode}
    \else\ifx <\next
      \percentchar
    \else
      \let\next\pm@module
    \fi\fi\fi\fi\fi
    \next}
\endgroup
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\pm@module}
% If we're not dealing with a block
% directive (|*| or |/|) i.e., it's a single special line, we set
% everything up to the next |>| appropriately and then change to the
% special macro font inside a group which will be ended at the start
% of the next line.  If the apparent module directive is missing the
% terminating |>| this will lose, but then so will the \texttt{docstrip}
% implementation.  An alternative strategy would be to have
% |\pm@module| make |>| active and clear a flag set here to indicate
% processing the directive.  Appropriate action could then be taken if
% the flag was found still to be set when processing the next line.
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.7i}{1992/07/11}{Support for fonts depending on nesting.}
%    \begin{macrocode}
\begingroup
\catcode`\~=\active
\lccode`\~=`\>
\lowercase{\gdef\pm@module#1~}{\pm@moduletrue
   \Module{#1}\begingroup
%    \end{macrocode}
%    We switch to a special font as soon the nesting is higher than
%    the current value of |\c@StandardModuleDepth|. We do a local
%    update to the |\guard@level| here which will be restored after
%    the current input line.
%    \begin{macrocode}
     \advance\guard@level\@ne
     \ifnum\guard@level>\c@StandardModuleDepth\AltMacroFont\fi
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\star@module}
% \begin{macro}{\slash@module}
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.7f}{1992/05/16}{Take account of nested guards.}
% \changes{v1.7i}{1992/07/11}{Add counter to determine when to switch to
%                           special font.}
% If the start or end of a module {\em block\/} is indicated, after
% setting the guard we have to check whether a change in the macrocode
% font should be done.  This will be the case if we are already inside
% a block or are ending the outermost block.  If so, we globally
% toggle the font for subsequent macrocode sections between the normal
% and special form, switching to the new one immediately.
% \changes{v1.7i}{1992/07/17}{Support for fonts depending on module
%                           nesting}
%    \begin{macrocode}
\lowercase{\gdef\star@module#1~}{%
  \Module{#1}%
  \global \advance \guard@level\@ne
  \ifnum \guard@level>\c@StandardModuleDepth
    \global\let\macro@font=\AltMacroFont \macro@font
  \fi}
\catcode`\>=\active
\gdef\slash@module#1>{%
  \Module{#1}%
  \global \advance \guard@level\m@ne
  \ifnum \guard@level=\c@StandardModuleDepth
    \global\let\macro@font\MacroFont  \macro@font
  \fi
}
\endgroup
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%  \begin{lcounter}{StandardModuleDepth}
% \changes{v1.7i}{1992/07/11}{Counter added.}
%    Counter defining up to which level modules are considered part of
%    the main code. If, for  example, the whole code is surrounded by
%    a |%<*package>| module we better set this counter to |1| to avoid
%    getting the whole code be displayed in typewriter italic.
%    \begin{macrocode}
\newcounter{StandardModuleDepth}
%    \end{macrocode}
%  \end{lcounter}
%
%
% \begin{tcounter}{\guard@level}
% \changes{v1.7f}{1992/05/16}{Added.}
% We need a counter to keep track of the guard nesting.
%    \begin{macrocode}
\newcount \guard@level
%    \end{macrocode}
% \end{tcounter}

% \begin{macro}{\Module}
% \changes{v1.7a}{1992/03/12}{Added.}
% \changes{v1.7d}{1992/04/25}{Use sans font for modules.}
% This provides a hook to determine the way the module directive is
% set.  It gets as argument everything between the angle brackets.
% The default is to set the contents in sans serif text between
% $\langle\,\rangle$ with the special characters suitably |\mathcode|d
% by |\mod@math@codes|.  (You can't just set it in a sans text font
% because normally \verb"|" will print as an em-dash.)  This is done
% differently depending on whether we have the NFSS or the old one.  In
% the latter case we can easily change |\fam| appropriately.
% \changes{v1.8c}{1993/10/25}{NFSS standard}
%    \begin{macrocode}
\@ifundefined{Module}{%
%    \end{macrocode}
%    With NFSS what we probably {\em should\/} do is change to a new
%    |\mathversion| but I (Dave Love) haven't spotted an easy way to
%    do so correctly if the document uses a version other than
%    |normal|.  (We need to know in what font to set the other
%    groups.)  This uses a new math alphabet rather than version and
%    consequently has to worry about whether we're using
%    \env{oldlfnt} or not.  I expect there's a better
% way\ldots
%    \begin{macrocode}
      \def\Module#1{\mod@math@codes$\langle\mathsf{#1}\rangle$}
  }{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\mod@math@codes}
% \changes{v1.7c}{1992/03/26}{Added.}
% \changes{v2.1e}{2010/02/04}{Added mathcodes for +,-,:, and = (pr/4096)}
%    As well as `words', the module
%    directive text might contain any of the characters \verb"*/+-,&|!()"
%    for the current version of \prg{docstrip}.  We only need
%    special action for two of them in the math code changing required
%    above: \verb"|" is changed to a |\mathop| (it's normally |"026A|) and
%    |&| is also made a |\mathop|, but in family 0.  Remember that |&|
%    will not have a special catcode when it's encountered.
%    \begin{macrocode}
\def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026
                    \mathcode`\-="702D \mathcode`\+="702B
                    \mathcode`\:="703A \mathcode`\=="703D }
%    \end{macrocode}
% \end{macro}
%
%
% \begin{lskip}{\MacrocodeTopsep}
% \begin{ldimen}{\MacroIndent}
%    In the code above, we have used two registers. Therefore we have
%    to allocate them. The default values might be overwritten with
%    the help of the |\DocstyleParms| macro.
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
% \changes{v1.5y}{1990/02/24}{Default changed.}
% \changes{v1.6b}{1990/06/15}{\cs{rm} moved before \cs{scriptsize} to
%                           avoid unnecessary fontwarning.}
%    \begin{macrocode}
\newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt
\newdimen\MacroIndent
\settowidth\MacroIndent{\rmfamily\scriptsize 00\ }
%    \end{macrocode}
% \end{ldimen}
% \end{lskip}
%
%
%
%
% \begin{environment}{macrocode*}
% \begin{macro}{\endmacrocode*}
%    Just as in the \env{verbatim} environment, there is also a
%    `star' variant of the \env{macrocode} environment in which a
%    space is shown by the symbol \verb*+ +.  Until this moment, I
%    have not yet used it (it will be used in the description of the
%    definition of |\xmacro@code| below) but it's exactly on this one
%    occasion {\em here\/} that you can't use it (cf.\ Münchhausens
%    Marsh problem)\footnote{Karl Friedrich Hieronymus Frhr.\ v.\
%    Münchhausen (*1720, \dag1797).  Several books were written
%    about fantastic adventures supposedly told by him (see
%    \cite{book:Raspe} or \cite{book:Buerger}). In one story he
%    escaped from the marsh by pulling himself out by his hair.}
%    directly. Because of this, on this one occasion we'll cheat
%    around the problem with an additional comment character.  But now
%    back to |\macrocode*|. We start with the macro |\macro@code|
%    which prepares everything and then call the macro |\sxmacro@code|
%    whose argument is terminated by the string
%\verb*+%    \end{macrocode*}+.
%    \begin{macrocode}
\@namedef{macrocode*}{\macro@code\sxmacro@code}
%    \end{macrocode}
%    As we know, |\sxmacro@code| and then |\end{macrocode*}|
%    (the macro, not the string), will be executed, so that for a
%    happy ending we still need to define the macro
%    |\endmacrocode*|.
%    \begin{macrocode}
\expandafter\let\csname endmacrocode*\endcsname = \endmacrocode
%    \end{macrocode}
% \end{macro}
% \end{environment}
%
%
%
%
%
%
%
% \begin{macro}{\xmacro@code}
\catcode`\!=\catcode`\%   ^^A In this section there must not be
                              ^^A any exclamation marks.
                              ^^A
%    As already mentioned, the macro |\xmacro@code| expects an
%    argument delimited by the string \verb*+%    \end{macrocode}+.  At
%    the moment that this macro is called, the |\catcode| of
%    \TeX's special characters are 12 (`other') or 13 (`active').
%    Because of this we need to utilize a different escape character
%    during the definition.  This happens locally.
%    \begin{macrocode*}
\begingroup
\catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@
%    \end{macrocode*}
%    Additionally, we need to ensure that the symbols in the above
%    string contain the |\catcode|$\,$s which are available
%    within the \env{macrocode} environment.
%    \begin{macrocode*}
\catcode`\{=12 \catcode`\}=12
\catcode`\%=12 \catcode`\ =\active \catcode`\\=\active
!%    \end{macrocode*}
!    Next follows the actual definition of  |\macro@code|;
!    notice the
!    use of the new escape character.  We manage to get the argument
!    surrounded by the string |\end{macrocode}|, but at the end
!    however, in spite of the actual characters used during the
!    definition of
!    this macro, |\end| with the argument |{macrocode}|
!    will be executed, to ensure a balanced environment.
!    \begin{macrocode*}
|gdef|xmacro@code#1%    \end{macrocode}[#1|end[macrocode]]
!%    \end{macrocode*}
! \begin{macro}{\sxmacro@code}
!    The definition of |\sxmacro@code| is completely analogous,
!    only
!    here a slightly different terminating string will be used.
!    Note that the space is not active in this environment.
!    \begin{macrocode}
|catcode`| =12
|gdef|sxmacro@code#1%    \end{macrocode*}[#1|end[macrocode*]]
!%    \end{macrocode}
!    because the |\catcode| changes have been made local by
!    commencing a
!    new group, there now follows the matching |\endgroup|
!    in a rather
!    unusual style of writing.
!    \begin{macrocode}
|endgroup
!%    \end{macrocode}
\catcode`\!=12
% \end{macro}
% \end{macro}
%
%
%
%
% \subsection{Macros for the `documentation parts'}
%
%

%    To put the labels in the left margin we have to use the
%    |\reversemarginpar| declaration. (This means that the
%    \texttt{doc.sty} can't be used with all classes or packages.)
%    We also
%    make the |\marginparpush| zero and |\marginparwidth| suitably
%    wide.
% \changes{v1.5d}{1989/04/28}{\cs{marginparwidth} setting added.}
%    \begin{macrocode}
\reversemarginpar
\setlength\marginparpush{0pt}  \setlength\marginparwidth{8pc}
%    \end{macrocode}
%
%    \begin{macrocode}
\setlength\marginparsep{\labelsep}
%    \end{macrocode}
%
% \begin{imacro}{\bslash}
% \changes{v1.7a}{1992/02/26}{Moved \cs{bslash} documentation to `user
%                           interface' part}
%    We start a new group in which to hide the alteration of
%    |\catcode|$\,$s, and make \verb+|+ introduce commands,
%    whilst |\| becomes an `other' character.
%
%    \begin{macrocode}
{\catcode`\|=\z@ \catcode`\\=12
%    \end{macrocode}
%    Now we are able to define |\bslash| (globally) to generate a
%    backslash of |\catcode| `other'.  We then close this group,
%    restoring original |\catcode|$\,$s.
%    \SpecialEscapechar{\|}
%    \begin{macrocode}
|gdef|bslash{\}}
%    \end{macrocode}
% \end{imacro}
%
%
%
% \begin{environment}{verbatim}
% \begin{environment}{verbatim*}
% \changes{v1.7i}{1992/07/12}{Added changed definition for verbatim!*.}
%    The \env{verbatim} environment holds no secrets; it consists of
%    the normal \LaTeX{} environment.  We also set the
%    |\@beginparpenalty| and change to the font given by
%    |\MacroFont|.
%    \begin{macrocode}
\def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim
              \MacroFont \frenchspacing \@vobeyspaces \@xverbatim}
%    \end{macrocode}
%    We deal in a similar way with the star form of this environment.
%    \begin{macrocode}
\@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim
%    \end{macrocode}
%
%  \changes{v2.1j}{2019/11/03}{Kernel now sets up \cs{verbvisiblespace} (gh/205)}
%  \changes{v2.1k}{2019/11/10}{Put the definition into the right command (gh/205)}
%    \begin{macrocode}
              \@setupverbvisiblespace
              \MacroFont \@vobeyspaces \@sxverbatim}
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{macro}{\@verbatim}
%    Additionally we redefine the |\@verbatim| macro so that it
%    suppresses |%| characters at the beginning of the line.  The
%    first lines are copied literally from \texttt{latex.tex}.
% \changes{v1.7i}{1992/07/12}{Added \cs{@@par} to clear possible
%                             \cs{parshape}.}
%  \changes{v3.0m}{2022/11/13}{Redefinitions of \cs{@verbatim} changed
%     to match the kernel definition (gh/953)}
%    \begin{macrocode}
\def\@verbatim{\trivlist \item\relax
  \if@minipage\else\vskip\parskip\fi
  \leftskip\@totalleftmargin\rightskip\z@
  \parindent\z@\parfillskip\@flushglue\parskip\z@
  \language\l@nohyphenation
  \@@par
  \@tempswafalse
%    \end{macrocode}
%    |\@verbatim| sets |^^M|, the end of line character, to
%    be equal to |\par|.  This control sequence is redefined
%    here; |\@@par| is the paragraph primitive of \TeX.
%    \changes{v1.7c}{1992/03/24}{Added \cs{interlinepenalty} to
%                             \cs{par} from verbatim.sty}
%    \begin{macrocode}
  \def\par{%
    \if@tempswa
      \leavevmode \null \@@par\penalty\interlinepenalty
    \else
      \@tempswatrue
      \ifhmode\@@par\penalty\interlinepenalty\fi
    \fi    
%    \end{macrocode}
%    We add a control sequence |\check@percent| to the definition
%    of |\par| whose task it is to check for a percent character.
%    \begin{macrocode}
   \check@percent}%
%    \end{macrocode}
%    The rest is again copied literally from \texttt{latex.tex} (less
%    "\tt").
% \changes{v1.7a}{1992/02/26}{Removed redundant \cs{tt}.}
% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
%                           which handles more ligatures.}
%    \begin{macrocode}
  \let\do\@makeother \dospecials
  \obeylines \verbatim@font \@noligs
  \everypar \expandafter{\the\everypar \unpenalty}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\check@percent}
%    Finally we define |\check@percent|.  Since this must compare a
%    character with a percent sign we must first (locally) change
%    percent's |\catcode| so that it is seen by \TeX.  The definition
%    itself is nearly trivial: grab the following character, check if
%    it is a |%|, and insert it again if not.  At the end of the
%    \env{verbatim} environment this macro will peek at the next
%    input line. In that case the argument to |\check@percent| might
%    be a |\par| or a macro with arguments. Therefore we make the
%    definition |\long| (|\par| allowed) and use the normal |\next|
%    mechanism to reinsert the argument after the |\fi| if necessary.
%  \changes{v1.5i}{1989/06/07}{Definition changed to `long'}
%  \changes{v1.5i}{1989/06/07}{Macro \cs{next} used to guard against
%                            macro with arguments}
%    There is a subtle problem here, the equal sign between
%    |\next| and |#1| is actually necessary. Do you see why?
%    The omission of this token once caused a funny error.
%  \changes{v1.5u}{1989/11/14}{equal sign added.}
%    \begin{macrocode}
{\catcode`\%=12
 \long\gdef\check@percent#1{\ifx #1%\let\next\@empty \else
                                    \let\next=#1\fi \next}}
%    \end{macrocode}
% \end{macro}
%
%
% In the early versions of the package it also redefined \cs{verb}
% because that didn't include the useful test for \enquote{newline} in
% the verbatim text. This is nowadays part of \LaTeX{} so we do not
% redefine it any longer (the original code is still kept in the file
% after \cs{endinput} to keep the long history intact).
%
% \begin{tcounter}{\macro@cnt}
%    \label{page:macro} The \env{macro} environment is implemented as
%    a \env{trivlist} environment, whereby in order that the macro
%    names can be placed under one another in the margin
%    (corresponding to the macro's nesting depth), the macro
%    |\makelabel| must be altered.  In order to store the nesting
%    depth, we use a counter. We also need a counter to count the
%    number of nested \env{macro} environments.
% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
% \changes{v1.9k}{1994/02/22}{Fix probably no longer necessary}
%    \begin{macrocode}
\newcount\macro@cnt \macro@cnt=0
%    \end{macrocode}
% \end{tcounter}
%
%
% \begin{lskip}{\MacroTopsep}
%    Here is the default value for the |\MacroTopsep| parameter
%    used above.
%    \begin{macrocode}
\newskip\MacroTopsep     \MacroTopsep = 7pt plus 2pt minus 2pt
%    \end{macrocode}
% \end{lskip}
%
%
%
%
%
% \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.
%
%
% \subsection{Creating index entries by scanning `macrocode'}
%
%  The following macros ensure that index entries are created for each
%  occurrence of a \TeX-like command (something starting with
%  `|\|') providing indexing has been turned on with |\PageIndex|
%  or |\CodelineIndex|.  With the default definitions of
%  |\specialMainMacroIndex|, etc., the index file generated is
%  intended to be processed by Chen's \prg{makeindex} program
%  \cite{art:Chen}.
%
%
%  Of course, in {\em this\/} package file itself we've sometimes had to
%  make \verb+|+ take the r\^ole of \TeX's escape character to
%  introduce command names at places where |\| has to belong to
%  some other category.  Therefore, we may also need to recognize
%  \verb+|+ as the introducer for a command when setting the text
%  inside the \env{macrocode} environment.  Other users may have the
%  need to make similar reassignments for their macros.
%
%
% \begin{imacro}{\SpecialEscapechar}\label{sect:specialescapechar}
% \begin{macro}{\active@escape@char}
% \begin{macro}{\special@escape@char}
%    The macro |\SpecialEscapechar| is used to denote a special escape
%    character for the next \env{macrocode} environment. It has one
%    argument---the new escape character given as a `single-letter'
%    control sequence.  Its main purpose is defining
%    |\special@escape@char| to produce the chosen escape character
%    |\catcode|$\,$d to 12 and |\active@escape@char| to produce the
%    same character but with |\catcode| 13.
%
%    The macro |\special@escape@char| is used to {\em print\/}
%    the escape character while |\active@escape@char| is needed
%    in the definition of |\init@crossref| to start the scanning
%    mechanism.
%
%    In the definition of |\SpecialEscapechar| we need an
%    arbitrary character with |\catcode| 13. We use `\~{}' and
%    ensure that it is active. The |\begingroup| is used to make
%    a possible change local to the expansion of
%    |\SpecialEscapechar|.
% \changes{v1.7g}{1992/06/19}{Making tilde active moved outside
%    definition}
%    \begin{macrocode}
\begingroup
\catcode`\~\active
\gdef\SpecialEscapechar#1{%
    \begingroup
%    \end{macrocode}
%    Now we are ready for the definition of
%    |\active@escape@char|.  It's a little tricky: we first
%    define locally the uppercase code of `\~{}' to be the new escape
%    character.
%    \begin{macrocode}
     \uccode`\~`#1%
%    \end{macrocode}
%    Around the definition of |\active@escape@char| we place an
%    |\uppercase| command. Recall that the expansion of
%    |\uppercase| changes characters according to their
%    |\uccode|, but leaves their |\catcode|$\,$s untouched
%    (cf.\ \TeX{}book page 41).
%    \begin{macrocode}
     \uppercase{\gdef\active@escape@char{~}}%
%    \end{macrocode}
%    The definition of |\special@escape@char| is easier, we use
%    |\string| to |\catcode| the argument of
%    |\SpecialEscapechar| to 12 and suppress the preceding
%    |\escapechar|.
%    \begin{macrocode}
     \escapechar\m@ne  \xdef\special@escape@char{\string#1}%
%    \end{macrocode}
%    Now we close the group and end the definition: the value of
%    |\escapechar| as well as the |\uccode| and
%    |\catcode| of `\~{}' will be restored.
%    \begin{macrocode}
   \endgroup}
\endgroup
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{imacro}
%
%
%
%
% \begin{macro}{\init@crossref}
%    The replacement text of |\init@crossref| should fulfill the
%    following tasks:
%    \begin{itemize}
%       \parindent4em
%       \item[(1)]
%          |\catcode| all characters used in macro names to
%          11 (i.e., `letter').
%       \item[(2)]
%          |\catcode| the `|\|' character to 13
%          (i.e., `active').
%       \item[(3a)]
%          |\let| the `|\|' equal |\scan@macro|
%          (i.e., start the macro scanning mechanism) if there is
%          no  special escape character (i.e., the
%          |\special@escape@char| is `|\|').
%       \item[(3b)]
%          Otherwise |\let| it equal |\bslash|, i.e.\
%          produce a printable |\|.
%       \item[(4)]
%          Make the \meta{special escape character} active.
%       \item[(5)]
%          |\let| the active version of the special escape
%          character
%          (i.e., the expansion of |\active@escape@char|) equal
%          |\scan@macro|.
%    \end{itemize}
%    The reader might ask why we bother to |\catcode| the
%    `|\|' first to 12 (at the end of |\macro@code|) then
%    re-|\catcode| it to 13 in order to produce a $|\|_{12}$
%    in case (3b) above.  This is done because we have to ensure that
%    `|\|' has |\catcode| 13 within the \env{macrocode}
%    environment.  Otherwise the delimiter for the argument of
%    |\xmacro@code| would not be found (parameter matching
%    depends on |\catcode|$\,$s).
%
%    Therefore we first re-|\catcode| some characters.
%    \begin{macrocode}
\begingroup   \catcode`\|=\z@  \catcode`\\=\active
%    \end{macrocode}
%    We carry out tasks (2) and (3b) first.
%    \SpecialEscapechar\|
%    \begin{macrocode}
|gdef|init@crossref{|catcode`|\|active   |let\|bslash
%    \end{macrocode}
%    Because of the popularity of the `|@|' character as a
%    `letter' in macros, we normally have to change its
%    |\catcode| here, and thus fulfill task (1).  But the macro
%    designer might use other characters as private letters as well,
%    so we use a macro to do the |\catcode| switching.
%    \SpecialEscapechar\|
%    \begin{macrocode}
    |MakePrivateLetters
%    \end{macrocode}
%    Now we |\catcode| the special escape character to 13 and
%    |\let| it equal |\scan@macro|, i.e., fulfill tasks (4)
%    and (5). Note the use of |\expandafter| to insert the chosen
%    escape character saved in |\special@escape@char| and
%    |\active@escape@char|.
%    \SpecialEscapechar\|
%    \begin{macrocode}
    |catcode|expandafter`|special@escape@char|active
    |expandafter|let|active@escape@char|scan@macro}
|endgroup
%    \end{macrocode}
%    If there is no special escape character, i.e., if
%    |\SpecialEscapechar| is |\\|, the second last line will
%    overwrite the previous definition of $|\|_{13}$.  In this
%    way all tasks are fulfilled.
%
%    For happy documenting we give default values to
%    |\special@escape@char| and |\active@escape@char| with
%    the following line:
%    \begin{macrocode}
\SpecialEscapechar{\\}
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{imacro}{\MakePrivateLetters}
%    Here is the default definition of this command, which makes just
%    the |@| into a letter. The user may change it if he/she
%    needs more or other characters masquerading as letters.
%    \begin{macrocode}
\@ifundefined{MakePrivateLetters}
    {\let\MakePrivateLetters\makeatletter}{}
%    \end{macrocode}
% \end{imacro}
%
% \begin{macro}{\close@crossref}
%    At the end of a cross-referencing part we prepare ourselves for
%    the next one by setting the escape character to `|\|'.
%    \begin{macrocode}
\def\close@crossref{\SpecialEscapechar\\}
%    \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{Macros for scanning macro names}
%
% \begin{macro}{\scan@macro}
% \changes{v1.5k}{1989/09/04}{Support for checksum added.}
% \begin{macro}{\macro@namepart}
%    The |\init@crossref| will have made |\active| our
%    |\special@escape@char|, so that each
%    |\active@escape@char| will invoke |\scan@macro| when
%    within the \env{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
%    \env{macrocode} environments.
%    \begin{macrocode}
\def\scan@macro{%
%    \end{macrocode}
%    First we output the character which triggered this macro.  Its
%    version |\catcode|$\,$d to 12 is saved in
%    |\special@escape@char|. We also call |\step@checksum|
%    to generate later on a proper check-sum (see section
%    \ref{sec:checksum} for details).
%    \begin{macrocode}
   \special@escape@char
   \step@checksum
%    \end{macrocode}
%    If the \env{macrocode} environment contains, for example, the
%    command |\\|, the second |\| should not start the
%    scanning mechanism. Therefore we use a switch to decide if
%    scanning of macro names is allowed.
%    \begin{macrocode}
   \ifscan@allowed
%    \end{macrocode}
%    The macro assembles the letters forming a \TeX\ command in
%    |\macro@namepart| so this is initially cleared; we then set
%    |\next| to the \textit{first\/} character following the
%    |\| and call |\macro@switch| to determine whether that
%    character is a letter or not.
%    \begin{macrocode}
      \let\macro@namepart\@empty
      \def\next{\futurelet\next\macro@switch}%
%    \end{macrocode}
%    As you recognize, we actually did something else, because we have
%    to defer the |\futurelet| call until after the final
%    |\fi|.  If, on the other hand, the scanning is disabled we
%    simply |\let| |\next| equal `empty'.
%    \begin{macrocode}
   \else \let\next\@empty \fi
%    \end{macrocode}
%    Now we invoke |\next| to carry out what's needed.
%    \begin{macrocode}
   \next}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
% \begin{imacro}{\EnableCrossrefs}
% \begin{imacro}{\DisableCrossrefs}
%    At this point we might define two macros which allow the user to
%    disable or enable the cross-referencing mechanism. Processing of
%    files will be faster if only main index entries are generated
%    (i.e., if |\DisableCrossrefs| is in force).
%    \begin{macrocode}
\def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack}
%    \end{macrocode}
%    The macro |\EnableCrossrefs| will also disable any
%    |\DisableCrossrefs| command encountered afterwards.
%    \begin{macrocode}
\def\EnableCrossrefs{\@bsphack\scan@allowedtrue
                     \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack}
%    \end{macrocode}
% \end{imacro}
% \end{imacro}
%
%
%
%
% \begin{macro}{\macro@switch}
%    Now that we have the character which follows the escape character
%    (in |\next|), we can determine whether it's a `letter'
%    (which probably includes |@|).
%
%    If it is, we let |\next| invoke a macro which assembles the
%    full command name.
%    \begin{macrocode}
\def\macro@switch{\ifcat\noexpand\next a%
     \let\next\macro@name
%    \end{macrocode}
%    Otherwise, we have a `single-character' command name.  For all
%    those single-character names, we use |\short@macro| to
%    process them into suitable index entries.
%    \begin{macrocode}
     \else \let\next\short@macro  \fi
%    \end{macrocode}
%    Now that we know what macro to use to process the macro name, we
%    invoke it~\ldots
%    \begin{macrocode}
   \next}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\short@macro}
%
% \changes{v1.5c}{1989/04/27}{Corrected bad bug by putting the
%                         scan@allowedfalse macro before printing
%                         the argument.}
% \changes{v1.7a}{1992/03/10}{Ensure character stored in
%           \cs{macro@namepart} as `letter' so index exclusion works.}
%    This macro will be invoked (with a single character as parameter)
%    when a single-character macro name has been spotted whilst
%    scanning within the \env{macrocode} environment.
%
%    First we take a look at the |\index@excludelist| to see
%    whether this macro name should produce an index entry.  This is
%    done by the |\ifnot@excluded| macro which assumes that the
%    macro name is saved in |\macro@namepart|.  The character
%    mustn't be stored with a special category code or exclusion from
%    the index won't work, so we use \cs{string} to normalize it
%    the same way it is done in \cs{DoNotIndex}, i.e. everything ends up
%    catcode 12 except for the space character.
% \changes{v2.0e}{1998/12/28}{Correctly use the case-changing trick.}
% \changes{v3.0l}{2022/11/03}{No longer using the case-changing trick.}
%    \begin{macrocode}
\def\short@macro#1{%
   \edef\macro@namepart{\string#1}%
%    \end{macrocode}
%    Any indexing is then delegated to
%    |\maybe@index@short@macro|. Depending on the actual character seen,
%    this macro has to do different things, which is why we keep it separate from
%    |\maybe@index@macro| to avoid the special tests in the more
%    common case of a multi-letter macro name.
%    \begin{macrocode}
     \maybe@index@short@macro\macro@namepart
%    \end{macrocode}
%    Then we disable the cross-referencing mechanism with
%    |\scan@allowedfalse| and print the actual character. The
%    index entry was generated first to ensure that no page break
%    intervenes (recall that a |^^M| will start a new line).
%    \begin{macrocode}
    \scan@allowedfalse#1%
%    \end{macrocode}
%    After typesetting the character we can safely enable the
%    cross-referencing feature again. Note that this macro won't be
%    called (since |\macro@switch| won't be called) if
%    cross-referencing is globally disabled.
%    \begin{macrocode}
    \scan@allowedtrue }
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\macro@name}
%    We now come to the macro which assembles command names which
%    consist of one or more `letters' (which might well include
%    |@| symbols, or anything else which has a |\catcode| of
%    11).
%
%    To do this we add the `letter' to the existing definition of
%    |\macro@namepart| (which you will recall was originally set
%    to |\@empty|).
%    \begin{macrocode}
\def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}%
%    \end{macrocode}
%    Then we grab hold of the {\em next\/} single character and let
%    |\more@macroname| determine whether it belongs to the letter
%    string forming the command name or is a `non-letter'.
%    \begin{macrocode}
     \futurelet\next\more@macroname}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
% \begin{macro}{\more@macroname}
%
%    This causes another call of |\macro@name| to add in the next
%    character, if it is indeed a `letter'.
%    \begin{macrocode}
\def\more@macroname{\ifcat\noexpand\next a%
     \let\next\macro@name
%    \end{macrocode}
%    Otherwise, it finishes off the index entry by invoking
%    |\macro@finish|.
%    \begin{macrocode}
     \else \let\next\macro@finish \fi
%    \end{macrocode}
%    Here's where we invoke whatever macro was |\let| equal to
%    |\next|.
%    \begin{macrocode}
     \next}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
% \begin{macro}{\macro@finish}
%    When we've assembled the full `letter'-string which forms the
%    command name, we set the characters forming the entire command
%    name, and generate an appropriate |\index| command (provided
%    the command name is not on the list of exclusions).  The
%    `|\|' is already typeset; therefore we only have to output
%    all `letters' saved in |\macro@namepart|.
%    \begin{macrocode}
\def\macro@finish{%
  \macro@namepart
%    \end{macrocode}
%    Then we call |\ifnot@excluded| to decide whether we have to
%    produce an index entry. The construction with |\@tempa| is
%    needed because we want the expansion of |\macro@namepart| in
%    the |\index| command.\footnote{The \texttt{\bslash index}
%    command will expand its argument in the \texttt{\bslash output}
%    routine.  At this time \texttt{\bslash macro@namepart} might have a
%    new value.}
%    \begin{macrocode}
%  \ifnot@excluded
%     \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
%     \@tempa  \fi
  \maybe@index@macro \macro@namepart
}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
% \subsection[The index exclude list]{The index exclude
%             list\footnotemark}
%            \footnotetext{Info: the incomplete commentary on
%            \texttt{\bslash DoNotIndex} and the macros it calls
%                          was written by Dave Love.}
%
%
%

% \def\MakePrivateLetters{%
%    \makeatletter
%    \catcode`\_11
%    \catcode`\:11}
%
%
% The following part of the code is a new implementation using the
% \LaTeX3 programming layer as the constructs and types
% provided therein are making programming much easier. Over time I
% will probably replace the rest of that \DOC code too.
%    \begin{macrocode}
\ExplSyntaxOn
%    \end{macrocode}
%
%
% \DescribeMacro\l__doc_donotindex_seq
%    Local sequence that holds names (as strings) of commands that
%    should not be indexed. Within a \DOC element environment that
%    element is placed into the sequence so that it isn't
%    unnecessarily index within that part of the code. As the sequence
%    is local it will revert this setting at the end of the
%    environment so that the command is indexed elsewhere (unless it
%    is generally disabled from indexing).
%
% \DescribeMacro\g__doc_idxtype_prop
%    Global property list that holds for all commands that are special
%    \DOC elements the type of the element. The key is the command
%    name without backslash and the  value is \DOC element type
%    identifier, e.g., |\texttt{Length}| for length registers if that
%    type has been set up. \DOC only indexes commands, that is things
%    starting with an escape character, i.e., a backslash (by
%    default). \DOC elements that do not start with an escape
%    character, e.g., environments are not identified when parsing
%    code so that aren't indexed automatically inside. Thus for them
%    there is no point in keeping them in that property list.
%
% \DescribeMacro{\doc_dont_index:n}
% \DescribeInterfaceMacro{\DoNotIndex}
%    Takes a clist of commands (with backslash) as input and exclude
%    all of them from the index. User facing we make this available as
%    |\DoNotIndex|.
%
%
% \DescribeInterfaceMacro\ShowIndexingState
%    Displays the current list of the exclude index list in a fairly
%    low-level form.
%
% \DescribeInterfaceMacro\RecordIndexType
%    This command takes two arguments: a command (with escape char)
%    and its type (i.e., first mandatory
%    argument of a |\NewDocElement| declaration). If |#1| should not be
%    included from the index, then the data is used to record that
%    this command is of this type. The information is then used to
%    generate appropriate index entries. Obviously, index entries
%    generated earlier will be listing the wrong type. Therefore this
%    information is also placed into the \texttt{.aux} file so that it
%    will be available  at the beginning of further runs.
%
%    This command is internally executed as part of any \DOC element
%    environment so  it only needs to be explicitly given if for some
%    reason a command with a special type has no corresponding environment.
%
%
%
%
%  \begin{macro}{\l__doc_donotindex_seq}
%  \begin{macro}{\g__doc_idxtype_prop}
%    Declarations.
%    \begin{macrocode}
\seq_new:N  \l__doc_donotindex_seq
\prop_new:N \g__doc_idxtype_prop
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
% ^^A --------------------------------------------------
%
%
%  \begin{macro}{\__doc_trace:x}
%    A helper for tracing\ldots
%    \begin{macrocode}
\cs_new:Npn\__doc_trace:x {
  \legacy_if:nTF{ doc@debugshow }{ \iow_term:x } { \use_none:n }
}
%    \end{macrocode}
%  \end{macro}
%
%
% ^^A --------------------------------------------------
%
%  \begin{macro}{\doc_dont_index:n}
%  \begin{macro}{\__doc_dont_index:n}
%  \begin{macro}{\__doc_dont_index_aux:n}
%
%    Parses the argument a clist of commands with
%    |\MakePrivateLetters| in force (so that special characters are
%    recognized as being part of command names) and puts each command
%    without is backslash as a string into the sequence
%    |\l__doc_donotindex_seq|.
%    \begin{macrocode}
\cs_new:Npn \doc_dont_index:n {
  \group_begin:
    \MakePrivateLetters
    \__doc_dont_index:n
}
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new:Npn \__doc_dont_index:n #1 {
  \group_end:
%    \end{macrocode}
%
%    \begin{macrocode}
  \__doc_trace:x{Disable~ indexing~ for~ '\tl_to_str:n{#1}' }
%    \end{macrocode}
%    Adding the commands to the |\l__doc_donotindex_seq| sequence is
%    done by mapping the function |\__doc_dont_index_aux:n|  on each
%    element in the clist.
%    \begin{macrocode}
  \clist_map_function:nN {#1} \__doc_dont_index_aux:n
}
%    \end{macrocode}
%    We record each command by using its name as a string.
%    This means more tokens in the sequence but it allows
%    to compare names not ``action'' which is important as different
%    commands may have the same meaning (e.g., they may not be defined
%    at all),
%    \begin{macrocode}
\cs_new:Npn \__doc_dont_index_aux:n #1 {
  \seq_put_right:Nx \l__doc_donotindex_seq {\expandafter\@gobble \string#1}
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\DoNotIndex}
%    The document-level interface
%    \begin{macrocode}
\cs_set_eq:NN \DoNotIndex \doc_dont_index:n
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\ShowIndexingState}
%    Some tracing information that may be helpful.
%    \begin{macrocode}
\def \ShowIndexingState {
  \__doc_trace:x{Show~ doc~ indexing~ state:}
  \seq_show:N  \l__doc_donotindex_seq
  \prop_show:N \g__doc_idxtype_prop
}
%    \end{macrocode}
%  \end{macro}



% ^^A --------------------------------------------------
%
%
%  \begin{macro}{\__doc_idxtype_put:Nn}
%  \begin{imacro}{\RecordIndexType}
%  \fmi{Change name of interface command!}
%  \begin{macro}{\RecordIndexTypeAux}
%    This is the internal form for |\RecordIndexType|. The first
%    argument is turned into a string and the rest of the processing
%    is then done by |\__doc_idxtype_put:nn|
%    \begin{macrocode}
\cs_new:Npn \__doc_idxtype_put:Nn #1#2 {
  \exp_args:Nx \__doc_idxtype_put:nn { \cs_to_str:N #1 }{#2}
%    \end{macrocode}
%    We also make an entry in the \texttt{.aux} file so that this
%    declaration becomes immediately available in the next
%    run. However, for this we aren't reusing |\__doc_idxtype_put:N|
%    (a.k.a.\ |\RecordIndexType|) since that would result in doubling
%    such lines each time the document is run. Instead we use
%    |\RecordIndexTypeAux| which is only updating the data structures
%    without writing to the \texttt{.aux} file.
%    \begin{macrocode}
  \protected@write\@auxout{}
     {\string\RecordIndexTypeAux {\string#1 }{#2} }
}
%    \end{macrocode}
%    When we execute this code from the \texttt{.aux} we better not
%    generate a new line in the \texttt{.aux}. Otherwise those would
%    cumulate over time.
%    \begin{macrocode}
\cs_new:Npn \RecordIndexTypeAux #1#2 {
  \exp_args:Nx \__doc_idxtype_put:nn { \cs_to_str:N #1 }{#2}
}
%    \end{macrocode}
%    Similarly, when the \texttt{.aux} is read at the end of the run we
%    should disable that command to avoid unnecessary processing.
%    \begin{macrocode}
\AtEndDocument{
  \cs_set_eq:NN \RecordIndexTypeAux \use_none:nn
}
%    \end{macrocode}
%    Finally, we provide the user-level interface
%    \begin{macrocode}
\cs_set_eq:NN \RecordIndexType \__doc_idxtype_put:Nn
%    \end{macrocode}
%  \end{macro}
%  \end{imacro}
%  \end{macro}
%
%
%  \begin{macro}{\__doc_idxtype_put_scan:nn}
%    When we want to record an index type for a scanned name we can't
%    turn that into a csname and then call |\__doc_idxtype_put:Nn|
%    because turning it into a csname may change the meaning of the
%    name from ``undefined'' to |\relax|. Got bitten by that when
%    processing the kernel sources containing |\@undefined| within the
%    code: suddenly that wasn't undefined any longer.
%    So here is another version that works only on characters as
%    input. As we don't know whether or not they are proper strings
%    already we first make sure that this is the case.
%    \begin{macrocode}
\cs_new:Npn \__doc_idxtype_put_scan:nn #1#2 {
  \exp_args:Nf \__doc_idxtype_put:nn { \tl_to_str:n {#1} }{#2}
%    \end{macrocode}
%    In this case we also have to append a backslash when writing to
%    the \texttt{.aux} file.
%    \begin{macrocode}
  \protected@write\@auxout{}
     {\string\RecordIndexTypeAux {\bslash #1 }{#2} }
}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\__doc_idxtype_put_scan:on}
%    And here is the one we really need since the characters are
%    stored in some macro.
%    \begin{macrocode}
\cs_generate_variant:Nn \__doc_idxtype_put_scan:nn {o}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\record@index@type@save}
%    And here is the interface to the rest of the code:
%    \begin{macrocode}
\cs_set_eq:NN \record@index@type@save \__doc_idxtype_put_scan:on
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\__doc_idxtype_put:nn}
%    This internal command takes two arguments: a command name as
%    string (no backslash) and its type (i.e., first mandatory
%    argument of a |\NewDocElement| declaration). If |#1| is not in
%    |\l__doc_donotindex_seq| it will add this data to the property
%    list |\g__doc_idxtype_prop| using |#1| as key and |#2| as its
%    value. If the key already exist its value will be overwritten. If
%    the command is later marked for exclusion from the index the
%    property list setting remains unchanged but as long as no index
%    is produced for the command it will not be consulted.
%
%   Note: the command assumes that |#1| is already in string form
%    \begin{macrocode}
\cs_new:Npn \__doc_idxtype_put:nn #1#2 {
%    \end{macrocode}
%    No mystery here: if the command is not marked for exclusion from
%    the index add the property. The extra |\tl_to_str:n| is a safety
%    measure in case the input wasn't already in that form (should
%    only be the case with broken input but \ldots)
%    \begin{macrocode}
  \exp_args:NNf
  \seq_if_in:NnTF \l__doc_donotindex_seq {\tl_to_str:n{#1}}
%    \end{macrocode}
%    Some tracing info \ldots{}
%    \begin{macrocode}
     {
       \__doc_trace:x{Not~ recording~ index~ type~ for~ '\bslash #1' }
     }
     {
       \__doc_trace:x{Recording~ index~ type~ for~ '\bslash #1' ~ as~ #2 }
%    \end{macrocode}
%    Stick the data into the property list:
%    \begin{macrocode}
       \prop_gput:Nnn \g__doc_idxtype_prop {#1}{#2}
     }
}
%    \end{macrocode}
%  \end{macro}
%
% ^^A --------------------------------------------------
%
%
%  \begin{macro}{\exp_args:co}
%    A helper: construct a function and call it with its first argument
%    expanded once:
%    \begin{macrocode}
\cs_new:Npn \exp_args:co #1#2
   { \cs:w #1 \exp_after:wN \cs_end:\exp_after:wN {#2} }
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\tl_to_str:o}
%    Another helper: take some token list variable, expand it and turn
%    it into a string.
%    \begin{macrocode}
\cs_generate_variant:Nn \tl_to_str:n {o}
%    \end{macrocode}
%  \end{macro}
%
%
%
% ^^A --------------------------------------------------
%
%
%
% \DescribeMacro\maybe@index@macro
%
%    This takes a macro name (without backslash) as parsed within a
%    \env{macrocode} environment and checks if it should get indexed
%    (i.e., is not on the exclude list) and if so how (i.e., gets it
%    index type property and makes the right choice depending on that.
%


%  \begin{macro}{\maybe@index@macro}
%  \begin{macro}{\__doc_maybe_index:o}
%    We first make sure that the argument is really a string (so that
%    we have a defined situation) and then
%    pass it on to |\__doc_maybe_index_aux:nN| to do the work.
%    The second argument defines the indexing operation
%    \cs{SpecialIndex} for multi-letter macros and below
%    \cs{SpecialShortIndex} for single character macros.
%    \begin{macrocode}
\cs_new:Npn \__doc_maybe_index:o #1 {
  \exp_args:Nf \__doc_maybe_index_aux:nN { \tl_to_str:o {#1} }
                                         \SpecialIndex
}
%    \end{macrocode}
%    And here is what we call it in the older non-expl3 code:
%    \begin{macrocode}
\cs_set_eq:NN \maybe@index@macro \__doc_maybe_index:o
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
%  \begin{macro}{\maybe@index@short@macro}
%  \begin{macro}{\__doc_maybe_index_short:o}
%    Single character macros are handled similarly but there the
%    indexing is done by \cs{SpecialShortIndex} and it is simpler
%    because we know that the argument contains a string token not letters.
% \changes{v3.0l}{2022/11/03}{We know the argument expands to a single string token}
%    \begin{macrocode}
\cs_new:Npn \__doc_maybe_index_short:o #1 {
  \exp_args:No \__doc_maybe_index_aux:nN #1
                                         \SpecialShortIndex
}
\cs_set_eq:NN \maybe@index@short@macro \__doc_maybe_index_short:o
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
%
%  \begin{macro}{\__doc_maybe_index_aux:nN}
%    Take a string (representing a macro without backslash) and make
%    the right choices with respect to indexing.
%    \begin{macrocode}
\cs_new:Npn \__doc_maybe_index_aux:nN #1#2 {
%    \end{macrocode}
%    A bit of tracing:
%    \begin{macrocode}
  \__doc_trace:x{Searching~ for~ '\bslash #1'}
%    \end{macrocode}
%    If the name is on the exclude list do nothing.
%    \begin{macrocode}
  \seq_if_in:NnTF \l__doc_donotindex_seq {#1}
%    \end{macrocode}
%
%    \begin{macrocode}
    {
     \__doc_trace:x{Not~ indexing~ '\bslash #1' }
    }
%    \end{macrocode}
%    Otherwise check if this name has an index type property attached
%    to it.
%    \begin{macrocode}
    {
     \prop_get:NnNTF \g__doc_idxtype_prop {#1} \l__doc_idxtype_tl
%    \end{macrocode}
%    If so construct and execute
%    |\Code|\meta{idxtype}|Index|\footnote{I guess this should really
%    be an internal name not a user-level one.} which is done inside
%    |\__doc_maybe_index_aux|
%    \begin{macrocode}
       {
        \exp_args:Ncno \__doc_maybe_index_aux:Nnn
              { Code \tl_use:N \l__doc_idxtype_tl Index }
              {code} {\bslash #1}
        }
%    \end{macrocode}
%    Otherwise execute |\SpecialIndex| which is a short form for
%    |\CodeMacroIndex{code}| or execute \cs{SpecialShortIndex} which
%    deals with some special cases for single letter macros.
%    \begin{macrocode}
        {
          \__doc_trace:x{Indexing~ '\bslash #1'\space (\string #2)}
          \exp_args:No #2 {\bslash #1}
        }
    }
}
%    \end{macrocode}
%  \end{macro}
%
%
%
%  \begin{macro}{\SpecialShortIndex}
%    \fmi{to be documented; also needs cleaning up as it is a mix of
%    old and new right now}
%    \begin{macrocode}
\cs_new:Npn \SpecialShortIndex #1 {
    \@SpecialIndexHelper@ #1\@nil
  \@bsphack
  \ifdoc@noindex \else
    \str_case_e:nnF {\@gtempa }
        {
          {\cs_to_str:N \^^M } {\def\reserved@a{ \string \space \actualchar }
                                \def\reserved@b { \space }
                                \let\reserved@c \@empty                          }
%    \end{macrocode}
%    With the fix for
%    \verb*=\ = we now have to look for a real space to handle that command sequence.
% \changes{v3.0l}{2022/11/03}{look for the right token}
%    \begin{macrocode}
          { ~ }                {\def\reserved@a{ \string \space \actualchar }
                                \def\reserved@b { \space }
                                \let\reserved@c \@empty                          }
          {\c_left_brace_str} { \def\reserved@a{ \bgroup \actualchar }
                                \def\reserved@b { \c_left_brace_str }
                                \def\reserved@c { \noexpand\iffalse
                                                  \c_right_brace_str
                                                  \noexpand\fi }                 }
          {\c_right_brace_str} { \def\reserved@a{ \egroup \actualchar
                                                  \noexpand\iffalse
                                                    \c_left_brace_str
                                                  \noexpand\fi }
                                 \def\reserved@b { \c_right_brace_str }
                                 \let\reserved@c \@empty                         }
%    \end{macrocode}
%    The case of \cs{verbatimchar} is tricky. We can't stick it into
%    the normal \cs{verb} because we would then get something like
%    \verb=\verb+\++= which would comes out as ``\verb+\++'' instead
%    of \verb=\+=. So we use the \cs{verb} to only generate the
%    backslash and then use \cs{texttt} on the \cs{verbatimchar}
%    itself. However, that is not enough if we are unlucky and
%    somebody (like Will :-)) has used something like \verb=&= with a
%    special catcode for the \cs{verbatimchar}. We therefore also
%    apply \cs{string} to it when we read it back.
%    \begin{macrocode}
          {\verbatimchar}  { \def\reserved@a{ \quotechar\verbatimchar
                                              \actualchar }
                             \let\reserved@b \@empty
                             \def\reserved@c
                                 { \string\texttt{\string\string\verbatimchar} } }
        }
        { \def\reserved@a {\quotechar \@gtempa \actualchar }
          \def\reserved@b {\quotechar \@gtempa  }
          \let\reserved@c \@empty                             }
    \special@index {
    \reserved@a
    \string\verb
    \quotechar *\verbatimchar \quotechar \bslash
    \reserved@b
    \verbatimchar
    \reserved@c
    \encapchar code}
  \fi
  \@esphack
}
%    \end{macrocode}
%  \end{macro}





%  \begin{macro}{\__doc_maybe_index_aux:Nnn}
%    Execute the function passed on as first argument taking argument
%    2 and 3 as input.
%    \begin{macrocode}
\cs_new:Npn \__doc_maybe_index_aux:Nnn #1#2#3 {
%    \end{macrocode}
%    We have to be a little careful: as that function name is
%    constructed it may not actually exist (as constructions generate
%    |\relax| in \TeX{} in that case). In that case we raise an error,
%    otherwise we execute (with a little bit of tracing info):
%    \begin{macrocode}
    \cs_if_exist:NTF #1
      {
        \__doc_trace:x{Indexing~ '#3'\space as~
                       \tl_use:N \l__doc_idxtype_tl }
        #1{#2}{#3}
      }
      {
        \PackageError{doc}{Doc~ element~
           '\tl_use:N \l__doc_idxtype_tl'~ unknown}%

          {When~ using~ '\string\RecordIndexType'~ the~ type~ must~
           be~ known~\MessageBreak
           to~ the~ system,~ i.e.,~ declared~ via~
           '\string\NewDocElement'\MessageBreak
           before~ it~ can~ be~ used~ in~ indexing.}
     }
}
%    \end{macrocode}
%  \end{macro}
%
%
%    Back to old style coding \ldots
%    \begin{macrocode}
\ExplSyntaxOff
%    \end{macrocode}
%
%
%
% \subsection{Macros for generating index entries}
%
% Here we provide default definitions for the macros invoked to create
% index entries; these are either invoked explicitly, or automatically
% by |\scan@macro|.  As already mentioned, the definitions given
% here presuppose that the |.idx| file will be processed by
% Chen's \prg{makeindex} program --- they may be redefined for use
% with the user's favorite such program.
%
% To assist the reader in locating items in the index, all such
% entries are sorted alphabetically {\em ignoring\/} the initial
% `|\|'; this is achieved by issuing an |\index| command which
% contains the `actual' operator for \prg{makeindex}.  The default
% value for the latter operator is `|@|', but the latter character is
% so popular in \LaTeX\ package files that it is necessary to substitute
% another character.  This is indicated to \prg{makeindex} by means
% of an `index style file'; the character selected for this function
% is |=|, and therefore this character too must be specially treated
% when it is met in a \TeX\ command.  A suitable index style file is
% provided amongst the supporting files for this style file in
% \texttt{gind.ist} and is generated from this source by processing
% with \texttt{docstrip} to extract the module \textbf{gind}.  A
% similar style file \texttt{gglo.ist} is supplied for sorting the
% change information in the glossary file and is extracted as module
% \textbf{gglo}.  First of all we add some information to the front of
% the \texttt{.ist} files.  \changes{v1.7a}{1992/03/11}{glo.ist and
% gind.ist now derivable from doc.dtx with docstrip.}
%    \begin{macrocode}
%</package>
%<+gind|gglo>%% This is a MAKEINDEX style file which should be used to
%<+gind>%% generate the formatted index for use with the doc
%<+gglo>%% generate the formatted change history for use with the doc
%<+gind|gglo>%% package. The TeX commands used below are defined in
%<+gind|gglo>%% doc.sty.  The commands for MAKEINDEX like `level'
%<+gind|gglo>%% `item_x1' are described in `` Makeindex, A General
%<+gind|gglo>%% Purpose, Formatter-Independent Index Processor'' by
%<+gind|gglo>%% Pehong Chen.
%<+gind|gglo>
%    \end{macrocode}
%
% \begin{imacro}{\actualchar}
% \begin{imacro}{\quotechar}
% \begin{imacro}{\levelchar}
%    First come the definitions of |\actualchar|,
%    |\quotechar| and |\levelchar|. Note, that our defaults
%    are not the ones used by the \prg{makeindex} program without a
%    style file.
%    \begin{macrocode}
%<*package>
\@ifundefined{actualchar}{\def\actualchar{=}}{}
\@ifundefined{quotechar}{\def\quotechar{!}}{}
\@ifundefined{levelchar}{\def\levelchar{>}}{}
%</package>
%<+gind|gglo>actual '='
%<+gind|gglo>quote '!'
%<+gind|gglo>level '>'
%<*package>
%    \end{macrocode}
% \end{imacro}
% \end{imacro}
% \end{imacro}
%
%
% \begin{imacro}{\encapchar}
%    The \prg{makeindex} default for the |\encapchar| isn't
%    changed.
%    \begin{macrocode}
\@ifundefined{encapchar}{\def\encapchar{|}}{}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{imacro}{\verbatimchar}
%    We also need a special character to be used as a delimiter for
%    the |\verb*| command used in the definitions below.
%    \begin{macrocode}
\@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
%    \end{macrocode}
% \end{imacro}
%
%
%
% \begin{macro}{\@SpecialIndexHelper@}
%    \fmi{doc or drop}
%    \begin{macrocode}
\begingroup
 \catcode`\|=0
 \catcode`\\=12
%    \end{macrocode}
%    \SpecialEscapechar\|
%    \begin{macrocode}
 |gdef|@SpecialIndexHelper@#1#2|@nil{%
   |if |noexpand#1\%
     |gdef|@gtempa{#2}%
   |else
     |begingroup
       |escapechar|m@ne
       |expandafter|gdef|expandafter|@gtempa|expandafter{|string#1#2}%
     |endgroup
   |fi}
|endgroup
%    \end{macrocode}
%
% \end{macro}
%
%
%
% \begin{imacro}{\SortIndex}
%    This macro is used to generate the index entries for any
%    single-character command that |\scan@macro| encounters.  The
%    first parameter specifies the lexical order for the character,
%    whilst the second gives the actual characters to be printed in
%    the entry. It can also be used directly to generate index entries
%    which differ in sort key and actual entry.
%    \begin{macrocode}
\def\SortIndex#1#2{%
  \ifdoc@noindex\else
    \index{#1\actualchar#2}%
  \fi
}
%    \end{macrocode}
% \end{imacro}
%
%
%
%
% \begin{imacro}{\LeftBraceIndex}
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
% \begin{imacro}{\RightBraceIndex}
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} These
%    two macros fix the problems with \prg{makeindex}.  Note the
%    `hack' with  \iffalse{-to get matching braces\fi |\iffalse}\fi|
%    to satisfy both \TeX{} and the
%    \prg{makeindex} program. When this is written to the
%    \texttt{.idx} file \TeX{} will see both braces (so we get a
%    balanced text).  \prg{makeindex} will also see balanced braces
%    but when the actual index entry is again processed by \TeX{} the
%    brace in between |\iffalse| |\fi| will vanish.
%    \begin{macrocode}
\@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{%
   \special@index{\bgroup\actualchar
                  \string\verb% % to fool emacs highlighting
                  \quotechar*\verbatimchar
                  \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{}

\@ifundefined{RightBraceIndex}{\def\RightBraceIndex{%
 \special@index{\egroup\actualchar\string\iffalse{\string\fi
           \string\verb% % to fool emacs highlighting
           \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{}
%    \end{macrocode}
% \end{imacro}
% \end{imacro}
%
%
% \begin{imacro}{\PercentIndex}
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
% \changes{v1.7c}{1992/03/25}{Default now for bug-fixed makeindex}
% By default we assume a version of \prg{makeindex} without the
% percent bug is being used.
%    \begin{macrocode}
\@ifundefined{PercentIndex}
  {\def\PercentIndex{\it@is@a\percentchar}}{}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{omacro}{\OldMakeindex}
% \changes{v1.7c}{1992/03/26}{Replaced \cs{NewMakeIndex}.}
% \begin{imacro}{\percentchar}
%    Here is one solution for the percent bug in \prg{makeindex}.
%    The macro |\percentchar| denotes a |%|$_{12}$.  Calling this from
%    a package or the driver file sets things up
%    appropriately.\label{bug:fixes}
%    \begin{macrocode}
\def\OldMakeindex{\def\PercentIndex{%
    \special@index{\quotechar\percentchar\actualchar
           \string\verb% % to fool emacs highlighting
           \quotechar*\verbatimchar\quotechar\bslash
           \percentchar\percentchar\verbatimchar}}}
{\catcode`\%=12 \gdef\percentchar{%}}
%    \end{macrocode}
% \end{imacro}
% \end{omacro}
%
%
% \begin{macro}{\it@is@a}
%    This macro is supposed to produce a correct |\SortIndex|
%    entry for a given character. Since this character might be
%    recognized as a `command' character by the index program used,
%    all characters are quoted with the |\quotechar|.
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
%    \begin{macrocode}
\def\it@is@a#1{\special@index{\quotechar #1\actualchar
                          \string\verb% % to fool emacs highlighting
                          \quotechar*\verbatimchar
                          \quotechar\bslash\quotechar#1\verbatimchar}}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
%
% \subsection{Redefining the \env{index} environment}
%
%\changes{v1.4r}{1989/04/22}{twocols env. placed into separate file}
%\changes{v1.4?}{1989/04/19}{use DEK's algorithm and implement
%                         a twocols env.}
%\changes{v1.4?}{1989/04/16}{changes to the index env.}
%\changes{v1.5a}{1989/04/26}{Now input multicol.sty instead of
%                         multcols.sty}

%
% \begin{ldimen}{\IndexMin}
% \begin{lcounter}{IndexColumns}
%    \changes{v1.4t}{1989/04/24}{Counter added.}
%    If \texttt{multicol} is in use,
%    when the index is started we compute the remaining space on the
%    current page; if it is greater than |\IndexMin|, the first
%    part of the index will then be placed in the available space.
%    The number of columns set is controlled by the counter
%    |\c@IndexColumns| which can be changed with a
%    |\setcounter| declaration.
%    \begin{macrocode}
\newdimen\IndexMin         \IndexMin       = 80pt
\newcount\c@IndexColumns   \c@IndexColumns = 3
%    \end{macrocode}
% \end{lcounter}
% \end{ldimen}
%
%
%
% \begin{environment}{theindex}
%    Now we start the multi-column mechanism, if appropriate. We use the
%    \LaTeX{} counter |\c@IndexColumns|  declared above to denote
%    the number of columns and insert the `index prologue' text (which
%    might contain a |\section| call, etc.). See the default
%    definition for an example.
%    \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.}
%    \changes{v1.5a}{1989/04/26}{Call multicols first}
%    \changes{v1.6e}{1991/04/03}{Turned into env definition.}
%    \changes{v1.7a}{1992/03/04}{Include test for multicols.}
%    \begin{macrocode}
\ifdoc@multicol
%    \end{macrocode}
%
%    \begin{macrocode}
  \RequirePackage{multicol}
%    \end{macrocode}
%
%    \begin{macrocode}
  \renewenvironment{theindex}
    {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]%
%    \end{macrocode}
%    Then we make a few last minute assignments to read the individual
%    index |\item|$\,$s and finish off by ignoring any initial
%    space.
%    \begin{macrocode}
      \IndexParms \let\item\@idxitem \ignorespaces}%
%    \end{macrocode}
%
% \begin{macro}{\endtheindex}
%    \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.}
%    At the end of the index, we have only to end the \env{multicols}
%    environment.
%    \begin{macrocode}
    {\end{multicols}}
%    \end{macrocode}
%    If we can't use \env{multicols} we warn the user and use an
%    environment that's basically the one from \texttt{article.sty}.
%    \begin{macrocode}
\else
  \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}
% \end{environment}
%
% Here are the necessary \prg{makeindex} declarations. We disable
% scanning of macro names inside the index with |\scan@allowedfalse\n|
% to avoid recursion.
%    \begin{macrocode}
%</package>
%<+gind>preamble
%<+gind>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
%<+gind>postamble
%<+gind>"\n\n \\end{theindex}\n"
%<*package>
%    \end{macrocode}
%
%
% \begin{imacro}{\IndexPrologue}
% \begin{macro}{\index@prologue}
% \changes{v1.9w}{1995/12/27}{Text changed}
% \changes{v1.9x}{1996/01/11}{Text depends on code lines used}
%    The |\IndexPrologue| macro is used to place a short message
%    into the document above the index.  It is implemented by
%    redefining |\index@prologue|, a macro which holds the
%    default text.  We'd better make it a |\long| macro to allow
%    |\par| commands in its argument.
%    \begin{macrocode}
\long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack}
%    \end{macrocode}
%    Now we test whether the default is already defined by another
%    package file. If not we define it.
% \changes{v2.0j}{2000/05/22}{Less obscure wording? (CAR pr/3202)}
%    \begin{macrocode}
\@ifundefined{index@prologue}
     {\def\index@prologue{\section*{Index}%
                 \markboth{Index}{Index}%
                 Numbers written in italic refer to the page
                 where the corresponding entry is described;
                 numbers underlined refer to the
                 \ifcodeline@index
                   code line of the
                 \fi
                 definition; numbers in roman refer to the
                 \ifcodeline@index
                   code lines
                 \else
                   pages
                 \fi
                 where the entry is used.
                 }}{}
%    \end{macrocode}
% \end{macro}
% \end{imacro}
%
%
%
% \begin{imacro}{\IndexParms}
%    These are some last-minute assignments for formatting the index
%    entries. They are defined in a separate macro so that a user can
%    substitute different definitions.  We start by defining the
%    various parameters controlling leading and the separation between
%    the two columns.  The entire index is set in |\small| size.
%    \begin{macrocode}
\@ifundefined{IndexParms}
    {\def\IndexParms{%
       \parindent \z@
       \columnsep 15pt
       \parskip 0pt plus 1pt
       \rightskip 15pt
       \mathsurround \z@
       \parfillskip=-15pt
        \small
%    \end{macrocode}
% \begin{macro}{\@idxitem}
% \begin{macro}{\subitem}
% \begin{macro}{\subsubitem}
%    Index items are formatted with hanging indentation for any items
%    which may require more than one line.
%    \begin{macrocode}
       \def\@idxitem{\par\hangindent 30pt}%
%    \end{macrocode}
%    Any sub-item in the index is formatted with a 15pt indentation
%    under its main heading.
%    \begin{macrocode}
       \def\subitem{\@idxitem\hspace*{15pt}}%
%    \end{macrocode}
%    Whilst sub-sub-items go in a further 10pt.
%    \begin{macrocode}
       \def\subsubitem{\@idxitem\hspace*{25pt}}%
%    \end{macrocode}
% \begin{macro}{\indexspace}
%    The \prg{makeindex} program generates an |\indexspace|
%    before each new alphabetic section commences. After this final
%    definition we end the |\@ifundefined| and the definition of
%    |\IndexParms|.
%    \begin{macrocode}
       \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}%
      }}{}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{imacro}
%
%
% \begin{imacro}{\efill}
%    This definition of |\efill| is intended to be used after index
%    items which have no following text (for example, ``\textit{
%    see\/}'' entries).  It just ensures that the current line is
%    filled, preventing ``|Underfull \hbox|'' messages.
%    \begin{macrocode}
\def\efill{\hfill\nopagebreak}%
%</package>
%<+gind|gglo>item_x1   "\\efill \n \\subitem "
%<+gglo>item_x2   "\\ "
%<+gind>item_x2   "\\efill \n \\subsubitem "
%<*package>
%    \end{macrocode}
% \end{imacro}
%
%
%
% \begin{imacro}{\pfill}
%     The following definitions provide the |\pfill| command; if
%    this is specified in the index style file to \prg{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\pfill{\unskip~%
           \leaders\hbox to.6em{\hss .\hss}\hfill
           \penalty500\strut\nobreak
           \leaders\hbox to.6em{\hss .\hss}\hfil
           ~\ignorespaces}%
%</package>
%<+gind|gglo>delim_0   "\\pfill "
%<+gind|gglo>delim_1   "\\pfill "
%<+gind|gglo>delim_2   "\\pfill "
%<*package>
%    \end{macrocode}
% \end{imacro}
%
%
%
% \begin{imacro}{\*}
%    Here is the definition for the |\*| macro. It isn't used in
%    this set of macros.
%    \begin{macrocode}
\def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{imacro}{\main}
%    The \textit{defining\/} entry for a macro name is flagged with
%    the string \texttt{\encapchar main}\footnote{With the current
%    definition of \texttt{\bslash encapchar} substituted for
%    \texttt{\encapchar}} in the |\index| command; \prg{makeindex}
%    processes this so that the |\main| macro will be invoked to
%    underline the page number(s) on which the {\em definition\/} of
%    the macro will be found.
%    \begin{macrocode}
\@ifundefined{main}{\def\main#1{\underline{#1}}}{}
%    \end{macrocode}
% \end{imacro}
%
% \begin{imacro}{\usage}
%    The |\usage| macro is used to indicate entries describing
%    the usage of a macro. The corresponding page number(s) will be
%    set in \textit{italics}.
%    \begin{macrocode}
\@ifundefined{usage}{\def\usage#1{\textit{#1}}}{}
%    \end{macrocode}
% \end{imacro}
%
% \begin{imacro}{\code}
%    The |\code| macro is used to indicate index entries to code lines
%    that aren't main entries.
%    By default we do nothing special with them
%    the usage of a macro.
%    \begin{macrocode}
\@ifundefined{code}{\def\code#1{#1}}{}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{imacro}{\PrintIndex}
% \changes{v1.5k}{1989/09/04}{\cs{printindex} changed to
%                             \cs{PrintIndex}}
% \changes{v1.7a}{1992/02/26}{Documentation moved to interface section.}
% \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.}
% \changes{v1.9w}{1995/12/29}{Turn the cmd into a noop after use.}
%    This is the same as |\printindex| in the \pkg{makeidx} package.
%    \begin{macrocode}
\def\PrintIndex{\@input@{\jobname.ind}%
                \global\let\PrintIndex\@empty}
%    \end{macrocode}
% \end{imacro}
%
%
% We want headings in the index (and changes list) according to the
% initial character of the next block of entries and have to instruct
% \prg{makeindex} appropriately.  Unfortunately the specification
% for this changed sometime between versions 2.4 and 2.11 of
% \prg{makeindex}.  We provide both ways of doing it but
% unfortunately this will always produce a warning message from
% \prg{makeindex}.  This is for older versions:
% \changes{v1.7h}{1992/07/01}{Turn off headings in gls file}
%    \begin{macrocode}
%</package>
%<+gind,gglo>% The next lines will produce some warnings when
%<+gind,gglo>% running Makeindex as they try to cover two different
%<+gind,gglo>% versions of the program:
%<+gind,gglo>lethead_prefix   "{\\bfseries\\hfil "
%<+gind,gglo>lethead_suffix   "\\hfil}\\nopagebreak\n"
%<+gind>lethead_flag       1
%<+gglo>lethead_flag       0
%    \end{macrocode}
% This works for newer ones:
%    \begin{macrocode}
%<+gind,gglo>heading_prefix   "{\\bfseries\\hfil "
%<+gind,gglo>heading_suffix   "\\hfil}\\nopagebreak\n"
%<+gind>headings_flag       1
%<+gglo>headings_flag       0
%<*package>
%    \end{macrocode}
%
%
%
% \subsection[Dealing with the change history]
%            {Dealing with the change history\footnotemark}
% \footnotetext{The whole section was proposed by Brian \textsc{Hamilton
%               Kelly}. He also documented and debugged the macros as
%               well as many other parts of this package.}
%
% To provide a change history log, the |\changes| command has
% been introduced.  This takes three arguments, respectively, the
% version number of the file, the date of the change, and some detail
% regarding what change has been made.  The second 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
% \prg{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{imacro}{\changes}
% \changes{BHK}{1989/04/26}{Documented \texttt{\protect\bslash changes}
%                         command.}
% \changes{BHK}{1989/04/26}{Changed definition of
%    \texttt{\protect\bslash protect}.} The output of the |\changes|
%    command goes into the \meta{Glossary\_File} and therefore uses
%    the normal |\glossaryentry| commands.\footnote{Note that a recent
%    change in \LaTeX{} 2.09 changed the command name in the
%    \texttt{.glo} file from \texttt{\bslash indexentry} to
%    \texttt{\bslash glossaryentry}.  It is therefore necessary to
%    have a special \prg{makeindex} style file called
%    \texttt{gglo.ist} to process this file correctly.} Thus
%    \prg{makeindex} or a similar program can be used to process
%    the output into a sorted ``glossary''.  The |\changes| command
%    commences by taking the usual measures to hide its spacing, and
%    then redefines |\protect| for use within the argument of the
%    generated |\indexentry| command.
%
%    We re-code nearly all chars found in |\sanitize| to letter
%    since the use of special package which make some characters
%    active might upset the |\changes| command when writing its
%    entries to the file. However we have to leave |%| as comment
%    and \verb*+ + as \meta{space} otherwise chaos will happen.
%    And, of course the |\| should be available as escape
%    character.
% \changes{v1.5v}{1990/01/28}{`Re-code a lot of chars.}
% \changes{v1.5m}{1989/09/20}{\cs{actualchar} in second level removed.}
% \changes{v1.5o}{1989/09/24}{New sorting.}
% \changes{v1.6c}{1990/06/29}{Again new sorting.}
% \changes{v1.9u}{1995/08/06}{Use \cs{protected@edef}}
%    \begin{macrocode}
\def\changes{\@bsphack\begingroup\@sanitize
   \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
   \changes@}
\def\changes@#1#2#3{%
  \protected@edef\@tempa{\noexpand\glossary{#1%
%    \end{macrocode}
%    If asked for we also show the date of in the change log (after
%    the version).
% \changes{v3.0g}{2022/06/01}{Show change dates if asked for (gh/531)}
%    \begin{macrocode}
                   \ifdoc@reportchangedates
                     \space -- #2\fi
                   \levelchar
%    \end{macrocode}
% \changes{v1.9u}{1995/08/06}{Use value of \cs{saved@macroname} to
%          find out about change entries at outer level}
%    If the macro |\saved@macroname| doesn't contain any macro name
%    (ie is empty) the current changes entry was done at top-level.
%    In this case we precede it by |\generalname|.
%    \begin{macrocode}
                   \ifx\saved@macroname\@empty
%    \end{macrocode}
%    Putting a |!| at the beginning of the entry hopefully moves this
%    entry to the very beginning during sorting.
%    \begin{macrocode}
                      \quotechar!%
                      \actualchar
                      \generalname
                   \else
%    \end{macrocode}
% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}}
%    \begin{macrocode}
                      \saved@indexname
                      \actualchar
                      \string\verb% % to fool emacs highlighting
                      \quotechar*%
                      \verbatimchar\saved@macroname
                      \verbatimchar
                   \fi
                   :\levelchar #3}}%
  \@tempa\endgroup\@esphack}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{macro}{\saved@macroname}
% \changes{BHK}{1989/04/26}{Provided for sorting outside \env{macro}
%    environment} The entries are sorted for convenience by the name
%    of the most recently introduced macroname (i.e., that in the most
%    recent |\begin{macro}| command).  We therefore provide
%    |\saved@macroname| to record that argument, and provide a default
%    definition in case |\changes| is used outside a \env{macro}
%    environment.  (This is a {\em wicked\/} hack to get such entries
%    at the beginning of the sorted list!  It works providing no macro
%    names start with |!| or |"|.)  \changes{v1.7a}{1992/03/02}{Changed
%    string used for better sorting.}
% \changes{v1.9u}{1995/08/06}{Now empty by default}
%    \begin{macrocode}
\def\saved@macroname{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\saved@indexname}
% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}}
%    The macroname being document without a backslash for the index
%    (or the environment name which doesn't have one in the first place).
%    \begin{macrocode}
\def\saved@indexname{}
%    \end{macrocode}
% \end{macro}
%
% \begin{imacro}{\generalname}
% \changes{v1.9u}{1995/08/06}{Macro added}
%    This macro holds the string placed before changes entries on
%    top-level.
%    \begin{macrocode}
\def\generalname{General}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{imacro}{\RecordChanges}
% \changes{BHK}{1989/04/26}{Renames former \texttt{\protect\bslash
%                         PrintChanges} command.}
%    To cause the changes to be written (to a \texttt{.glo}) file, we
%    define |\RecordChanges| to invoke \LaTeX's usual
%    |\makeglossary| command.
%    \begin{macrocode}
\let\RecordChanges\makeglossary
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{ldimen}{\GlossaryMin}
%    \changes{BHK}{1989/04/26}{Added to support
%                            \texttt{\protect\bslash changes}.}
% \begin{lcounter}{GlossaryColumns}
%    \changes{BHK}{1989/04/26}{Added to support \texttt{\protect\bslash
%    changes}.} The remaining macros are all analogues of those used
%    for the \env{theindex} environment.  When the glossary is
%    started we compute the space which remains at the bottom of the
%    current page; if this is greater than |\GlossaryMin| then the
%    first part of the glossary will be placed in the available space.
%    The number of columns set are controlled by the counter
%    |\c@GlossaryColumns| which can be changed with a |\setcounter|
%    declaration.
%    \begin{macrocode}
\newdimen\GlossaryMin         \GlossaryMin       = 80pt
\newcount\c@GlossaryColumns   \c@GlossaryColumns = 2
%    \end{macrocode}
% \end{lcounter}
% \end{ldimen}
%
%
% \begin{environment}{theglossary}
%  \changes{BHK}{1989/04/26}{Added to support
%                            \texttt{\protect\bslash changes}.}
% \changes{v1.5p}{1989/09/28}{Now call \cs{multicols} first.}
%    \changes{v1.6e}{1991/04/03}{Turned into env definition.}
%    \changes{v1.7a}{1992/03/10}{Changed to work without multicols if
%                              necessary.}
%    \changes{BHK}{1989/04/26}{Added to support
%                            \texttt{\protect\bslash changes}.}
%    The environment \env{theglossary} is defined in the same manner
%    as the \env{theindex} environment.
%    \begin{macrocode}
\ifdoc@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{environment}
%
% Here are the necessary \prg{makeindex} declarations with scanning
% disabled as for the index.
%    \begin{macrocode}
%</package>
%<+gglo>preamble
%<+gglo>"\n \\begin{theglossary} \n
%<+gglo>    \\makeatletter\\scan@allowedfalse\n"
%<+gglo>postamble
%<+gglo>"\n\n \\end{theglossary}\n"
%    \end{macrocode}
% This difference from \texttt{gind.ist} is necessary if you have an
% up-to-date \LaTeX.
%    \begin{macrocode}
%<+gglo>keyword "\\glossaryentry"
%<*package>
%    \end{macrocode}
%
%
% \begin{imacro}{\GlossaryPrologue}
%    \changes{BHK}{1989/04/26}{Added to support
%                            \texttt{\protect\bslash changes}.}
% \begin{macro}{\glossary@prologue}
%    \changes{BHK}{1989/04/26}{Added to support
%                            \texttt{\protect\bslash changes}.}
%    The |\GlossaryPrologue| macro is used to place a short
%    message above the glossary into the document.  It is implemented
%    by redefining |\glossary@prologue|, a macro which holds the
%    default text.  We better make it a long macro to allow
%    |\par| commands in its argument.
%    \begin{macrocode}
\long\def\GlossaryPrologue#1{\@bsphack
                             \def\glossary@prologue{#1}%
                             \@esphack}
%    \end{macrocode}
%    Now we test whether the default is already defined by another
%    package file. If not we define it.
%    \begin{macrocode}
\@ifundefined{glossary@prologue}
     {\def\glossary@prologue{\section*{{Change History}}%
                 \markboth{{Change History}}{{Change History}}%
                 }}{}
%    \end{macrocode}
% \end{macro}
% \end{imacro}
%
% \begin{imacro}{\GlossaryParms}
%    \changes{BHK}{1989/04/26}{Added to support
%                            \texttt{\protect\bslash changes}.}
% Unless the user specifies otherwise, we set the change history
% using the same parameters as for the index except that we make it sort
% of ragged right as it contains text that often doesn't break nicely in
% small columns.
% \changes{v2.1g}{2016/02/15}{Use ragged setting by default}
%    \begin{macrocode}
\@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms
  \expandafter\def\expandafter\GlossaryParms\expandafter{\GlossaryParms
     \rightskip 15pt plus 1fil
     \parfillskip -15pt plus -1fil\relax}
}{}
%    \end{macrocode}
% \end{imacro}
%
% \begin{imacro}{\PrintChanges}
%    \changes{BHK}{1989/04/26}{Added to support
%                            \texttt{\protect\bslash changes}.}
%    To read in and print the sorted change history, just put the
%    |\PrintChanges| command as the last (commented-out, and thus
%    executed during the documentation pass through the file) command
%    in your package file.  Alternatively, this command may form one of
%    the arguments of the |\MaybeStop| command, although a
%    change history is probably {\em not\/} required if only the
%    description is being printed.
%
%    The command assumes that \prg{makeindex} or some other program
%    has processed the \texttt{.glo} file to generate a sorted
%    \texttt{.gls} file.
% \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.}
% \changes{v1.9w}{1995/12/29}{Turn the cmd into a noop after use.}
%    \begin{macrocode}
\def\PrintChanges{\@input@{\jobname.gls}%
                  \global\let\PrintChanges\@empty}
%    \end{macrocode}
% \end{imacro}
%
%
%
%
%
% \subsection{Bells and whistles}
%
% \begin{imacro}{\MaybeStop}
% \changes{v1.5k}{1989/09/04}{Support for checksum.}
% \begin{imacro}{\Finale}
% \changes{v1.5k}{1989/09/04}{Support for checksum.}
% \changes{v1.5z}{1990/04/22}{Define \cs{Finale} globally.}
% \begin{imacro}{\AlsoImplementation}
% \changes{v1.9w}{1995/12/27}{Macro added}
% \begin{imacro}{\OnlyDescription}
%    If |\AlsoImplementation| is in force the whole documentation
%    including the code part will be typeset. This is the default.
%    \begin{macrocode}
\newcommand\AlsoImplementation{%
%    \end{macrocode}
%    To make this happen we have to define
%    |\MaybeStop| in a way that its argument is typeset at the
%    very end or more exactly at |\Finale|. For this we
%    save its argument in the macro |\Finale|.
%    \begin{macrocode}
   \long\def\MaybeStop##1{\@bsphack\gdef\Finale{##1%
%    \end{macrocode}
%    But |\Finale| will be called at the very end of a file. This
%    is exactly the point were we want to know if the file is
%    uncorrupted. Therefore we also call |\check@checksum| at this
%    point.
%    \begin{macrocode}
                  \check@checksum}%
%    \end{macrocode}
%    On the other hand: |\MaybeStop| is more or less a
%    dividing point between description and code. So we start to look
%    for the check-sum of the documented file by calling
%    |\init@checksum|.
%    \begin{macrocode}
              \init@checksum
              \@esphack}%
         }
%    \end{macrocode}
%
%    Since |\AlsoImplementation| should be the default we execute it
%    and thus |\MaybeStop| gets the desired meaning.
%    \begin{macrocode}
\AlsoImplementation
%    \end{macrocode}
%    When the user places an |\OnlyDescription| declaration in
%    the driver file the document should only be typeset up to
%    |\MaybeStop|. We therefore have to redefine this macro.
%    \begin{macrocode}
\def\OnlyDescription{\@bsphack\long\def\MaybeStop##1{%
%    \end{macrocode}
%    In this case the argument of |\MaybeStop| should be set
%    and afterwards \TeX{} should stop reading from this file.
%    Therefore we finish this macro with
%    \begin{macrocode}
           ##1\endinput}\@esphack}
%    \end{macrocode}
%    If no |\MaybeStop| command is given we silently ignore a
%    |\Finale| issued.
% \changes{v1.9n}{1994/04/28}{Ignore \cs{Finale} if no
%                  \cs{MaybeStop} is given}
%    \begin{macrocode}
\let\Finale\relax
%    \end{macrocode}
% \end{imacro}
% \end{imacro}
% \end{imacro}
% \end{imacro}
%
%
%  \begin{omacro}{\StopEventually}
%    The old wrong name for |\MaybeStop|. We need to use |\def|
%    (i.e., expansion) as |\MaybeStop| gets redefined once in a while.
%    \begin{macrocode}
\def\StopEventually{\MaybeStop}
%    \end{macrocode}
%  \end{omacro}
%
% \begin{imacro}{\meta}
% \changes{v1.4t}{1989/04/24}{Macro added.}
% \changes{v1.5w}{1990/02/03}{Breaks at space allowed.}
% \changes{v1.6a}{1990/05/24}{Extra space bug corrected.}
%    The |\meta| macro is a bit tricky. We want to allow line
%    breaks at blanks in the argument but we don't want a break
%    in between. In the past this was done by defining |\meta| in a way that a
%    \verb*+ + is active when the argument is scanned. Words are then
%    scanned into |\hbox|es. The active \verb*+ + will end the
%    preceding |\hbox| add an ordinary space and open a new
%    |\hbox|. In this way breaks are only possible at spaces.  The
%    disadvantage of this method was that |\meta| was neither robust
%    nor could it be |\protect|ed. The new implementation  fixes this
%    problem by defining |\meta| in a radically different way: we
%    prevent hyphenation by defining a |\language| which has no
%    patterns associated with it and use this to typeset the words
%    within the angle brackets.
% \changes{v2.0i}{2000/05/21}{New implementation (pr/3170)}
%    \begin{macrocode}
\ifx\l@nohyphenation\undefined
  \newlanguage\l@nohyphenation
\fi
%    \end{macrocode}
%
%    \begin{macrocode}
\DeclareRobustCommand\meta[1]{%
%    \end{macrocode}
%    Since the old implementation of |\meta| could be used in math we
%    better ensure that this is possible with the new one as
%    well. So we use |\ensuremath| around |\langle| and
%    |\rangle|. However this is not enough: if |\meta@font@select|
%    below expands to |\itshape| it will fail if used in math
%    mode. For this reason we hide the whole thing inside an
%    |\nfss@text| box in that case.
% \changes{v2.0l}{2000/06/10}{Fixing changes for (pr/3170)}
%    \begin{macrocode}
     \ensuremath\langle
     \ifmmode \expandafter \nfss@text \fi
     {%
      \meta@font@select
%    \end{macrocode}
%    Need to keep track of what we changed just in case the user
%    changes font inside the argument so we store the font explicitly.
% \changes{v2.0m}{2000/07/04}{More fixing changes for (pr/3170)}
%    \begin{macrocode}
      \edef\meta@hyphen@restore
        {\hyphenchar\the\font\the\hyphenchar\font}%
      \hyphenchar\font\m@ne
      \language\l@nohyphenation
      #1\/%
      \meta@hyphen@restore
     }\ensuremath\rangle
}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{macro}{\meta@font@select}
% \changes{v2.0k}{2000/05/26}{Macro added (pr/3170)}
%    Make font used inside |\meta| customizable.
%    \begin{macrocode}
\def\meta@font@select{\itshape}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{imacro}{\IndexInput}
%    This next macro may be used to read in a separate file (possibly
%    a package file that is {\em not\/} documented by this means) and
%    set it verbatim, whilst scanning for macro names and indexing the
%    latter.  This could be a useful first pass in preparing to
%    generate documentation for the file read.
%    \begin{macrocode}
\def\IndexInput#1{%
%    \end{macrocode}
%     We commence by setting up a group, and initializing a
%    |\trivlist| as is normally done by a
%    |\begin{macrocode}| command.
%    \begin{macrocode}
     \begingroup \macro@code
%    \end{macrocode}
%    We also make spacing behave as in the \env{macrocode}
%    environment, because otherwise all the spaces will be shown
%    explicitly.
%    \begin{macrocode}
   \frenchspacing \@vobeyspaces
%    \end{macrocode}
%    Then it only remains to read in the specified file, and finish
%    off the |\trivlist|.
% \changes{v1.5t}{1989/11/07}{Call \cs{endmacrocode} instead
%                             of \cs{endtrivlist}.}
%    \begin{macrocode}
     \input{#1}\endmacrocode
%    \end{macrocode}
%    Of course, we need to finish off the group as well.
%    \begin{macrocode}
     \endgroup}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{imacro}{\maketitle}
%    The macro to generate titles is easily altered in order that it
%    can be used more than once (an article with many titles).  In the
%    original, diverse macros were concealed after use with
%    |\relax|. We must cancel anything that may have been put
%    into |\@thanks|, etc., otherwise {\em all\/} titles will
%    carry forward any earlier such setting!
%  \changes{v1.5j}{1989/06/09}{thispagestyle plain removed}
%  \changes{v1.9r}{1994/06/09}{Added new definitions of
%                 \cs{@makefnmark} and \cs{@makefntext}}
%    \begin{macrocode}
\def\maketitle{\par
      \begingroup \def \thefootnote {\fnsymbol {footnote}}%
      \setcounter {footnote}\z@
      \def\@makefnmark{\hbox to\z@{$\m@th^{\@thefnmark}$\hss}}%
      \long\def\@makefntext##1{\parindent 1em\noindent
            \hbox to1.8em{\hss$\m@th^{\@thefnmark}$}##1}%
      \if@twocolumn \twocolumn [\@maketitle ]%
      \else \newpage \global \@topnum \z@ \@maketitle \fi
%    \end{macrocode}
% \changes{v1.5k}{1989/09/04}{Added \cs{ps@titlepage}}
%    For special formatting requirements (such as in TUGboat), we use
%    pagestyle |titlepage| for this; this is later defined to be
%    |plain|, unless already defined, as, for example, by
%    |ltugboat.sty|.
%    \begin{macrocode}
       \thispagestyle{titlepage}\@thanks \endgroup
%    \end{macrocode}
%    If the driver file documents many files, we don't want parts of a
%    title of one to propagate to the next, so we have to cancel
%    these:
%    \begin{macrocode}
      \setcounter {footnote}\z@
      \gdef\@date{\today}\gdef\@thanks{}%
      \gdef\@author{}\gdef\@title{}}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{imacro}{\ps@titlepage}
% \changes{v1.5k}{1989/09/04}{Added \texttt{\protect\bslash
%    ps@titlepage}} When a number of articles are concatenated into a
%    journal, for example, it is not usual for the title pages of such
%    documents to be formatted differently.  Therefore, a class
%    such as \cls{ltugboat} can define this macro in advance.
%    However, if no such definition exists, we use pagestyle
%    \texttt{plain} for title pages.
%    \begin{macrocode}
\@ifundefined{ps@titlepage}
    {\let\ps@titlepage=\ps@plain}{}
%    \end{macrocode}
% \end{imacro}
%
% \begin{imacro}{\MakeShortVerb}
% \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters
%                           \cs{dospecials}, \cs{@sanitize}).}
% This arranges an abbreviation for |\verb| such that if you say
% |\MakeShortVerb{\|\meta{c}|}| subsequently using
% \meta{c}\meta{text}\meta{c} is equivalent to
% |\verb|\meta{c}\meta{text}\meta{c}.\footnote{Warning:
% the commentary in the rest of this section was written by Dave
% Love.}  In addition, the fact
% that \meta{c} is made active is recorded for the benefit of the
% \env{verbatim} and \env{macrocode} environments.
% Note particularly that the definitions below are global.
% The first thing we do (it needn't be first) is to record
% the---presumably new---special character in |\dospecials| and
% |\@sanitize| using |\add@special|.
%
% \changes{v1.9e.2}{1994/02/07}{-js: Check if \protect\meta{c} is
%                              already an
%                              abbreviation for \cs{verb}.}
% Some unwary user might issue |\MakeShortVerb| for a second time, we
% better protect against this. We assume that this happened if a
% control sequence |\cc\|\meta{c} is bound, the probability that this
% name is used by another module is low. We will output a warning
% below, so that a possible error might be noticed by the programmer
% if he reads the |LOG| file. (Should have used module internal names,
% 'though.)
%
% \begin{imacro}{\MakeShortVerb*}
% \changes{v2.1a}{2003/12/09}{(HjG) Added \texttt{*} form}
% This arranges an abbreviation for |\verb*| such that if you say
% |\MakeShortVerb*{\|\meta{c}|}| subsequently using
% \meta{c}\meta{text}\meta{c} is equivalent to
% |\verb*|\meta{c}\meta{text}\meta{c}.
%    \begin{macrocode}
%</package>
%<*package|shortvrb>
\def\MakeShortVerb{%
  \@ifstar
    {\def\@shortvrbdef{\verb*}\@MakeShortVerb}%
    {\def\@shortvrbdef{\verb}\@MakeShortVerb}}
%    \end{macrocode}
% \end{imacro}
% \end{imacro}
%
% \begin{macro}{\@MakeShortVerb}
%    \begin{macrocode}
\def\@MakeShortVerb#1{%
  \expandafter\ifx\csname cc\string#1\endcsname\relax
%    \end{macrocode}
% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}}
%    \begin{macrocode}
    \@shortvrbinfo{Made }{#1}\@shortvrbdef
    \add@special{#1}%
%    \end{macrocode}
% Then the character's current catcode is stored in |\cc\|\meta{c}.
%    \begin{macrocode}
    \expandafter
    \xdef\csname cc\string#1\endcsname{\the\catcode`#1}%
%    \end{macrocode}
% The character is spliced into the definition using the same trick as
% used in |\verb| (for instance), having activated |~| in a group.
%    \begin{macrocode}
    \begingroup
      \catcode`\~\active  \lccode`\~`#1%
      \lowercase{%
%    \end{macrocode}
% The character's old meaning is recorded in |\ac\|\meta{c} prior to
% assigning it a new one.
%    \begin{macrocode}
      \global\expandafter\let
         \csname ac\string#1\endcsname~%
      \expandafter\gdef\expandafter~\expandafter{\@shortvrbdef~}}%
    \endgroup
%    \end{macrocode}
% Finally the character is made active.
%    \begin{macrocode}
    \global\catcode`#1\active
%    \end{macrocode}
% If we suspect that \meta{c} is already a short reference, we tell
% the user. Now he or she is responsible if anything goes wrong\,\dots
%    \begin{macrocode}
  \else
%    \end{macrocode}
% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}}
%    \begin{macrocode}
    \@shortvrbinfo\@empty{#1 already}%
                         {\@empty\verb% % to fool emacs highlighting
                          (*)}%
  \fi}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{imacro}{\DeleteShortVerb}
% \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters
%                           \cs{dospecials}, \cs{@sanitize}).}
% Here's the means of undoing a |\MakeShortVerb|, for instance in a
% region where you need to use the character outside a verbatim
% environment.  It arranges for |\dospecials| and |\@sanitize| to be
% altered appropriately, restores the saved catcode and, if necessary,
% the character's meaning (as stored by
% |\MakeShortVerb|).  If the catcode wasn't stored in
% |\cc\|\meta{c} (by |\MakeShortVerb|) the command is silently
% ignored.
% \changes{v1.7a}{1992/02/28}{Check for previous matched
%                           \cs{MakeShortVerb}
%                           to avoid error.}
%    \begin{macrocode}
\def\DeleteShortVerb#1{%
  \expandafter\ifx\csname cc\string#1\endcsname\relax
%    \end{macrocode}
% \changes{v2.1a}{2003/12/10}{(HjG) Notify user
%             if it's not a short verb character}
%    \begin{macrocode}
    \@shortvrbinfo\@empty{#1 not}%
                         {\@empty\verb% % to fool emacs highlighting
                          (*)}%
  \else
%    \end{macrocode}
% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}}
%    \begin{macrocode}
    \@shortvrbinfo{Deleted }{#1 as}%
                            {\@empty\verb% % to fool emacs
                                           % highlighting
                            (*)}%
    \rem@special{#1}%
    \global\catcode`#1\csname cc\string#1\endcsname
%    \end{macrocode}
% \changes{v1.9e.2}{1994/02/07}{-js: Reset `cc`\protect\meta{c} in
%                       in \cs{DeleteShortVerb}}
% We must not forget to reset |\cc\|\meta{c}, otherwise the check in
% |\MakeShortVerb| for a repeated definition will not work.
%    \begin{macrocode}
    \global \expandafter\let \csname cc\string#1\endcsname \relax
    \ifnum\catcode`#1=\active
      \begingroup
        \catcode`\~\active   \lccode`\~`#1%
        \lowercase{%
          \global\expandafter\let\expandafter~%
          \csname ac\string#1\endcsname}%
      \endgroup \fi \fi}
%    \end{macrocode}
% \end{imacro}
%
%  \begin{macro}{\@shortvrbinfo}
% \changes{v1.9v}{1995/11/03}{(DPC) Macro added}
% \changes{v2.1a}{2003/12/10}{(HjG) Third argument added
%             on behalf of \cmd{\MakeShortVerb*}}
% Helper function for info messages.
%    \begin{macrocode}
\def\@shortvrbinfo#1#2#3{%
%<shortvrb>  \PackageInfo{shortvrb}{%
%<!shortvrb>  \PackageInfo{doc}{%
     #1\expandafter\@gobble\string#2 a short reference
                                          for \expandafter\string#3}}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\add@special}
% \changes{v1.7a}{1992/02/27}{Added for short verb facility.}
% This helper macro adds its argument to the
% |\dospecials| macro which is conventionally used by verbatim macros
% to alter the catcodes of the currently active characters.  We need
% to add |\do\|\meta{c} to the expansion of |\dospecials| after
% removing the character if it was already there to avoid multiple
% copies building up should |\MakeShortVerb| not be balanced by
% |\DeleteShortVerb| (in case anything that uses |\dospecials| cares
% about repetitions).
%    \begin{macrocode}
\def\add@special#1{%
  \rem@special{#1}%
  \expandafter\gdef\expandafter\dospecials\expandafter
    {\dospecials \do #1}%
%    \end{macrocode}
% Similarly we have to add |\@makeother\|\meta{c} to |\@sanitize|
% (which is used in things like |\index| to re-catcode all special
% characters except braces).
%    \begin{macrocode}
  \expandafter\gdef\expandafter\@sanitize\expandafter
    {\@sanitize \@makeother #1}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\rem@special}
% \changes{v1.7a}{1992/02/27}{Added for short verb facility.}
% The inverse of |\add@special| is slightly trickier.  |\do| is
% re-defined to expand to nothing if its argument is the character of
% interest, otherwise to expand simply to the argument.  We can then
% re-define |\dospecials| to be the expansion of itself.  The space
% after |=`##1| prevents an expansion to |\relax|!
%    \begin{macrocode}
\def\rem@special#1{%
  \def\do##1{%
    \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}%
  \xdef\dospecials{\dospecials}%
%    \end{macrocode}
% Fixing |\@sanitize| is the same except that we need to re-define
% |\@makeother| which obviously needs to be done in a group.
%    \begin{macrocode}
  \begingroup
    \def\@makeother##1{%
      \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}%
    \xdef\@sanitize{\@sanitize}%
  \endgroup}
%</package|shortvrb>
%<*package>
%    \end{macrocode}
% \end{macro}
%
%
% \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 initializes the count (when called from
% |\MaybeStop|).
% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
%    \begin{macrocode}
\def\init@checksum{\relax
    \global\bslash@cnt\z@}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\check@checksum}
% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
% This reports the sum compared with the value (|\bslash@cnt|) the
% file advertises.  It's called from |\Finale| (if that hasn't been
% re-defined).
% \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum
%    is specified in the file}
%    \begin{macrocode}
\def\check@checksum{\relax
  \ifnum\check@sum>\m@ne
%    \end{macrocode}
%    We do nothing if the checksum in the file is negative (or not given as
%    it is initialized with -1).
%    \begin{macrocode}
     \ifnum\check@sum=\z@
       \typeout{**********************************}%
       \typeout{* This macro file has no checksum!}%
       \typeout{* The checksum should be \the\bslash@cnt!}%
       \typeout{**********************************}%
     \else
       \ifnum\check@sum=\bslash@cnt
         \typeout{*******************}%
         \typeout{* Checksum passed *}%
         \typeout{*******************}%
       \else
         \PackageError{doc}{Checksum not passed
                    (\the\check@sum<>\the\bslash@cnt)}%
          {The file currently documented seems to be wrong.^^J%
           Try to get a correct version.}%
       \fi
     \fi
  \fi
  \global\check@sum\m@ne}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{tcounter}{\check@sum}
% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
% \begin{tcounter}{\bslash@cnt}
% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
% We need to define counters, |\bslash@cnt| for the number of
% backslashes counted and |\check@sum| for the value advertised by the
% file if any. A negative value means there is no checksum checking which is the default.
% \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum
%    is specified in the file}
%    \begin{macrocode}
\newcount\check@sum           \check@sum  = \m@ne
\newcount\bslash@cnt          \bslash@cnt = \z@
%    \end{macrocode}
% \end{tcounter}
% \end{tcounter}
%
%
% \begin{omacro}{\CheckSum}
% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
% This is the interface to setting |\check@sum|.
%    \begin{macrocode}
\def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack}
%    \end{macrocode}
% \end{omacro}
%
%
%
% \begin{macro}{\step@checksum}
% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
% This advances the count when a backslash is encountered in the
% macrocode.
%    \begin{macrocode}
\def\step@checksum{\global\advance\bslash@cnt\@ne}
%    \end{macrocode}
% \end{macro}
%
% \begin{omacro}{\CharacterTable}
%    The user interface to the character table-checking does some
%    |\catcode|ing and then compares the following table with the
%    stored version. We need to have |@| of type ``other'' within the
%    table since this is the way it is usually returned when reading
%    in a normal document. To nevertheless have a private letter we
%    use |~| for this purpose. |~| does no harm as a ``letter'' as it
%    comes last in the table and therefore will not gobble following
%    space.
% \changes{v1.5m}{1989/09/20}{Macro added to check character translation
%                           problems.}
% \changes{v1.5q}{1989/11/01}{Made character table more readable.}
% \changes{v1.5t}{1989/11/07}{Make \string\~{} letter in chartable
%                           macros.}
% \changes{v1.5u}{1989/11/14}{Made @ other in default table.}
%    \begin{macrocode}
\def\CharacterTable{\begingroup \CharTableChanges \character@table}
%    \end{macrocode}
% \end{omacro}
%
% \def\MakePrivateLetters{\catcode`\~=11\makeatletter}
%
% \begin{macro}{\character@table}
% This does the work of comparing the tables and reporting the result.
% Note that the following code is enclosed in a group
% with |~| catcoded to letter.
%    \begin{macrocode}
\begingroup
  \catcode`\~=11
  \gdef\character@table#1{\def\used~table{#1}%
      \ifx\used~table\default~table
           \typeout{***************************}%
           \typeout{* Character table correct *}%
           \typeout{***************************}%
      \else
         \PackageError{doc}{Character table corrupted}
                           {\the\wrong@table}
         \show\default~table
         \show\used~table
      \fi
      \endgroup}
%    \end{macrocode}
% \end{macro}
%
% \begin{omacro}{\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{omacro}
%
% \begin{macro}{\default~table}
% Here's what the table {\em should\/} look like (modulo spaces).
%    \begin{macrocode}
  \makeatother
  \gdef\default~table
     {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
      Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
      Digits        \0\1\2\3\4\5\6\7\8\9
      Exclamation   \!     Double quote  \"     Hash (number) \#
      Dollar        \$     Percent       \%     Ampersand     \&
      Acute accent  \'     Left paren    \(     Right paren   \)
      Asterisk      \*     Plus          \+     Comma         \,
      Minus         \-     Point         \.     Solidus       \/
      Colon         \:     Semicolon     \;     Less than     \<
      Equals        \=     Greater than  \>     Question mark \?
      Commercial at \@     Left bracket  \[     Backslash     \\
      Right bracket \]     Circumflex    \^     Underscore    \_
      Grave accent  \`     Left brace    \{     Vertical bar  \|
      Right brace   \}     Tilde         \~}
\endgroup
%    \end{macrocode}
% \end{macro}
% \let\MakePrivateLetters=\makeatletter
%
% \begin{macro}{\wrong@table}
% \changes{v1.7a}{1992/02/28}{Moved to where the catcodes are right
%                           so it works.}
% We need a help message in case of problems.
%    \begin{macrocode}
  \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J
            I now \string\show\space you both tables for comparison.}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection[Attaching line numbers to code lines]
%            {Attaching line numbers to code lines\footnotemark}
%            \footnotetext{Warning: the commentary was written by Dave
%            Love.}
%
%
% The code in this section allows index entries to refer to code line
% numbers---the number of the first line of macrocode in the
% \env{macro} environment.
%
%
% \begin{macro}{\codeline@index}
% Indexing by code line is controlled by the |codeline@index| switch.
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
% \changes{v1.7a}{1992/02/24}{Documented code line no. support.}
% \begin{imacro}{\CodelineNumbered}
% \changes{v1.8a}{1993/05/19}{Macro added}
%    \begin{macrocode}
\newif\ifcodeline@index \codeline@indexfalse
\let\CodelineNumbered\codeline@indextrue
%    \end{macrocode}
% \end{imacro}
% \end{macro}
%
% \begin{macro}{\codeline@wrindex}
%    The code index entries are written out by |\special@index|.  If
%    indexing is by code line this is |\let| to |\codeline@wrindex|;
%    if indexing is by page it is just |\index|.  However, if
%    |\nofiles| is given, we omit writing such an index entry at all.
% \changes{v1.7j}{1992/08/14}{Added \cs{if@filesw}.}
%    \begin{macrocode}
\def\codeline@wrindex#1{\if@filesw
     \begingroup
        \set@display@protect
        \immediate\write\@indexfile
            {\string\indexentry{#1}%
             {\number\c@CodelineNo}}%
      \endgroup
    \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\special@index}
% By default no index entries are written out.
%    \begin{macrocode}
\let\special@index = \@gobble
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\CodelineIndex}
% \changes{v1.5u}{1989/11/14}{Added \cs{PageIndex} and
%                  \cs{CodelineIndex} (Undoc)}
% This switches on use of the index file with |\makeindex|, sets the
% switch to indicate code line numbering and defines |\special@index|
% appropriately.
%    \begin{macrocode}
\def\CodelineIndex{\makeindex
                   \codeline@indextrue
                   \let\special@index\codeline@wrindex}
%    \end{macrocode}
% \end{macro}
% \begin{imacro}{\PageIndex}
% |\PageIndex| is similar.
%    \begin{macrocode}
\def\PageIndex{\makeindex
               \codeline@indexfalse
               \let\special@index\index}
%    \end{macrocode}
% \end{imacro}
%
%
% \begin{lcounter}{CodelineNo}
% \changes{v1.5l}{1989/09/10}{Counter added to support code line
%                             numbers}
% \changes{v1.5y}{1990/02/24}{Default changed.}
% \changes{v1.6b}{1990/06/15}{\cs{rm} moved before \cs{scriptsize} to
%                           avoid unnecessary fontwarning.}
% We need a counter to keep track of the line number.
%    \begin{macrocode}
\newcount\c@CodelineNo  \c@CodelineNo\z@
%    \end{macrocode}
% \end{lcounter}
%
% \begin{macro}{\theCodelineNo}
% \changes{v1.7a}{1992/02/25}{Existing definition not overwritten.}
% \changes{v1.7a}{1992/03/12}{Use \cs{reset@font} for NFSS.}
% This provides a hook to control the format of line numbers which may
% be defined in a class file.
%    \begin{macrocode}
\@ifundefined{theCodelineNo}
  {\ifx\selectfont\undefined
     \def\theCodelineNo{\rmfamily\scriptsize\arabic{CodelineNo}}%
   \else
     \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}%
   \fi}
  {}
%    \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{Layout Parameters for documenting package files}
%
% \begin{macro}{\tolerance}
%    People documenting package files would probably rather have things
%    ``sticking out'' in overfull |\hbox|es and poorish spacing,
%    because they probably don't want to spend a lot of time on making
%    all the line breaks perfect!
%    \begin{macrocode}
       \tolerance=1000\relax
%    \end{macrocode}
% \end{macro}
%
%
% The following |\mathcode| definitions allow the characters
% `|\|'
% and `\texttt{@}' to appear in |\ttfamily| font when invoked in math
% mode;\footnote{You may wonder why the definitions state that both
%                characters belong to the {\em variable family\/}
%                (i.e.\ the number 7 in front). The reason is this:
%                Originally the \texttt{\bslash mathcode} of
%                \texttt{\bslash} was defined to be \texttt{"075C},
%                i.e.\ ordinary character number 92 (hex 5C) in
%                math family number 7 which is the typewriter family in
%                standard \LaTeX.
%                But this file should not depend on this specific
%                setting, so I changed these
%                \texttt{\bslash mathcode}$\,$s
%                to work with any family assignments. For an example
%                see the article about the new font selection scheme.}
% particularly for something like |\@abc=1|.
%
% If an {\em old\/} version of the \pkg{german} package is in
% force, then the `|"|' character is active and would upset the
% definition of the \meta{16-bit number} quantities below, therefore
% we change the |\catcode| of |"| inside a group, and use
% |\global|.
%    \begin{macrocode}
{ \catcode`\"=12
  \global\mathcode`\\="705C \global\mathcode`\@="7040 }
%    \end{macrocode}
% \MakeShortVerb{\"}
%
% \begin{macro}{\DocstyleParms}
%    This macro can be used, for example, to assign new values to
%    |\MacrocodeTopsep| and |\MacroIndent| and some other internal
%    registers.  If it is already defined, the default definition
%    won't be carried out. Note that it is necessary to assign new
%    values via this macro if it should be done in a class file (like
%    \texttt{ltugboat.cls} for example) since the registers are
%    undefined before \texttt{doc.sty} is read in.  The default values
%    for the internal registers are scattered over this file.
% \changes{v1.5u}{1989/11/14}{\cs{DocStyleParms} now empty}
% \changes{v2.1h}{2018/02/01}{Only use\cs{DocStyleParms} if defined
%                             (previously the test defined it)}
%    \begin{macrocode}
\@ifundefined{DocstyleParms}{}{\DocstyleParms}
%    \end{macrocode}
%    Clear out |\DocstyleParms| after use (or non-use).
%    \begin{macrocode}
 \let\DocstyleParms\relax
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\AmSTeX}
%   \changes{v1.5j}{1989/06/09}{Macro AmsTeX renamed to AmSTeX}
% \begin{macro}{\BibTeX}
% \begin{macro}{\SliTeX}
%    Here are a few definitions which can usefully be employed when
%    documenting package files: now we can readily refer to \AmSTeX,
%    \BibTeX\ and \SliTeX, as well as the usual \TeX\ and \LaTeX.
%    \begin{macrocode}
\@ifundefined{AmSTeX}
   {\def\AmSTeX{\leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex%
        \hbox{$\mathcal M$}\kern-.2em\mathcal S$-\TeX}}}{}
\@ifundefined{BibTeX}
   {\def\BibTeX{{\rmfamily B\kern-.05em%
    \textsc{i\kern-.025em b}\kern-.08em%
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{}
\@ifundefined{SliTeX}
   {\def\SliTeX{{\rmfamily S\kern-.06emL\kern-.18em\raise.32ex\hbox
                {\scshape i}\kern -.03em\TeX}}}{}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\PlainTeX}
% \changes{v1.5g}{1989/05/07}{space between plain and TeX changed.}
% \begin{macro}{\Web}
%     There's even a \PlainTeX{} and a \Web.
%    \begin{macrocode}
\@ifundefined{PlainTeX}{\def\PlainTeX{\textsc{Plain}\kern2pt\TeX}}{}
\@ifundefined{Web}{\def\Web{\textsc{Web}}}{}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \subsection{Changing the \texttt{\protect\bslash catcode} of \%}
%
% \begin{imacro}{\MakePercentIgnore}
% \begin{imacro}{\MakePercentComment}
%    And finally the most important bit: we change the |\catcode|
%    of `|%|' so that it is ignored (which is how we are able to
%    produce this document!). We provide two commands to do the actual
%    switching.
%^^A The |\MakePercentIgnore| is then called as the
%^^A last command in this file.
%    \begin{macrocode}
\def\MakePercentIgnore{\catcode`\%9\relax}
\def\MakePercentComment{\catcode`\%14\relax}
%    \end{macrocode}
% \end{imacro}
% \end{imacro}
%
% \begin{imacro}{\DocInput}
%    The two macros above are now used to define the |\DocInput| macro
%    which was introduced in version v1.5l (or so) of the \DOC{}
%    package. In older versions |\MakePercentIgnore| was placed
%    at the very end of \texttt{doc.sty}.
%    \begin{macrocode}
\def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
%    \end{macrocode}
% \end{imacro}
%
% \subsection{GetFileInfo}
%
% \begin{macro}{\GetFileInfo}
% \changes{v1.9o}{1994/05/08}{Macro added}
% \changes{v1.9z}{1997/02/05}{Missing percent latex/2404}
%    Define |\filedate| and friends from info in the
%    |\ProvidesPackage| etc.\ commands.
%    \begin{macrocode}
\def\GetFileInfo#1{%
  \def\filename{#1}%
  \def\@tempb##1 ##2 ##3\relax##4\relax{%
    \def\filedate{##1}%
    \def\fileversion{##2}%
    \def\fileinfo{##3}}%
  \edef\@tempa{\csname ver@#1\endcsname}%
  \expandafter\@tempb\@tempa\relax? ? \relax\relax}
%    \end{macrocode}
% \end{macro}
%




% \section{Integrating hypdoc}
%
%    If the option \texttt{hyperref} is selected (which is the
%    default), then we load the \pkg{hypdoc} package. We do that as
%    late as possible so that we don't generate option clashes if it
%    is also loaded in the preamble. That package currently changes
%    more commands than it should (not knowing about their new
%    definitions defined below) so we have to save and restore a few.
%
%    Midterm all this code in \pkg{hypdoc} should be directly included
%    in \DOC. For now, while they are separate we have to do this
%    juggling.
%    \begin{macrocode}
\AddToHook{begindocument/before}[doc/hyperref]{%
 \ifdoc@hyperref
%    \end{macrocode}
%    Annoying to code around issue \#22
%    \begin{macrocode}
  \expandafter\let\expandafter\doc@eoph@@k\csname doc.sty-h@@k\endcsname
%    \end{macrocode}
%    We require the package without any option so if it was already
%    loaded there is no option clash.
%    \begin{macrocode}
  \RequirePackage{hypdoc}
  \expandafter\let\csname doc.sty-h@@k\endcsname\doc@eoph@@k
%    \end{macrocode}
%    After \pkg{hypdoc} got loaded we need to undefine those macros
%    again so that later on \texttt{Macro} and \texttt{Env} \DOC items
%    appear to be undefined.
%    \begin{macrocode}
  \let\PrintDescribeMacro \@@PrintDescribeMacro
  \let\PrintDescribeEnv \@@PrintDescribeEnv
  \let\PrintMacroName \@@PrintMacroName
  \let\PrintEnvName \@@PrintEnvName
  \let\SpecialUsageIndex \@@SpecialUsageIndex
  \let\SpecialEnvIndex \@@SpecialEnvIndex
  \let\SortIndex \@@SortIndex
  \let\DescribeMacro \@@DescribeMacro
  \let\DescribeEnv \@@DescribeEnv
%    \end{macrocode}
%    The package adds new definitions for \cs{special@index} into
%    \cs{CodelineIndex} and \cs{PageIndex} but since we are loading it
%    very late we are already past them (in the preamble). So we test
%    the final state and do it here, if necessary.
%    \begin{macrocode}
  \ifx\special@index\@gobble  % do we write index entries at all?
  \else
    \ifcodeline@index
      \let\special@index\HD@codeline@wrindex
    \else
      \let\special@index\HD@page@wrindex
    \fi
  \fi
%    \end{macrocode}
%    The \pkg{amsmath} documentation uses \cs{env} in headings and
%    with \pkg{hyperref} enabled this causes trouble in bookmarks.
% \fmi{fix elsewhere eventually}
%    \begin{macrocode}
  \AddToHook{class/amsdtx/after}{%
     \pdfstringdefDisableCommands{\let\env\@empty }}%
%    \end{macrocode}
%    That package also adds extra code into |\index| entries but it doesn't
%    know about all the stuff that \DOC does (now). So we need to provide
%    us with two helpers that handle the |\encapchar| case in some entries.
%    \begin{macrocode}
  \def\doc@providetarget{\HD@target}%
  \def\doc@handleencap#1{\encapchar hdclindex{\the\c@HD@hypercount}{#1}}%
%    \end{macrocode}
%    If that package is not loaded these helpers do little to nothing.
%    \begin{macrocode}
 \else
  \let\doc@providetarget\@empty
  \def\doc@handleencap#1{\encapchar #1}%
%    \end{macrocode}
%    We define the next commands just in case the user changed the option
%    \texttt{hyperref} from \texttt{true} to \texttt{false} without
%    removing the auxiliary files.
%    \begin{macrocode}
  \def\hdclindex#1#2{\ifx\@nil#2\@nil\else\csname #2\expandafter\endcsname\fi}%
  \def\hdpindex   #1{\ifx\@nil#1\@nil\else\csname #1\expandafter\endcsname\fi}%
\fi
}  
%    \end{macrocode}
%
%
%
%
%
% \section{Integrating the \DOX package code}
%
% The code in this section is largely taken over from the \DOX package
% by Didier with only minor modifications (so far). This means it is a
% bit back and forth and both the code and the documentation need
% further updates.
%
% \subsection{\DOX environments}

% \begin{macro}{\@doc@env,\@doc@env@}
% \fmi{original doc -- fix}
%   \marg{are-we-macrolike}\marg{item}\marg{indextype}\marg{name}\\
%   In \texttt{doc.sty}, the \texttt{macro} and \texttt{environment}
%   environments go through the \cs{m@cro@} macro which implements specific
%   parts by testing a boolean condition as its first argument. This mechanism
%   is not extensible, so I have to hack away a more generic version that
%   would work for any new \texttt{dox} item, only which looks pretty much
%   like the original one (with the addition of options management).
%
%    First step is to see if we have a comma-separated list of names
%    in |#3| and if so we call the macro doing the work individually
%    for each
%    \begin{macrocode}
\ExplSyntaxOn
%    \end{macrocode}
%
%    \begin{macrocode}
\long\def\@doc@env#1#2#3{
%    \end{macrocode}
%    The |\endgroup| here closes the scanning of names (using special catcodes).
%    \begin{macrocode}
  \endgroup
  \clist_map_inline:nn {#3} { \@doc@env@{#1}{#2}{##1} }
}

\ExplSyntaxOff
%    \end{macrocode}
%
%    And here is the payload for each name from the given list:
%    \begin{macrocode}
\long\def\@doc@env@#1#2#3{%
  \topsep\MacroTopsep
  \trivlist
    \edef\saved@macroname{\string#3}%
%    \end{macrocode}
% Since version 2.1g, \texttt{doc} creates a \cs{saved@indexname} command
% which in used by \cs{changes}. We now support that as well. The expansion of
% this command depends on whether the documented item is macrolike or not,
% which we don't know here (it's only know by \cs{NewDocElement}). That's why we
% need one specific command generating \cs{saved@indexname} the right way for
% every single item. These commands are
%    named\cs{@Save\meta{item}IndexName};
% they are technically part of the generated API, only not meant for public
% use.
%
% \fmi{above docu is no longer right (but code probably  needs further changes
% anyway)}
%
%    |#1| is either \texttt{TT} (for true = macrolike) or \texttt{TF}.
%    If true then we drop the first char from |\saved@macroname| and
%    store the result in |\saved@indexname| and use the latter for
%    sorting in the index.
%    \begin{macrocode}
    \if #1%
      \edef\saved@indexname{\expandafter\@gobble\saved@macroname}%
%
%    \end{macrocode}
%    If the \DOC element described is macrolike but not a normal
%    ``macro'' then its type should be recorded and this is the places
%    where this happens. For macros (which should make up the bulk of
%    these items) we don't do this and for anything else that looks
%    from an indexing perspective like a macro we don't do that either
%    to keep the list of exceptions small. That would be the case if
%    the indexing command |\Code|\meta{doc-element}|Index| is
%    equivalent to \cs{CodeMacroIndex}.
%    \begin{macrocode}
      \expandafter\ifx
                  \csname Code#2Index\endcsname
                  \CodeMacroIndex
      \else
        \record@index@type@save
          {\saved@indexname}{#2}%
      \fi
    \else
      \let\saved@indexname\saved@macroname
    \fi
%
    \def\makelabel##1{\llap{##1}}%
    \if@inlabel
      \let\@tempa\@empty
      \count@\macro@cnt
      \loop\ifnum\count@>\z@
        \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne
      \repeat
      \edef\makelabel##1{\llap{\vtop to\baselineskip{\@tempa\hbox{##1}\vss}}}%
      \advance\macro@cnt\@ne
    \else
      \macro@cnt\@ne
    \fi
    \ifdoc@noprint
      \item
    \else
      \edef\@tempa{%
        \noexpand\item[%
%    \end{macrocode}
% The second notable modification to the original macro involves dynamically
% constructing the name of the print macro:
%    \begin{macrocode}
        \noexpand\doc@providetarget
        \noexpand\strut
        \noexpand\@nameuse{Print#2Name}{\saved@macroname}]}%
      \@tempa
    \fi
    \ifdoc@noindex\else
      \global\advance\c@CodelineNo\@ne
%    \end{macrocode}
% and the third one involves dynamically constructing the name of the index
% macro:
%    \begin{macrocode}
      \csname SpecialMain#2Index\expandafter\endcsname
        \expandafter{\saved@macroname}\nobreak
      \global\advance\c@CodelineNo\m@ne
    \fi
%    \end{macrocode}
%    Suppress further |\index| entries when we are within a
%    \texttt{macrolike} environment. There is no point doing that for
%    non-\texttt{macrolike} environments are index entries are only
%    generated for items starting with a backslash anyway.
% \fmi{fix}
%    \begin{macrocode}
    \if#1\expandafter\DoNotIndex \expandafter {\saved@macroname}\fi
    \ignorespaces}
%    \end{macrocode}
% \end{macro}
%
%
%
%
%
%
% \begin{macro}{\doc@env}
%   \marg{true-value}\marg{item}\oarg{options}\\
%   Handle optional arguments and call \cs{@doc@env}. Because environments can
%   be nested, we can't rely on grouping for getting options default values.
%   Hence, we need to reset the options at every call.
% \fmi{Use 2e interface for \cs{keys\_set:nn} when available}
%    \begin{macrocode}
\def\doc@env#1#2[#3]{%
  \@nameuse{doc@noprint\doc@noprintdefault}%
  \@nameuse{doc@noindex\doc@noindexdefault}%
  \csname keys_set:nn\endcsname{doc}{#3}%
  \begingroup
    \ifdoc@outer
      \catcode`\\12
    \fi
    \MakePrivateLetters
    \@doc@env{#1}{#2}%
}
%    \end{macrocode}
% \end{macro}



% \subsection{\DOC descriptions}
%
% \begin{macro}{\@doc@describe}
%   \marg{item}\marg{name}\\
%    \begin{macrocode}
\def\@doc@describe#1#2{%
    \ifdoc@noprint\else
      \marginpar{\raggedleft
%    \end{macrocode}
%    The hyperref target has to be in horizontal mode (which is the
% case if it is after the \cs{strut}).
%    \begin{macrocode}
                 \strut
                 \doc@providetarget
                 \@nameuse{PrintDescribe#1}{#2}}%
    \fi
    \ifdoc@noindex\else
      \@nameuse{Special#1Index}{#2}%
    \fi
  \@esphack
  \endgroup
  \ignorespaces}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\doc@describe}
%   \marg{item}\oarg{options}\\
%   Handle optional arguments and call \cs{@doc@describe}.
% \fmi{Use 2e interface for \cs{keys\_set:nn} when available}
%    \begin{macrocode}
\def\doc@describe#1[#2]{%
  \leavevmode\@bsphack
  \csname keys_set:nn\endcsname{doc}{#2}%
  \@doc@describe{#1}}
%    \end{macrocode}
% \end{macro}
%
%
%
%
% \subsection{API construction}
%
%
%  \begin{macro}{\@temptokenb}
%    A scratch register (which may have been defined elsewhere)
%    \begin{macrocode}
\@ifundefined{temptokenb}{\newtoks\@temptokenb}{}
%    \end{macrocode}
%  \end{macro}
%
%
% \begin{macro}{\doc@createspecialmainindex}
%   \marg{item}\marg{idxtype}\marg{idxcat}
% \begin{macro}{\doc@createspecialmainmacrolikeindex}
%   \marg{item}\marg{idxtype}\marg{idxcat}\\
% \fmi{original doc -- fix}
%   The ``macrolike'' version does something similar to |doc|'s
%   \cs{SpecialIndex@} macro, but simplified. Let's just hope nobody will ever
%   define \verb*|\ | or nonletter macros as macrolike \DOC elements\ldots
%    \begin{macrocode}
\def\doc@createspecialindexes#1#2#3{%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@temptokena{\space (#2)}%
  \@temptokenb{#3:}%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@nameedef{SpecialMain#1Index}##1{%
    \noexpand\@bsphack
  \ifdoc@toplevel
    \noexpand\special@index{##1\noexpand\actualchar
    {\string\ttfamily\space##1}%
    \ifx\@nil#2\@nil\else \the\@temptokena \fi
    \noexpand\encapchar main}%
  \fi
  \ifx\@nil#3\@nil\else
    \noexpand\special@index{\the\@temptokenb\noexpand\levelchar
      ##1\noexpand\actualchar{\string\ttfamily\space##1}%
      \noexpand\encapchar main}%
  \fi
    \noexpand\@esphack}%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@nameedef{Special#1Index}##1{%
    \noexpand\@bsphack
  \ifdoc@toplevel
    \noexpand\doc@providetarget
    \noexpand\index{##1\noexpand\actualchar{\string\ttfamily\space##1}%
    \ifx\@nil#2\@nil\else \the\@temptokena \fi
           \noexpand\doc@handleencap{usage}}%
  \fi
  \ifx\@nil#3\@nil\else
    \noexpand\index{\the\@temptokenb\noexpand\levelchar
       ##1\noexpand\actualchar{\string\ttfamily\space##1}%
           \noexpand\doc@handleencap{usage}}%
  \fi
    \noexpand\@esphack}}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\doc@createspecialmacrolikeindexes#1#2#3{%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@temptokena{\space (#2)}%
  \@temptokenb{#3:}%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@nameedef{Code#1Index}##1##2{%
    \noexpand\@SpecialIndexHelper@##2\noexpand\@nil
    \noexpand\@bsphack
  \noexpand\ifdoc@noindex\noexpand\else
    \ifdoc@toplevel
      \noexpand\special@index{\noexpand\@gtempa\noexpand\actualchar
	\string\verb% % to fool emacs highlighting
	\noexpand\quotechar*\noexpand\verbatimchar
	\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar
	\ifx\@nil#2\@nil\else \the\@temptokena \fi
	\noexpand\encapchar ##1}%
    \fi
    \ifx\@nil#3\@nil\else
      \noexpand\special@index{\the\@temptokenb\noexpand\levelchar
	\noexpand\@gtempa\noexpand\actualchar
	\string\verb% % to fool emacs highlighting
	\noexpand\quotechar*\noexpand\verbatimchar
	\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar
	\noexpand\encapchar ##1}%
    \fi
  \noexpand\fi
    \noexpand\@esphack}%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@nameedef{SpecialMain#1Index}##1{%
    \expandafter\noexpand\csname Code#1Index\endcsname
        {main}{##1}}%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@nameedef{Special#1Index}##1{%
    \noexpand\@SpecialIndexHelper@##1\noexpand\@nil
    \noexpand\@bsphack
  \noexpand\ifdoc@noindex\noexpand\else
    \ifdoc@toplevel
      \noexpand\doc@providetarget
      \noexpand\index{\noexpand\@gtempa\noexpand\actualchar
	\string\verb% % to fool emacs highlighting
	\noexpand\quotechar*\noexpand\verbatimchar
	\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar
	\ifx\@nil#2\@nil\else \the\@temptokena \fi
	\noexpand\doc@handleencap{usage}}%
    \fi
    \ifx\@nil#3\@nil\else
      \noexpand\index{\the\@temptokenb\noexpand\levelchar
	\noexpand\@gtempa\noexpand\actualchar
	\string\verb% % to fool emacs highlighting
	\noexpand\quotechar*\noexpand\verbatimchar
	\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar
	\noexpand\doc@handleencap{usage}}%
    \fi
  \noexpand\fi
    \noexpand\@esphack}}
%    \end{macrocode}
% \end{macro}
% \end{macro}



% \begin{macro}{\doc@createdescribe}
%   \marg{item}
%    \begin{macrocode}
\def\doc@createdescribe#1{%
  \@namedef{Describe#1}{%
%    \end{macrocode}
%    Because of the optional argument we have to set
%    |\MakePrivateLetters| already before parsing that (fingers
%    crossed). Otherwise incorrect but quite common usage, such as
%    |\DescribeMacro\foo@bar| will break because the scan for the
%    optional argument will tokenize the following input (i.e., |\foo|
%    in that case) before the |@| sign becomes a letter. As a result
%    |DescribeMacro| would receive only |\foo| as its argument.
%    \begin{macrocode}
    \begingroup
      \MakePrivateLetters
      \@ifnextchar[%]
      {\doc@describe{#1}}{\doc@describe{#1}[]}}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\doc@createenv}
%   \marg{item}\marg{envname}
%    \begin{macrocode}
\def\doc@createenv#1#2#3{%
  \@namedef{#3}{%
    \@ifnextchar[%]
    {\doc@env{#1}{#2}}{\doc@env{#1}{#2}[]}}%
%    \end{macrocode}
%    Instead of |\let|ting the end of the environment to
%    |\endtrivlist| we use one level of expansion. This way any
%    possible change in that environment (if that ever happens) is
%    properly reflected.
%    \begin{macrocode}
  \@namedef{end#3}{\endtrivlist}%
%  \expandafter\let\csname end#3\endcsname\endtrivlist
}
%    \end{macrocode}
% \end{macro}


%
%  \begin{macro}{\@nameedef}
%
%    \begin{macrocode}
\def\@nameedef#1{\expandafter\edef\csname #1\endcsname}
%    \end{macrocode}
%  \end{macro}

%
% \subsection{API creation}
%
% The whole user interface is created in one macro call.
%
%\begin{verbatim}
% defaults:
%
%  idxtype   = #3
%  idxgroup  = #3s
%  printtype =
%\end{verbatim}



%  \begin{macro}{\doc@declareerror}
%
%    \begin{macrocode}
\def\doc@declareerror#1#2{%
   \PackageError{doc}{Doc element '#1/#2' already defined?\@gobble}%
      {There is already a definition for
       '\string\Print#1Name',\MessageBreak
       '\string\PrintDescribe#1'
       or the environment '#2'.\MessageBreak
       Maybe you are overwriting something by mistake!\MessageBreak
       Otherwise use '\string\RenewDocElement' instead.}%
}
%    \end{macrocode}
%  \end{macro}

%  \begin{macro}{\doc@notdeclarederror}
%
%    \begin{macrocode}
\def\doc@notdeclarederror#1#2{%
   \PackageError{doc}{Doc element '#1/#2' unknown}%
      {I expected an existing definition for
       '\string\Print#1Name',\MessageBreak
       '\string\PrintDescribe#1' and
       the environment '#2' but\MessageBreak
       not all of them are defined.\MessageBreak
       Maybe you wanted to use
       '\string\NewDocElement'?}%
}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\doc@ignoredinfo}
%
%    \begin{macrocode}
\def\doc@ignoredinfo#1#2{%
  \PackageInfo{doc}{Doc element '#1/#2' declaration
    ignored}%
}
%    \end{macrocode}
%  \end{macro}
%
%
% \begin{imacro}{\NewDocElement}
%   \oarg{options}\marg{name}\marg{envname}
%
%    \begin{macrocode}
\newcommand\NewDocElement[3][]{%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@ifundefined{Print#2Name}%
      {\@ifundefined{PrintDescribe#2}%
           {\@ifundefined{#3}%
               {\@ifundefined{end#3}%
                    {\@NewDocElement{#1}}%
                    \doc@declareerror
               }\doc@declareerror
           }\doc@declareerror
      }\doc@declareerror
  {#2}{#3}%
}
%    \end{macrocode}
%  \end{imacro}
%
% \begin{imacro}{\ProvideDocElement}
%   \oarg{options}\marg{name}\marg{envname}
%    This does nothing unless the doc element could be declared with
%    \cs{NewDocElement}.
%    \begin{macrocode}
\newcommand\ProvideDocElement[3][]{%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@ifundefined{Print#2Name}%
      {\@ifundefined{PrintDescribe#2}%
           {\@ifundefined{#3}%
               {\@ifundefined{end#3}%
                    {\@NewDocElement{#1}}%
                    \doc@ignoredinfo
               }\doc@ignoredinfo
           }\doc@ignoredinfo
      }\doc@ignoredinfo
  {#2}{#3}%
}
%    \end{macrocode}
%  \end{imacro}
%
%
% \begin{imacro}{\RenewDocElement}
%   \oarg{options}\marg{name}\marg{envname}
%
%    \begin{macrocode}
\newcommand\RenewDocElement[3][]{%
%    \end{macrocode}
%
%    \begin{macrocode}
  \@ifundefined{Print#2Name}\doc@notdeclarederror
      {\@ifundefined{PrintDescribe#2}\doc@notdeclarederror
           {\@ifundefined{#3}\doc@notdeclarederror
               {\@ifundefined{end#3}\doc@notdeclarederror
                    {\@NewDocElement{#1}}%
               }%
           }%
      }%
  {#2}{#3}%
}
%    \end{macrocode}
%  \end{imacro}
%
%
% \begin{macro}{\@NewDocElement}
%   \marg{options}\marg{name}\marg{envname}
%
%    \begin{macrocode}
\def\@NewDocElement#1#2#3{%
%    \end{macrocode}
%
%    \begin{macrocode}
  \doc@macrolikefalse
  \doc@topleveltrue
%    \end{macrocode}
%
% \fmi{Use 2e interface for \cs{keys\_set:nn} when available}
%    \begin{macrocode}
  \def\doc@idxtype{#3}%
  \def\doc@idxgroup{#3s}%
  \let\doc@printtype\@empty
  \csname keys_set:nn\endcsname{doc}{#1}%
%    \end{macrocode}
%   \begin{imacro}{\Print...Name}
%     \marg{name}
% \fmi{extremely messy this with so many \cs{expandafter}s \ldots{}
%       should reimplement in expl3}
%    \begin{macrocode}
  \ifx\doc@printtype\@empty
    \@temptokena{}%
  \else
    \@temptokena\expandafter{\expandafter
         \textnormal\expandafter{\expandafter
         \space\expandafter
         (\doc@printtype)}}%
  \fi
  \@nameedef{Print#2Name}##1{%
     {\noexpand\MacroFont
      \ifdoc@macrolike
         \noexpand\string
      \fi
      ##1%
      \the\@temptokena
     }}%
%    \end{macrocode}
%   \end{imacro}
%
%   \begin{imacro}{\PrintDescribe...}
%     \marg{name}
%    \begin{macrocode}
  \expandafter\let\csname PrintDescribe#2\expandafter\endcsname
                  \csname Print#2Name\endcsname
%    \end{macrocode}
%   \end{imacro}
%
%   \begin{imacro}{\SpecialMain...Index}
%     \marg{name}
%   \begin{imacro}{\Special...Index}
%     \marg{name}
%    \begin{macrocode}
  \edef\doc@expr{%
     \ifdoc@macrolike
       \noexpand\doc@createspecialmacrolikeindexes
     \else
       \noexpand\doc@createspecialindexes
     \fi
     {#2}%
    }%
   \expandafter\expandafter\expandafter
   \doc@expr
   \expandafter\expandafter\expandafter
     {\expandafter\doc@idxtype\expandafter}\expandafter
     {\doc@idxgroup}%
%    \end{macrocode}
%   \end{imacro}
%   \end{imacro}
%
%   \begin{imacro}{\Describe...}
%     \oarg{options}\marg{name}
%    \begin{macrocode}
  \doc@createdescribe{#2}%
%    \end{macrocode}
%   \end{imacro}
%
%   \begin{environment}{\meta{DocElement}}
%  \fmi{can't have formatting in argument -- fix}
%     \oarg{options}\marg{name}
%    \begin{macrocode}
    \ifdoc@macrolike
      \doc@createenv{TT}{#2}{#3}%
    \else
      \doc@createenv{TF}{#2}{#3}%
    \fi
}
%    \end{macrocode}
%   \end{environment}
% \end{macro}





% \subsection{Setting up the default \DOC elements}

% \subsubsection{Macro facilities}
%
%    Macros get only a single index entry (no index group, no index
%    type) and they do not get any label either when printing in the margin.
%    \begin{macrocode}
\NewDocElement[macrolike = true ,
                idxtype   = ,
                idxgroup  = ,
                printtype =
               ]{Macro}{macro}
%    \end{macrocode}


%  \begin{macro}{\SpecialMainIndex}
%
%    In \DOC v2 we had \cs{SpecialMainIndex} and
%    \cs{SpecialMainEnvIndex} but now with additional \DOC elements we
%    always add the element name after ``\texttt{Main}'' so this would
%    be \cs{SpecialMainMacroIndex}. We use |\def| not |\let| so any
%    redefinition of |\SpecialMainMacroIndex| will be transparent.
%    \begin{macrocode}
\def\SpecialMainIndex{\SpecialMainMacroIndex}
%    \end{macrocode}
%  \end{macro}

%  \begin{macro}{\SpecialUsageIndex}
%    \DOC v2 also had \cs{SpecialUsageIndex} which is now called
%    \cs{SpecialMacroIndex} generating the ``usage'' index entry  for
%    a macro. Again we provide that as an alias via |\def|.
%
%    In fact the documentation of \DOC v2 claimed that one can use
%    this for both macros and environments but that was never true as
%    for environments the result was that the first character was
%    dropped in sorting of the index. The correct way is to use
%    \cs{SpecialEnvIndex} for this.
%    \begin{macrocode}
\def\SpecialUsageIndex{\SpecialMacroIndex}
%    \end{macrocode}
%  \end{macro}
%

%  \begin{macro}{\SpecialIndex}
%    \begin{macrocode}
\def\SpecialIndex     {\CodeMacroIndex{code}}
%    \end{macrocode}
%  \end{macro}


%
% \subsubsection{Environment facilities}
%
%    Providing documentation support for environments. Here we differ
%    from \DOC V2 by marking the environments with ``(\textit{env.})''
%    when printing the name in the margin.
%    \begin{macrocode}
\NewDocElement[macrolike = false ,
                idxtype   = env.  ,
                idxgroup  = environments ,
                printtype = \textit{env.}
               ]{Env}{environment}
%    \end{macrocode}
%
%
%
%    To be able to restore the definition after \pkg{hypdoc} is loaded
%    we better save them here. We only load the package at the end of
%    the preamble, but the user might do this earlier and then chaos
%    is ensured.
%    \begin{macrocode}
  \let\@@PrintDescribeMacro \PrintDescribeMacro
  \let\@@PrintDescribeEnv \PrintDescribeEnv
  \let\@@PrintMacroName \PrintMacroName
  \let\@@PrintEnvName \PrintEnvName
  \let\@@SpecialUsageIndex \SpecialUsageIndex
  \let\@@SpecialEnvIndex \SpecialEnvIndex
  \let\@@SortIndex \SortIndex
  \let\@@DescribeMacro \DescribeMacro
  \let\@@DescribeEnv \DescribeEnv
%    \end{macrocode}
%
%
% \section{Misc additions}

% \begin{imacro}{\cs}
%    \begin{macrocode}
\DeclareRobustCommand\cs[1]{\texttt{\bslash #1}}
%    \end{macrocode}
%    \cls{amsdtx} has its own definition for \cs{cs} but that now
%    gets overwritten because the class loads \pkg{doc} afterwards. So
%    for now we reinstall it here.
%    \fmi{fix elsewhere}
%    \begin{macrocode}
\AddToHook{class/amsdtx/after}{%
  \DeclareRobustCommand\cs[1]{%
    \@boxorbreak{%
        \ntt
        \addbslash#1\@empty
        \@xp\@xp\@xp\@indexcs\@xp\@nobslash\string#1\@nil
    }%
  }%
  \def\cn{\cs}%
}
%    \end{macrocode}
% \end{imacro}


% We can now finish the \texttt{docstrip} main module.
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%
% \Finale
% \PrintChanges
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\endinput
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



^^A  Needed for emacs
^^A
^^A  Local Variables: 
^^A  mode: latex
^^A  coding: utf-8-unix
^^A  End: