latex2e (8jun22)

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

1 files changed, 3051 insertions, 1674 deletions

diff --git a/Master/texmf-dist/source/latex/base/doc.dtx b/Master/texmf-dist/source/latex/base/doc.dtx
index 41bc0733155..d6b21744df0 100644
--- a/Master/texmf-dist/source/latex/base/doc.dtx
+++ b/Master/texmf-dist/source/latex/base/doc.dtx
@@ -1,7 +1,7 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 1993-2021
-% The LaTeX Project and any individual authors listed elsewhere
+% Copyright 1993-2022
+% The LaTeX3 Project and any individual authors listed elsewhere
 % in this file.
 %
 % This file is part of the LaTeX base system.
@@ -33,10 +33,20 @@
 % ^^A category for `<'
 %\catcode`\<=14
 %<+package|shortvrb>\NeedsTeXFormat{LaTeX2e}[1994/12/01]
-%<+package> \ProvidesPackage{doc}
+%<+package>
+%<+package>\providecommand\DeclareRelease[3]{}
+%<+package>\providecommand\DeclareCurrentRelease[2]{}
+%<+package>
+%<+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>  [2021/10/04 v2.1n
-%<+package|shortvrb>   Standard LaTeX documentation package (FMi)]
+%<+package|shortvrb>  [2022/06/08 v3.0j
+%<+package|shortvrb>   Standard LaTeX documentation package V3 (FMi)]
 %\catcode`\<=12
 %
 %%
@@ -47,7 +57,7 @@
 %
 %
 %% Package `doc' to use with LaTeX 2e
-%% Copyright (C) 1989-2020 Frank Mittelbach, all rights reserved.
+%% Copyright (C) 1989-2022 Frank Mittelbach, all rights reserved.
 %
 %
 % Version:     Date:     Changes:
@@ -128,18 +138,104 @@
 % \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
 % \DoNotIndex{\bfdefault}
 %
-% \MakeShortVerb{\"}
+% \MakeShortVerb{\|}
 % \setcounter{StandardModuleDepth}{1}
 %
 % {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print
-% \gdef\dimenvalue#1pt{$#1$pt}}  ^^A register values with a - sign
+% \gdef\dimenvalue#1pt{$#1$pt}}  ^^A 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 comands\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}
 %
-% \newcommand{\DOC}{\texttt{doc}}
 %
 % \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}}
 % \GetFileInfo{doc.sty}
 %
-% \CheckSum{2213}  ^^A % keep the checksum in this file
+% \CheckSum{0}  ^^A % keep the checksum in this file but not now :-)
 %
 % \title{The \DOC{} and \texttt{shortvrb} Packages\thanks
 %    {This file has version number \fileversion{} dated \filedate{}.}}
@@ -149,190 +245,77 @@
 %        provided by Andrew Mills; fairly substantial additions,
 %        particularly from \texttt{newdoc},  and
 %        documentation of post-v1.5q features added at v1.7a by Dave
-%        Love (SERC Daresbury Lab). Extraction of \texttt{shortvrb}
-%        package added by Joachim Schrod (TU~Darmstadt).}}
+%        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}
-%    This package contains the definitions that are necessary to
-%    format the documentation of package files.  The package was
-%    developed in Mainz in cooperation with the Royal Military College
-%    of Science.  This is an update which documents various changes
-%    and new features in \DOC{} and integrates the features of
-%    \textsf{newdoc}.
+%    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 be 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}
 %
-% \newif\ifmulticols
-% \IfFileExists{multicol.sty}{\multicolstrue}{}
 %
-% \ifmulticols
+% \newpage
+%
 % \addtocontents{toc}{\protect\begin{multicols}{2}}
-% \fi
 %
-% {\parskip 0pt                ^^A We have to reset \parskip
+% ^^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}
 %
-% \ifmulticols
-% \begin{multicols}{2}[\section*{Preface to version 1.7}]
-% \else \section*{Preface to version 1.7} \fi
-%
-% This version of \texttt{doc.dtx} documents changes which have occurred
-% since the last published version \cite{art:doc} but which have been
-% present in distributed versions of \texttt{doc.sty} for some time.  It
-% also integrates the (undocumented) features of the distributed
-% \texttt{newdoc.sty}.
-%
-% The following changes and additions have been made to the user
-% interface since the published version~\cite{art:doc}.  See
-% \S\ref{sec:interface} for more details.
-% \begin{description}
-% \item[Driver mechanism] "\DocInput" is now used in the driver file
-%    to input possibly multiple independent \DOC{} files and \DOC{} no
-%    longer has to be the last package.  "\IndexListing" is replaced
-%    by "\IndexInput";
-% \item[Indexing] is controlled by "\PageIndex" and "\CodelineIndex",
-%    one of which must be specified to produce an index---there is no
-%    longer a "\makeindex" in the default "\DocstyleParms";
-% \item[The \texttt{macro} environment] now takes as argument the
-%    macro name {\em with\/} the backslash;
-% \item[Verbatim text] Newlines are now forbidden inside "\verb" and
-%    commands "\MakeShortVerb" and "\DeleteShortVerb" are provided for
-%    verbatim shorthand;
-% \item[\texttt{\bslash par}] can now be used in "\DoNotIndex";
-% \item[Checksum/character table support] for ensuring the integrity
-%    of distributions is added;
-% \item[\texttt{\bslash printindex}] becomes "\PrintIndex";
-% \item[\texttt{multicol.sty}] is no longer necessary to use \DOC{} or
-%    print the documentation (although it is recommended);
-% \item[`Docstrip' modules] are recognised and formatted specially.
-% \end{description}
-%
-% As well as adding some completely new stuff,
-% the opportunity has been taken to add some commentary to the code
-% formerly in \texttt{newdoc.sty} and that added after version 1.5k of
-% \texttt{doc.sty}.  Since (as noted in the sections concerned) this
-% commentary wasn't written by Frank Mittelbach but the code was, it is
-% probably {\em not\/} true in this case that ``if the code and
-% comments disagree both are probably wrong''!
 %
-% \subsection*{Bugs}
 %
-% There are some known bugs in this version:
-% \begin{itemize}
-% \item The "\DoNotIndex" command doesn't work for some single
-%    character commands most noticeable "\%".
-% \item The `General changes' glossary entry would come out after
-%    macro names with a leading "!" and possibly a leading |"|;
-% \item If you have an old version of \textsf{makeindex} long "\changes"
-%    entries will come out strangely and you may find the section
-%    header amalgamated with the first changes entry.  Try to get an
-%    up-to-date one (see p.~\pageref{makeindex:version});
-% \item Because the accompanying \textsf{makeindex} style files support
-%    the inconsistent attribute specifications of older and newer
-%    versions \textsf{makeindex} always complains about three `unknown
-%    specifier's when sorting the index and changes entries.
-% \item If "\MakeShortVerb" and "\DeleteShortVerb" are used with
-%    single character arguments, e.g., "{|}" instead of "{\|}" chaos
-%    may happen.
-% \end{itemize}
-% (Some `features' are documented below.)
-%
-% \subsection*{Wish list}
-%
-% \begin{itemize}
-% \item Hooks to allow "\DescribeMacro" and "\DescribeEnv" to write
-% out to a special file information about the package's `exported'
-% definitions which they describe.  This could subsequently be
-% included in the \texttt{docstrip}ped \texttt{.sty} file in a
-% suitable form for use by smart editors in command completion,
-% spelling checking etc., based on the packages used in a document.
-% This would need agreement on a `suitable form'.  \item Indexing of
-% the modules used in \texttt{docstrip}'s "%<" directives.  I'm not
-% sure how to index directives containing module combinations; \item
-% Writing out bibliographic information about the package; \item Allow
-% turning off use of the special font for, say, the next guarded
-% block.
-% \end{itemize}
-%
-% \ifmulticols
-% \end{multicols}
-%
-% \begin{multicols}{2}[\medskip \rule{\textwidth}{.3pt}
-%                      \section{Introduction}]
-% \else
 % \section{Introduction}
-% \fi
-%
-% The \TeX{} macros which are described here allow definitions and
-% documentation to be held in one and the same file.  This has the
-% advantage that normally very complicated instructions are made
-% simpler to understand by comments inside the definition. In addition
-% to this, updates are easier and only one source file needs to be
-% changed.  On the other hand, because of this, the package files are
-% considerably longer: thus \TeX{} takes longer to load them.  If this
-% is a problem, there is an easy remedy: one needs only to run the
-% \texttt{docstrip.tex} program that removes nearly all lines that begin
-% with a
-% percent sign.
 %
-% The idea of integrated documentation was born with the development
-% of the \TeX{} program; it was crystallized in Pascal with the \Web{}
-% system.  The advantages of this method are plain to see (it's easy
-% to make comparisons \cite{art:Knuthliterat}).  Since this
-% development, systems similar to \Web{} have been developed for other
-% programming languages. But for one of the most complicated
-% programming languages (\TeX) the documentation has however been
-% neglected.  The \TeX{} world seems to be divided between:---
-% \begin{itemize} \item a couple of ``wizards'', who produce many
-% lines of completely unreadable code ``off the cuff'', and \item many
-% users who are amazed that it works just how they want it to do.  Or
-% rather, who despair that certain macros refuse to do what is
-% expected of them.\end{itemize}
+% 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.
 %
-% 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.
+% 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.
 %
-% The method of documentation of \TeX{} macros which I have introduced
-% here should also only be taken as a first sketch.  It is designed
-% explicitly to run under \LaTeX{} alone.  Not because I was of the
-% opinion that this was the best starting point, but because from this
-% starting point it was the quickest to develop.\footnote{This
-% argument is a bad one, however, it is all too often trotted out.} As
-% a result of this design decision, I had to move away from the
-% concept of modularization; this was certainly a step backward.
-%
-% I would be happy if this article could spark off discussion over
-% \TeX\ documentation.  I can only advise anyone who thinks that they
-% can cope without documentation to ``Stop Time'' until he or she
-% completely understands the \AmSTeX{} source code.
-%
-%
-%
-%
-%
-% \subsection{Using the \DOC{} package}
-%
-% Just like any other package, invoke it by requesting it with a
-% |\usepackage| command in the preamble. \textsf{Doc}'s use of
-% |\reversemarginpars| may make it incompatible with some classes.
-% \changes{v1.7a}{1992/02/25}{Altered usage info}
-%
-%
-% \ifmulticols\end{multicols}\fi
+% 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}
@@ -342,36 +325,38 @@
 % package one has to prepare a special driver file which produces the
 % formatted document. This driver file has the following
 % characteristics:
-%
-% \noindent |\documentclass[|\meta{options}]^^A
-%           |{|\meta{document-class}|}|\\[1pt]
+% \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}|
-%
-% The \meta{document-class} might be any document class, I normally
+% \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|.
 %
-% \DescribeMacro\DocInput \DescribeMacro\IndexInput
-% Finally the \meta{special input commands} part should contain one or
-% more |\DocInput|\meta{file name} and/or
-% |\IndexInput|\meta{file name} commands.  The
+%
+% \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
+% |\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".
+% |\maketitle|.
 %
 % As an example, the driver file for the \DOC{} package itself is
-% the following text surrounded by "%<*driver>" and "%</driver>".
+% 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
@@ -379,7 +364,7 @@
 % the \texttt{docstrip} program.
 % The line numbers below are added by
 % \DOC{}'s formatting.
-% Note that the class \textsf{ltxdoc} has the \DOC{} package
+% Note that the class \cls{ltxdoc} has the \DOC{} package
 % preloaded.
 % \changes{v1.7a}{1992/03/06}{Added
 %                 docstrip-derivable driver file as example.}
@@ -387,20 +372,83 @@
 %    \begin{macrocode}
 %<*driver>
 \documentclass{ltxdoc}
+
+\usepackage[T1]{fontenc}
+\usepackage{xspace}          
+
+\OnlyDescription
+
 \EnableCrossrefs
- %\DisableCrossrefs % Say \DisableCrossrefs if index is ready
+ %\DisableCrossrefs     % Say \DisableCrossrefs if index is ready
 \CodelineIndex
-\RecordChanges                  % Gather update information
- %\OnlyDescription  % comment out for implementation details
- %\OldMakeindex     % use if your MakeIndex is pre-v2.9
-\setlength\hfuzz{15pt}  % dont make so many
-\hbadness=7000          % over and under full box warnings
+\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}
 %
@@ -413,10 +461,18 @@
 % \LaTeX{} commands except that the character `|%|' cannot be
 % used as a comment character.
 % \SortIndex{\string^\string^A}{\string\verb\verbatimchar
-% \string^\string^A\verbatimchar \encapchar usage} To allow user
-% comments, the |^^A| character is defined as a comment character
-% later on.  Such `metacomments' may be also be included simply by
-% surrounding them with "\iffalse" \ldots~"\fi".
+% \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
@@ -430,13 +486,17 @@
 % \DescribeEnv{macrocode}
 % On the other hand, if the documentation of these macros is to be
 % produced, the `definition parts' should be typeset verbatim. To
-% achieve this, these parts are surrounded by the \textsf{macrocode}
+% achieve this, these parts are surrounded by the \env{macrocode}
 % environment.
 % More exactly: before a `definition part' there should be a line
-% containing\\
-% \hspace*{\MacroIndent}\verb*+%    \begin{macrocode}+\\
-% and after this part a line\\
-% \hspace*{\MacroIndent}\verb*+%    \end{macrocode}+\\
+% 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'.
@@ -444,16 +504,16 @@
 % Inside a `definition part' all \TeX{} commands are allowed; even the
 % percent sign could be used to suppress unwanted spaces etc.
 %
-% \DescribeEnv{macrocode*} Instead of the \textsf{macrocode}
-% environment one can also use the \textsf{macrocode$*$} environment
+% \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 new macros}
+% \subsection{Describing the usage of macros and environments}
 %
-% \DescribeMacro\DescribeMacro
+% \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
@@ -461,35 +521,38 @@
 % |\DescribeMacro{\DescribeMacro}| to make clear that this is the
 % point where the usage of |\DescribeMacro| is explained.
 %
-% \DescribeMacro\DescribeEnv
-% An analogous macro |\DescribeEnv| should be used to indicate
-% that a \LaTeX{} environment is explained. It will produce a somewhat
-% different index entry. Below I used |\DescribeEnv{verbatim}|.
+% 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}|.
 %
-% \DescribeEnv{verbatim}
-% It is often a good idea to include examples of the usage of new macros
-% in the text. Because of the |%| sign in the first column of every
-% row, the \textsf{verbatim} environment is slightly altered to suppress
-% those
-% characters.\footnote{These macros were written by Rainer
-%                      Sch\"opf~\cite{art:verbatim}. He also
-%                      provided a new \textsf{verbatim} environment
-%                      which can be used inside of other macros.}
-% \DescribeEnv{verbatim*}
-% The \textsf{verbatim$*$} environment is changed in the same way.
-% \changes{v1.7a}{1992/02/26}{Documented \cs{verb} change.}
-% \DescribeMacro\verb
-% The "\verb" command is re-implemented to give an error report if a
-% newline appears in its argument.
-% The \textsf{verbatim} and \textsf{verbatim$*$} environments set text
-% in the style defined by "\MacroFont"~(\S\ref{sec:macrofont}).
 %
+% \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 new macros}
+% \subsection{Describing the definition of macros and environments}
 %
 % \DescribeEnv{macro}
-% To describe the definition of a new macro we use the \textsf{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
@@ -505,20 +568,26 @@
 % 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
+% |\mbox{}|---in this environment before |\begin{macrocode}| or the
 % marginal label won't print in the right place.
 %
-% \DescribeMacro\MacrocodeTopsep
-% \DescribeMacro\MacroTopsep
+% \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 \textsf{macrocode} and the \textsf{macro}
-% \DescribeMacro\MacroIndent
+% and below the \env{macrocode} and the \env{macro}
+% \DescribeLaTeXDimen\MacroIndent
 % environment, |\MacroIndent| is used to indent the lines of code
 % and
-% \DescribeMacro\MacroFont \label{sec:macrofont}
+% \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
+% 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|
@@ -526,17 +595,34 @@
 % be changed directly as long as the redefinition happens before
 % the |\begin{document}|.
 %
+% \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 the margins}
+% \subsection{Formatting names in the margin}
 %
-% \DescribeMacro\PrintDescribeMacro
-% \DescribeMacro\PrintDescribeEnv
-% \DescribeMacro\PrintMacroName
-% \DescribeMacro\PrintEnvName
-% As mentioned earlier, some macros and the \textsf{macro} environment
-% print their arguments in the margin. This is actually done by four
+% \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
@@ -544,33 +630,157 @@
 %                     file.
 %                     For example, if you don't like any names in the
 %                     margin
-%                     but want a fine index you can simply
-%                     \texttt{\bslash let}
-%                     these macros equal \texttt{\bslash @gobble}.
-%                     The doc package won't redefine any existing
-%                     definitions of these macros.}
-% They are named |\PrintDescribeMacro|, |\PrintDescribeEnv|,
-% |\PrintMacroName| (called by the \textsf{macro} environment) and
-% |\PrintEnvName| (called by the \textsf{environment} environment).
+%                     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.
+%
+% \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}
 %
-% \DescribeMacro\SpecialEscapechar
+% \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 \textsf{macrocode} environment and its counterpart
-% \textsf{macrocode$*$} produce an index entry for every occurrence of a
+% 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 "\|" for example to denote that `\verb+|+'
+% 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 \textsf{macrocode} or
-% \textsf{macrocode$*$} environment.
+% 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
@@ -582,20 +792,24 @@
 %
 % \subsection{Cross-referencing all macros used}
 %
-% \DescribeMacro\DisableCrossrefs \DescribeMacro\EnableCrossrefs As
-% already mentioned, every new macro name used within a
-% \textsf{macrocode} or \textsf{macrocode$*$} environment will produce
-% an index entry. In this way one can easily find out where a specific
-% macro is used.  Since \TeX{} is considerably slower when it has to
-% produce such a bulk of index entries one can turn off this feature
-% by using |\DisableCrossrefs| in the driver file. To turn it on again
-% just use |\EnableCrossrefs|.\footnote{Actually, \texttt{\bslash
-% EnableCrossrefs} changes things more drastically; any following
-% \texttt{\bslash DisableCrossrefs} which might be present in the
-% source will be ignored.}
-%
-%
-% \DescribeMacro\DoNotIndex
+% \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|
@@ -605,26 +819,28 @@
 %
 % All three above declarations are local to the current group.
 %
-% Production (or not) of the index (via the "\makeindex" commend) is
+% Production (or not) of the index (via the |\makeindex| commend) is
 % controlled by using or omitting the following declarations in the
 % driver file preamble; if neither is used, no index is produced.
-% \DescribeMacro\PageIndex Using "\PageIndex" makes all index
+% \DescribeInterfaceMacro\PageIndex Using |\PageIndex| makes all index
 % entries refer to their page number; with
-% \DescribeMacro\CodelineIndex "\CodelineIndex", index entries
-% produced by "\DescribeMacro" and "\DescribeEnv" refer to page number
-% but those produced by the \textsf{macro} environment refer to the
+% \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
-% \textsf{macrocode} environment in the \textsf{macro} environment.}
-% \DescribeMacro\theCodelineNo
+% \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
+% |\theCodelineNo|.  Its default definition is to use scriptsize
 % arabic numerals; a user-supplied definition won't be overwritten.
 %
-% \DescribeMacro\CodelineNumbered
+% \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.
+% numbered use |\CodelineNumbered| instead of |\CodelineIndex|. This
+% prevents the generation of an unnecessary |.idx| file.
 %
 %
 % \subsection{Producing the actual index entries}
@@ -632,7 +848,7 @@
 % Several of the aforementioned macros will produce some sort of index
 % entries. These entries have to be sorted by an external
 % program---the current implementation assumes that the
-% \textsf{makeindex} program by Chen~\cite{art:Chen} is used.
+% \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
@@ -644,25 +860,25 @@
 %
 %  To allow the user to change the specific characters recognized by
 %  his or her index program all characters which have special meaning
-%  in the \textsf{makeindex} program are given symbolic
+%  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).
 %
-% \DescribeMacro{\actualchar}
+% \DescribeInterfaceMacro{\actualchar}
 % The |\actualchar| is used to separate the `key' and the actual
 % index entry.
-% \DescribeMacro{\quotechar}
+% \DescribeInterfaceMacro{\quotechar}
 % The |\quotechar| is used before a special index program
 % character to suppress its special meaning.
-% \DescribeMacro{\encapchar}
+% \DescribeInterfaceMacro{\encapchar}
 %  The |\encapchar| separates the indexing information from a
-% letter string which \textsf{makeindex} uses as a \TeX{} command to
+% 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.
-% \DescribeMacro{\levelchar}
+% \DescribeInterfaceMacro{\levelchar}
 %  Additionally |\levelchar| is used to separate `item',
 % `subitem' and `subsubitem' entries.
 %
@@ -670,33 +886,54 @@
 % which index program is used. In this way your files will be
 % portable.
 %
-% \DescribeMacro\SpecialMainIndex
-% \DescribeMacro\SpecialMainEnvIndex
+% \fmi{describe old \cs{SpecialMainIndex} and \cs{SpecialUsageIndex}}
+%
+% \DescribeInterfaceMacro\SpecialMainMacroIndex
+% \DescribeInterfaceMacro\SpecialMainEnvIndex
 % To produce a main index entry for a macro the
-% |\SpecialMainIndex| macro\footnote{This macro is called by the
-% \textsf{macro} environment.} may be used.  It is called `special'
+% |\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
-% \textsf{environment} environment.}
-% \DescribeMacro\SpecialIndex
-% If you want a normal index entry for a macro name
-% |\SpecialIndex| might be used.\footnote{This macro is called
-% within the \textsf{macrocode} environment when encountering a macro
-% name.}
-% \DescribeMacro\SpecialUsageIndex
-% \DescribeMacro\SpecialEnvIndex
+% \env{environment} environment.}
+%
+% \DescribeInterfaceMacro\SpecialMacroIndex
+% \DescribeInterfaceMacro\SpecialEnvIndex
 % To index the usage of a macro or an environment
-% |\SpecialUsageIndex| and |\SpecialEnvIndex| may be used.
-% \DescribeMacro\SortIndex
-% Additionally a |\SortIndex| command is provided.  It takes two
-% arguments---the sort key and the actual index entry.
+% |\SpecialMacroIndex| and |\SpecialEnvIndex| may be used.
 %
 % All these macros are normally used by other macros; you will need
 % them only in an emergency.
 %
-% \DescribeMacro\verbatimchar
+% \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.
@@ -704,12 +941,14 @@
 % referenced indirectly, by the macro |\verbatimchar|. It expands
 % by default to \verb?+?  but if your code lines contain macros with
 % `\texttt{+}' characters in their names (e.g.\ when you use \verb?\+?)
-% you will end up with an index entry containing \verb?\verb+\++?
-% which will be typeset as `\verb+\++' and not as `\verb?\+?'. In this
-% case you should redefine |\verbatimchar| globally or locally to
-% overcome this problem.
-%
-% \DescribeMacro\*
+% 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}
@@ -721,49 +960,39 @@
 %   \index{index entries\levelchar Special macros for \*}
 %\end{verbatim}
 %
-% \DescribeMacro\OldMakeindex
-% Versions of \textsf{makeindex} prior to 2.9 had some bugs affecting
-% \DOC{}.  One of these,
-% pertaining to the "%" character doesn't have a work-around
-% appropriate for versions with and without the
-% bug.\label{makeindex:version}  If
-% you have an old version, invoke "\OldMakeindex" in a
-% package file or the driver file to prevent problems with index entries
-% such as "\%", although you'll probably normally want to turn off
-% indexing of "\%" anyway.  Try to get an up-to-date \textsf{makeindex}
-% from one of the \TeX{} repositories.
-%
 %
 % \subsection{Setting the index entries}
 %
 % \changes{v1.7a}{1992/03/11}{Usage note on gind.ist.} After the first
 % formatting pass through the \texttt{.dtx} file you need to sort the
 % index entries written to the \texttt{.idx} file using
-% \textsf{makeindex} or your favourite alternative.  You need a
-% suitable style file for \textsf{makeindex} (specified by the
+% \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}.
 %
-% \DescribeMacro\PrintIndex
+% \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
-% amongt the arguments of the |\StopEventually| macro, in
+% 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. This is controlled by the \LaTeX{} counter
+% 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 \textsf{theindex}
+% start a new page unnecessarily.  Therefore the \env{theindex}
 % environment is redefined.
-% \DescribeMacro\IndexMin
-% When the \textsf{theindex} environment starts it will measure how much
+% \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.
@@ -771,23 +1000,23 @@
 % Then a short introduction about the meaning of several index entries
 % is typeset (still in onecolumn mode). Afterwards the actual index
 % entries follow in multi-column mode.
-% \DescribeMacro\IndexPrologue
+% \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 \textsf{theindex} environment is finished the last page will
+% 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.
-% \DescribeMacro\IndexParms
+% \DescribeInterfaceMacro\IndexParms
 % Formatting of the index columns (values for |\columnssep|
 % etc.)\ is controlled by the |\IndexParms| macro. It assigns the
 % following values:
-% \SpecialUsageIndex{\parindent}\SpecialUsageIndex{\columnsep}^^A
-% \SpecialUsageIndex{\parskip}\SpecialUsageIndex{\rightskip}^^A
-% \SpecialUsageIndex{\mathsurround}\SpecialUsageIndex{\parfillskip}
+% \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    &
@@ -800,24 +1029,27 @@
 %                         \expandafter\dimenvalue\the\parfillskip
 %  \end{tabular}
 % \end{center}
-% \DescribeMacro{\@idxitem}
+% \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.
 %
-% \DescribeMacro\main
-% \DescribeMacro\usage
+% \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 {\em italics}). As usual these commands are user
+% (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}
 %
-% \DescribeMacro\DocstyleParms If you want to overwrite some default
+% \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
@@ -828,10 +1060,13 @@
 %
 % The doc package currently assigns values to the following
 % registers:
-% \SpecialUsageIndex{\IndexMin}\SpecialUsageIndex{\MacrocodeTopsep}^^A
-% \SpecialUsageIndex{\MacroTopsep}^^A
-% \SpecialUsageIndex{\MacroIndent}\SpecialUsageIndex{\marginparpush}^^A
-% \SpecialUsageIndex{\marginparwidth}\SpecialUsageIndex{\tolerance}
+% \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    &
@@ -847,34 +1082,34 @@
 %
 % \subsection{Short input of verbatim text pieces}
 %
-% \DescribeMacro\MakeShortVerb
-% \DescribeMacro{\MakeShortVerb*} \DescribeMacro\DeleteShortVerb It is
-% awkward to have to type, say, "\verb|"\ldots"|" continually when
+% \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 "|" if you have |"| active to do
+% (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
+% |\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
+% |\verb|\meta{c}\meta{text}\meta{c};  analogously, the |*|-form
+% |\MakeShortVerb*{\|\meta{c}|}| gives you the equivalent of
+% |\verb*|\meta{c}\meta{text}\meta{c}.  Use
+% |\DeleteShortVerb{\|\meta{c}|}| if you subsequently want \meta{c} to
 % revert to its previous meaning---you can always turn it on again
 % after the unusual section.  The `short verb' commands make global
-% changes.  The abbreviated "\verb" may not appear in the argument of
-% another command just like "\verb".  However the `short verb'
-% character may be used freely in the \textsf{verbatim} and
-% \textsf{macrocode} environments without ill effect.
-% "\DeleteShortVerb" is silently ignored if its argument does not
+% 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"
+% 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}.
@@ -885,24 +1120,33 @@
 % 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 the \LaTeX{} format.
+% \LaTeX{} and \TeX{} are already defined in \texttt{latex.tex}.
 %
-% \DescribeMacro\meta
+% \DescribeInterfaceMacro\meta
 % Another useful macro is |\meta| which has one argument and
 % produces something like \meta{dimen parameter}.
 %
-% \DescribeMacro\OnlyDescription
-% \DescribeMacro\StopEventually
+% \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
-% you have to place the command |\StopEventually| at a suitable
-% point in your file.  This macro has one argument in which you put
+% \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 |\StopEventually|
-% \DescribeMacro\Finale
+% 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.
@@ -910,17 +1154,17 @@
 % Thus you can use this feature to produce a local guide for the
 % \TeX{} users which describes only the usage of macros (most of them
 % won't be interested in your definitions anyway).  For the same
-% reason the |\maketitle| \DescribeMacro\maketitle command is slightly
+% 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.
-% \DescribeMacro{\ps@titlepage} To avoid an unwanted
+% \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 \textsf{ltugboat.cls} to
+% undefined.  This allows class files like \cls{ltugboat.cls} to
 % define their own page styles for title pages.
 %
-% \DescribeMacro\AlsoImplementation
+% \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
@@ -933,24 +1177,23 @@
 % \end{quote}
 % to make sure that all documents will show the code part.
 %
-% \DescribeMacro\IndexInput \label{..Input} Last but not least I
+% \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} (these days
-% called \texttt{latex.ltx}) getting a verbatim
+% feature to cross-reference \texttt{latex.tex} getting a verbatim
 % copy with about 15 pages index.\footnote{It took quite a long time
 % and the resulting \texttt{.idx} file was longer than the
 % \texttt{.dvi} file.  Actually too long to be handled by the
-% \textsf{makeindex} program directly (on our MicroVAX) but the final
+% \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.}
-% \DescribeMacro\changes
+% \DescribeInterfaceMacro\changes
 % To maintain a change history within the file, the |\changes|
-% command may be placed amongt the description part of the changed
+% 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
@@ -960,7 +1203,7 @@
 % |\glossary| mechanism is used for this) which may be printed
 % after suitable formatting. The |\changes| macro generates the
 % printed entry in such a change history; because old
-% versions\footnote{Before 2.6.} of the \textsf{makeindex}
+% 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
@@ -970,101 +1213,38 @@
 % text |\generalname| is used instead of the macro name.  When
 % referring to macros in change descriptions it is conventional to use
 % |\cs{|\meta{macroname}|}| rather than attempting to format it properly
-% and using up valuable characters in the entry with old \textsf{makeindex}
+% and using up valuable characters in the entry with old \prg{makeindex}
 % versions.
 %
 % \changes{v1.7a}{1992/02/26}{Description of \cs{RecordChanges} etc.
 % added
-% to interface section.} \DescribeMacro\RecordChanges To cause the
-% change information to be written out, include "\RecordChanges" in
-% the driver file.  \DescribeMacro\PrintChanges To read in and print
+% 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 |\StopEventually| command, although a change
+% 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 \textsf{makeindex} or some
+% 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 \textsf{makeindex}
+% sorted \texttt{.gls} file.  You need a special \prg{makeindex}
 % style file; a suitable one is supplied with \DOC{}, called
-% \texttt{gglo.ist}.  \DescribeMacro\GlossaryMin
-% \DescribeMacro\GlossaryPrologue \DescribeMacro\GlossaryParms The
-% "\GlossaryMin", "\GlossaryPrologue" and "\GlossaryParms" macros are
-% analogous to the "\Index"\ldots\ versions.  (The \LaTeX{} `glossary'
+% \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.)
 %
-% \label{sec:checksum}
-% \DescribeMacro\CharacterTable
-% \DescribeMacro\CheckSum
-% To overcome some of the problems of sending files over the networks
-% we developed two macros which should detect corrupted files. If one
-% places the lines
-% \begin{flushleft}
-% \small\ttfamily        ^^A \ttfamily to get the blanks between "..."s
-%                        ^^A right
-%"%%\CharacterTable"\\
-%"%% {Upper-case   "
-%"\A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z"\\
-%"%%  Lower-case   "
-%"\a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z"\\
-%"%%  Digits        \0\1\2\3\4\5\6\7\8\9"\\
-%"%%  Exclamation   \!     Double quote  "\verb=\"=
-%"    Hash (number) \#"\\
-%"%%  Dollar        \$     Percent       \%     Ampersand     \&"\\
-%"%%  Acute accent  \'     Left paren    \(     Right paren   \)"\\
-%"%%  Asterisk      \*     Plus          \+     Comma         \,"\\
-%"%%  Minus         \-     Point         \.     Solidus       \/"\\
-%"%%  Colon         \:     Semicolon     \;     Less than     \<"\\
-%"%%  Equals        \=     Greater than  \>     Question mark \?"\\
-%"%%  Commercial at \@     Left bracket  \[     Backslash     \\"\\
-%"%%  Right bracket \]     Circumflex    \^     Underscore    \_"\\
-%"%%  Grave accent  \`     Left brace    \{     Vertical bar  \|"\\
-%"%%  Right brace   \}     Tilde         \~}"\\
-%"%%"
-%\end{flushleft}
-% at the beginning of the file then character translation failures
-% will be detected, provided of course, that the used \DOC{}
-% package has a correct default table.  The percent
-% signs\footnote{There are two percent signs in each line. This has
-% the effect that these lines are not removed by the
-% \texttt{docstrip.tex} program.} at the beginning of the lines should
-% be typed in, since only the \DOC{} package should look at this
-% command.
-%
-%
-% Another problem of mailing files is possible truncation.  To detect
-% these sort of errors we provide a |\CheckSum| macro.  The check-sum
-% of a file is simply the number of backslashes in the code, i.e.\ all
-% lines between the \textsf{macrocode} environments.  But don't be
-% afraid: you don't have count the code-lines yourself; this is done
-% by the \DOC{} package for you.  You simply have add
-% \begin{quote}
-%    |%   \CheckSum{0}|
-% \end{quote}
-% near the beginning of the file and
-% use
-% the |\StopEventually| (which starts looking for backslashes) and the
-% |\Finale| command.  The latter will inform you either that your file
-% has no check-sum (telling you the right number) or that your number
-% is incorrect 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.
 %
-%
-% \DescribeMacro\bslash
+% \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
@@ -1072,53 +1252,55 @@
 % |\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|
+% $|\|_{12}$.  This means that you have to |\protect|
 % it if it is used in `moving arguments'.
 %
-% \DescribeMacro\MakePrivateLetters
+% \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
+% 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".
+% default definition is just |\makeatletter|.
 %
-% \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules
-% \DescribeMacro\Module \DescribeMacro\AltMacroFont The `module'
-% directives of the \textsf{docstrip} system \cite{art:docstrip} are
-% normally recognised and invoke special formatting.  This can be
+% \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
+% |\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
+% 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
+% line beginning with |%<| or is between lines starting with
+% |%<*|\meta{name list}|>| and |%</|\meta{name list}|>|.  The
+% directive is formatted by the macro |\Module| whose single argument
 % is the text of the directive between, but not including, the angle
 % brackets; this macro may be re-defined in the driver or package file
 % and by default produces results like \Module{+foo\string|bar} with no
 % following space.
 %
-% \DescribeMacro{StandardModuleDepth} Sometimes (as in this file) the
+% \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
+% 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
+% |\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.}
@@ -1126,26 +1308,482 @@
 % To sum up, the basic structure of a \texttt{.dtx} file without any
 % refinements is like this:
 % \begin{verse}\small
-% "% "\meta{waffle}\ldots\\
+% |% |\meta{waffle}\ldots\\
 % \quad\ldots \\
-% "% \DescribeMacro{\fred}"\\
-% "% "\meta{description of fred's use}\\
+% |% \DescribeMacro{\fred}|\\
+% |% |\meta{description of fred's use}\\
 % \quad\ldots\\
-% "% \StopEventually{"\meta{finale code}"}"\\
+% |% \MaybeStop{|\meta{finale code}|}|\\
 % \quad\ldots\\
-% "% \begin{macro}{\fred}"\\
-% "% "\meta{commentary on macro fred}\\
+% |% \begin{macro}{\fred}|\\
+% |% |\meta{commentary on macro fred}\\
 % \verb*+%    \begin{macrocode}+\\
 % \meta{code for macro fred}\\
 % \verb*+%    \end{macrocode}+\\
-% "% \end{macro}"\\
+% |% \end{macro}|\\
 % \quad\ldots\\
-% "% \Finale \PrintIndex \PrintChanges"
+% |% \Finale \PrintIndex \PrintChanges|
 % \end{verse}
-% For examples of the use of most---if not all---of the features
-% described above consult the \texttt{doc.dtx} source itself.
+% 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.
 %
-% \subsection{Acknowledgements}
+% 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 comands\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
@@ -1158,14 +1796,14 @@
 % \texttt{doc.dtx} after its publication in \textsl{TUGboat\/} have
 % been never properly described. Beside this splendid work he kindly
 % provided additional code (like ``docstrip'' module formatting) which
-% I think every \textsf{doc.dtx} user will be grateful for.
+% I think every \DOC user will be grateful for.
 %
 %
-% \StopEventually{
+% \MaybeStop{
 %  \begin{thebibliography}{1}
 %    \bibitem{book:Buerger}  \textsc{G. A. B\"urger}.
-%      \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldz\"uge
-%                und lustige Abenteuer des Freyherrn v.\ M\"unchhausen.
+%      \newblock 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.
@@ -1189,20 +1827,20 @@
 %      \newblock \texttt{docstrip.dtx} (to appear).
 %      \newblock The file is part of the DOC package.
 %    \bibitem{book:Raspe} \textsc{R. E. Raspe} (*1737, \dag 1797).
-%      \newblock Baron M\"unchhausens narrative of his marvellous
+%      \newblock Baron Münchhausens narrative of his marvelous
 %                travels and campaigns in Russia.
 %      \newblock Oxford, 1785.
-%    \bibitem{art:verbatim} \textsc{Rainer Sch\"opf}.
+%    \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}
 %
-%  \ifmulticols
 %  \addtocontents{toc}{\protect\end{multicols}}
-%  \fi
 %
-% } ^^A end \StopEventually
+%  \PrintIndex
+%
+% } ^^A end \MaybeStop
 %
 %
 % \section{The Description of Macros}
@@ -1228,50 +1866,211 @@
 \@ifundefined{macro@cnt}{}{\endinput}
 %    \end{macrocode}
 %
-% \DescribeMacro\fileversion
-% \DescribeMacro\filedate
-% \DescribeMacro\docdate
+% \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 \textsf{macrocode}
+% 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 a new comment
-% sign.  Because all sensible signs are already occupied, we will
-% choose one that can only be entered indirectly:
+% 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}
+\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{Options supported by \DOC{}}
+% \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}
+%
+%    \begin{macrocode}
+\ExplSyntaxOn
+%    \end{macrocode}
+% Some keys are available as options for use in \cs{usepackage} some are
+% for the generated item \api's:
+% \fmi{cleanup documentation (and code once the new key interface is there)}
+%    \begin{macrocode}
+\newif \ifdoc@noprint
+\newif \ifdoc@noindex
+\newif \ifdoc@hyperref \doc@hyperreftrue
+\newif \ifdoc@multicol \doc@multicoltrue
+\newif \ifdoc@debugshow
+\newif \ifdoc@reportchangedates
+\keys_define:nn {doc}
+  {
+    noprint  .choice:,
+    noprint / true  .code:n = { \legacy_if_set_true:n  { doc@noprint } },
+    noprint / false .code:n = { \legacy_if_set_false:n { doc@noprint } },
+    noprint  .default:n = { true },
+    noindex  .choice:,
+    noindex / true  .code:n = { \legacy_if_set_true:n  { doc@noindex } },
+    noindex / false .code:n = { \legacy_if_set_false:n { doc@noindex } },
+    noindex  .default:n = { true },
+    hyperref  .choice:,
+    hyperref / true  .code:n = { \legacy_if_set_true:n  { doc@hyperref } },
+    hyperref / false .code:n = { \legacy_if_set_false:n { doc@hyperref } },
+    hyperref  .default:n = { true },
+%    \end{macrocode}
+% \changes{v3.0h}{2022/06/01}{fix choice key name (gh/750)}
+%    \begin{macrocode}
+    nohyperref  .choice:,
+    nohyperref / true  .code:n = { \legacy_if_set_false:n  { doc@hyperref } },
+    nohyperref / false .code:n = { \legacy_if_set_true:n { doc@hyperref } },
+    nohyperref  .default:n = { true },
+    multicol  .choice:,
+    multicol / true  .code:n = { \legacy_if_set_true:n  { doc@multicol } },
+    multicol / false .code:n = { \legacy_if_set_false:n { doc@multicol } },
+    multicol  .default:n = { true },
+    nomulticol  .choice:,
+    nomulticol / true  .code:n = { \legacy_if_set_false:n  { doc@multicol } },
+    nomulticol / false .code:n = { \legacy_if_set_true:n { doc@multicol } },
+%    \end{macrocode}
+% \changes{v3.0h}{2022/06/01}{fix default key name (gh/750)}
+%    \begin{macrocode}
+    nomulticol  .default:n = { true },
+    debugshow  .choice:,
+    debugshow / true  .code:n = { \legacy_if_set_true:n  { doc@debugshow } },
+    debugshow / false .code:n = { \legacy_if_set_false:n { doc@debugshow } },
+    debugshow  .default:n = { true },
+    reportchangedates  .choice:,
+    reportchangedates / true  .code:n = { \legacy_if_set_true:n  { doc@reportchangedates } },
+    reportchangedates / false .code:n = { \legacy_if_set_false:n { doc@reportchangedates } },
+    reportchangedates  .default:n = { true },
+  }
+%    \end{macrocode}
+% This one is for \cs{usepackage} and \cs{NewDocElement}:
+%    \begin{macrocode}
+\newif \ifdoc@toplevel \doc@topleveltrue
+\keys_define:nn {doc}
+  {
+    toplevel  .choice:,
+    toplevel / true  .code:n = { \legacy_if_set_true:n  { doc@toplevel } },
+    toplevel / false .code:n = { \legacy_if_set_false:n { doc@toplevel } },
+    toplevel  .default:n = { true },
+    notoplevel  .choice:,
+    notoplevel / true  .code:n = { \legacy_if_set_false:n  { doc@toplevel } },
+    notoplevel / false .code:n = { \legacy_if_set_true:n { doc@toplevel } },
+    notoplevel  .default:n = { true }
+  }
+%    \end{macrocode}
+% These are for \cs{NewDocElement}:
+%    \begin{macrocode}
+\newif \ifdoc@macrolike
+\keys_define:nn {doc}
+  {
+    macrolike  .choice:,
+    macrolike / true  .code:n = { \legacy_if_set_true:n  { doc@macrolike } },
+    macrolike / false .code:n = { \legacy_if_set_false:n { doc@macrolike } },
+    macrolike  .default:n = { true },
+    envlike  .choice:,
+    envlike / true  .code:n = { \legacy_if_set_false:n  { doc@macrolike } },
+    envlike / false .code:n = { \legacy_if_set_true:n { doc@macrolike } },
+    envlike  .default:n = { true }
+  }
+
+\keys_define:nn { doc }
+  {
+    idxtype  .tl_set:N = \doc@idxtype,
+    idxgroup .tl_set:N = \doc@idxgroup,
+    printtype .tl_set:N = \doc@printtype
+  }
+%    \end{macrocode}
+% And this one only for instances of doc elements in the document, it
+%    covers the case where you want to document a macro which is
+%    declared to be \cs{outer}. This is not a concept officially
+%    supported by \LaTeX{} but there are cases when it gets used.
+%    \begin{macrocode}
+\newif\ifdoc@outer
+\keys_define:nn {doc}
+  {
+    outer  .choice:,
+    outer / true  .code:n = { \legacy_if_set_true:n  { doc@outer } },
+    outer / false .code:n = { \legacy_if_set_false:n { doc@outer } },
+    outer  .default:n = { true },
+  }
+\ExplSyntaxOff
+%    \end{macrocode}
+%
+% \subsection{Processing the package keys}
+%
+%    \begin{macrocode}
+\ProcessKeyOptions
+%    \end{macrocode}
 %
-%   Not options available at the moment
 %
+% \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 \textsf{macrocode}.  Put more precisely, they will be
+%    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.
@@ -1307,7 +2106,7 @@
 %    \begin{macrocode}
 \def\macro@code{%
 %    \end{macrocode}
-%    In theory it should consist of a \textsf{trivlist} environment, but
+%    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}
@@ -1384,7 +2183,7 @@
 % 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".
+% appropriately if so using |\check@module|.
 %    \begin{macrocode}
    \global\@newlistfalse
    \global\@minipagefalse
@@ -1408,9 +2207,9 @@
 % \begin{macro}{\blank@linetrue}
 % \begin{macro}{\blank@linefalse}
 %    |\ifblank@line| is the switch used in the definition above.
-%    In the original \textsf{verbatim} environment the |\if@tempswa|
+%    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 \textsf{macrocode} environment.
+%    while processing lines in the \env{macrocode} environment.
 %    \begin{macrocode}
 \newif\ifblank@line
 %    \end{macrocode}
@@ -1419,10 +2218,10 @@
 % \end{macro}
 %
 % \begin{macro}{\endmacrocode}
-%    Because we have begun a \textsf{trivlist} environment in the
-%    \textsf{macrocode} environment, we must also end it.  We must
-%    also act on the value of the "pm@module" flag (see below) and
-%    empty "\everypar".
+%    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{%
@@ -1439,7 +2238,7 @@
 % \end{macro}
 %
 %
-% \begin{macro}{\MacroFont}
+% \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
@@ -1459,7 +2258,7 @@
 %    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
+% \changes{v2.1l}{2019/12/16}{Use \cs{shapedefault} not
 %    \cs{updefault} for extended NFSS}
 %    \begin{macrocode}
     \def\MacroFont{\small
@@ -1477,9 +2276,9 @@
   \fi
   }{}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
-% \begin{macro}{\AltMacroFont}
+% \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.}
@@ -1487,9 +2286,9 @@
 % \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
+% 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}{%
@@ -1514,8 +2313,8 @@
  \fi
   }{}
 %    \end{macrocode}
-%    To allow changing the "\MacroFont" in the preamble we defer
-%    defining the internally used "\macro@font" until after the
+%    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}
@@ -1523,23 +2322,23 @@
 \AtBeginDocument{\let\macro@font\MacroFont}
 %    \end{macrocode}
 % \end{macro}
-% \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
+% 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
+% 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 "/"
+% 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"
+% 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
+% 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.
@@ -1553,25 +2352,27 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
-% \begin{macro}{\DontCheckModules}
-% \begin{macro}{\CheckModules}
+% \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.
+% checking on and off using the |check@modules| switch.
 %    \begin{macrocode}
 \def\DontCheckModules{\check@modulesfalse}
 \def\CheckModules{\check@modulestrue}
 \newif\ifcheck@modules  \check@modulestrue
 %    \end{macrocode}
 % \end{macro}
-% \end{macro}
-% \end{macro}
+% \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".
+% 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
@@ -1582,7 +2383,7 @@
 %
 % \begin{macro}{\check@angle}
 % \changes{v1.7a}{1992/03/12}{Added.}
-% Before looking ahead for the "<" the "%" is gobbled by the
+% Before looking ahead for the |<| the |%| is gobbled by the
 % argument here.
 %    \begin{macrocode}
 \def\check@angle#1{\futurelet\next\ch@angle}
@@ -1591,9 +2392,9 @@
 % \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{}
+%    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
@@ -1644,13 +2445,13 @@
 % \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
+% 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}
+% 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
+% |\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.}
@@ -1663,8 +2464,8 @@
    \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 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
@@ -1706,8 +2507,7 @@
 % \end{macro}
 % \end{macro}
 %
-%
-%  \begin{macro}{\c@StandardModuleDepth}
+%  \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
@@ -1716,38 +2516,39 @@
 %    \begin{macrocode}
 \newcounter{StandardModuleDepth}
 %    \end{macrocode}
-%  \end{macro}
+%  \end{lcounter}
 %
 %
-% \begin{macro}{\guard@level}
+% \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{macro}
+% \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 "|" will print as an em-dash.)  This is done
+% $\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.
+% 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
+%    |\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
+%    |normal|.  (We need to know in what font to set the other
 %    groups.)  This uses a new math alphabet rather than version and
 %    consequently has to worry about whether we're using
-%    \textsf{oldlfnt} or not.  I expect there's a better
+%    \env{oldlfnt} or not.  I expect there's a better
 % way\ldots
 %    \begin{macrocode}
       \def\Module#1{\mod@math@codes$\langle\mathsf{#1}\rangle$}
@@ -1759,11 +2560,11 @@
 % \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 "*/+-,&|!()"
-%    for the current version of \textsf{docstrip}.  We only need
+%    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: "|" is changed to a "\mathop" (it's normally |"026A|) and
-%    "&" is also made a "\mathop", but in family 0.  Remember that "&"
+%    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
@@ -1772,27 +2573,9 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\mathsf}
-% \changes{v1.7c}{1992/03/26}{Added.}
-% \changes{v1.7d}{1992/04/25}{Use sans font for modules.}
-% \changes{v1.7n}{1993/02/21}{\cs{sfmath} Renamed to \cs{mathsf}.}
-% \changes{v1.8c}{1993/10/25}{NFSS standard}
-% If NFSS is in use we need a new math alphabet which uses a sans serif
-% font. To support both the release one and two of NFSS the alphabet
-% was renamed to "\mathsf" which is defined in NFSS2.
-%    \begin{macrocode}
-%\ifx\selectfont\undefined
-%\else
-%  \ifx\mathsf\undefined
-%    \newmathalphabet*{\mathsf}{\sfdefault}{m}{n}\fi
-%\fi
-%    \end{macrocode}
-% \end{macro}
 %
-%
-%
-% \begin{macro}{\MacrocodeTopsep}
-% \begin{macro}{\MacroIndent}
+% \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.
@@ -1805,22 +2588,22 @@
 \newdimen\MacroIndent
 \settowidth\MacroIndent{\rmfamily\scriptsize 00\ }
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{ldimen}
+% \end{lskip}
 %
 %
 %
 %
 % \begin{environment}{macrocode*}
 % \begin{macro}{\endmacrocode*}
-%    Just as in the \textsf{verbatim} environment, there is also a
-%    `star' variant of the \textsf{macrocode} environment in which a
+%    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\"unchhausens
+%    occasion {\em here\/} that you can't use it (cf.\ Münchhausens
 %    Marsh problem)\footnote{Karl Friedrich Hieronymus Frhr.\ v.\
-%    M\"unchhausen (*1720, \dag1797).  Several books were written
+%    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.}
@@ -1865,7 +2648,7 @@
 %    \end{macrocode*}
 %    Additionally, we need to ensure that the symbols in the above
 %    string contain the |\catcode|$\,$s which are available
-%    within the \textsf{macrocode} environment.
+%    within the \env{macrocode} environment.
 %    \begin{macrocode*}
 \catcode`\{=12 \catcode`\}=12
 \catcode`\%=12 \catcode`\ =\active \catcode`\\=\active
@@ -1908,65 +2691,7 @@
 % \subsection{Macros for the `documentation parts'}
 %
 %
-% \begin{macro}{\DescribeMacro}
-% \begin{macro}{\Describe@Macro}
-% \changes{v1.5v}{1990/01/28}{Macro added.}
-% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary
-%                             fix}
-% \begin{macro}{\DescribeEnv}
-% \begin{macro}{\Describe@Env}
-% \changes{v1.5v}{1990/01/28}{Macro added.}
-% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary
-%                             fix}
-%    The |\DescribeMacro| and |\DescribeEnv| macros should
-%    print their arguments in the margin and produce an index entry.
-%    We simply use |\marginpar| to get the desired result. This
-%    is however not the best solution because the labels might be
-%    slightly misplaced. One also might get a lot of `marginpar moved'
-%    messages which are hard-wired into the \LaTeX{} output
-%    routine.\footnote{It might be better to change these macros into
-%    environments like the \textsf{macro} environment.} First we change
-%    to horizontal mode if necessary. The \LaTeX{} macros
-%    |\@bsphack| and |\@esphack| are used to make those
-%    commands invisible (i.e.\ to normalize the surrounding space and
-%    to make the |\spacefactor| transparent).
-% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.}
-%    \begin{macrocode}
-\def\DescribeMacro{\leavevmode\@bsphack
-%    \end{macrocode}
-%    When documenting the code for the \texttt{amstex.sty} option we
-%    encountered a bug: the |\catcode| of |@| was active and
-%    therefore couldn't be used in command names. So we first have to
-%    make sure that we get all |\catcode|s right by calling
-%    |\MakePrivateLetters| inside a group. Then we call
-%    |\Describe@Macro| to do the work.
-% \changes{v2.0g}{1999/03/22}{Parse backslash as letter in argument
-%        to \cs{DescribeMacro}.}
-% \changes{v2.0h}{1999/03/25}{Correct errors introduced in v2.0g.}
-%    \begin{macrocode}
-   \begingroup\MakePrivateLetters\Describe@Macro}
-\def\Describe@Macro#1{\endgroup
-              \marginpar{\raggedleft\PrintDescribeMacro{#1}}%
-%    \end{macrocode}
-%    Note the use of |\raggedleft| to place the output flushed
-%    right. Finally we call a macro which produces the actual index
-%    entry and finish with |\@esphack| to leave no
-%    trace.\footnote{The whole mechanism won't work because
-%                    of the \texttt{\bslash leavevmode} in front.
-%                    As a temporary change \texttt{\bslash ignorespaces}
-%                    is added.}
-%    \begin{macrocode}
-              \SpecialUsageIndex{#1}\@esphack\ignorespaces}
-%    \end{macrocode}
-%    The |\DescribeEnv| macro is completely analogous.
-% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.}
-%    \begin{macrocode}
-\def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters
-  \Describe@Env}
-\def\Describe@Env#1{\endgroup
-              \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
-              \SpecialEnvIndex{#1}\@esphack\ignorespaces}
-%    \end{macrocode}
+
 %    To put the labels in the left margin we have to use the
 %    |\reversemarginpar| declaration. (This means that the
 %    \texttt{doc.sty} can't be used with all classes or packages.)
@@ -1978,12 +2703,12 @@
 \reversemarginpar
 \setlength\marginparpush{0pt}  \setlength\marginparwidth{8pc}
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
 %
-% \begin{macro}{\bslash}
+%    \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
@@ -2000,14 +2725,14 @@
 %    \begin{macrocode}
 |gdef|bslash{\}}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
 %
 % \begin{environment}{verbatim}
 % \begin{environment}{verbatim*}
 % \changes{v1.7i}{1992/07/12}{Added changed definition for verbatim!*.}
-%    The \textsf{verbatim} environment holds no secrets; it consists of
+%    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|.
@@ -2032,7 +2757,7 @@
 % \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 the \LaTeX{} format.
+%    first lines are copied literally from \texttt{latex.tex}.
 % \changes{v1.7i}{1992/07/12}{Added \cs{@@par} to clear possible
 %                             \cs{parshape}.}
 %    \begin{macrocode}
@@ -2056,7 +2781,7 @@
 %    \begin{macrocode}
    \check@percent}%
 %    \end{macrocode}
-%    The rest is again copied literally from the \LaTeX{} format (less
+%    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,
@@ -2074,7 +2799,7 @@
 %    percent's |\catcode| so that it is seen by \TeX.  The definition
 %    itself is nearly trivial: grab the following character, check if
 %    it is a |%|, and insert it again if not.  At the end of the
-%    \textsf{verbatim} environment this macro will peek at the next
+%    \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|
@@ -2093,16 +2818,16 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\verb}
+% \begin{imacro}{\verb}
 % \changes{v1.7a}{1992/02/27}{Now warns about newlines (from
 %                           newdoc with `@noligs added).}
 % \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX \cs{verb}}
-% We re-define "\verb" to check for newlines in its argument since a
+% We re-define |\verb| to check for newlines in its argument since a
 % missing delimiter is difficult to detect in \DOC{} source.
 % The code is the same as in \texttt{latex.tex} of September 19, 1993.
 % Perhaps there should be a font-changing
-% hook rather than just using "\ttfamily", but if so it probably should be
-% different from "\MacroFont" since that normally includes "\small"
+% hook rather than just using |\ttfamily|, but if so it probably should be
+% different from |\MacroFont| since that normally includes |\small|
 % and would look wrong inline.
 % \changes{v1.7a}{1992/02/28}{Added math mode check (from verbatim.sty)}
 %    \begin{macrocode}
@@ -2111,24 +2836,27 @@
     \ttfamily \verb@eol@error \let\do\@makeother \dospecials
     \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 % \begin{macro}{\verb@balance@group}
 % \begin{macro}{\verb@egroup}
 % \begin{macro}{\verb@eol@error}
 % \changes{v1.8b}{1993/09/21}{Renamed \cs{verb@err} to
 %                   \cs{verb@eol@error}, as in new LaTeX verbatim.}
-% \changes{v2.1n}{2021/05/28}{Use same error message text as in format}
 %    \begin{macrocode}
 \let\verb@balance@group\@empty
-
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \def\verb@egroup{\global\let\verb@balance@group\@empty\egroup}
-
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \begingroup
   \obeylines%
   \gdef\verb@eol@error{\obeylines%
     \def^^M{\verb@egroup\@latex@error{%
-            \noexpand\verb ended by end of line}\@ehc}}%
+            \noexpand\verb command ended by end of line}\@ehc}}%
 \endgroup
 %    \end{macrocode}
 % \end{macro}
@@ -2155,7 +2883,7 @@
 %
 % \begin{macro}{\verbatim@nolig@list}
 % \begin{macro}{\do@noligs}
-%     These macros replace the old "\@noligs" mechanism by an
+%     These macros replace the old |\@noligs| mechanism by an
 %     extensible version to allow more ligatures to be added.
 %    \begin{macrocode}
 \def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-}
@@ -2168,240 +2896,29 @@
 % \end{macro}
 % \end{macro}
 %
-%
-% \begin{macro}{\macro}
-% \begin{macro}{\m@cro@}
-% \changes{v1.5v}{1990/01/28}{\cs{macro@} renamed to \cs{m@cro@}
-%                  since AmSTeX
-%      defines another macro of the same name.}
-% \begin{macro}{\macro@cnt}
-%    \label{page:macro} The \textsf{macro} environment is implemented as
-%    a \textsf{trivlist} environment, whereby in order that the macro
+% \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 \textsf{macro} environments.
+%    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}
-%    The environment takes an argument---the macro name to be
-%    described.  Since this name may contain special `letters' we have
-%    to re-|\catcode| them before scanning the argument. This is done
-%    by the |\MakePrivateLetters| macro.
-% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
-% \changes{v1.7a}{1992/02/26}{Catcode backslash to other (from newdoc).}
-% \changes{v1.9k}{1994/02/22}{Don't omit extra group}
-%    \begin{macrocode}
-\def\macro{\begingroup
-   \catcode`\\12
-   \MakePrivateLetters \m@cro@ \iftrue}
-%    \end{macrocode}
-%
-% \begin{environment}{environment}
-% \changes{v1.8c}{1993/10/25}{Environment added}
-%    The ``environment'' environment will be implemented just like the
-%    ``macro'' environment flagging any differences in the code by
-%    passing |\iffalse| or |\iftrue| to the |\m@cro@| environment
-%    doing the actual work.
-%    \begin{macrocode}
-\def\environment{\begingroup
-   \catcode`\\12
-   \MakePrivateLetters \m@cro@ \iffalse}
-%    \end{macrocode}
-% \end{environment}
-%
-%    After scanning the argument we close the group to get the normal
-%    |\catcode|$\,$s back. Then we assign a special value to
-%    |\topsep| and start a \textsf{trivlist} environment.
-% \changes{v1.5f}{1989/05/07}{MacroTopsep parameter added.}
-% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
-% \changes{v1.8c}{1993/10/25}{Support ``environment'' env}
-% \changes{v1.9k}{1994/02/22}{Remove \cs{macro@level}}
-%    \begin{macrocode}
-\long\def\m@cro@#1#2{\endgroup \topsep\MacroTopsep \trivlist
-%    \end{macrocode}
-% We also save the name being described in |\saved@macroname| for
-% use in conjunction with the |\changes| macro.
-%    \begin{macrocode}
-  \edef\saved@macroname{\string#2}%
-  #1
-%    \end{macrocode}
-%    If documenting an environment we put is name in |\saved@indexname|
-%    otherwise the name without the backslash.
-% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}}
-%    \begin{macrocode}
-    \let\saved@indexname\saved@macroname
-  \else
-    \edef\saved@indexname{\expandafter\@gobble\string#2}%
-  \fi
-%    \end{macrocode}
-%    Now there follows a variation of |\makelabel| which is used
-%    should the environment not be nested, or should it lie between
-%    two successive |\begin{macro}| instructions or explanatory
-%    text.  One can recognize this with the switch |\if@inlabel|
-%    which will be |true| in the case of successive |\item|
-%    commands.
-%    \begin{macrocode}
-  \def\makelabel##1{\llap{##1}}%
-%    \end{macrocode}
-%    If |@inlabel| is |true| and if $\verb=\macro@cnt= > 0$
-%    then the above definition needs to be changed, because in this
-%    case \LaTeX{} would otherwise put the labels all on the same line
-%    and this would lead to them being overprinted on top of each
-%    other.  Because of this |\makelabel| needs to be redefined
-%    in this case.
-%    \begin{macrocode}
-  \if@inlabel
-%    \end{macrocode}
-%    If |\macro@cnt| has the value $1$, then we redefine
-%    |\makelabel| so that the label will be positioned in the
-%    second line of the margin.  As a result of this, two macro names
-%    appear correctly, one under the other.  It's important whilst
-%    doing this that the generated label box is not allowed to have
-%    more depth than a normal line since otherwise the distance
-%    between the first two text lines of \TeX{} will be incorrectly
-%    calculated. The definition should then look like:
-%\begin{verbatim}
-%     \def\makelabel##1{\llap{\vtop to \baselineskip
-%          {\hbox{\strut}\hbox{##1}\vss}}}
-%\end{verbatim}
-%    Completely analogous to this is the case where labels need to be
-%    placed one under the other.  The lines above are only an example
-%    typeset with the \textsf{verbatim} environment. To produce the real
-%    definition we save the value of |\macro@cnt| in
-%    |\count@| and empty the temp macro |\@tempa| for later
-%    use.
-%    \begin{macrocode}
-    \let\@tempa\@empty \count@\macro@cnt
-%    \end{macrocode}
-%    In the following loop we append for every already typeset label
-%    an |\hbox{\strut}| to the definition of |\@tempa|.
-%    \begin{macrocode}
-    \loop \ifnum\count@>\z@
-      \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat
-%    \end{macrocode}
-%    Now be put the definition of |\makelabel| together.
-% \changes{v1.5b}{1989/04/27}{vbox to vtop changed in makelabel (test)}
-% \changes{v1.5e}{1989/04/28}{ht strutbox changed to baselineskip
-%                             (test)}
-%    \begin{macrocode}
-    \edef\makelabel##1{\llap{\vtop to\baselineskip
-                               {\@tempa\hbox{##1}\vss}}}%
-%    \end{macrocode}
-%    Next we increment the value of the nesting depth counter.  This
-%    value inside the \textsf{macro} environment is always at least one
-%    after this point, but its toplevel definition is zero. Provided
-%    this environment has been used correctly, $|\macro@cnt|=0$
-%    should not occur when |@inlabel|=\textsf{true}.  It is
-%    however possible if this environment is used within other list
-%    environments (but this would have little point).
-%    \begin{macrocode}
-    \advance \macro@cnt \@ne
-%    \end{macrocode}
-%    If |@inlabel| is false we reset |\macro@cnt| assuming
-%    that there is enough room to print the macro name without
-%    shifting.
-%    \begin{macrocode}
-  \else  \macro@cnt\@ne  \fi
-%    \end{macrocode}
-%    Now the label will be produced using |\item|. The following
-%    line is only a hack saving the day until a better solution is
-%    implemented.  We have to face two problems: the argument might be
-%    a |\par| which is forbidden in the argument of other macros
-%    if they are not defined as |\long|, or it is something like
-%    |\iffalse| or |\else|, i.e.\ something which will be
-%    misinterpreted when \TeX{} is skipping conditional text. In both
-%    cases |\item| will bomb, so we protect the argument by using
-%    |\string|.
-%    \begin{macrocode}
-  \edef\@tempa{\noexpand\item[%
-%    \end{macrocode}
-%    Depending on whether we are inside a ``macro'' or ``environment''
-%    environment we use |\PrintMacroName| or |\PrintEnvName| to
-%    display the name.
-%    \begin{macrocode}
-     #1%
-       \noexpand\PrintMacroName
-     \else
-       \noexpand\PrintEnvName
-     \fi
-     {\string#2}]}%
-  \@tempa
-%    \end{macrocode}
-%    At this point we also produce an index entry.  Because it is not
-%    known which index sorting program will be used, we do not use the
-%    command |\index|, but rather a command
-%    |\SpecialMainIndex| after advancing the counter for indexing
-%    by line number.  This may be redefined by the user in
-%    order to generate an index entry which will be understood by the
-%    index program in use (note the definition of
-%    |\SpecialMainIndex| for our installation).
-% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
-% \changes{v1.9u}{1995/08/06}{Removed brace group which
-%           killed \cs{DoNotIndex}}
-%    We advance the current codeline number and after producing an
-%    index entry revert to the original value
-%    \begin{macrocode}
-  \global\advance\c@CodelineNo\@ne
-%    \end{macrocode}
-%    Again the macro to call depends on the environment we are
-%    actually in.
-%    \begin{macrocode}
-   #1%
-      \SpecialMainIndex{#2}\nobreak
-      \DoNotIndex{#2}%
-   \else
-      \SpecialMainEnvIndex{#2}\nobreak
-   \fi
-  \global\advance\c@CodelineNo\m@ne
-%    \end{macrocode}
-%    The |\nobreak| is needed to prevent a page break after the
-%    |\write| produced by the |\SpecialMainIndex| macro.  We
-%    exclude the new macro in the cross-referencing feature, to
-%    prevent spurious non-main entry references.  Regarding possibly
-%    problematic arguments, the implementation takes
-%    care of |\par| and the conditionals are uncritical.
-%  \changes{v1.7a}{1992/03/02}{Removed redundant code checking for
-%                             \cs{par}.}^^A
-%
-%    Because the space symbol should be ignored between the
-%    |\begin{macro}{...}| and the following text we must take
-%    care of this with |\ignorespaces|.
-%    \begin{macrocode}
-  \ignorespaces}
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+% \end{tcounter}
 %
 %
-%
-% \begin{macro}{\endmacro}
-% \begin{macro}{\endenvironment}
-%     Older releases of this environment omit the |\endgroup| token,
-%     when being nested. This was done to avoid unnecessary stack usage.
-%     However it does not work if \textsf{macro} and
-%     \textsf{environment} environments are mixed, therefore we now
-%     use a simpler approach.
-% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.}
-% \changes{v1.9k}{1994/02/22}{Don't checkfor nesting}
-%    \begin{macrocode}
-\let\endmacro \endtrivlist
-\let\endenvironment\endmacro
-%    \end{macrocode}
-%  \end{macro}
-%  \end{macro}
-%
-% \begin{macro}{\MacroTopsep}
+% \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{macro}
+% \end{lskip}
 %
 %
 %
@@ -2413,49 +2930,15 @@
 % Therefore we define those macros only if they have not already
 % been defined.
 %
-% \begin{macro}{\PrintMacroName}
-% \begin{macro}{\PrintEnvName}
-% \begin{macro}{\PrintDescribeMacro}
-% \begin{macro}{\PrintDescribeEnv}
-%    The formatting of the macro name in the left margin is done by
-%    these macros. We first set a |\strut| to get the height and
-%    depth of the normal lines. Then we change to the
-%    |\MacroFont| using |\string| to |\catcode| the
-%    argument to other (assuming that it is a macro name). Finally we
-%    print a space.  The font change remains local since this macro
-%    will be called inside an |\hbox|.
-%    \begin{macrocode}
-\@ifundefined{PrintMacroName}
-   {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{}
-%    \end{macrocode}
-%    We use the same formatting conventions when describing a macro.
-%    \begin{macrocode}
-\@ifundefined{PrintDescribeMacro}
-   {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{}
-%    \end{macrocode}
-%    To format the name of a new environment there is no need to use
-%    |\string|.
-%    \begin{macrocode}
-\@ifundefined{PrintDescribeEnv}
-   {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{}
-\@ifundefined{PrintEnvName}
-   {\def\PrintEnvName#1{\strut \MacroFont #1\ }}{}
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-%
 %
 % \subsection{Creating index entries by scanning `macrocode'}
 %
 %  The following macros ensure that index entries are created for each
 %  occurrence of a \TeX-like command (something starting with
-%  `|\|') providing indexing has been turned on with "\PageIndex"
-%  or "\CodelineIndex".  With the default definitions of
-%  |\SpecialMainIndex|, etc., the index file generated is
-%  intended to be processed by Chen's \textsf{makeindex} program
+%  `|\|') 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}.
 %
 %
@@ -2464,15 +2947,15 @@
 %  introduce command names at places where |\| has to belong to
 %  some other category.  Therefore, we may also need to recognize
 %  \verb+|+ as the introducer for a command when setting the text
-%  inside the \textsf{macrocode} environment.  Other users may have the
+%  inside the \env{macrocode} environment.  Other users may have the
 %  need to make similar reassignments for their macros.
 %
 %
-% \begin{macro}{\SpecialEscapechar}\label{sect:specialescapechar}
+% \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 \textsf{macrocode} environment. It has one
+%    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
@@ -2528,7 +3011,7 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
-% \end{macro}
+% \end{imacro}
 %
 %
 %
@@ -2564,7 +3047,7 @@
 %    `|\|' first to 12 (at the end of |\macro@code|) then
 %    re-|\catcode| it to 13 in order to produce a $|\|_{12}$
 %    in case 3b) above.  This is done because we have to ensure that
-%    `|\|' has |\catcode| 13 within the \textsf{macrocode}
+%    `|\|' 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).
@@ -2574,7 +3057,7 @@
 \begingroup   \catcode`\|=\z@  \catcode`\\=\active
 %    \end{macrocode}
 %    We carry out tasks 2) and 3b) first.
-%    \SpecialEscapechar{\|}
+%    \SpecialEscapechar\|
 %    \begin{macrocode}
 |gdef|init@crossref{|catcode`|\|active   |let\|bslash
 %    \end{macrocode}
@@ -2613,7 +3096,7 @@
 %
 %
 %
-% \begin{macro}{\MakePrivateLetters}
+% \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.
@@ -2621,7 +3104,7 @@
 \@ifundefined{MakePrivateLetters}
     {\let\MakePrivateLetters\makeatletter}{}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 % \begin{macro}{\close@crossref}
 %    At the end of a cross-referencing part we prepare ourselves for
@@ -2642,10 +3125,10 @@
 %    The |\init@crossref| will have made |\active| our
 %    |\special@escape@char|, so that each
 %    |\active@escape@char| will invoke |\scan@macro| when
-%    within the \textsf{macrocode} environment.  By this means, we can
+%    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
-%    \textsf{macrocode} environments.
+%    \env{macrocode} environments.
 %    \begin{macrocode}
 \def\scan@macro{%
 %    \end{macrocode}
@@ -2658,7 +3141,7 @@
    \special@escape@char
    \step@checksum
 %    \end{macrocode}
-%    If the \textsf{macrocode} environment contains, for example, the
+%    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.
@@ -2689,22 +3172,9 @@
 % \end{macro}
 %
 %
-% \begin{macro}{\ifscan@allowed}
-% \begin{macro}{\scan@allowedtrue}
-% \begin{macro}{\scan@allowedfalse}
-%    |\ifscan@allowed| is the switch used above to determine if
-%    the |\active@escape@char|\SpecialIndex{\active@escape@char}
-%    should start the macro scanning mechanism.
-%    \begin{macrocode}
-\newif\ifscan@allowed    \scan@allowedtrue
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
 %
-% \begin{macro}{\EnableCrossrefs}
-% \begin{macro}{\DisableCrossrefs}
+% \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
@@ -2718,8 +3188,8 @@
 \def\EnableCrossrefs{\@bsphack\scan@allowedtrue
                      \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack}
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{imacro}
+% \end{imacro}
 %
 %
 %
@@ -2750,6 +3220,10 @@
 %
 %
 % \begin{macro}{\short@macro}
+%
+% \fmi{this needs cleaning up too, the results in the index are
+% currently wrong for cases like `\cs{ }' and the like.}
+%
 % \changes{v1.5c}{1989/04/27}{Corrected bad bug by putting the
 %                         scan@allowedfalse macro before printing
 %                         the argument.}
@@ -2757,7 +3231,7 @@
 %           \cs{macro@namepart} as `letter' so index exclusion works.}
 %    This macro will be invoked (with a single character as parameter)
 %    when a single-character macro name has been spotted whilst
-%    scanning within the \textsf{macrocode} environment.
+%    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
@@ -2775,14 +3249,14 @@
    \uccode`\&=\expandafter`\string#1%
    \uppercase{\def\x{\def\macro@namepart{&}}}%
    \expandafter\endgroup\x
-   \ifnot@excluded
 %    \end{macrocode}
-%    If necessary the index entry is produced by the macro
-%    |\produce@index|. Depending on the actual character seen,
-%    this macro has to do different things, so we pass the character
-%    as an argument.
+%    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}
-     \produce@index{#1}\fi
+     \maybe@index@short@macro\macro@namepart
 %    \end{macrocode}
 %    Then we disable the cross-referencing mechanism with
 %    |\scan@allowedfalse| and print the actual character. The
@@ -2803,104 +3277,6 @@
 %
 %
 %
-% \begin{macro}{\produce@index}
-% \changes{v1.4s}{1989/04/23}{Added noexpand to all
-%                           \cs{if} tests
-%               to avoid garbage produced by new active chars}
-% \changes{v1.4s}{1989/04/23}{Used \texttt{\protect\bslash string} for
-%                          the same reason.}
-% \changes{v1.5c}{1989/04/27}{Corrected bad bug by placing the
-%                         scan@allowedfalse macro into short@macro}
-%    This macro is supposed to generate a suitable |\SortIndex|
-%    command for a given single-letter control sequence.  We test
-%    first for the cases which involve active characters (i.e.\ the
-%    backslash, the special escape character (if any), the space and
-%    the |^^M|).  Using the |\if| test (testing for
-%    character codes), we have to ensure that the argument isn't
-%    expanded.
-%    \begin{macrocode}
-\def\produce@index#1{%
-  \if\noexpand#1\special@escape@char
-%    \end{macrocode}
-%    If the character is the special escape character (or the
-%    `|\|' in case there was none) the |\it@is@a| macro is
-%    used to produce the actual |\SortIndex| call.
-%    \begin{macrocode}
-     \scan@allowedfalse \it@is@a\special@escape@char \else
-%    \end{macrocode}
-%    Next comes the test for a `|\|' which must be the
-%    $|\|_{13}$ expanding to |\bslash|.
-%    \begin{macrocode}
-     \if\noexpand#1\bslash \it@is@a\bslash \else
-%    \end{macrocode}
-%    Another possibility is \verb*+ +$_{13}$. Recall that |\space|
-%    produces a \verb*+ +$_{10}$.
-%    \begin{macrocode}
-       \if\noexpand#1\space \it@is@a\space \else
-%    \end{macrocode}
-%    The last\footnote{Well, it isn't the last active character after
-%    all. I added \texttt{\bslash @noligs} some days ago and now
-%    \texttt{`} too is active. So we have to make sure that such
-%    characters don't get expanded in the index.} possibility of an
-%    active character is |^^M|\@.  In this case we don't test for
-%    character codes, since it is easier to look if the character is
-%    equal to |\par|. (We are inside the \textsf{macrocode}
-%    environment.)
-%    \begin{macrocode}
-         \ifx#1\par
-%    \end{macrocode}
-%    If we end up here we have just scanned a |\^^M| or something
-%    similar. Since this will be treated like \verb*+\ + by \TeX{} we
-%    produce a corresponding index entry.
-%    \begin{macrocode}
-         \it@is@a\space \else
-%    \end{macrocode}
-%    If it is the token |\relax| we do nothing. This can't happen
-%    when the `doc' package is used in the way described here, but was
-%    added to allow extensions like the \texttt{idxverb} option.
-%  \changes{v1.5t}{1989/11/14}{Added \cs{relax} as a possible token to
-%                           allow extensions.}
-%    \begin{macrocode}
-         \ifx#1\relax \else
-%    \end{macrocode}
-%    The next three branches are needed because of bugs in
-%    our \textsf{makeindex} program. You can't produce unbalanced index
-%    entries\footnote{This is possible for \TeX{} if you use
-%                     \texttt{\string{$_{12}$ \rmfamily or
-%                     \ttfamily\string}$_{12}$},
-%                     but \textsf{makeindex} will complain.}
-%    and you have to double a percent character. To get around these
-%    restrictions we use special macros to produce the |\index|
-%    calls.\footnote{Brian \textsc{Hamilton Kelly} has written fixes for
-%                  all three
-%                  bugs. When they've found their way through all
-%                    installations,
-%                    the lines above will be removed. See
-%                    page~\pageref{bug:fixes} if you already have them.
-%                    (I'm not sure which versions incorporate these, but
-%                    2.11 is OK.  See also
-%                    \pageref{makeindex:version}.)}
-%    \begin{macrocode}
-           \if\noexpand#1\bgroup \LeftBraceIndex \else
-             \if\noexpand#1\egroup \RightBraceIndex \else
-               \if\noexpand#1\percentchar \PercentIndex \else
-%    \end{macrocode}
-%    All remaining characters are used directly to produce their index
-%    entries. This is possible even for the characters which have
-%    special meanings in the index program, provided we quote the
-%    characters.  (This is correctly done in |\it@is@a|.)
-%    \begin{macrocode}
-                 \it@is@a{\string#1}%
-%    \end{macrocode}
-%    We now need a whole pile of |\fi|$\,$s to match up with
-%    the |\if|$\,$s.
-%    \begin{macrocode}
-       \fi \fi \fi \fi \fi \fi \fi \fi}
-%    \end{macrocode}
-% \end{macro}
-%
-%
-%
 % \begin{macro}{\macro@name}
 %    We now come to the macro which assembles command names which
 %    consist of one or more `letters' (which might well include
@@ -2968,9 +3344,11 @@
 %    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}
+%  \ifnot@excluded
+%     \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
+%     \@tempa  \fi
+  \maybe@index@macro \macro@namepart
+}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -2980,155 +3358,525 @@
 %
 % \subsection[The index exclude list]{The index exclude
 %             list\footnotemark}
-%            \footnotetext{Warning: the incomplete commentary on
+%            \footnotetext{Info: the incomplete commentary on
 %            \texttt{\bslash DoNotIndex} and the macros it calls
 %                          was written by Dave Love.}
 %
-%    The internal form of the index exclude list is
-% \begin{quote}
-% \meta{macro name}|,|\meta{macro name}|,|
-% \ldots|,|
-% \end{quote}
-% where \meta{macro name} is a macro name like
-% $"\"_{12}"p"{_{11}}"@"_{11}$ or $"\"_{12}"$"_{11}$.  Note that the "\"
-% has category `other' and the other characters in the name are all
-% `letter', regardless of their normal category.
 %
-% \begin{macro}{\DoNotIndex}
-%    This macro is used to suppress macro names in the index.  It
-%    starts off with a new group because we have to change the
-%    |\catcode|$\,$s of all characters which belong to `letters'
-%    while macros are defined.
+%
+
+% \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}
-\def\DoNotIndex{\begingroup \MakePrivateLetters
-    \catcode`\\12
+\ExplSyntaxOn
 %    \end{macrocode}
-%    Then we call the macro which actually reads the argument given by
-%    the user.
+%
+%
+% \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}
-    \do@not@index}
+\seq_new:N  \l__doc_donotindex_seq
+\prop_new:N \g__doc_idxtype_prop
 %    \end{macrocode}
-% \end{macro}
+%  \end{macro}
+%  \end{macro}
 %
+% ^^A --------------------------------------------------
 %
 %
-% \begin{macro}{\do@not@index}
-%    We make the |\do@not@index| macro |\long|
-%    since the user might want to exclude the |\par|
-%    macro.
+%  \begin{macro}{\__doc_trace:x}
+%    A helper for tracing\ldots
 %    \begin{macrocode}
-\long\def\do@not@index#1{%
+\cs_new:Npn\__doc_trace:x {
+  \legacy_if:nTF{ doc@debugshow }{ \iow_term:x } { \use_none:n }
+}
 %    \end{macrocode}
-%    It just adds to a token list after finishing the group in which
-%    the catcodes were changed.
-%    \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.}
+%  \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}
-    \endgroup
-    \addto@hook\index@excludelist{#1,}}
+\cs_new:Npn \doc_dont_index:n {
+  \group_begin:
+    \MakePrivateLetters
+    \__doc_dont_index:n
+}
 %    \end{macrocode}
-% \end{macro}
 %
-% \begin{macro}{\addto@hook}
-% The code for adding tokens (the second argument) to a token list
-% (the first argument) is taken from~\cite{art:verbatim}, but it needs
-% to be "\long" in case "\par" is amongt the tokens.
 %    \begin{macrocode}
-\long\def\addto@hook#1#2{#1\expandafter{\the#1#2}}
+\cs_new:Npn \__doc_dont_index:n #1 {
+  \group_end:
 %    \end{macrocode}
-% \end{macro}
 %
-% \begin{macro}{\index@excludelist}
-% We need an initially-empty register for the excluded list.
 %    \begin{macrocode}
-\newtoks\index@excludelist
-\index@excludelist{}
+  \__doc_trace:x{Disable~ indexing~ for~ '\tl_to_str:n{#1}' }
 %    \end{macrocode}
-% \end{macro}
+%    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}{\ifnot@excluded}
-%    \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.}
-% \begin{macro}{\expanded@notin}
-%    Now we take a look at the |\index@excludelist| to see
-%    whether a macro name saved in |\macro@namepart| should
-%    produce an index entry. This macro is a pseudo |\if|; it
-%    should expand to |\iftrue| or |\iffalse| depending on
-%    the contents of |\index@excludelist|.
+%  \begin{macro}{\DoNotIndex}
+%    The document-level interface
 %    \begin{macrocode}
-\begingroup
+\cs_set_eq:NN \DoNotIndex \doc_dont_index:n
 %    \end{macrocode}
-%    First we change "\catcode"s so that "\" is `other' and "|" a
-%    temporary for the escape character. This is necessary since our
-%    macro names are stored that way in the "\index@excludelist".
+%  \end{macro}
+%
+%
+%  \begin{macro}{\ShowIndexingState}
+%    Some tracing information that may be helpful.
 %    \begin{macrocode}
-\catcode`\|=0%
-\catcode`\\=12
+\def \ShowIndexingState {
+  \__doc_trace:x{Show~ doc~ indexing~ state:}
+  \seq_show:N  \l__doc_donotindex_seq
+%  \tl_analysis_show:N\l__doc_donotindex_seq
+  \prop_show:N \g__doc_idxtype_prop
+}
 %    \end{macrocode}
-%    Then we define "\ifnot@excluded" to call "\expanded@notin" with
-%    two arguments: the first is the string "\" followed by the
-%    contents of "\macro@namepart" followed by a "," and the second is
-%    "\the" followed by "\index@excludelist". To achieve the expansion
-%    of "\macro@namepart", i.e.\ to pass its contents, we need a
-%    suitable number of "\expandafter"s.
-%    \SpecialEscapechar{\|}
+%  \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}
-|gdef|ifnot@excluded{|expandafter
-     |expanded@notin|expandafter{|expandafter
-     \|macro@namepart,}{|the|index@excludelist}}
-|endgroup
+\cs_new:Npn \RecordIndexTypeAux #1#2 {
+  \exp_args:Nx \__doc_idxtype_put:nn { \cs_to_str:N #1 }{#2}
+}
 %    \end{macrocode}
-%    The macro "\expanded@notin" now does the dirty work. It first
-%    defines a macro "\in@@" with a very special parameter text. If
-%    you look closely "\in@@" has three arguments, the first one is
-%    delimited by the first argument of "\expanded@notin" (i.e.\ by
-%    the string starting with a "\" and ending with a "," above), the
-%    second is undelimited (which means that it will get the next
-%    token after our string, and the third is delimited again and will
-%    get the rest up to the token "\in@@". In other words the token
-%    "\in@@" is also used as a delimiter.
-%    \begin{macrocode}
-\def\expanded@notin#1#2{%
- \def\in@@##1#1##2##3\in@@{%
-%    \end{macrocode}
-%    Now the replacement text simply compares the second argument
-%    (i.e.\ the undelimited one after our string) to the token
-%    "\expanded@notin". This is an unclosed "\ifx" statement which
-%    means that this macro behaves similar to a normal \TeX{}
-%    conditional.
-%    \begin{macrocode}
-  \ifx\expanded@notin##2}%
-%    \end{macrocode}
-%    After all these preparations we call "\in@@". First we expand the
-%    token after "\in@@" (which is "\the" from the second argument to
-%    "\expanded@notin"). As a result we get the contents of the
-%    "\index@excludelist" inserted after "\in@@". After this contents
-%    we add once more the string we are looking for, then the token
-%    "\expanded@notin" and finally the token "\in@@".
-%    \begin{macrocode}
- \expandafter\in@@#2#1\expanded@notin\in@@}
-%    \end{macrocode}
-%    Now what happens when the macro "\in@@" above gets called? The
-%    first argument to "\in@@" is delimited by our string. In other
-%    words it will get everything from the contents of
-%    "\index@excludelist" before this string. If the string is not in
-%    "\index@excludelist" then it gets the whole contents, since after
-%    it we had inserted the string one more. In this case the next
-%    token is "\expanded@notin" which gets assigned to the second
-%    argument and the third argument will be empty. If, on the other
-%    hand, the string was inside "\index@excludelist" then the second
-%    argument will not be the token "\expanded@notin" and the third
-%    argument will be all the garbage up to "\in@@". Therefore testing
-%    the seconded argument, as done in the definition of "\in@@" will
-%    tell us  whether or not the string is in "\index@includelist" and
-%    this was exactly what we wanted. (Deep breath.) You got
-%    that?\footnote{\TeX{}book page 125. The code described above is
-%    originally due to Michael Spivak who used a similar method within
-%    the \AmSTeX{} macros.}
-% \end{macro}
-% \end{macro}
+%    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}.
+%    \begin{macrocode}
+\cs_new:Npn \__doc_maybe_index_short:o #1 {
+  \exp_args:Nf \__doc_maybe_index_aux:nN { \tl_to_str:o {#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                          }
+          { }                  {\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}
 %
 %
 %
@@ -3138,20 +3886,20 @@
 % index entries; these are either invoked explicitly, or automatically
 % by |\scan@macro|.  As already mentioned, the definitions given
 % here presuppose that the |.idx| file will be processed by
-% Chen's \textsf{makeindex} program --- they may be redefined for use
-% with the user's favourite such program.
+% 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 \textsf{makeindex}.  The default
+% 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 \textsf{makeindex} by means
+% 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 amongt the supporting files for this style file in
+% 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
@@ -3172,12 +3920,12 @@
 %<+gind|gglo>
 %    \end{macrocode}
 %
-% \begin{macro}{\actualchar}
-% \begin{macro}{\quotechar}
-% \begin{macro}{\levelchar}
+% \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 \textsf{makeindex} program without a
+%    are not the ones used by the \prg{makeindex} program without a
 %    style file.
 %    \begin{macrocode}
 %<*package>
@@ -3190,85 +3938,39 @@
 %<+gind|gglo>level '>'
 %<*package>
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+% \end{imacro}
+% \end{imacro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\encapchar}
-%    The \textsf{makeindex} default for the |\encapchar| isn't
+% \begin{imacro}{\encapchar}
+%    The \prg{makeindex} default for the |\encapchar| isn't
 %    changed.
 %    \begin{macrocode}
 \@ifundefined{encapchar}{\def\encapchar{|}}{}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\verbatimchar}
+% \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{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\SpecialIndex}
-%    The |\SpecialIndex| command creates index entries for
-%    macros.  If the argument is |\|$xyz$, the command produces
-%    \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}|
-%    given the above defined defaults for |\actualchar|,
-%    |\quotechar| and |\verbatimchar|.  We first remove the
-%    initial `|\|' to get a better index.
-% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
-%    \begin{macrocode}
-\def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble
-                                      \string#1\actualchar
-%    \end{macrocode}
-%    Then follows the actual entry. A |\quotechar| is placed
-%    before the |*| to allow its use as a special \textsf{makeindex}
-%    character.  Again |\@bsphack| and |\@esphack| are used
-%    to make the macros invisible.
-%    \begin{macrocode}
-      \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}%
-    \@esphack}
-%    \end{macrocode}
-% \end{macro}
-
-% \begin{macro}{\SpecialMainIndex}
-% \begin{macro}{\SpecialMainEnvIndex}
-% \begin{macro}{\SpecialUsageIndex}
-%    The |\SpecialMainIndex| macro is used to cross-reference the
-%    names introduced by the \textsf{macro} environment.  The action is
-%    as for |\SpecialIndex|, except that \textsf{makeindex} is
-%    instructed to `encap'sulate the entry with the string
-%    \verb=|main= to cause it to generate a call of the |\main|
-%    macro.
-% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
-% \changes{v2.0c}{1998/08/22}{Correctly handle single character
-%                   control sequences like \cs{<}.}
 %
-%    |\SpecialMainIndex| passes the macro name to be indexed on to the
-%    macro |\SpecialIndex@|.
-%    \begin{macrocode}
-\def\SpecialMainIndex#1{\@bsphack\SpecialIndex@{#1}{\encapchar main}%
-                        \@esphack}
-%    \end{macrocode}
-%
-% \begin{macro}{\SpecialIndex@}
-% \changes{v2.0c}{1998/08/22}{Macro added.}
-% \changes{v2.0f}{1999/02/27}{Temp fix to allow strange code in arg 1
-%                             (PR 2968)}
-%    The macro |\SpecialIndex@| does the real work for |\SpecialMainIndex|
-%    and |\SpecialUsageIndex|. It takes two arguments: the macro to be
-%    indexed (as a control sequence or list of character tokens) and the
-%    additional text for the index.
-% \changes{v2.0g}{1999/03/22}{Correct so-called temp fix. I'm not going to
-%                   explain this.}
+% \begin{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}%
@@ -3279,137 +3981,13 @@
      |endgroup
    |fi}
 |endgroup
-\def\SpecialIndex@#1#2{%
 %    \end{macrocode}
-%    The first thing it does is to convert the macro into a list of
-%    characters. Note that a character token list remains (mostly) unchanged.
-%    \begin{macrocode}
-   \@SpecialIndexHelper@#1\@nil
-%    \end{macrocode}
-%    The macro name \verb*|\ | has to handled in a special way. The reason
-%    is that the space token is skipped when \TeX\ is scanning macro
-%    parameters, so that the trick used below will not work.
-%    So, we check whether the replacement text of |\@tempa| starts with
-%    a space token and write the appropriate index entry.
-%    \begin{macrocode}
-   \def\@tempb{ }%
-   \ifcat \@tempb\@gtempa
-      \special@index{\quotechar\space\actualchar
-                     \string\verb\quotechar*\verbatimchar
-                     \quotechar\bslash\quotechar\space\verbatimchar#2}%
-   \else
-%    \end{macrocode}
-%    Having handled this special case we have to distinguish control
-%    sequences consisting of one or more
-%    letters and those that consists of exactly one nonletter. As character
-%    tokens in the replacement text of the macro |\@gtempa| have all
-%    category code $12$ (other), this is difficult. For simplicity, we treat
-%    all single character control sequences alike, irregardless of whether
-%    the character is a letter or not. This has the advantage that it works
-%    even for strange settings of the category codes.
 %
-%    We define a utility macro |\@tempb| with two arguments, the second
-%    delimited by |\relax|.
-%    It will be called later so that the first argument is the first character
-%    of the macro name, and the second argument receives the rest of the
-%    characters. So we distinguish the two cases above by checking whether
-%    the second argument is empty.
-%    \begin{macrocode}
-     \def\@tempb##1##2\relax{\ifx\relax##2\relax
-%    \end{macrocode}
-%    If so, we define the helper macro |\@tempc| in a way that it
-%    adds quotechars in critical places.
-%    \begin{macrocode}
-          \def\@tempc{\special@index{\quotechar##1\actualchar
-                      \string\verb\quotechar*\verbatimchar
-                      \quotechar\bslash\quotechar##1\verbatimchar#2}}%
-%    \end{macrocode}
-%    Otherwise we write the characters as in |\SpecialIndex|.
-%    \begin{macrocode}
-        \else
-          \def\@tempc{\special@index{##1##2\actualchar
-                       \string\verb\quotechar*\verbatimchar
-                       \bslash##1##2\verbatimchar#2}}%
-        \fi}%
-%    \end{macrocode}
-%    Now pass the list of characters to \@tempb and call \@tempc to do the
-%    work.
-%    \begin{macrocode}
-     \expandafter\@tempb\@gtempa\relax
-     \@tempc
-   \fi}
-%    \end{macrocode}
-% \end{macro}
-%
-%    Slightly simpler is the main entry for environments
-% \changes{v1.9e}{1994/02/03}{use \cs{ttfamily} with \cs{string}}
-% \changes{v1.9f}{1994/02/07}{should have used \cs{noexpand}, sigh}
-% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}}
-% \changes{v1.9j}{1994/02/16}{Back to string:-)}
-% \changes{v1.9s}{1994/10/14}{Added missing percent and changed to
-%                             \cs{ttfamily}}
-% \changes{v2.0d}{1998/12/20}{Correctly handle second index entry
-%    by using \cs{special@index} not \cs{index} (PR/2928).}
-% \changes{v2.0e}{1998/12/28}{Use \cs{string}, not \cs{protect} in argument to
-%             \cs{special@index}.}
-% \changes{v2.1c}{2004/07/23}{environment names incorrectly sorted in
-%           index (pr/3615)}
-%    \begin{macrocode}
-\def\SpecialMainEnvIndex#1{\@bsphack\special@index{%
-                                      #1\actualchar
-                                      {\string\ttfamily\space#1}
-                                         (environment)%
-                                      \encapchar main}%
-    \special@index{environments:\levelchar#1\actualchar{%
-                   \string\ttfamily\space#1}\encapchar
-           main}\@esphack}
-%    \end{macrocode}
-%    The |\SpecialUsageIndex| is similar to |\SpecialMainIndex|, except
-%    that it uses the standard |\index| command.
-%    \texttt{usage} instead of \texttt{main}.
-%    \begin{macrocode}
-\def\SpecialUsageIndex#1{\@bsphack
-   {\let\special@index\index\SpecialIndex@{#1}{\encapchar usage}}%
-   \@esphack}
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-%
-%
-%
-% \begin{macro}{\SpecialEnvIndex}
-%    Indexing environments is done a little bit differently; we produce
-%    two index entries with the |\SpecialEnvIndex| macro:
-% \changes{v1.9e}{1994/02/03}{The index needs protecting}
-% \changes{v1.9g}{1994/02/08}{should have used \cs{noexpand}, sigh}
-% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}}
-%    \begin{macrocode}
-\def\SpecialEnvIndex#1{\@bsphack
-%    \end{macrocode}
-%    First we sort the environment under its own name stating in the
-%    actual entry that this is an environment.
-%    \begin{macrocode}
-    \index{#1\actualchar{\protect\ttfamily#1}
-           (environment)\encapchar usage}%
-%    \end{macrocode}
-%    The second entry is sorted as a subitem under the key
-%    `environments:'.
-% \changes{v2.1b}{2004/02/09}{environment names incorrectly sorted in
-%           index (pr/3615)}
-%    \begin{macrocode}
-    \index{environments:\levelchar#1\actualchar
-          {\protect\ttfamily#1}\encapchar usage}\@esphack}
-%    \end{macrocode}
-%    Because both entries correspond to `descriptions' of the
-%    environment, we encapsulate the page numbers with the
-%    |\usage| macro.
 % \end{macro}
 %
 %
 %
-% \begin{macro}{\SortIndex}
+% \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,
@@ -3417,76 +3995,87 @@
 %    the entry. It can also be used directly to generate index entries
 %    which differ in sort key and actual entry.
 %    \begin{macrocode}
-\def\SortIndex#1#2{\index{#1\actualchar#2}}
+\def\SortIndex#1#2{%
+  \ifdoc@noindex\else
+    \index{#1\actualchar#2}%
+  \fi
+}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
 %
-% \begin{macro}{\it@is@a}
-%    This macro is supposed to produce a correct |\SortIndex|
-%    entry for a given character. Since this character might be
-%    recognised as a `command' character by the index program used,
-%    all characters are quoted with the |\quotechar|.
-% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
-%    \begin{macrocode}
-\def\it@is@a#1{\special@index{\quotechar #1\actualchar
-                          \string\verb\quotechar*\verbatimchar
-                          \quotechar\bslash\quotechar#1\verbatimchar}}
-%    \end{macrocode}
-% \end{macro}
-%
-%
 %
-% \begin{macro}{\LeftBraceIndex}
+% \begin{imacro}{\LeftBraceIndex}
 % \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
-% \begin{macro}{\RightBraceIndex}
+% \begin{imacro}{\RightBraceIndex}
 % \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} These
-%    two macros fix the problems with \textsf{makeindex}.  Note the
+%    two macros fix the problems with \prg{makeindex}.  Note the
 %    `hack' with |\iffalse}\fi| to satisfy both \TeX{} and the
-%    \textsf{makeindex} program. When this is written to the
+%    \prg{makeindex} program. When this is written to the
 %    \texttt{.idx} file \TeX{} will see both braces (so we get a
-%    balanced text).  \textsf{makeindex} will also see balanced braces
+%    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\quotechar*\verbatimchar
-          \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{}
+   \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
+ \special@index{\egroup\actualchar\string\iffalse{\string\fi
+           \string\verb% % to fool emacs highlighting
            \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{}
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{imacro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\PercentIndex}
+% \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 \textsf{makeindex} without the
+% 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{macro}
-% \begin{macro}{\OldMakeindex}
+% \end{imacro}
+%
+%
+% \begin{omacro}{\OldMakeindex}
 % \changes{v1.7c}{1992/03/26}{Replaced \cs{NewMakeIndex}.}
-% \begin{macro}{\percentchar}
-%    Here is one solution for the percent bug in \textsf{makeindex}.
+% \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
+    \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{macro}
+% \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}
 %
 %
@@ -3494,7 +4083,7 @@
 %
 %
 %
-% \subsection{Redefining the \textsf{index} environment}
+% \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
@@ -3502,34 +4091,10 @@
 %\changes{v1.4?}{1989/04/16}{changes to the index env.}
 %\changes{v1.5a}{1989/04/26}{Now input multicol.sty instead of
 %                         multcols.sty}
-% \begin{macro}{\ifhave@multicol}
-% \changes{v1.7a}{1992/03/04}{Added to support avoiding multicol.sty} By
-%    default the index is set in three columns, and will start on the
-%    same page as, and underneath, the last part of the text of the
-%    documented package file, if possible.  The last page will be
-%    reformatted with balanced columns.  This requires the
-%    \textsf{multicols} environment which is described elsewhere.  So
-%    that \DOC{} can be run independently of
-%    \texttt{multicol.sty} we first check for its existence and set
-%    the "have@multicol" flag appropriately for use below.
-%  \changes{v1.9a}{1993/12/02}{Use \cs{IfFileExists}}
-%  \changes{v1.9m}{1994/04/28}{Use \cs{RequirePackage} to load multicol}
-%    \begin{macrocode}
-\newif\ifhave@multicol
-%    \end{macrocode}
-%    If we found \texttt{multicol.sty} we use it.  It would be nice to
-%    delay this (and the re-definition of "theindex") until we knew
-%    whether an index was actually required \ldots
-%    \begin{macrocode}
-\IfFileExists{multicol.sty}{\have@multicoltrue
-                            \RequirePackage{multicol}%
-                           }{}
-%    \end{macrocode}
-% \end{macro}
 
 %
-% \begin{macro}{\IndexMin}
-% \begin{macro}{\c@IndexColumns}
+% \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
@@ -3542,8 +4107,9 @@
 \newdimen\IndexMin         \IndexMin       = 80pt
 \newcount\c@IndexColumns   \c@IndexColumns = 3
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{lcounter}
+% \end{ldimen}
+%
 %
 %
 % \begin{environment}{theindex}
@@ -3557,7 +4123,14 @@
 %    \changes{v1.6e}{1991/04/03}{Turned into env definition.}
 %    \changes{v1.7a}{1992/03/04}{Include test for multicols.}
 %    \begin{macrocode}
-\ifhave@multicol
+\ifdoc@multicol
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+  \RequirePackage{multicol}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
   \renewenvironment{theindex}
     {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]%
 %    \end{macrocode}
@@ -3570,17 +4143,15 @@
 %
 % \begin{macro}{\endtheindex}
 %    \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.}
-%    At the end of the index, we have only to end the \textsf{multicols}
+%    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 \textsf{multicols} we warn the user and use an
+%    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
-  \typeout{Can't find multicol.sty -- will use normal index layout if
-     necessary.}
   \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi
     \columnseprule \z@  \columnsep 35\p@
     \twocolumn[\index@prologue]%
@@ -3591,8 +4162,8 @@
 % \end{macro}
 % \end{environment}
 %
-% Here are the necessary \textsf{makeindex} declarations. We disable
-% scanning of macro names inside the index with "\scan@allowedfalse\n"
+% 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>
@@ -3604,7 +4175,7 @@
 %    \end{macrocode}
 %
 %
-% \begin{macro}{\IndexPrologue}
+% \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}
@@ -3639,11 +4210,11 @@
                  }}{}
 %    \end{macrocode}
 % \end{macro}
-% \end{macro}
+% \end{imacro}
 %
 %
 %
-% \begin{macro}{\IndexParms}
+% \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
@@ -3678,7 +4249,7 @@
        \def\subsubitem{\@idxitem\hspace*{25pt}}%
 %    \end{macrocode}
 % \begin{macro}{\indexspace}
-%    The \textsf{makeindex} program generates an |\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|.
@@ -3690,10 +4261,10 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
-% \end{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\efill}
+% \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
@@ -3706,104 +4277,96 @@
 %<+gind>item_x2   "\\efill \n \\subsubitem "
 %<*package>
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
 %
-% \begin{macro}{\pfill}
-% \begin{macro}{\dotfil}
-% \begin{macro}{\dotfill}
+% \begin{imacro}{\pfill}
 %     The following definitions provide the |\pfill| command; if
-%    this is specified in the index style file to \textsf{makeindex} as
+%    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.
-%  \changes{v2.1i}{2018/09/25}{Guard against following \cs{unskip} (git/23)}
 %    \begin{macrocode}
-\def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus  1fill\kern\z@}%
-\def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil\kern\z@}%
-\def\pfill{\unskip~\dotfill\penalty500\strut\nobreak
-               \dotfil~\ignorespaces}%
+\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{macro}
-% \end{macro}
-% \end{macro}
+% \end{imacro}
 %
 %
 %
-% \begin{macro}{\*}
+% \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{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\main}
+% \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; \textsf{makeindex}
+%    \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{macro}
+% \end{imacro}
 %
-% \begin{macro}{\usage}
+% \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{macro}
+% \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{macro}{\PrintIndex}
+% \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 \textsf{makeidx} package.
+%    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{macro}
+% \end{imacro}
 %
-% \begin{macro}{\printindex}
-%    Since the above macro was called |\printindex| in older versions
-%    of \texttt{doc.sty} the following definition was provided up to
-%    version 1.9y.
-% \changes{v1.9z}{1996/04/17}{Commented out}
-%    \begin{macrocode}
-%\def\printindex{\typeout{\string\printindex\space is obsolete!}%
-%                \typeout{Please use \string\PrintIndex\space
-%                         if you are a macro implementor^^J
-%                         or get a newer version of the documented
-%                         software if you are a user}%
-%                \PrintIndex}
-%    \end{macrocode}
-% \end{macro}
 %
 % We want headings in the index (and changes list) according to the
 % initial character of the next block of entries and have to instruct
-% \textsf{makeindex} appropriately.  Unfortunately the specification
+% \prg{makeindex} appropriately.  Unfortunately the specification
 % for this changed sometime between versions 2.4 and 2.11 of
-% \textsf{makeindex}.  We provide both ways of doing it but
+% \prg{makeindex}.  We provide both ways of doing it but
 % unfortunately this will always produce a warning message from
-% \textsf{makeindex}.  This is for older versions:
+% \prg{makeindex}.  This is for older versions:
 % \changes{v1.7h}{1992/07/01}{Turn off headings in gls file}
 %    \begin{macrocode}
 %</package>
@@ -3839,13 +4402,13 @@
 % is otherwise ignored, but the others are written out and may be used
 % to generate a history of changes, to be printed at the end of the
 % document.  However, note that older versions of Chen's standard
-% \textsf{makeindex}
+% \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{macro}{\changes}
+% \begin{imacro}{\changes}
 % \changes{BHK}{1989/04/26}{Documented \texttt{\protect\bslash changes}
 %                         command.}
 % \changes{BHK}{1989/04/26}{Changed definition of
@@ -3855,9 +4418,9 @@
 %    change in \LaTeX{} 2.09 changed the command name in the
 %    \texttt{.glo} file from \texttt{\bslash indexentry} to
 %    \texttt{\bslash glossaryentry}.  It is therefore necessary to
-%    have a special \textsf{makeindex} style file called
+%    have a special \prg{makeindex} style file called
 %    \texttt{gglo.ist} to process this file correctly.} Thus
-%    \textsf{makeindex} or a similar program can be used to process
+%    \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
@@ -3880,42 +4443,57 @@
    \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
    \changes@}
 \def\changes@#1#2#3{%
-  \protected@edef\@tempa{\noexpand\glossary{#1\levelchar
+  \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
+%    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".
+%    In this case we precede it by |\generalname|.
 %    \begin{macrocode}
-                                 \ifx\saved@macroname\@empty
-                                   \space
-                                   \actualchar
-                                   \generalname
-                                 \else
+                   \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\quotechar*%
-                                   \verbatimchar\saved@macroname
-                                   \verbatimchar
-                                 \fi
-                                 :\levelchar #3}}%
+                      \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 \textsf{macro}
+% \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 \textsf{macro}
+%    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
+%    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}
@@ -3932,17 +4510,17 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\generalname}
+% \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{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\RecordChanges}
+% \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
@@ -3951,17 +4529,16 @@
 %    \begin{macrocode}
 \let\RecordChanges\makeglossary
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\GlossaryMin}
+% \begin{ldimen}{\GlossaryMin}
 %    \changes{BHK}{1989/04/26}{Added to support
 %                            \texttt{\protect\bslash changes}.}
-% \begin{macro}{\c@GlossaryColumns}
+% \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 \textsf{theindex} environment.  When the glossary is
+%    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.
@@ -3972,8 +4549,8 @@
 \newdimen\GlossaryMin         \GlossaryMin       = 80pt
 \newcount\c@GlossaryColumns   \c@GlossaryColumns = 2
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{lcounter}
+% \end{ldimen}
 %
 %
 % \begin{environment}{theglossary}
@@ -3983,13 +4560,12 @@
 %    \changes{v1.6e}{1991/04/03}{Turned into env definition.}
 %    \changes{v1.7a}{1992/03/10}{Changed to work without multicols if
 %                              necessary.}
-% \begin{macro}{\endglossary}
 %    \changes{BHK}{1989/04/26}{Added to support
 %                            \texttt{\protect\bslash changes}.}
-%    The environment \textsf{theglossary} is defined in the same manner
-%    as the \textsf{theindex} environment.
+%    The environment \env{theglossary} is defined in the same manner
+%    as the \env{theindex} environment.
 %    \begin{macrocode}
-\ifhave@multicol
+\ifdoc@multicol
   \newenvironment{theglossary}{%
     \begin{multicols}\c@GlossaryColumns
                      [\glossary@prologue][\GlossaryMin]%
@@ -4004,10 +4580,9 @@
     {\if@restonecol\onecolumn\else\clearpage\fi}
 \fi
 %    \end{macrocode}
-% \end{macro}
 % \end{environment}
 %
-% Here are the necessary \textsf{makeindex} declarations with scanning
+% Here are the necessary \prg{makeindex} declarations with scanning
 % disabled as for the index.
 %    \begin{macrocode}
 %</package>
@@ -4025,7 +4600,7 @@
 %    \end{macrocode}
 %
 %
-% \begin{macro}{\GlossaryPrologue}
+% \begin{imacro}{\GlossaryPrologue}
 %    \changes{BHK}{1989/04/26}{Added to support
 %                            \texttt{\protect\bslash changes}.}
 % \begin{macro}{\glossary@prologue}
@@ -4050,9 +4625,9 @@
                  }}{}
 %    \end{macrocode}
 % \end{macro}
-% \end{macro}
+% \end{imacro}
 %
-% \begin{macro}{\GlossaryParms}
+% \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
@@ -4067,19 +4642,20 @@
      \parfillskip -15pt plus -1fil\relax}
 }{}
 %    \end{macrocode}
-% \end{macro}
-% \begin{macro}{\PrintChanges}
+% \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 |\StopEventually| command, although a
+%    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 \textsf{makeindex} or some other program
+%    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}.}
@@ -4088,7 +4664,7 @@
 \def\PrintChanges{\@input@{\jobname.gls}%
                   \global\let\PrintChanges\@empty}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
 %
@@ -4096,25 +4672,25 @@
 %
 % \subsection{Bells and whistles}
 %
-% \begin{macro}{\StopEventually}
+% \begin{imacro}{\MaybeStop}
 % \changes{v1.5k}{1989/09/04}{Support for checksum.}
-% \begin{macro}{\Finale}
+% \begin{imacro}{\Finale}
 % \changes{v1.5k}{1989/09/04}{Support for checksum.}
 % \changes{v1.5z}{1990/04/22}{Define \cs{Finale} globally.}
-% \begin{macro}{\AlsoImplementation}
+% \begin{imacro}{\AlsoImplementation}
 % \changes{v1.9w}{1995/12/27}{Macro added}
-% \begin{macro}{\OnlyDescription}
+% \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
-%    |\StopEventually| in a way that its argument is typeset at the
+%    |\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\StopEventually##1{\@bsphack\gdef\Finale{##1%
+   \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
@@ -4123,7 +4699,7 @@
 %    \begin{macrocode}
                   \check@checksum}%
 %    \end{macrocode}
-%    On the other hand: |\StopEventually| is more or less a
+%    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|.
@@ -4134,35 +4710,44 @@
 %    \end{macrocode}
 %
 %    Since |\AlsoImplementation| should be the default we execute it
-%    and thus |\StopEventually| gets the desired meaning.
+%    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
-%    |\StopEventually|. We therefore have to redefine this macro.
+%    |\MaybeStop|. We therefore have to redefine this macro.
 %    \begin{macrocode}
-\def\OnlyDescription{\@bsphack\long\def\StopEventually##1{%
+\def\OnlyDescription{\@bsphack\long\def\MaybeStop##1{%
 %    \end{macrocode}
-%    In this case the argument of |\StopEventually| should be set
+%    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 |\StopEventually| command is given we silently ignore a
+%    If no |\MaybeStop| command is given we silently ignore a
 %    |\Finale| issued.
 % \changes{v1.9n}{1994/04/28}{Ignore \cs{Finale} if no
-%                  \cs{StopEventually} is given}
+%                  \cs{MaybeStop} is given}
 %    \begin{macrocode}
 \let\Finale\relax
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+% \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{macro}{\meta}
+% \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.}
@@ -4216,7 +4801,7 @@
      }\ensuremath\rangle
 }
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
 % \begin{macro}{\meta@font@select}
@@ -4228,7 +4813,7 @@
 % \end{macro}
 %
 %
-% \begin{macro}{\IndexInput}
+% \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
@@ -4243,7 +4828,7 @@
 %    \begin{macrocode}
      \begingroup \macro@code
 %    \end{macrocode}
-%    We also make spacing behave as in the \textsf{macrocode}
+%    We also make spacing behave as in the \env{macrocode}
 %    environment, because otherwise all the spaces will be shown
 %    explicitly.
 %    \begin{macrocode}
@@ -4260,10 +4845,10 @@
 %    \begin{macrocode}
      \endgroup}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\maketitle}
+% \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
@@ -4299,56 +4884,56 @@
       \gdef\@date{\today}\gdef\@thanks{}%
       \gdef\@author{}\gdef\@title{}}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\ps@titlepage}
+% \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 \textsf{ltugboat} can define this macro in advance.
+%    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{macro}
+% \end{imacro}
 %
-% \begin{macro}{\MakeShortVerb}
+% \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
+% 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:
+% |\verb|\meta{c}\meta{text}\meta{c}.\footnote{Warning:
 % the commentary in the rest of this section was written by Dave
 % Love.}  In addition, the fact
 % that \meta{c} is made active is recorded for the benefit of the
-% \textsf{verbatim} and \textsf{macrocode} environments.
+% \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".
+% 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
+% 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
+% 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,
+% if he reads the |LOG| file. (Should have used module internal names,
 % 'though.)
 %
-% \begin{macro}{\MakeShortVerb*}
+% \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
+% 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}.
+% |\verb*|\meta{c}\meta{text}\meta{c}.
 %    \begin{macrocode}
 %</package>
 %<*package|shortvrb>
@@ -4357,7 +4942,10 @@
     {\def\@shortvrbdef{\verb*}\@MakeShortVerb}%
     {\def\@shortvrbdef{\verb}\@MakeShortVerb}}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
+% \end{imacro}
+%
+% \begin{macro}{\@MakeShortVerb}
 %    \begin{macrocode}
 \def\@MakeShortVerb#1{%
   \expandafter\ifx\csname cc\string#1\endcsname\relax
@@ -4367,19 +4955,19 @@
     \@shortvrbinfo{Made }{#1}\@shortvrbdef
     \add@special{#1}%
 %    \end{macrocode}
-% Then the character's current catcode is stored in "\cc\"\meta{c}.
+% 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.
+% 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
+% The character's old meaning is recorded in |\ac\|\meta{c} prior to
 % assigning it a new one.
 %    \begin{macrocode}
       \global\expandafter\let
@@ -4398,20 +4986,24 @@
 %    \end{macrocode}
 % \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}}
 %    \begin{macrocode}
-    \@shortvrbinfo\@empty{#1 already}{\@empty\verb(*)}%
+    \@shortvrbinfo\@empty{#1 already}%
+                         {\@empty\verb% % to fool emacs highlighting
+                          (*)}%
   \fi}
 %    \end{macrocode}
 % \end{macro}
-% \begin{macro}{\DeleteShortVerb}
+%
+%
+% \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
+% 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
+% 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
+% |\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}
@@ -4423,19 +5015,24 @@
 % \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(*)}%
+    \@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(*)}%
+    \@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
-%                       \cs{DeleteShortVerb}}
-% We must not forget to reset "\cc\"\meta{c}, otherwise the check in
-% "\MakeShortVerb" for a repeated definition will not work.
+%                       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
@@ -4446,7 +5043,7 @@
           \csname ac\string#1\endcsname}%
       \endgroup \fi \fi}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %  \begin{macro}{\@shortvrbinfo}
 % \changes{v1.9v}{1995/11/03}{(DPC) Macro added}
@@ -4465,12 +5062,12 @@
 % \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
+% |\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
+% 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
+% 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{%
@@ -4478,29 +5075,31 @@
   \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
+% 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
+% 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"!
+% 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.
+% 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{%
@@ -4511,19 +5110,6 @@
 %<*package>
 %    \end{macrocode}
 % \end{macro}
-% \begin{macro}{\MakeShortverb}
-% \begin{macro}{\DeleteShortverb}
-% \changes{v1.7a}{1992/02/27}{Added (from newdoc).}
-% These commands from \textsf{newdoc} are now obsolete.
-%    \begin{macrocode}
-\def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb
-                         syntax, this is obsolete ***}\MakeShortVerb}
-\def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb
-                         syntax, this is obsolete ***}\DeleteShortVerb}
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
 %
 %
 % \subsection[Providing a checksum and character table]
@@ -4535,7 +5121,7 @@
 % \begin{macro}{\init@checksum}
 % The checksum mechanism works by counting backslashes in the
 % macrocode.  This initializes the count (when called from
-% "\StopEventually").
+% |\MaybeStop|).
 % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
 %    \begin{macrocode}
 \def\init@checksum{\relax
@@ -4546,8 +5132,8 @@
 %
 % \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
+% 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}
@@ -4581,12 +5167,12 @@
 % \end{macro}
 %
 %
-% \begin{macro}{\check@sum}
+% \begin{tcounter}{\check@sum}
 % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
-% \begin{macro}{\bslash@cnt}
+% \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
+% 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}
@@ -4594,17 +5180,17 @@
 \newcount\check@sum           \check@sum  = \m@ne
 \newcount\bslash@cnt          \bslash@cnt = \z@
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{tcounter}
+% \end{tcounter}
 %
 %
-% \begin{macro}{\CheckSum}
+% \begin{omacro}{\CheckSum}
 % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.}
-% This is the interface to setting "\check@sum".
+% This is the interface to setting |\check@sum|.
 %    \begin{macrocode}
 \def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack}
 %    \end{macrocode}
-% \end{macro}
+% \end{omacro}
 %
 %
 %
@@ -4617,13 +5203,13 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\CharacterTable}
+% \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
+%    |\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
+%    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
@@ -4635,12 +5221,14 @@
 %    \begin{macrocode}
 \def\CharacterTable{\begingroup \CharTableChanges \character@table}
 %    \end{macrocode}
-% \end{macro}
+% \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.
+% with |~| catcoded to letter.
 %    \begin{macrocode}
 \begingroup
   \catcode`\~=11
@@ -4659,22 +5247,22 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\CharTableChanges}
+% \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
+%    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
+%    ``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''
+%    they are actually equal. For this reason |\CharTableChanges| can
+%    be set up to locally restore the |\catcode|s of such ``letters''
 %    to ``other''.
 %    \begin{macrocode}
   \global\let\CharTableChanges\@empty
 %    \end{macrocode}
-% \end{macro}
+% \end{omacro}
 %
 % \begin{macro}{\default~table}
 % Here's what the table {\em should\/} look like (modulo spaces).
@@ -4719,34 +5307,40 @@
 %
 % The code in this section allows index entries to refer to code line
 % numbers---the number of the first line of macrocode in the
-% \textsf{macro} environment.
+% \env{macro} environment.
 %
 %
 % \begin{macro}{\codeline@index}
-% Indexing by code line is controlled by the "codeline@index" switch.
+% Indexing by code line is controlled by the |codeline@index| switch.
 % \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)}
 % \changes{v1.7a}{1992/02/24}{Documented code line no. support.}
-% \begin{macro}{\CodelineNumbered}
+% \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}
-% \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.
+%    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}}\fi}
+             {\number\c@CodelineNo}}%
+      \endgroup
+    \fi}
 %    \end{macrocode}
 % \end{macro}
+%
 % \begin{macro}{\special@index}
 % By default no index entries are written out.
 %    \begin{macrocode}
@@ -4756,8 +5350,8 @@
 % \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"
+% 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
@@ -4765,17 +5359,17 @@
                    \let\special@index\codeline@wrindex}
 %    \end{macrocode}
 % \end{macro}
-% \begin{macro}{\PageIndex}
-% "\PageIndex" is similar.
+% \begin{imacro}{\PageIndex}
+% |\PageIndex| is similar.
 %    \begin{macrocode}
 \def\PageIndex{\makeindex
                \codeline@indexfalse
                \let\special@index\index}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 %
-% \begin{macro}{\c@CodelineNo}
+% \begin{lcounter}{CodelineNo}
 % \changes{v1.5l}{1989/09/10}{Counter added to support code line
 %                             numbers}
 % \changes{v1.5y}{1990/02/24}{Default changed.}
@@ -4785,7 +5379,8 @@
 %    \begin{macrocode}
 \newcount\c@CodelineNo  \c@CodelineNo\z@
 %    \end{macrocode}
-% \end{macro}
+% \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.}
@@ -4817,7 +5412,6 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \DeleteShortVerb{\"}
 %
 % The following |\mathcode| definitions allow the characters
 % `|\|'
@@ -4835,9 +5429,9 @@
 %                \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$.
+% particularly for something like |\@abc=1|.
 %
-% If an {\em old\/} version of the \textsf{german} package is in
+% 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
@@ -4907,8 +5501,8 @@
 %
 % \subsection{Changing the \texttt{\protect\bslash catcode} of \%}
 %
-% \begin{macro}{\MakePercentIgnore}
-% \begin{macro}{\MakePercentComment}
+% \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
@@ -4919,10 +5513,10 @@
 \def\MakePercentIgnore{\catcode`\%9\relax}
 \def\MakePercentComment{\catcode`\%14\relax}
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{imacro}
+% \end{imacro}
 %
-% \begin{macro}{\DocInput}
+% \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
@@ -4930,7 +5524,7 @@
 %    \begin{macrocode}
 \def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
 %    \end{macrocode}
-% \end{macro}
+% \end{imacro}
 %
 % \subsection{GetFileInfo}
 %
@@ -4951,6 +5545,779 @@
 %    \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 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{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}{\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>
@@ -4958,5 +6325,15 @@
 %
 %
 % \Finale
-% \PrintIndex \PrintChanges
+% \PrintChanges
+%
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \endinput
+
+^^A  Needed for emacs
+^^A
+^^A  Local Variables: 
+^^A  mode: latex
+^^A  coding: utf-8-unix
+^^A  End: