% \iffalse meta-comment
%
%% File: l3doc.dtx
%
% Copyright (C) 1990-2024 The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
\input docstrip %
\askforoverwritefalse
\preamble

Copyright (C) 1990-2024 The LaTeX Project

It may be distributed and/or modified under the conditions of
the LaTeX Project Public License (LPPL), either version 1.3c of
this license or (at your option) any later version.  The latest
version of this license is in the file:

   https://www.latex-project.org/lppl.txt

This file is part of the "l3kernel bundle" (The Work in LPPL)
and all files in that bundle must be distributed together.

\endpreamble
% stop docstrip adding \endinput
\postamble
\endpostamble
\generate{\file{l3doc.cls}{\from{l3doc.dtx}{class,cfg}}}
%\generate{\file{l3doc.ist}{\from{l3doc.dtx}{docist}}}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</driver>
%
%<*driver|class>
\RequirePackage{calc}
%</driver|class>
%
%<*driver>
\documentclass{l3doc}
\usepackage{framed}
\begin{document}
  \DocInput{l3doc.dtx}
\end{document}
%</driver>
%
% This isn't included in the typeset documentation because it's a bit
% ugly:
%<*class>
\ProvidesExplClass{l3doc}{2024-03-14}{}
  {L3 Experimental documentation class}
%</class>
% \fi
%
% \title{The \cls{l3doc} class -- experimental\thanks{%
%    On popular request we now distribute the document for this
%    experimental class.  However, please note that it is by no means
%    in final state and is \emph{likely} to undergo modifications,
%    even \emph{incompatible ones}! Thus, using it might therefore
%    require you to do updates, if the class changes.}}
%
% \author{\Team}
% \date{Released 2024-03-14}
% \maketitle
% \tableofcontents
%
% \begin{documentation}
%
%
% \section{Introduction}
%
% Code and documentation for this class have been written prior to the
% change of \pkg{doc} from version 2 to version 3, which already shows
% how far behind this class currently is. So take the following
% warning seriously please:
%
%  \begin{quote}
% \textbf{It is much less stable than the main \pkg{expl3} packages.\\
%   Use at own risk!}
%  \end{quote}
%
% This is an ad-hoc class for documenting the \pkg{expl3} bundle, a
% collection of modules or packages that make up \LaTeX3's programming
% environment.  Eventually it will replace the \cls{ltxdoc} class for
% \LaTeX3, but not before the good ideas in \pkg{hypdoc}, \cls{xdoc2},
% \pkg{docmfp}, and \cls{gmdoc} are incorporated.
%
% It is written as a \enquote{self-contained} docstrip file: executing
% |latex l3doc.dtx| generates the \file{l3doc.cls} file and typesets
% this documentation; execute |tex l3doc.dtx| to only generate
% \file{l3doc.cls}.
%
% \section{Features of other packages}
%
% This class builds on the \pkg{ltxdoc} class and the \pkg{doc} package,
% but in the time since they were originally written some improvements
% and replacements have appeared that we would like to use as
% inspiration.
%
% These packages or classes are \pkg{hypdoc}, \pkg{docmfp}, \pkg{gmdoc},
% and \pkg{xdoc}.  I have summarised them below in order to work out
% what sort of features we should aim at a minimum for \pkg{l3doc}.
%
% \subsection{The \pkg{hypdoc} package}
%
% This package provides hyperlink support for the \pkg{doc} package.  I
% have included it in this list to remind me that cross-referencing
% between documentation and implementation of methods is not very
% good. (\emph{E.g.}, it would be nice to be able to automatically
% hyperlink the documentation for a function from its implementation and
% vice-versa.)
%
% \subsection{The \pkg{docmfp} package}
%
% \begin{itemize}
%   \item Provides \cs{DescribeRoutine} and the \env{routine}
%     environment (\emph{etc.}) for MetaFont and MetaPost code.
%   \item Provides \cs{DescribeVariable} and the \env{variable}
%     environment (\emph{etc.})  for more general code.
%   \item Provides \cs{Describe} and the \env{Code} environment
%     (\emph{etc.})  as a generalisation of the above two
%     instantiations.
%   \item Small tweaks to the DocStrip system to aid non-\LaTeX{} use.
% \end{itemize}
%
% \subsection{The \pkg{xdoc2} package}
%
% \begin{itemize}
%   \item Two-sided printing.
%   \item \cs{NewMacroEnvironment}, \cs{NewDescribeEnvironment}; similar
%     idea to \pkg{docmfp} but more comprehensive.
%   \item Tons of small improvements.
% \end{itemize}
%
% \subsection{The \pkg{gmdoc} package}
%
% Radical re-implementation of \pkg{doc} as a package or class.
% \begin{itemize}
%   \item Requires no |\begin{macrocode}| blocks!
%   \item Automatically inserts |\begin{macro}| blocks!
%   \item And a whole bunch of other little things.
% \end{itemize}
%
% \section{Problems \& Todo}
%
% Problems at the moment:
% (1)~not flexible in the types of things that can be documented;
% (2)~no obvious link between the |\begin{function}| environment for
%     documenting things to the |\begin{macro}| function that's used
%     analogously in the implementation.
%
% The \env{macro} should probably be renamed to \env{function} when it
% is used within an implementation section.  But they should have the
% same syntax before that happens!
%
% Furthermore, we need another \enquote{layer} of documentation commands
% to account for \enquote{user-macro} as opposed to
% \enquote{code-functions}; the \pkg{expl3} functions should be
% documented differently, probably, to the \pkg{ltcmd} user macros (at
% least in terms of indexing).
%
% In no particular order, a list of things to do:
% \begin{itemize}
%   \item Rename \env{function}/\env{macro} environments to better
%     describe their use.
%   \item Generalise \env{function}/\env{macro} for documenting
%     \enquote{other things}, such as environment names, package
%     options, even keyval options.
%   \item New function like \tn{part} but for files (remove awkward
%     \enquote{File} as \tn{partname}).
%   \item Something better to replace \cs{StopEventually}; I'm thinking
%     two environments \env{documentation} and \env{implementation} that
%     can conditionally typeset/ignore their material.  (This has been
%     implemented but needs further consideration.)
%   \item Hyperlink documentation and implementation of macros (see the
%     \textsc{dtx} file of \pkg{svn-multi} v2 as an example).  This is
%     partially done, now, but should be improved.
% \end{itemize}
%
% \section{Documentation}
%
% \subsection{Configuration}
%
% Before class options are processed, \pkg{l3doc} loads a configuration
% file \file{l3doc.cfg} if it exists, allowing you to customise the
% behaviour of the class without having to change the documentation
% source files.
%
% For example, to produce documentation on letter-sized paper instead of
% the default A4 size, create \file{l3doc.cfg} and include the line
% \begin{verbatim}
% \PassOptionsToClass{letterpaper}{l3doc}
% \end{verbatim}
%
% By default, \pkg{l3doc} selects the |T1| font encoding and loads the
% Latin Modern fonts.  To prevent this, use the class option
% |cm-default|.
%
% \subsection{Class options}
%
% The class recognises a number of options, some of which are generally
% useful and some of which are aimed squarely at use by the kernel team only.
%
% \DescribeOption{full}
% \DescribeOption{onlydoc}
% When the \texttt{full} option is set (the standard setting), both the
% documentation and implementation parts of the source are typeset. If on the
% other hand the \texttt{onlydoc} option is set, only the documentation part
% is typeset.
%
% \DescribeOption{lm-default}
% Selects whether the standard font set up is Latin Modern in the \texttt{T1}
% encoding (the standard setting) or leaves the font setup unchanged.
%
% \DescribeOption{kernel}
% Determines whether \pkg{l3doc} treats internal functions and variables
% belonging to |kernel| module as allowable in code, for instance
% \cs{__kernel_tl_to_str:w}, \cs{c__kernel_expl_date_tl}, and
% \cs{l__kernel_expl_bool}. In general,
% \emph{no} internal material from outside the current module is allowed.
% However, for bootstrapping the \pkg{expl3} kernel, a small number of
% cross-module functions are needed. To suppress the error message that
% would otherwise arise, the class option \texttt{kernel} may be given.
%
% \DescribeOption{check}
% When the \texttt{check} option is given, the class will record all commands
% defined and documented in a \texttt{\meta{name}.cmds} file. This will show
% which are both documented and defined, which are only documented and which
% are only defined. (Here, \enquote{defined} means listed using a
% \texttt{macro} or \texttt{variable} environment in the implementation part of
% the source file).
%
% \DescribeOption{checktest}
% When \texttt{checktest} is given as an option, the class will check that each
% function entry in the implementation part of the source is marked using
% \cs{UnitTest}.
%
% \DescribeOption{show-notes}
% \DescribeOption{hide-notes}
% These complementary options determine if the information given using the
% \cs{NB} and \cs{NOTE} commands is printed.
%
% \DescribeOption{cs-break}
% \DescribeOption{cs-break-nohyphen}
% The commands \cs{cmd} and \cs{cs} allow hyphenation of control sequences
% after (most) underscores. By default, a hyphen is used to mark the
% hyphenation, but this can be changed with the \texttt{cs-break-nohyphen}
% class option. To disable hyphenation of control sequences entirely, use
% \texttt{cs-break = false}.
%
% By default, class options
% \begin{verbatim}
%   full , check = false , checktest = false , lm-default
% \end{verbatim}
% are set.
%
% \subsection{Partitioning documentation and implementation}
%
% \pkg{doc} uses the \cs{OnlyDocumentation}/\cs{AlsoImplementation}
% macros to guide the use of \cs{StopEventually}|{}|, which is intended
% to be placed to partition the documentation and implementation within
% a single \file{.dtx} file.
%
% This isn't very flexible, since it assumes that we \emph{always} want
% to print the documentation.  For the \pkg{expl3} sources, I wanted to
%  be able to input \file{.dtx} files in two modes: only displaying
% the documentation, and only displaying the implementation.  For
% example:
% \begin{verbatim}
% \DisableImplementation
% \DocInput{l3basics,l3prg,...}
% \EnableImplementation
% \DisableDocumentation
% \DocInputAgain
% \end{verbatim}
%
% The idea being that the entire \pkg{expl3} bundle can be documented,
% with the implementation included at the back.  Now, this isn't
% perfect, but it's a start.
%
% Use |\begin{documentation}...\end{documentation}| around the
% documentation, and |\begin{implementation}...\end{implementation}|
% around the implementation.  The
% \cs{EnableDocumentation}/\cs{EnableImplementation} causes them to
% be typeset when the \file{.dtx} file is \cs{DocInput}; use
% \cs{DisableDocumentation}/\cs{DisableImplementation} to omit the
% contents of those environments.
%
% Note that \cs{DocInput} now takes comma-separated arguments, and
% \cs{DocInputAgain} can be used to re-input all \file{.dtx} files
% previously input in this way.
%
% \subsection{General text markup}
%
% Many of the commands in this section come from \pkg{ltxdoc} with some
% improvements.
%
% \begin{function}{\cmd, \cs}
%   \begin{syntax}
%     \cmd{\cmd} \oarg{options} \meta{control sequence}\\
%     \cs{cs} \oarg{options} \marg{csname}
%   \end{syntax}
%   These commands are provided to typeset control sequences.
%   |\cmd\foo| produces \enquote{\cmd\foo} and |\cs{foo}| produces the
%   same.  In general, \cs{cs} is more robust since
%   it doesn't rely on catcodes being \enquote{correct} and is therefore
%   recommended.
%
%   These commands are aware of the |@@| \pkg{DocStrip} syntax and
%   replace such instances correctly in the typeset documentation.
%   This only happens after a |%<@@=|\meta{module}|>| declaration.
%
%   Additionally, commands can be used in the argument of \cs{cs}.  For
%   instance, |\cs{\meta{name}:\meta{signature}}| produces
%   \cs[no-index]{\meta{name}:\meta{signature}}.
%
%   The \meta{options} are a key--value list which can contain the
%   following keys:
%   \begin{itemize}
%     \item |index=|\meta{name}: the \meta{csname} is indexed as if
%       one had written \cs{cs}\Arg{name}.
%     \item |no-index|: the \meta{csname} is not indexed.
%     \item |module=|\meta{module}: the \meta{csname} is indexed in
%       the list of commands from the \meta{module}; the \meta{module}
%       can in particular be |TeX| for \enquote{\TeX{} and \LaTeXe{}}
%       commands, or empty for commands which should be placed in the
%       main index.  By default, the \meta{module} is deduced
%       automatically from the command name.
%     \item |replace| is a boolean key (\texttt{true} by default) which
%       indicates whether to replace |@@| as \pkg{DocStrip} does.
%   \end{itemize}
%   These commands allow hyphenation of control sequences after (most) underscores.
%   By default, a hyphen is used to mark the hyphenation, but this can be changed with
%   the \texttt{cs-break-nohyphen} class option.
%   To disable hyphenation of control sequences entirely, use
%   \texttt{cs-break = false}.
% \end{function}
%
%
% \begin{function}{\tn}
%   \begin{syntax}
%     \cs{tn} \oarg{options} \marg{csname}
%   \end{syntax}
%   Analoguous to \cs{cs} but intended for \enquote{traditional} \TeX{}
%   or \LaTeXe{} commands; they are indexed accordingly.  This is in
%   fact equivalent to \cs{cs} |[module=TeX, replace=false,|
%   \meta{options}|]| \Arg{csname}.
% \end{function}
%
% \begin{function}{\meta}
%   \begin{syntax}
%     \cs{meta} \Arg{name}
%   \end{syntax}
%   \cs{meta} typesets the \meta{name} italicised in \meta{angle
%     brackets}.  Within a \env{function} environment or similar, angle
%   brackets |<...>| are set up to be a shorthand for |\meta{...}|.
%
%   This function has additional functionality over its \pkg{ltxdoc}
%   versions; underscores can be used to subscript material as in math
%   mode.  For example, |\meta{arg_{xy}}| produces
%   \enquote{\meta{arg_{xy}}}.
% \end{function}
%
% \begin{function}{\Arg, \marg, \oarg, \parg}
%   \begin{syntax}
%     |\Arg| \Arg{name}
%   \end{syntax}
%   Typesets the \meta{name} as for \cs{meta} and wraps it in braces.
%
%   The \cs{marg}/\cs{oarg}/\cs{parg} versions follow from \pkg{ltxdoc}
%   in being used for \enquote{mandatory} or \enquote{optional} or
%   \enquote{picture} brackets as per \LaTeXe{} syntax.
% \end{function}
%
% \begin{function}{\file, \env, \pkg, \cls}
%   \begin{syntax}
%     \cs{pkg} \Arg{name}
%   \end{syntax}
%   These all take one argument and are intended to be used as semantic
%   commands for representing files, environments, package names, and
%   class names, respectively.
% \end{function}
%
% \begin{function}{\NB, \NOTE}
%   \begin{syntax}
%     \cs{NB} \marg{tag} \marg{comments}
%     \verb|\begin{NOTE}| \marg{tag}
%     \qquad\meta{comments}
%     \verb|\end{NOTE}|
%   \end{syntax}
%   Make notes in the source that are not typeset by default. When the \verb|show-notes|
%   class option is active, the comments are typeset in a detokenized and verbatim mode, respectively.
% \end{function}
%
% \subsection{Describing functions in the documentation}
%
% \DescribeEnv{function}
% \DescribeEnv{variable}
% Two heavily-used environments are defined to describe \pkg{expl3} functions
% and variables.  If describing a variable, use the latter environment; it
% behaves identically to the \env{function} environment.
% \DescribeEnv{syntax}
% Both of the above environments are typically combined with the \env{syntax}
% environment, to describe their syntax.
% \begin{framed}
%   \vspace{-\baselineskip}
% \begin{verbatim}
% \begin{function}{\package_function_one:N, \package_function_two:n}
%   \begin{syntax}
%     \cs{package_function_one:N} \meta{cs}
%     \cs{package_function_two:n} \marg{Argument}
%   \end{syntax}
% Descriptive text here ...
% \end{function}
% \end{verbatim}
%   \hrulefill
%   \par
%   \hspace*{0.25\textwidth}
%   \begin{minipage}{0.5\textwidth}
%     \begin{function}{\package_function_one:N, \package_function_two:n}
%       \begin{syntax}
%         \cs[no-index]{package_function_one:N} \meta{cs}
%         \cs[no-index]{package_function_two:n} \marg{Argument}
%       \end{syntax}
%       \emph{Descriptive text here …}
%     \end{function}
%   \end{minipage}
% \end{framed}
%
% Function environments take an optional argument to indicate whether
% the function(s) it describes are expandable (use |EXP|) or
% restricted-expandable (use |rEXP|) or defined in conditional forms
% (use |TF|, |pTF|, or |noTF|).  Note that |pTF| implies |EXP| since
% predicates must always be expandable, and that |noTF| means that the
% function without |TF| should be documented in addition to |TF|.  For
% the conditional forms |TF| and |pTF|, the argument of the
% \env{function} environment is \emph{not} in fact a command that
% exists: in the example below, \cs[no-index]{tl_if_empty:N} does not
% exist, but its conditional forms \cs{tl_if_empty:NT},
% \cs{tl_if_empty:NF}, \cs{tl_if_empty:NTF} and predicate form
% \cs{tl_if_empty_p:N} exist:
% \begin{framed}
%   \vspace{-\baselineskip}
% \begin{verbatim}
% \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c}
%   \begin{syntax}
%     \cs{tl_if_empty_p:N} \meta{tl~var}
%     \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests if the \meta{token list variable} is entirely empty
%   (\emph{i.e.}~contains no tokens at all).
% \end{function}
% \end{verbatim}
%   \hrulefill
%   \par
%   \hspace*{0.25\textwidth}
%   \begin{minipage}{0.5\textwidth}
%     \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c}
%       \begin{syntax}
%         \cs{tl_if_empty_p:N} \meta{tl~var}
%         \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
%       \end{syntax}
%       Tests if the \meta{token list variable} is entirely empty
%       (\emph{i.e.}~contains no tokens at all).
%     \end{function}
%   \end{minipage}
% \end{framed}
%
% \DescribeEnv{texnote}
% This environment is used to call out sections within \env{function}
% and similar environments that are only of interest to seasoned
% \TeX{} developers.
%
% \subsection{Describing functions in the implementation}
%
% \DescribeEnv{macro}
% The well-used environment from \LaTeXe{} for marking up the
% implementation of macros/functions remains the \env{macro}
% environment.  Some changes in \pkg{l3doc}: it now accepts
% comma-separated lists of functions, to avoid a very large number of
% consecutive |\end{macro}| statements.
% Spaces and new lines are ignored (the option |[verb]| prevents this).
% \begin{verbatim}
% % \begin{macro}{\foo:N, \foo:c}
% %   \begin{macrocode}
% ... code for \foo:N and \foo:c ...
% %   \end{macrocode}
% % \end{macro}
% \end{verbatim}
% If you are documenting an auxiliary macro, it's generally not
% necessary to highlight it as much and you also don't need to check it
% for, say, having a test function and having a documentation chunk
% earlier in a \env{function} environment.  \pkg{l3doc} will pick up these
% cases from the presence of |__| in the name, or you may force marking
% as internal by using |\begin{macro}[int]| to mark it as such. The margin
% call-out is then printed in grey for such cases.
%
% For documenting \pkg{expl3}-type conditionals, you may also pass this
% environment a |TF| option (and omit it from the function name) to
% denote that the function is provided with |T|, |F|, and |TF| suffixes.
% A similar |pTF| option prints both |TF| and |_p| predicate forms.
% An option |noTF| prints both the |TF| forms and a form with neither
% |T| nor |F|, to document functions such as \cs[no-index]{prop_get:NN}
% which also have conditional forms (\cs[no-index]{prop_get:NNTF}).
%
% In a very small number of cases, there is no user documentation for
% a \enquote{public} function. In these rare cases, the option
% |no-user-doc| may be added to suppress the undefined reference that
% would otherwise then arises.
%
% \DescribeMacro{\TestFiles}
% \cs{TestFiles}\marg{list of files} is used to indicate which test
% files are used for the current code; they are printed in the
% documentation.
%
% \DescribeMacro{\UnitTested}
% Within a \env{macro} environment, it is a good idea to mark whether a
% unit test has been created for the commands it defines.  This is
% indicated by writing \cs{UnitTested} anywhere within |\begin{macro}|
%   \dots |\end{macro}|.
%
% If the class option |checktest| is enabled, then it is an \emph{error}
% to have a \env{macro} environment without a call to
% \file{Testfiles}.  This is intended for large packages such as
% \pkg{expl3} that should have absolutely comprehensive tests suites and
% whose authors may not always be as sharp at adding new tests with new
% code as they should be.
%
% \DescribeMacro{\TestMissing}
% If a function is missing a test, this may be flagged by writing (as
% many times as needed) \cs{TestMissing} \marg{explanation of test
%   required}.  These missing tests are summarised in the listing
% printed at the end of the compilation run.
%
% \DescribeEnv{variable}
% When documenting variable definitions, use the \env{variable}
% environment instead.  Here it behaves identically to the
% \env{macro} environment, except that if the class option |checktest|
% is enabled, variables are not required to have a test file.
%
% \DescribeEnv{arguments}
% Within a \env{macro} environment, you may use the \env{arguments}
% environment to describe the arguments taken by the function(s).  It
% behaves like a modified enumerate environment.
% \begin{verbatim}
% % \begin{macro}{\foo:nn, \foo:VV}
% % \begin{arguments}
% %   \item Name of froozle to be frazzled
% %   \item Name of muble to be jubled
% % \end{arguments}
% %   \begin{macrocode}
% ... code for \foo:nn and \foo:VV ...
% %   \end{macrocode}
% % \end{macro}
% \end{verbatim}
%
%
% \subsection{Keeping things consistent}
%
% Whenever a function is either documented or defined with
% \env{function} and \env{macro} respectively, its name is stored in a
% sequence for later processing.
%
% At the end of the document (\emph{i.e.}, after the \file{.dtx} file
% has finished processing), the list of names is analysed to check
% whether all defined functions have been documented and vice versa. The
% results are printed in the console output.
%
% If you need to do more serious work with these lists of names, take a
% look at the implementation for the data structures and methods used to
% store and access them directly.
%
% \subsection{Documenting templates}
%
% The following macros are provided for documenting templates; might end
% up being something completely different but who knows.
% \begin{quote}\parskip=0pt\obeylines
%   |\begin{TemplateInterfaceDescription}| \Arg{template type name}
%   |  \TemplateArgument{none}{---}|
%   \textsc{or one or more of these:}
%   |  \TemplateArgument| \Arg{arg no} \Arg{meaning}
%   \textsc{and}
%   |\TemplateSemantics|
%   |  | \meta{text describing the template type semantics}
%   |\end{TemplateInterfaceDescription}|
% \end{quote}
%
% \begin{quote}\parskip=0pt\obeylines
%   |\begin{TemplateDescription}| \Arg{template type name} \Arg{name}
%   \textsc{one or more of these:}
%   |  \TemplateKey| \marg{key name} \marg{type of key}
%   |    |\marg{textual description of meaning}
%   |    |\marg{default value if any}
%   \textsc{and}
%   |\TemplateSemantics|
%   |  | \meta{text describing special additional semantics of the template}
%   |\end{TemplateDescription}|
% \end{quote}
%
% \begin{quote}\parskip=0pt\obeylines
%   |\begin{InstanceDescription}| \oarg{text to specify key column width (optional)}
%   \hfill\marg{template type name}\marg{instance name}\marg{template name}
%   \textsc{one or more of these:}
%   |  \InstanceKey| \marg{key name} \marg{value}
%   \textsc{and}
%   |\InstanceSemantics|
%   |  | \meta{text describing the result of this instance}
%   |\end{InstanceDescription}|
% \end{quote}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3doc} implementation}
%
%    \begin{macrocode}
%<*class>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=codedoc>
%    \end{macrocode}
%
% \subsection{Variables}
%
% \begin{variable}{\g_docinput_clist}
%   The list of files which have been input through \cs{DocInput}.
%    \begin{macrocode}
\clist_new:N \g_docinput_clist
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_doc_functions_seq, \g_doc_macros_seq}
%   All functions documented through \env{function}, and all macros
%   introduced through \env{macro}.  They can be compared to see what
%   documentation or code is missing.
%    \begin{macrocode}
\seq_new:N \g_doc_functions_seq
\seq_new:N \g_doc_macros_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_detect_internals_bool, \l_@@_detect_internals_tl}
%   If \texttt{true}, \pkg{l3doc} will check for use of internal
%   commands \cs[no-index]{__\meta{pkg}_\ldots{}} from other packages in
%   the argument of the \texttt{macro} environment, and in the code typeset in
%   \texttt{macrocode} environments, but not in~\cs{cs}.  Also a token list
%   to store temporary data for this purpose.
%    \begin{macrocode}
\bool_new:N \l_@@_detect_internals_bool
\bool_set_true:N \l_@@_detect_internals_bool
\tl_new:N \l_@@_detect_internals_tl
\tl_new:N \l_@@_detect_internals_cs_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_output_coffin}
%   The \env{function} environment is typeset by combining coffins
%   containing various pieces (function names, description, \emph{etc.})
%   into this coffin.
%    \begin{macrocode}
\coffin_new:N \l_@@_output_coffin
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {\l_@@_functions_coffin, \l_@@_descr_coffin, \l_@@_syntax_coffin}
%   These coffins contain respectively the list of function names
%   (argument of the \env{function} environment), the text between
%   |\begin{function}| and |\end{function}|, and the syntax given in the
%   \env{syntax} environment.
%    \begin{macrocode}
\coffin_new:N \l_@@_functions_coffin
\coffin_new:N \l_@@_descr_coffin
\coffin_new:N \l_@@_syntax_coffin
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_syntax_box}
%   The contents of the \env{syntax} environment are typeset in this box
%   before being transferred to \cs{l_@@_syntax_coffin}.
%    \begin{macrocode}
\box_new:N \g_@@_syntax_box
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_in_function_bool}
%   True when inside a \texttt{function} or \texttt{variable}
%   environment.  Used by the \texttt{syntax} environment to determine
%   its behaviour.
%    \begin{macrocode}
\bool_new:N \l_@@_in_function_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_long_name_bool, \l_@@_trial_width_dim}
%   The boolean \cs{l_@@_long_name_bool} is \texttt{true} if the width
%   \cs{l_@@_trial_width_dim} of the coffin \cs{l_@@_functions_coffin}
%   (containing the current function names) is bigger than the space
%   available in the margin.
%    \begin{macrocode}
\bool_new:N \l_@@_long_name_bool
\dim_new:N \l_@@_trial_width_dim
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_nested_macro_int}
%   The nesting of \env{macro} environments (this is now~$0$ outside a
%   \env{macro} environment).
%    \begin{macrocode}
\int_new:N \l_@@_nested_macro_int
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \l_@@_macro_tested_bool,
%     \g_@@_missing_tests_prop,
%     \g_@@_not_tested_seq,
%     \g_@@_testfiles_seq,
%   }
%   A boolean describing whether the current macro has tests, and some
%   global structures which contain information about test files and
%   which tests are missing.
%    \begin{macrocode}
\bool_new:N \l_@@_macro_tested_bool
\prop_new:N \g_@@_missing_tests_prop
\seq_new:N \g_@@_not_tested_seq
\seq_new:N \g_@@_testfiles_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \l_@@_macro_deprecated_bool ,
%     \l_@@_macro_internal_bool,
%     \l_@@_macro_nodoc_bool ,
%     \l_@@_macro_TF_bool,
%     \l_@@_macro_pTF_bool,
%     \l_@@_macro_noTF_bool,
%     \l_@@_macro_EXP_bool,
%     \l_@@_macro_rEXP_bool,
%     \l_@@_macro_var_bool,
%     \l_@@_override_module_tl,
%     \l_@@_macro_documented_tl,
%   }
%   Contain information about some options of function/macro
%   environments.  We initialize \cs{l_@@_override_module_tl} to avoid
%   overriding module names by an empty name (meaning no module).
%    \begin{macrocode}
\bool_new:N \l_@@_macro_deprecated_bool
\bool_new:N \l_@@_macro_internal_bool
\bool_new:N \l_@@_macro_nodoc_bool
\bool_new:N \l_@@_macro_TF_bool
\bool_new:N \l_@@_macro_pTF_bool
\bool_new:N \l_@@_macro_noTF_bool
\bool_new:N \l_@@_macro_EXP_bool
\bool_new:N \l_@@_macro_rEXP_bool
\bool_new:N \l_@@_macro_var_bool
\tl_new:N \l_@@_override_module_tl
\tl_set:Nn \l_@@_override_module_tl { \q_no_value }
\tl_new:N \l_@@_macro_documented_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \g_@@_lmodern_bool,
%     \g_@@_checkfunc_bool,
%     \g_@@_checktest_bool,
%     \g_@@_cs_break_bool,
%     \g_@@_show_notes_bool,
%     \g_@@_kernel_bool
%   }
%   Information about package options.
%    \begin{macrocode}
\bool_new:N \g_@@_lmodern_bool
\bool_new:N \g_@@_checkfunc_bool
\bool_new:N \g_@@_checktest_bool
\bool_new:N \g_@@_kernel_bool
\bool_new:N \g_@@_cs_break_bool
\bool_new:N \g_@@_show_notes_bool
\bool_gset_true:N \g_@@_cs_break_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_tmpa_tl, \l_@@_tmpb_tl, \l_@@_tmpa_int, \l_@@_tmpa_seq}
%   Some temporary variables.
%    \begin{macrocode}
\tl_new:N \l_@@_tmpa_tl
\tl_new:N \l_@@_tmpb_tl
\int_new:N \l_@@_tmpa_int
\int_new:N \l_@@_tmpa_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_names_block_tl}
%   List of local sequence variables (produced through
%   \cs{@@_lseq_name:n}), one for each set of variants in a
%   \env{function} or \env{macro} environment.  More precisely these
%   sequences are named after the base forms, such as \cs{clist_count:n}
%   or \cs{clist_count:N} (which are not variants).  Each of these
%   sequences have the base name (without any signature) as their first
%   item, followed by the list of variant's signatures, or
%   \cs{scan_stop:} to denote the absence of signature (no colon).
%    \begin{macrocode}
\tl_new:N \l_@@_names_block_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_variants_seq}
%   Stores rather temporarily the list of variants (signatures only) of
%   a function/macro that is being documented.  It is global because we
%   need it to keep its value throughout cells of an alignment.
%    \begin{macrocode}
\seq_new:N \g_@@_variants_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_names_verb_bool}
%   Set to |true| if the main argument of a macro/function environment
%   should be used as is, without removing any comma or space.
%    \begin{macrocode}
\bool_new:N \l_@@_names_verb_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_names_seq}
%   List of functions/environments/\ldots{} appearing as arguments of a
%   given \env{function} or \env{macro} environment.  These are the
%   names after conversion of |_@@| and |@@| to |__|\meta{module name}
%   and other sanitizing.
%    \begin{macrocode}
\seq_new:N \l_@@_names_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_nested_names_seq}
%   Collects all macros in nested \env{macro} environments, to use them
%   in the \enquote{End definition} text.
%    \begin{macrocode}
\seq_new:N \g_@@_nested_names_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \l_@@_index_macro_tl, \l_@@_index_key_tl,
%     \l_@@_index_module_tl, \l_@@_index_internal_bool,
%     \l_@@_macro_do_not_index_tl
%   }
%   When analyzing a control sequence found within a \env{macrocode}
%   environment, \cs{l_@@_index_macro_tl} holds the control sequence
%   (partially a string), \cs{l_@@_index_key_tl} holds the future
%   sort key in the index, and \cs{l_@@_index_module_tl} is the
%   subindex in which the control sequence should be listed.
%   \cs{l_@@_index_internal_bool} indicates when the control sequence is
%   internal and should be indexed in a slightly different subindex.
%   Finally, \cs{l_@@_macro_do_not_index_tl} indicates control sequences
%   which should not be indexed in a specifiv \env{macro} envronment.
%    \begin{macrocode}
\tl_new:N \l_@@_index_macro_tl
\tl_new:N \l_@@_index_key_tl
\tl_new:N \l_@@_index_module_tl
\tl_new:N \l_@@_macro_do_not_index_tl
\bool_new:N \l_@@_index_internal_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_module_name_tl}
%   The module name, set when reading a line |<@@=|\meta{module}|>|.
%    \begin{macrocode}
\tl_new:N \g_@@_module_name_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\c_@@_iow_rule_tl, \c_@@_iow_midrule_tl}
%   $40$~equal signs.
%    \begin{macrocode}
\tl_const:Nn \c_@@_iow_rule_tl
  { ======================================== }
\tl_const:Nn \c_@@_iow_mid_rule_tl
  { -------------------------------------- }
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {\l_@@_macro_box, \l_@@_macro_index_box, \l_@@_macro_int}
%   A vertical box in which the names given to the macro environment are
%   typeset, a horizontal box in which we store the targets created by
%   indexing commands, and the number of macros so far (including those
%   from surrounding \env{macro} environments).
%    \begin{macrocode}
\box_new:N \l_@@_macro_box
\box_new:N \l_@@_macro_index_box
\int_new:N \l_@@_macro_int
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \l_@@_cmd_tl,
%     \l_@@_cmd_index_tl,
%     \l_@@_cmd_module_tl,
%     \l_@@_cmd_noindex_bool,
%     \l_@@_cmd_replace_bool,
%   }
%   Variables used to control the behaviour of \cs{cmd}, \cs{cs} and
%   \cs{tn}.
%    \begin{macrocode}
\tl_new:N \l_@@_cmd_tl
\tl_new:N \l_@@_cmd_index_tl
\tl_new:N \l_@@_cmd_module_tl
\bool_new:N \l_@@_cmd_noindex_bool
\bool_new:N \l_@@_cmd_replace_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_in_implementation_bool}
%   This boolean is \texttt{true} within the \env{implementation}
%   environment, and \texttt{false} anywhere else.
%    \begin{macrocode}
\bool_new:N \l_@@_in_implementation_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \g_@@_typeset_documentation_bool,
%     \g_@@_typeset_implementation_bool
%   }
%   These booleans control whether the documentation/implementation
%   should be typeset.  By default both should be.
%    \begin{macrocode}
\bool_new:N \g_@@_typeset_documentation_bool
\bool_new:N \g_@@_typeset_implementation_bool
\bool_set_true:N \g_@@_typeset_documentation_bool
\bool_set_true:N \g_@@_typeset_implementation_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_base_name_tl, \l_@@_variants_prop}
%   The name of the macro which is being documented (without its
%   signature), and a property list mapping base forms of variants to
%   all variants which have the same base form.
%    \begin{macrocode}
\tl_new:N \g_@@_base_name_tl
\prop_new:N \l_@@_variants_prop
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_function_label_clist, \l_@@_no_label_bool}
%   Option of a \env{function} environment which replaces the label that
%   would normally be inserted by labels for the given list of control
%   sequences.  This is only useful to avoid duplicate labels when a
%   function's documentation appears multiple times.
%    \begin{macrocode}
\clist_new:N \l_@@_function_label_clist
\bool_new:N \l_@@_no_label_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_date_added_tl, \l_@@_date_updated_tl}
%   Values of some options of the \env{function} environment.
%    \begin{macrocode}
\tl_new:N \l_@@_date_added_tl
\tl_new:N \l_@@_date_updated_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_macro_argument_tl}
%   Save the argument of a \env{macro} or \env{function} environment for
%   use in error messages.
%    \begin{macrocode}
\tl_new:N \l_@@_macro_argument_tl
%    \end{macrocode}
% \end{variable}
%
% ^^A Bruno: what does the next line do?
%    \begin{macrocode}
% \int_new:N \c@CodelineNo
%    \end{macrocode}
%
% \subsection{Variants and helpers}
%
% \begin{macro}{\@@_tmpa:w, \@@_tmpb:w}
%   Auxiliary macros for temporary use.
%    \begin{macrocode}
\cs_new_eq:NN \@@_tmpa:w ?
\cs_new_eq:NN \@@_tmpb:w ?
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \seq_set_split:NoV,
%     \tl_to_str:f
%   }
%   A few missing variants.
%    \begin{macrocode}
\cs_generate_variant:Nn \seq_set_split:Nnn { NoV }
\cs_generate_variant:Nn \tl_to_str:n { f }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[TF]{\@@_if_almost_str:n}
%   Used to test if the argument of |\cmd| or other macros to be indexed
%   is almost a string or not: for instance this is \texttt{false} if |#1|
%   contains |\meta{...}|.  The surprising |f|-expansion is there to
%   cope with the case of |#1| starting with \cs{c_backslash_str}
%   which should be expanded and considered to be \enquote{normal}.
%    \begin{macrocode}
\prg_new_protected_conditional:Npnn \@@_if_almost_str:n #1 { TF , T , F }
  {
    \int_compare:nNnTF
      { \tl_count:n {#1} }
      < { \tl_count:e { \tl_to_str:f {#1} } }
      { \prg_return_false: }
      { \prg_return_true: }
  }
\prg_generate_conditional_variant:Nnn \@@_if_almost_str:n { V } { T }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_trim_right:Nn, \@@_trim_right:No}
%   Removes all material after |#2| in the token list variable~|#1|.
%   Perhaps combine with \cs{@@_key_trim_module:n}?
%    \begin{macrocode}
\cs_new_protected:Npn \@@_trim_right:Nn #1#2
  {
    \cs_set:Npn \@@_tmp:w ##1 #2 ##2 \q_stop { \exp_not:n {##1} }
    \__kernel_tl_set:Nx #1 { \exp_after:wN \@@_tmp:w #1 #2 \q_stop }
  }
\cs_generate_variant:Nn \@@_trim_right:Nn { No }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[TF]{\@@_str_if_begin:nn, \@@_str_if_begin:oo}
%   True if the first string starts with the second.
%    \begin{macrocode}
\prg_new_protected_conditional:Npnn \@@_str_if_begin:nn #1#2 { TF , T , F }
  {
    \tl_if_in:ooTF
      { \exp_after:wN \scan_stop: \tl_to_str:n {#1} }
      { \exp_after:wN \scan_stop: \tl_to_str:n {#2} }
      { \prg_return_true: }
      { \prg_return_false: }
  }
\prg_generate_conditional_variant:Nnn \@@_str_if_begin:nn
  { oo } { TF , T , F }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_replace_at_at:N}
% \begin{macro}{\@@_replace_at_at_aux:Nn}
%   The goal is to replace |@@| by the current module name.  We take
%   advantage of this function to also detect internal macros.  If there is
%   no \meta{module~name}, do nothing.  Otherwise, sanitize the catcodes
%   of |@| and~|_|, temporarily change |@@@@| to |aa| with different catcodes and later to |@@|, and replace |__@@| and |_@@| and |@@| by
%   |__|\meta{module~name}.  The result contains |_| with category
%   code letter because this is what the |macrocode| environment
%   expects.  Other use cases can apply \cs{tl_to_str:n} if needed.
%   Note that we include spaces between the
%   |@| in the code below, since it is also processed through the same
%   replacement rules.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_replace_at_at:N #1
  {
    \tl_if_empty:NF \g_@@_module_name_tl
      {
        \exp_args:NNo \@@_replace_at_at_aux:Nn
          #1 \g_@@_module_name_tl
      }
  }
\cs_new_protected:Npe \@@_replace_at_at_aux:Nn #1#2
  {
    \tl_replace_all:Nnn #1 { \token_to_str:N @ } { @ }
    \tl_replace_all:Nnn #1 { \token_to_str:N _ } { _ }
    \tl_replace_all:Nnn #1 { @ @ @ @ } { \token_to_str:N a a }
    \tl_replace_all:Nnn #1 { _ _ @ @ } { _ _ #2 }
    \tl_replace_all:Nnn #1 {   _ @ @ } { _ _ #2 }
    \tl_replace_all:Nnn #1 {     @ @ } { _ _ #2 }
    \tl_replace_all:Nnn #1 { \token_to_str:N a a } { @ @ }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}
%   {
%     \@@_detect_internals:N,
%     \@@_detect_internals_aux:N,
%     \@@_if_detect_internals_ok:NF
%   }
%   After splitting at each |__| and removing the leading item from the
%   sequence (since it does not follow |__|), remove everything after
%   any space or end-of-line to get a good approximation of the control
%   sequence (for the warning message).  Then check if that starts with
%   something allowed: |@@| module name and |:| or |_|, or if the
%   relevant boolean is set |kernel_| (it seems safe to assume we will
%   not define a |\__kernel:...| command).  For the message itself
%   remove anything after any |_| or |:| (with either catcode) to get a
%   guess of the module name.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_detect_internals:N #1
  {
    \bool_if:NT \l_@@_detect_internals_bool
      { \@@_detect_internals_aux:N #1 }
  }
\group_begin:
  \char_set_catcode_active:N \^^M
  \cs_new_protected:Npn \@@_detect_internals_aux:N #1
    {
      \tl_set_eq:NN \l_@@_detect_internals_tl #1
      \tl_replace_all:NVn \l_@@_detect_internals_tl \c_underscore_str { _ }
      \seq_set_split:NnV \l_@@_tmpa_seq { _ _ } \l_@@_detect_internals_tl
      \seq_pop_left:NN \l_@@_tmpa_seq \l_@@_detect_internals_tl
      \seq_map_variable:NNn \l_@@_tmpa_seq \l_@@_detect_internals_tl
        {
          \@@_trim_right:No \l_@@_detect_internals_tl
            \c_catcode_active_space_tl
          \@@_trim_right:Nn \l_@@_detect_internals_tl ^^M
          \@@_if_detect_internals_ok:NF \l_@@_detect_internals_tl
            {
              \tl_set_eq:NN \l_@@_detect_internals_cs_tl \l_@@_detect_internals_tl
              \@@_trim_right:Nn \l_@@_detect_internals_tl _
              \@@_trim_right:Nn \l_@@_detect_internals_tl :
              \@@_trim_right:No \l_@@_detect_internals_tl { \token_to_str:N : }
              \msg_warning:nneee { l3doc } { foreign-internal }
                { \tl_to_str:N \l_@@_detect_internals_cs_tl }
                { \tl_to_str:N \l_@@_detect_internals_tl }
                { \tl_to_str:N \g_@@_module_name_tl }
            }
        }
    }
\group_end:
\prg_new_protected_conditional:Npnn \@@_if_detect_internals_ok:N #1 { F }
  {
    \@@_str_if_begin:ooTF {#1} { \g_@@_module_name_tl _ }
      { \prg_return_true: }
      {
        \@@_str_if_begin:ooTF {#1} { \g_@@_module_name_tl : }
          { \prg_return_true: }
          {
            \bool_if:NTF \g_@@_kernel_bool
              {
                \@@_str_if_begin:ooTF {#1} { kernel _ }
                  { \prg_return_true: }
                  { \prg_return_false: }
              }
              { \prg_return_false: }
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[rEXP]{\@@_signature_base_form:n}
% \begin{macro}
%   {\@@_signature_base_form_aux:n, \@@_signature_base_form_aux:w}
%   Expands to the \enquote{base form} of the signature.  For instance,
%   given |noxcfvV| it would obtain |nnnNnnn|, or given |ow| it would
%   obtain |nw|.  The loop stops at the first token that is not
%   recognized; the rest is enclosed in \cs{exp_not:n}.
%    \begin{macrocode}
\cs_new:Npn \@@_signature_base_form:n #1
  { \@@_signature_base_form_aux:n #1 \q_stop }
\cs_new:Npn \@@_signature_base_form_aux:n #1
  {
    \str_case:nnTF {#1}
      {
        { N } { N }
        { c } { N }
        { n } { n }
        { o } { n }
        { f } { n }
        { e } { n }
        { x } { n }
        { V } { n }
        { v } { n }
      }
      { \@@_signature_base_form_aux:n }
      { \@@_signature_base_form_aux:w #1 }
  }
\cs_new:Npn \@@_signature_base_form_aux:w #1 \q_stop
  { \exp_not:n {#1} }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_predicate_from_base:n}
%   Get predicate from a function's base name.  The code is not broken
%   by functions with no signature.  The |n|-type version can be used
%   for keys and other non-control sequences.  The output after
%   |e|-expansion is a string.
%    \begin{macrocode}
\cs_new:Npn \@@_predicate_from_base:n #1
  {
    \@@_get_function_name:n {#1}
    \tl_to_str:n { _p: }
    \@@_get_function_signature:n {#1}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_split_function_do:nn, \@@_split_function_do:on}
% \begin{macro}{\@@_get_function_name:n, \@@_get_function_signature:n}
% \begin{macro}{\@@_split_function_auxi:w, \@@_split_function_auxii:w}
%   Similar to internal functions defined in \pkg{l3basics}, but here we
%   operate on strings directly rather than control sequences.
%    \begin{macrocode}
\cs_new:Npn \@@_get_function_name:n #1
  { \@@_split_function_do:nn {#1} { \use_i:nnn } }
\cs_new:Npn \@@_get_function_signature:n #1
  { \@@_split_function_do:nn {#1} { \use_ii:nnn } }
\cs_set_protected:Npn \@@_tmpa:w #1
  {
    \cs_new:Npn \@@_split_function_do:nn ##1
      {
        \exp_after:wN \@@_split_function_auxi:w
        \tl_to_str:n {##1} \q_mark \c_true_bool
        #1 \q_mark \c_false_bool
        \q_stop
      }
    \cs_new:Npn \@@_split_function_auxi:w
      ##1 #1 ##2 \q_mark ##3##4 \q_stop ##5
      { \@@_split_function_auxii:w {##5} ##1 \q_mark \q_stop {##2} ##3 }
    \cs_new:Npn \@@_split_function_auxii:w
      ##1##2 \q_mark ##3 \q_stop
      { ##1 {##2} }
  }
\exp_args:No \@@_tmpa:w { \token_to_str:N : }
\cs_generate_variant:Nn \@@_split_function_do:nn { o }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[rEXP]{\@@_key_get_base:nN}
%   Get the base form of a function and store it.  As part of getting
%   the base form, change trailing |T| or |F| to |TF|, skipping that
%   change if the function contains no colon to avoid changing for
%   instance some names ending in \texttt{PDF} or similar.  The various
%   letters |z| serve as end-delimiters different from any outcome of
%   \cs{tl_to_str:n}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_key_get_base:nN #1#2
  {
    \@@_if_almost_str:nTF {#1}
      {
        \@@_key_get_base_TF:nN {#1} \l_@@_tmpa_tl
        \__kernel_tl_set:Nx #2
          { \@@_split_function_do:on \l_@@_tmpa_tl { \@@_base_form_aux:nnN } }
      }
      { \tl_set:Nn #2 {#1} }
  }
\cs_new:Npe \@@_key_get_base_TF:nN #1#2
  {
    \__kernel_tl_set:Nx #2 { \exp_not:N \tl_to_str:n {#1} }
    \tl_if_in:NoF #2 { \tl_to_str:n {:} }
      { \exp_not:N \prg_break: }
    \tl_if_in:onT { #2 z } { \tl_to_str:n {TF} z }
      { \exp_not:N \prg_break: }
    \tl_if_in:onT { #2 z } { \tl_to_str:n {T} z }
      {
        \tl_put_right:Nn #2 { \tl_to_str:n {F} }
        \exp_not:N \prg_break:
      }
    \tl_if_in:onT { #2 z } { \tl_to_str:n {F} z }
      {
        \tl_put_right:Nn #2 { z }
        \tl_replace_once:Nnn #2 { \tl_to_str:n {F} z } { \tl_to_str:n {TF} }
        \exp_not:N \prg_break:
      }
    \exp_not:N \prg_break_point:
  }
\cs_new:Npn \@@_base_form_aux:nnN #1#2#3
  {
    \exp_not:n {#1}
    \bool_if:NT #3
      {
        \token_to_str:N :
        \bool_lazy_or:nnTF
            { \str_if_eq_p:nn { #1 ~ } { \exp_args } }
            { \str_if_eq_p:nn { #1 ~ } { \exp_last_unbraced } }
          { \exp_not:n {#2} }
          { \@@_signature_base_form:n {#2} }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_base_form_signature_do:nnn}
%   Do |#2{#1}| if there is no signature, or if |#1| contains two colons
%   in a row (this covers the weird function |\::N| and so on).
%   Otherwise apply |#3| with the following two arguments: the base form
%   of |#1|, and the original signature with an extra pair of braces.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_base_form_signature_do:nnn #1#2#3
  {
    \@@_split_function_do:nn {#1}
      { \@@_base_form_aux:nnnnnN {#1} {#2} {#3} }
  }
\cs_new_protected:Npn \@@_base_form_aux:nnnnnN #1#2#3#4#5#6
  {
    \bool_if:NTF #6
      {
        \tl_if_head_eq_charcode:nNTF {#4} :
          { #2 {#1} }
          {
            \use:e
              {
                \exp_not:n {#3}
                { \@@_base_form_aux:nnN {#4} {#5} #6 }
              }
                {#4} {#5}
          }
      }
      { #2 {#1} }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[pTF]{\@@_date_compare:nNn}
% \begin{macro}{\@@_date_compare_aux:nnnNnnn, \@@_date_compare_aux:w}
%   Expects |#1| and |#3| to be dates in the format YYYY-MM-DD (but
%   accepts YYYY or YYYY-MM too).  Compares them using |#2| (one of |<|,
%   |=|, |>|), filling in zeros for missing data.
%    \begin{macrocode}
\prg_new_conditional:Npnn \@@_date_compare:nNn #1#2#3 { TF , T , F , p }
  { \@@_date_compare_aux:w #1--- \q_mark #2 #3--- \q_stop }
\cs_new:Npn \@@_date_compare_aux:w
    #1 - #2 - #3 - #4 \q_mark #5 #6 - #7 - #8 - #9 \q_stop
  {
    \@@_date_compare_aux:nnnNnnn
      { \tl_if_empty:nTF {#1} { 0 } {#1} }
      { \tl_if_empty:nTF {#2} { 0 } {#2} }
      { \tl_if_empty:nTF {#3} { 0 } {#3} }
      #5
      { \tl_if_empty:nTF {#6} { 0 } {#6} }
      { \tl_if_empty:nTF {#7} { 0 } {#7} }
      { \tl_if_empty:nTF {#8} { 0 } {#8} }
  }
\cs_new:Npn \@@_date_compare_aux:nnnNnnn #1#2#3#4#5#6#7
  {
    \int_compare:nNnTF {#1} = {#5}
      {
        \int_compare:nNnTF {#2} = {#6}
          {
            \int_compare:nNnTF {#3} #4 {#7}
              { \prg_return_true: } { \prg_return_false: }
          }
          {
            \int_compare:nNnTF {#2} #4 {#6}
              { \prg_return_true: } { \prg_return_false: }
          }
      }
      {
        \int_compare:nNnTF {#1} #4 {#5}
          { \prg_return_true: } { \prg_return_false: }
      }
    \use_none:n
    \q_stop
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_gprop_name:n, \@@_lseq_name:n}
%   We need to keep track of some information about control sequences
%   (and other strings) that are being (or have been) documented.  Some
%   is stored into global props and some into local seqs, whose name
%   does not follow conventions: it is \cs[no-index]{g_@@} or
%   \cs[no-index]{l_@@} followed by a space and by the string, which can
%   be arbitrary.  We cannot reasonably use a single big |prop| for
%   speed reasons.
%    \begin{macrocode}
\cs_new:Npn \@@_gprop_name:n #1 { g_@@ ~ \tl_to_str:n {#1} }
\cs_new:Npn \@@_lseq_name:n #1 { l_@@ ~ \tl_to_str:n {#1} }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Messages}
%
%    \begin{macrocode}
\msg_new:nnnn { l3doc } { no-signature-TF }
  { Function/macro~'#1'~cannot~be~turned~into~a~conditional. }
  {
    A~function~or~macro~environment~with~option~pTF,~TF~or~noTF~
    received~the~argument~'#1'.~This~function's~name~has~no~
    ':'~hence~it~is~not~clear~where~to~add~'_p'~or~'TF'.~
    Please~follow~expl3~naming~conventions.
  }
\msg_new:nnn { l3doc } { date-format }
  { The~date~'#1'~should~be~given~in~YYYY-MM-DD~format. }
\msg_new:nnn { l3doc } { future-date }
  { The~added/updated~date~'#2'~of~'#1'~is~in~the~future. }
\msg_new:nnn { l3doc } { syntax-nested-function }
  {
    The~'syntax'~environment~should~be~used~in~the~
    innermost~'function'~environment.
  }
\msg_new:nnn { l3doc } { multiple-syntax }
  {
    The~'syntax'~environment~should~only~be~used~once~in~
    a~'function'~environment.
  }
\msg_new:nnn { l3doc } { deprecated-option }
  { The~option~'#1'~has~been~deprecated~for~'#2'. }
\msg_new:nnn { l3doc } { foreign-internal }
  {
    A~control~sequence~of~the~form~'...__#1'~was~used.~
    It~should~only~be~used~in~the~module~'#2'
    \tl_if_empty:nF {#3} { ,~not~in~'#3' } .
  }
%    \end{macrocode}
%
% \subsection{Options and configuration}
%
%    \begin{macrocode}
\DeclareKeys [ l3doc / options ]
  {
    a5paper .code:n = \@latexerr { Option~not~supported } { } ,
    full .code:n =
      {
        \bool_gset_true:N \g_@@_typeset_documentation_bool
        \bool_gset_true:N \g_@@_typeset_implementation_bool
      } ,
    onlydoc .code:n = 
      {
        \bool_gset_true:N \g_@@_typeset_documentation_bool
        \bool_gset_false:N \g_@@_typeset_implementation_bool
      } ,
    check .bool_gset:N = \g_@@_checkfunc_bool ,
    checktest .bool_gset:N = \g_@@_checktest_bool ,
    kernel .bool_gset:N = \g_@@_kernel_bool ,
    stdmodule .bool_gset_inverse:N = \g_@@_kernel_bool ,
    lm-default .bool_gset:N = \g_@@_lmodern_bool ,
    cs-break .bool_gset_inverse:N = \g_@@_cs_break_bool ,
    cs-break-nohyphen .code:n = \PassOptionsToPackage{nohyphen}{underscore} ,
    show-notes .bool_gset:N = \g_@@_show_notes_bool,
    hide-notes .bool_gset_inverse:N = \g_@@_show_notes_bool
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\DeclareUnknownKeyHandler [ l3doc / options ]
  { \PassOptionsToClass { \CurrentOption } { article } }
\SetKeys [ l3doc / options ]
  { full , check = false , checktest = false , lm-default }
\PassOptionsToClass { a4paper } { article }
%    \end{macrocode}
%
% Input a local configuration file, if it exists, with a message to the
% console that this has happened. Since we distribute a \file{.cfg} file
% with the class, this should usually always be true. Therefore, check
% for \cs{ExplMakeTitle} (defined in \enquote{our} \file{.cfg} file) and
% only output the informational message if it's not found.
%
%    \begin{macrocode}
\msg_new:nnn { l3doc } { input-cfg }
  { Local~config~file~l3doc.cfg~loaded. }
\file_if_exist:nT { l3doc.cfg }
  {
    \file_input:n { l3doc.cfg }
    \cs_if_exist:cF { ExplMakeTitle }
      { \msg_info:nn { l3doc } { input-cfg } }
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\ProcessKeyOptions [ l3doc / options ]
%    \end{macrocode}
%
%
% \subsection{Class and package loading}
%
%    \begin{macrocode}
\LoadClass{article}
\RequirePackage{doc}
\RequirePackage
  {
    array,
    alphalph,
    amsmath,
    amssymb,
    booktabs,
    color,
    colortbl,
    hologo,
    enumitem,
    pifont,
    textcomp,
    trace,
    csquotes,
    fancyvrb,
    underscore,
    verbatim
  }
\raggedbottom
%    \end{macrocode}
%
% Depending on the option, load the package \pkg{lmodern} to set the
% font.  Then replace the italic typewriter font with the oblique shape
% instead; the former makes my skin crawl. (Will, Aug 2011)
%    \begin{macrocode}
\bool_if:NT \g_@@_lmodern_bool
  {
    \RequirePackage[T1]{fontenc}
    \RequirePackage{lmodern}
    \group_begin:
      \ttfamily
      \DeclareFontShape{T1}{lmtt}{m}{it}{<->ec-lmtto10}{}
    \group_end:
  }
%    \end{macrocode}
%
% Must be last, as usual.
%    \begin{macrocode}
\RequirePackage{hypdoc}
%    \end{macrocode}
%
% \subsection{Configuration and tweaks}
%
% \begin{macro}{\MakePrivateLetters}
%   A few more letters are \enquote{private} in a \LaTeX3 programming
%   environment.
%    \begin{macrocode}
\cs_gset:Npn \MakePrivateLetters
  {
    \char_set_catcode_letter:N \@
    \char_set_catcode_letter:N \_
    \char_set_catcode_letter:N \:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{CodelineNo}
%   Some configurations which have to do with line numbering.
%    \begin{macrocode}
\setcounter{StandardModuleDepth}{1}
\@addtoreset{CodelineNo}{part}
\tl_replace_once:Nnn \theCodelineNo
  { \HDorg@theCodelineNo }
  { \textcolor[gray]{0.5} { \sffamily\tiny\arabic{CodelineNo} } }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\verbatim, \endverbatim}
%   In \file{.dtx} documents, the \env{verbatim} environment adds extra
%   space because it only removes the first \enquote{\%} sign, and not
%   the indentation (typically a space).  Fix it with \pkg{fancyvrb}:
%    \begin{macrocode}
\fvset{gobble=2}
\cs_gset_eq:NN \verbatim \Verbatim
\cs_gset_eq:NN \endverbatim \endVerbatim
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ifnot@excluded}
%   This function tests whether a macro name stored in
%   \tn{macro@namepart} was excluded from indexing by \tn{DoNotIndex}.
%   Rather than trying to fix catcodes that come into here, turn
%   everything to string catcodes.  This is slightly inefficient as we
%   could have ensured that \tn{index@excludelist} has string catcodes
%   in the first place.
%    \begin{macrocode}
\cs_set_protected:Npn \ifnot@excluded
  {
    \exp_args:Nee \expanded@notin
      { \c_backslash_str \tl_to_str:N \macro@namepart , }
      { \exp_args:NV \tl_to_str:n \index@excludelist }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pdfstringnewline}
% \begin{macro}{\@@_pdfstring_newline:w}
%   We avoid some hyperref warnings by making |\\| (almost) trivial in
%   bookmarks: more precisely it might be used with a star and an
%   optional argument, which we thus remove using an \pkg{ltcmd}
%   expandable command.  Since there cannot be trailing optional
%   arguments, pick up an extra mandatory one and put it back.
%    \begin{macrocode}
\cs_new:Npn \pdfstringnewline { : ~ }
\DeclareExpandableDocumentCommand
  { \@@_pdfstring_newline:w } { s o m } { \pdfstringnewline #3 }
\pdfstringdefDisableCommands
  { \cs_set_eq:NN \\ \@@_pdfstring_newline:w }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Design}
%
% Increase the text width slightly so that width the standard fonts
% 72~columns of code may appear in a \env{macrocode} environment.
% Increase the marginpar width slightly, for long command names.  And
% increase the left margin by a similar amount.
%    \begin{macrocode}
\setlength   \textwidth      { 385pt }
\addtolength \marginparwidth {  30pt }
\addtolength \oddsidemargin  {  20pt }
\addtolength \evensidemargin {  20pt }
%    \end{macrocode}
% (These were introduced when \cls{article} was the documentclass, but
% I've left them here for now to remind me to do something about them
% later.)
%
% \begin{macro}{\list}
% \begin{macro}{\@@_oldlist:nn}
%   Customise lists.
%    \begin{macrocode}
\cs_new_eq:NN \@@_oldlist:nn \list
\cs_gset:Npn \list #1 #2
  { \@@_oldlist:nn {#1} { #2 \dim_zero:N \listparindent } }
\setlength \parindent  { 2em }
\setlength \itemindent { 0pt }
\setlength \parskip    { 0pt plus 3pt minus 0pt }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\partname}
%   Use \enquote{File} as a name in Part titles.
%    \begin{macrocode}
\tl_gset:Nn \partname {File}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l@section, \l@subsection}
%   Customise the table of contents (as we have so many sections).
%   Different design and/or structure is called for.
%    \begin{macrocode}
\@addtoreset{section}{part}
\cs_gset:Npn \l@section #1#2
  {
    \ifnum \c@tocdepth >\z@
      \addpenalty\@secpenalty
      \addvspace{1.0em \@plus\p@}
      \setlength\@tempdima{2.5em}  % was 1.5em
      \begingroup
        \parindent \z@ \rightskip \@pnumwidth
        \parfillskip -\@pnumwidth
        \leavevmode \bfseries
        \advance\leftskip\@tempdima
        \hskip -\leftskip
        #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
      \endgroup
    \fi
  }
\cs_gset:Npn \l@subsection
  { \@dottedtocline{2}{2.5em}{2.3em} }  % #2 = 1.5em
%    \end{macrocode}
% \end{macro}
%
% \subsection{Text markup}
%
% Make "|" and |"| be \enquote{short verb} characters, but not in the
% document preamble, where an active character may interfere with
% packages that are loaded.  Remove these short-hands at the end of the
% document before reading the \file{.aux} file, as they may appear in
% labels (for instance, \pkg{l3fp} documents an operation "||").
%    \begin{macrocode}
\AtBeginDocument
  {
    \MakeShortVerb \"
    \MakeShortVerb \|
  }
\AtEndDocument
  {
    \DeleteShortVerb \"
    \DeleteShortVerb \|
  }
%    \end{macrocode}
%
% \begin{macro}{\eTeX, \IniTeX, \Lua, \LuaTeX, \pdfTeX, \XeTeX,
%   \pTeX, \upTeX, \epTeX, \eupTeX}
%   Some commands for logos.
%    \begin{macrocode}
\providecommand*\eTeX{\hologo{eTeX}}
\providecommand*\IniTeX{\hologo{iniTeX}}
\providecommand*\Lua{Lua}
\providecommand*\LuaTeX{\hologo{LuaTeX}}
\providecommand*\pdfTeX{\hologo{pdfTeX}}
\providecommand*\XeTeX{\hologo{XeTeX}}
\providecommand*\pTeX{p\kern-.2em\hologo{TeX}}
\providecommand*\upTeX{up\kern-.2em\hologo{TeX}}
\providecommand*\epTeX{$\varepsilon$-\pTeX}
\providecommand*\eupTeX{$\varepsilon$-\upTeX}
\providecommand*\ConTeXt{\hologo{ConTeXt}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\cmd, \cs, \tn}
%   They rely on a common auxiliary \cs{@@_cmd:nn} which receives as
%   arguments the options and some tokens whose string representation
%   starts with a backslash (to support cases such as |\cs{pkg_\ldots}|,
%   we do not turn the whole argument into a string).
%    \begin{macrocode}
\DeclareDocumentCommand \cmd { O{} m }
  { \@@_cmd:no {#1} { \token_to_str:N #2 } }
\DeclareDocumentCommand \cs  { O{} m }
  { \@@_cmd:no {#1} { \c_backslash_str #2 } }
\DeclareDocumentCommand \tn  { O{} m }
  {
    \@@_cmd:no
      { module = TeX , replace = false , #1 }
      { \c_backslash_str #2 }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\meta}
%   A document-level command.
%    \begin{macrocode}
\DeclareDocumentCommand \meta { m }
  { \texttt{ \@@_meta:n {#1} } }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \@@_pdfstring_cmd:w,
%     \@@_pdfstring_cs:w,
%     \@@_pdfstring_meta:w
%   }
%   To work within a bookmark, these commands must be expandable.
%    \begin{macrocode}
\DeclareExpandableDocumentCommand
  { \@@_pdfstring_cmd:w } { o m } { \token_to_str:N #2 }
\DeclareExpandableDocumentCommand
  { \@@_pdfstring_cs:w }  { o m } { \textbackslash \tl_to_str:n {#2} }
\cs_new:Npn \@@_pdfstring_meta:w #1
  { < \tl_to_str:n {#1} > }
\pdfstringdefDisableCommands
  {
    \cs_set_eq:NN \cmd       \@@_pdfstring_cmd:w
    \cs_set_eq:NN \cs        \@@_pdfstring_cs:w
    \cs_set_eq:NN \tn        \@@_pdfstring_cs:w
    \cs_set_eq:NN \meta      \@@_pdfstring_meta:w
    \cs_set_eq:NN \@@_meta:n \@@_pdfstring_meta:w
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Arg, \marg, \oarg, \parg}
%   |\marg{text}| prints \marg{text}, \enquote{mandatory argument}.\\
%   |\oarg{text}| prints \oarg{text}, \enquote{optional argument}.\\
%   |\parg{te,xt}| prints \parg{te,xt}, \enquote{picture mode argument}.
%   Finally, \cs{Arg} is the same as \cs{marg}.
%    \begin{macrocode}
\newcommand\Arg[1]
  { \texttt{\char`\{} \@@_meta:n {#1} \texttt{\char`\}} }
\providecommand\marg[1]{ \Arg{#1} }
\providecommand\oarg[1]{ \texttt[ \@@_meta:n {#1} \texttt] }
\providecommand\parg[1]{ \texttt( \@@_meta:n {#1} \texttt) }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\file, \env, \pkg, \cls}
%   This list may change\dots this is just my preference for markup.
%    \begin{macrocode}
\DeclareRobustCommand \file {\nolinkurl}
\DeclareRobustCommand \env {\texttt}
\DeclareRobustCommand \pkg {\textsf}
\DeclareRobustCommand \cls {\textsf}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\EnableDocumentation, \EnableImplementation}
% \begin{macro}{\DisableDocumentation, \DisableImplementation}
%   Control whether to typeset the documentation/implementation or not.
%   These simply set two switches.
%    \begin{macrocode}
\NewDocumentCommand \EnableDocumentation { }
  { \bool_gset_true:N \g_@@_typeset_documentation_bool }
\NewDocumentCommand \EnableImplementation { }
  { \bool_gset_true:N \g_@@_typeset_implementation_bool }
\NewDocumentCommand \DisableDocumentation { }
  { \bool_gset_false:N \g_@@_typeset_documentation_bool }
\NewDocumentCommand \DisableImplementation { }
  { \bool_gset_false:N \g_@@_typeset_implementation_bool }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{environment}{documentation}
% \begin{environment}{implementation}
%   If the documentation/implementation should be typeset, then simply
%   set the boolean \cs{l_@@_in_implementation_bool} which indicates
%   whether we are within the implementation section.  Otherwise use
%   \cs{comment} (and a paired \cs{endcomment}).
%    \begin{macrocode}
\NewDocumentEnvironment { documentation } { }
  {
    \bool_if:NTF \g_@@_typeset_documentation_bool
      { \bool_set_false:N \l_@@_in_implementation_bool }
      { \comment }
  }
  { \bool_if:NF \g_@@_typeset_documentation_bool { \endcomment } }
\NewDocumentEnvironment { implementation } { }
  {
    \bool_if:NTF \g_@@_typeset_implementation_bool
      { \bool_set_true:N \l_@@_in_implementation_bool }
      { \comment }
  }
  { \bool_if:NF \g_@@_typeset_implementation_bool { \endcomment } }
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{environment}{variable}
%   The \env{variable} environment behaves as a \env{function} or
%   \env{macro} environment depending on the part of the document.
%    \begin{macrocode}
\DeclareDocumentEnvironment { variable } { O{} +v }
  {
    \bool_if:NTF \l_@@_in_implementation_bool
      { \@@_macro:nnw { var , #1 } {#2} }
      { \@@_function:nnw {#1} {#2} }
  }
  {
    \bool_if:NTF \l_@@_in_implementation_bool
      { \@@_macro_end: }
      { \@@_function_end: }
  }
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{function}
% \begin{environment}{macro}
%   Environment for documenting function(s), and environment for
%   documenting the implementation of a macro.
%    \begin{macrocode}
\DeclareDocumentEnvironment { function } { O{} +v }
  { \@@_function:nnw {#1} {#2} }
  { \@@_function_end: }
\DeclareDocumentEnvironment { macro } { O{} +v }
  { \@@_macro:nnw {#1} {#2} }
  { \@@_macro_end: }
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{environment}{syntax}
%   Syntax block placed next to the list of functions to illustrate
%   their use.  TODO: test that the \env{syntax} environment is only
%   used inside the \env{function} environment, and that it only appears
%   once.
%    \begin{macrocode}
\NewDocumentEnvironment { syntax } { }
  { \@@_syntax:w }
  {
    \@@_syntax_end:
    \ignorespacesafterend
  }
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{texnote}
%   Used to describe information destined to \TeX{} experts only.
%    \begin{macrocode}
\NewDocumentEnvironment { texnote } { }
  {
    \endgraf
    \vspace{3mm}
    \small\textbf{\TeX~hackers~note:}
  }
  {
    \vspace{3mm}
  }
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{arguments}
%   This environment is designed to be used within a \env{macro}
%   environment to describe the arguments of the macro/function.
%    \begin{macrocode}
\NewDocumentEnvironment { arguments } { }
  {
    \enumerate [
      nolistsep ,
      label = \texttt{\#\arabic*} ~ : ,
      labelsep = * ,
    ]
  }
  {
    \endenumerate
  }
%    \end{macrocode}
% \end{environment}
%
% \begin{macro}{\CodedocExplain, \CodedocExplainEXP, \CodedocExplainREXP, \CodedocExplainTF}
%   Explanation of stars and |TF| notations, for use in third-party
%   packages.
%    \begin{macrocode}
\NewDocumentCommand { \CodedocExplain } { }
  { \CodedocExplainEXP \ \CodedocExplainREXP \ \CodedocExplainTF }
\NewDocumentCommand { \CodedocExplainEXP } { }
  {
    \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{expstar}{}}%
    \write \@auxout { \def \string \Codedoc@expstar { } }
    \@@_typeset_exp:\ indicates~fully~expandable~functions,~which~
    can~be~used~within~an~\texttt{e}-type~argument~(inside~an~\tn{expanded}),~
    \texttt{x}-type~argument~(in~plain~\TeX{}~terms,~inside~an~\tn{edef}),~
    as~well~as~within~an~\texttt{f}-type~argument.
  }
\NewDocumentCommand { \CodedocExplainREXP } { }
  {
    \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{rexpstar}{}}%
    \write \@auxout { \def \string \Codedoc@rexpstar { } }
    \@@_typeset_rexp:\ indicates~
    restricted~expandable~functions,~which~can~be~used~within~an~
    \texttt{x}-type~argument~or~an~\texttt{e}-type~argument,~
    but~cannot~be~fully~expanded~within~an~\texttt{f}-type~argument.
  }
\NewDocumentCommand { \CodedocExplainTF } { }
  {
    \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{explTF}{}}%
    \write \@auxout { \def \string \Codedoc@explTF { } }
    \@@_typeset_TF:\ indicates~conditional~(\texttt{if})~functions~
    whose~variants~with~\texttt{T},~\texttt{F}~and~\texttt{TF}~
    argument~specifiers~expect~different~
    \enquote{true}/\enquote{false}~branches.
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Implementing text markup}
%
% Keys for \cs{cmd}, \cs{cs} and \cs{tn}.
%    \begin{macrocode}
\keys_define:nn { l3doc/cmd }
  {
    index     .tl_set:N     = \l_@@_cmd_index_tl        ,
    module    .tl_set:N     = \l_@@_cmd_module_tl       ,
    no-index  .bool_set:N   = \l_@@_cmd_noindex_bool    ,
    replace   .bool_set:N   = \l_@@_cmd_replace_bool    ,
  }
%    \end{macrocode}
%
% \begin{macro}[do-not-index={\\,\_,\1,\c,\2}]{\@@_cmd:nn, \@@_cmd:no}
%   Apply the key--value \meta{options}~|#1| after setting some
%   default values.  Then (unless |replace=false|) replace |@@| in~|#2|,
%   which is a bit tricky: the |_| must be given the catcode expected by
%   \cs{@@_replace_at_at:N}, but should be reverted to their original
%   catcode (normally active, needed for line-breaking) without
%   rescanning the whole argument.  Then typeset the command in
%   \tn{verbatim@font}, after turning it to harmless characters if
%   needed (and keeping the underscore breakable); in any case, spaces
%   must be turned into \tn{@xobeysp} and we must use \tn{@} to avoid
%   longer spaces after a control sequence that ends for instance with a
%   colon (empty signature).  Finally, produce an index entry.
%   Indexing is suppressed when \cs{l_@@_cmd_noindex_bool} is true.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_cmd:nn #1#2
  {
    \bool_set_false:N \l_@@_cmd_noindex_bool
    \bool_set_true:N \l_@@_cmd_replace_bool
    \tl_set:Nn \l_@@_cmd_index_tl { \q_no_value }
    \tl_set:Nn \l_@@_cmd_module_tl { \q_no_value }
    \keys_set:nn { l3doc/cmd } {#1}
    \tl_set:Nn \l_@@_cmd_tl {#2}
    \bool_if:NT \l_@@_cmd_replace_bool
      {
        \tl_set_rescan:Nnn \l_@@_tmpb_tl { } { _ }
        \tl_replace_all:NVn \l_@@_cmd_tl \l_@@_tmpb_tl { _ }
        \@@_replace_at_at:N \l_@@_cmd_tl
        \tl_replace_all:NnV \l_@@_cmd_tl { _ } \l_@@_tmpb_tl
      }
%    \end{macrocode}
% Typesetting.
% Note the replacement for the underscore is to permit linebreaks.
% The \texttt{underscore} package adds the linebreak,
% and the regex results in applying the breakable underscore only to the \emph{last}
% of a run of underscores, and not if the underscore follows a backslash.
%    \begin{macrocode}
    \mode_if_math:T { \mbox }
      {
        \bool_if:NT \l_@@_allow_indexing_bool { \@@_target: }
        \verbatim@font
        \@@_if_almost_str:VT \l_@@_cmd_tl
          {
            \__kernel_tl_set:Nx \l_@@_cmd_tl { \tl_to_str:N \l_@@_cmd_tl }
            \bool_if:NT \g_@@_cs_break_bool
              {
                \regex_replace_all:nnN
                  { ([^\\\_]\_*) \_ ([^\_]) }
                  { \1 \c{BreakableUnderscore} \2 }
                  \l_@@_cmd_tl
              }
          }
        \tl_replace_all:Nnn \l_@@_cmd_tl { ~ } { \@xobeysp }
        \l_@@_cmd_tl
        \@
      }
%    \end{macrocode}
% Indexing.
%    \begin{macrocode}
    \bool_if:NT \l_@@_allow_indexing_bool
      {
        \bool_if:NF \l_@@_cmd_noindex_bool
          {
            \quark_if_no_value:NF \l_@@_cmd_index_tl
              {
                \__kernel_tl_set:Nx \l_@@_cmd_tl
                  { \c_backslash_str \exp_not:o { \l_@@_cmd_index_tl } }
              }
            \exp_args:No \@@_key_get:n { \l_@@_cmd_tl }
            \quark_if_no_value:NF \l_@@_cmd_module_tl
              {
                \__kernel_tl_set:Nx \l_@@_index_module_tl
                  { \tl_to_str:N \l_@@_cmd_module_tl }
              }
            \@@_special_index_module:ooonN
              { \l_@@_index_key_tl }
              { \l_@@_index_macro_tl }
              { \l_@@_index_module_tl }
              { usage }
              \l_@@_index_internal_bool
          }
      }
  }
\cs_generate_variant:Nn \@@_cmd:nn { no }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \@@_meta:n,
%     \@@_ensuremath_sb:n,
%     \@@_meta_original:n
%   }
%   Store |#1| in \cs{l_@@_tmpa_tl} and replaces every underscore,
%   regardless of its category (\enquote{math toggle},
%   \enquote{alignment}, \enquote{superscript}, \enquote{subscript},
%   \enquote{letter}, \enquote{other}, or \enquote{active}) by
%   \cs{@@_ensuremath_sb:n} (which creates math subscripts), then runs
%   the code used for \tn{meta} in \pkg{doc.sty}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_meta:n #1
  {
    \tl_set:Nn \l_@@_tmpa_tl {#1}
    \tl_map_inline:nn
      { { 3 } { 4 } { 7 } { 8 } { 11 } { 12 } { 13 } }
      {
        \tl_set_rescan:Nnn \l_@@_tmpb_tl
          { \char_set_catcode:nn { `_ } {##1} } { _ }
        \tl_replace_all:NVn \l_@@_tmpa_tl \l_@@_tmpb_tl
          { \@@_ensuremath_sb:n }
      }
    \exp_args:NV \@@_meta_original:n \l_@@_tmpa_tl
  }
\cs_new_protected:Npn \@@_ensuremath_sb:n #1
  { \ensuremath { \sb {#1} } }
\cs_new_protected:Npn \@@_meta_original:n #1
  {
    \ensuremath \langle
    \mode_if_math:T { \nfss@text }
    {
      \meta@font@select
      \edef \meta@hyphen@restore
        { \hyphenchar \the \font \the \hyphenchar \font }
      \hyphenchar \font \m@ne
      \language \l@nohyphenation
      #1 \/
      \meta@hyphen@restore
    }
    \ensuremath \rangle
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Common between \env{macro} and \env{function}}
%
% \begin{macro}
%   {
%     \@@_typeset_exp:, \@@_typeset_rexp:,
%     \@@_typeset_TF:, \@@_typeset_aux:n
%   }
%   Used by \cs{@@_macro_single:nNN} and in the \env{function} environment
%   to typeset conditionals and auxiliary functions.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_typeset_exp:
  {
    \cs_if_exist:NTF \Codedoc@expstar
      { \hyperlink { expstar } }
      { \mbox }
    {$\star$}
  }
\cs_new_protected:Npn \@@_typeset_rexp:
  {
    \cs_if_exist:NTF \Codedoc@rexpstar
      { \hyperlink { rexpstar } }
      { \mbox }
    { \ding { 73 } } % hollow star
  }
\cs_new_protected:Npn \@@_typeset_TF:
  {
    \cs_if_exist:NTF \Codedoc@explTF
      { \hyperlink { explTF } }
      { \mbox }
      {
        \itshape TF
        \makebox[0pt][r]
          {
            \underline { \phantom{\itshape TF} \kern-0.1em }
          }
      }
  }
\cs_new_protected:Npn \@@_typeset_aux:n #1
  {
    { \color[gray]{0.5} #1 }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {\@@_get_hyper_target:nN, \@@_get_hyper_target:oN, \@@_get_hyper_target:eN}
%   Create a \pkg{hyperref} anchor from a macro name~|#1| and stores it
%   in the token list variable~|#2|.  For instance, |\prg_replicate:nn|
%   gives |doc/function//prg/replicate:nn|.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_get_hyper_target:nN #1#2
  {
    \__kernel_tl_set:Nx #2 { \tl_to_str:n {#1} }
    \tl_replace_all:NVn #2 \c_underscore_str { / }
    \tl_remove_all:NV   #2 \c_backslash_str
    \tl_put_left:Nn #2 { doc/function// }
  }
\cs_generate_variant:Nn \@@_get_hyper_target:nN { o , e }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_names_get_seq:nN}
%   The argument~|#1| (argument of a |function| or |macro| environment)
%   has catcodes $10$ (space), $12$ (other) and $13$ (active).  Sanitize
%   catcodes.  If the |verb| option was used, output a one-item
%   sequence.  Otherwise, remove any \enquote{\%} character at the
%   beginning of a line.  Remove tabs and newlines.  Finally, convert
%   |_@@| and |@@| to |__|\meta{module name} (if it is non-empty).  At
%   this point, \cs{l_@@_tmpa_tl} contains a comma-delimited list of
%   names, where |@| and~|_| have category code letter.  Turn it to a
%   string, parse it as a comma-delimited list (in particular this
%   removes spaces), and output a sequence of function/macro names.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_names_get_seq:nN #1#2
  {
    \__kernel_tl_set:Nx \l_@@_tmpa_tl { \tl_to_str:n {#1} }
    \bool_if:NTF \l_@@_names_verb_bool
      {
        \seq_clear:N #2
        \seq_put_right:NV #2 \l_@@_tmpa_tl
      }
      {
        \tl_remove_all:Ne \l_@@_tmpa_tl
          { \iow_char:N \^^M \c_percent_str }
        \tl_remove_all:Ne \l_@@_tmpa_tl { \tl_to_str:n { ^ ^ A } }
        \tl_remove_all:Ne \l_@@_tmpa_tl { \iow_char:N \^^I }
        \tl_remove_all:Ne \l_@@_tmpa_tl { \iow_char:N \^^M }
        \@@_detect_internals:N \l_@@_tmpa_tl
        \@@_replace_at_at:N \l_@@_tmpa_tl
        \exp_args:NNe \seq_set_from_clist:Nn #2
          { \tl_to_str:N \l_@@_tmpa_tl }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_names_parse:, \@@_names_parse_one:n}
%   The goal is to group variants together.  We populate
%   \cs{l_@@_names_block_tl} with local sequence variable named with
%   \cs{@@_lseq_name:n} after the base forms.  When encountering a new
%   base form, set the corresponding local sequence to hold the
%   \meta{base name} (stripped of the signature) and add the local
%   sequence to the list \cs{l_@@_names_block_tl}.  In all cases append
%   the signature to the local sequence, which thus takes the form
%   \meta{base name}, \meta{signature_1}, \meta{signature_2} and so on.
%   If the original function had no signature (no colon) then use
%   \cs{scan_stop:} as the signature (there can be no variant).  We
%   special case commands |#1| starting with |\::|, namely weird
%   functions named |\::N| and the like.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_names_parse:
  {
    \tl_clear:N \l_@@_names_block_tl
    \seq_map_function:NN
      \l_@@_names_seq
      \@@_names_parse_one:n
  }
\cs_new_protected:Npn \@@_names_parse_one:n #1
  {
    \@@_split_function_do:nn {#1}
      { \@@_names_parse_one_aux:nnNn }
    {#1}
  }
\cs_new_protected:Npn \@@_names_parse_one_aux:nnNn #1#2#3#4
  {
    \bool_if:NTF #3
      {
        \tl_if_head_eq_charcode:nNTF {#2} :
          { \@@_names_parse_aux:nnn {#4} {#4} { \scan_stop: } }
          {
            \exp_args:Ne \@@_names_parse_aux:nnn
              { \@@_base_form_aux:nnN {#1} {#2} #3 }
              {#1} {#2}
          }
      }
      {
        \bool_if:NT \l_@@_macro_TF_bool
          { \msg_error:nne { l3doc } { no-signature-TF } {#4} }
        \@@_names_parse_aux:nnn {#4} {#4} { \scan_stop: }
      }
  }
\cs_new_protected:Npn \@@_names_parse_aux:nnn #1
  { \exp_args:Nc \@@_names_parse_aux:Nnn { \@@_lseq_name:n {#1} } }
\cs_new_protected:Npn \@@_names_parse_aux:Nnn #1#2#3
  {
    \tl_if_in:NnF \l_@@_names_block_tl {#1}
      {
        \tl_put_right:Nn \l_@@_names_block_tl {#1}
        \seq_clear_new:N #1
        \seq_put_right:Nn #1 {#2}
      }
    \seq_put_right:Nn #1 {#3}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_names_typeset:}
% \begin{macro}{\@@_names_typeset_auxi:n}
%   This code is in particular used when typesetting function names in a
%   \env{function} environment.  The mapping over \cs{l_@@_names_block_tl}
%   cannot use \cs{tl_map_inline:Nn} because the code following |\\|
%   would not be expandable, thus breaking \tn{bottomrule}.
%
%   Call \cs{@@_names_typeset_auxi:n} on each local sequence (which
%   holds a set of variants).  The first step is to pop the base form
%   and change spaces to category other so
%   that they get displayed eventually.  Then store the variants in
%   \cs{g_@@_variants_seq}, remove the first, which will be displayed
%   more prominently, and reconstruct the actual name, passing it to
%   \cs{@@_names_typeset_auxii:n}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_names_typeset:
  {
    \tl_map_function:NN \l_@@_names_block_tl
      \@@_names_typeset_auxi:n
  }
\cs_new_protected:Npn \@@_names_typeset_auxi:n #1
  {
    \seq_pop:NN #1 \l_@@_tmpa_tl
    \tl_gset_eq:NN \g_@@_base_name_tl \l_@@_tmpa_tl
    \tl_greplace_all:NnV \g_@@_base_name_tl
      { ~ } \c_catcode_other_space_tl
    \seq_get:NN #1 \l_@@_tmpa_tl
    \str_if_eq:VnTF \l_@@_tmpa_tl { \scan_stop: }
      {
        \seq_gclear:N \g_@@_variants_seq
        \@@_names_typeset_auxii:e { \g_@@_base_name_tl }
      }
      {
        \seq_gset_eq:NN \g_@@_variants_seq #1
        \seq_gpop:NN \g_@@_variants_seq \l_@@_tmpb_tl
        \@@_names_typeset_auxii:e
          { \g_@@_base_name_tl : \l_@@_tmpb_tl }
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}
%   {\@@_names_typeset_auxii:n, \@@_names_typeset_auxii:e}
%   In case the option |pTF| was given, typeset predicates before the
%   |TF| functions.  In case the option |noTF| was given, typeset the
%   non-|TF| function as well.  Pass the relevant boolean in both cases
%   to control whether to append |TF|.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_names_typeset_auxii:n #1
  {
    \bool_if:NT \l_@@_macro_pTF_bool
      {
        \@@_names_typeset_block:eN
          { \@@_predicate_from_base:n {#1} }
          \c_false_bool
      }
    \bool_if:NT \l_@@_macro_noTF_bool
      { \@@_names_typeset_block:nN {#1} \c_false_bool }
    \@@_names_typeset_block:nN {#1} \l_@@_macro_TF_bool
  }
\cs_generate_variant:Nn \@@_names_typeset_auxii:n { e }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_names_typeset_block:nN, \@@_names_typeset_block:eN}
%   Names in \env{function} and \env{macro} environments are typeset
%   differently.  To distinguish the two note that
%   \cs{l_@@_nested_macro_int} is at least one when in an \env{macro}
%   environment (we assume \env{function} is not nested inside it).  A
%   block is a function with all its variants.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_names_typeset_block:nN
  {
    \int_compare:nNnTF \l_@@_nested_macro_int = 0
      { \@@_typeset_function_block:nN }
      { \@@_macro_typeset_block:nN }
  }
\cs_generate_variant:Nn \@@_names_typeset_block:nN { e }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[pTF]{\@@_if_macro_internal:n}
% \begin{macro}[EXP]{\@@_if_macro_internal_aux:w}
%   Determines whether the given macro should be considered internal or
%   public.  If an option such as |int| was given then the answer is
%   \cs{l_@@_macro_internal_bool}, otherwise check for whether the macro
%   name contains~|__|.
%    \begin{macrocode}
\prg_new_conditional:Npnn \@@_if_macro_internal:n #1 { p , T , F , TF }
  {
    \bool_if:NTF \l_@@_macro_internal_bool
      { \prg_return_true: }
      {
        \tl_if_empty:eTF
          {
            \exp_after:wN \@@_if_macro_internal_aux:w
            \tl_to_str:n { #1 ~ __ }
          }
          { \prg_return_false: } { \prg_return_true: }
      }
  }
\exp_last_unbraced:NNNNo
  \cs_new:Npn \@@_if_macro_internal_aux:w #1 { \tl_to_str:n { __ } } { }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_names_block_base_map:N}
%   The \cs{l_@@_names_block_tl} contains sequence variables
%   corresponding to different base functions and their variants.  For
%   each such sequence, put the first and second items in
%   \cs{l_@@_tmpa_tl} and \cs{l_@@_tmpb_tl} and build the base
%   function's name.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_names_block_base_map:N #1
  {
    \tl_map_inline:Nn \l_@@_names_block_tl
      {
        \group_begin:
          \seq_set_eq:NN \l_@@_tmpa_seq ##1
          \seq_pop:NN \l_@@_tmpa_seq \l_@@_tmpa_tl
          \seq_get:NN \l_@@_tmpa_seq \l_@@_tmpb_tl
          \exp_args:NNe
        \group_end:
        #1
          {
            \l_@@_tmpa_tl
            \str_if_eq:VnF \l_@@_tmpb_tl { \scan_stop: }
              { : \l_@@_tmpb_tl }
            \bool_if:NT \l_@@_macro_TF_bool { TF }
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{The \env{function} environment}
%
%    \begin{macrocode}
\keys_define:nn { l3doc/function }
  {
    TF .value_forbidden:n = true ,
    TF .code:n =
      {
        \bool_set_true:N \l_@@_macro_TF_bool
      } ,
    EXP .value_forbidden:n = true ,
    EXP .code:n =
      {
        \bool_set_true:N \l_@@_macro_EXP_bool
        \bool_set_false:N \l_@@_macro_rEXP_bool
      } ,
    rEXP .value_forbidden:n = true ,
    rEXP .code:n =
      {
        \bool_set_false:N \l_@@_macro_EXP_bool
        \bool_set_true:N \l_@@_macro_rEXP_bool
      } ,
    pTF .value_forbidden:n = true ,
    pTF .code:n =
      {
        \bool_set_true:N \l_@@_macro_pTF_bool
        \bool_set_true:N \l_@@_macro_TF_bool
        \bool_set_true:N \l_@@_macro_EXP_bool
        \bool_set_false:N \l_@@_macro_rEXP_bool
      } ,
    noTF .value_forbidden:n = true ,
    noTF .code:n =
      {
        \bool_set_true:N \l_@@_macro_noTF_bool
        \bool_set_true:N \l_@@_macro_TF_bool
      } ,
    added .code:n = { \@@_date_set_past:Nn \l_@@_date_added_tl {#1} },
    updated .code:n = { \@@_date_set_past:Nn \l_@@_date_updated_tl {#1} } ,
    deprecated .bool_set:N = \l_@@_macro_deprecated_bool , 
    no-user-doc .bool_set:N = \l_@@_macro_nodoc_bool ,
    tested .code:n = { } ,
    label .code:n =
      {
        \clist_set:Nn \l_@@_function_label_clist {#1}
        \bool_set_true:N \l_@@_no_label_bool
      } ,
    verb .value_forbidden:n = true ,
    verb .bool_set:N = \l_@@_names_verb_bool ,
    module .tl_set:N = \l_@@_override_module_tl ,
  }
%    \end{macrocode}
%
% \begin{macro}[do-not-index={\A,\Z,\d,\1,\2,\3}]
%     {\@@_date_set:Nn,\@@_date_set_past:Nn}
%   Normalize the date into the format \texttt{YYYY-MM-DD}; more
%   precisely month and day are allowed to be single digits.  The
%   \cs{@@_date_set_past:Nn} function only allows dates in the past (or
%   same day).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_date_set:Nn #1#2
  {
    \tl_set:Nn #1 {#2}
    \regex_replace_once:nnNF
      { \A(\d\d\d\d)[-/](\d\d?)[-/](\d\d?)\Z } { \1-\2-\3 } #1
      {
        \msg_error:nnn { l3doc } { date-format } {#2}
        \tl_set:Nn #1 { 1970-01-01 }
      }
  }
\cs_new_protected:Npn \@@_date_set_past:Nn #1#2
  {
    \@@_date_set:Nn #1 {#2}
    \exp_args:No \@@_date_compare:nNnT
      {#1} > { \c_sys_year_int - \c_sys_month_int - \c_sys_day_int }
      {
        \msg_error:nnee { l3doc } { future-date }
          { \tl_to_str:N \l_@@_macro_argument_tl }
          {#1}
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_function:nnw}
%   \begin{arguments}
%     \item Key--value list.
%     \item Comma-separated list of functions; input has already been
%       sanitised by catcode changes before reading the argument.
%   \end{arguments}
% \begin{macro}{\@@_function_end:}
%   Make sure any paragraph is finished, and similar safe practices at
%   the beginning of an environment which will typeset material.
%   Initialize some variables.  Parse the key--value list.  Clean up the
%   list of functions, then go through them to extract some data.  After
%   this, typeset the function names in the coffin
%   \cs{l_@@_functions_coffin} and measure it to know if it fits in the
%   margin.  Finally, start a vertical coffin for the main part of the
%   environment.  This coffin stops when the environment ends, then all
%   the pieces are assembled into a single coffin, which is typeset.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function:nnw #1#2
  {
    \@@_function_typeset_start:
    \@@_function_init:
    \tl_set:Nn \l_@@_macro_argument_tl {#2}
    \keys_set:nn { l3doc/function } {#1}
    \@@_names_get_seq:nN {#2} \l_@@_names_seq
    \@@_names_parse:
    \@@_function_typeset:
    \@@_function_reset:
    \@@_function_descr_start:w
  }
\cs_new_protected:Npn \@@_function_end:
  {
    \@@_function_descr_stop:
    \@@_function_assemble:
    \@@_function_typeset_stop:
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}
%   {\@@_function_typeset_start:, \@@_function_typeset_stop:}
%   At the start of the \env{function} environment, before performing
%   any assignment, close the last paragraph, and set up the typesetting
%   scene.  Further code typesets a coffin, so we end the paragraph and
%   allow a page break.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function_typeset_start:
  {
    \par \bigskip \noindent
  }
\cs_new_protected:Npn \@@_function_typeset_stop:
  {
    \par
    \dim_set:Nn \prevdepth { \box_dp:N \l_@@_descr_coffin }
    \allowbreak
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_function_init:}
%   Complain if \texttt{function} environments are nested.  Clear
%   various variables.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function_init:
  {
    \box_if_empty:NF \g_@@_syntax_box
      { \msg_error:nn { l3doc } { syntax-nested-function } }
    \coffin_clear:N \l_@@_descr_coffin
    \box_gclear:N \g_@@_syntax_box
    \coffin_clear:N \l_@@_syntax_coffin
    \coffin_clear:N \l_@@_functions_coffin
    \bool_set_false:N \l_@@_macro_TF_bool
    \bool_set_false:N \l_@@_macro_pTF_bool
    \bool_set_false:N \l_@@_macro_noTF_bool
    \bool_set_false:N \l_@@_macro_EXP_bool
    \bool_set_false:N \l_@@_macro_rEXP_bool
    \bool_set_false:N \l_@@_no_label_bool
    \bool_set_false:N \l_@@_names_verb_bool
    \bool_set_true:N \l_@@_in_function_bool
    \clist_clear:N \l_@@_function_label_clist
    \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
    \char_set_active_eq:NN \< \@@_shorthand_meta:
    \char_set_catcode_active:N \<
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_shorthand_meta:, \@@_shorthand_meta:w}
%   Allow |<...>| to be used as markup for |\meta{...}|.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_shorthand_meta:
  { \mode_if_math:TF { < } { \@@_shorthand_meta:w } }
\cs_new_protected_nopar:Npn \@@_shorthand_meta:w #1 > { \meta {#1} }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_function_reset:}
%   Clear some variables.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function_reset:
  {
    \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_function_typeset:}
%   Typeset in the coffin \cs{l_@@_functions_coffin} the functions listed in
%   \cs{l_@@_names_block_tl} and the relevant dates, then set
%   \cs{l_@@_long_name_bool} to be \texttt{true} if this coffin is
%   larger than the available width in the margin.  The function
%   \cs{@@_typeset_functions:} is quite involved hence given later.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function_typeset:
  {
    \dim_zero:N \l_@@_trial_width_dim
    \hcoffin_set:Nn \l_@@_functions_coffin { \@@_typeset_functions: }
    \dim_set:Nn \l_@@_trial_width_dim
      { \box_wd:N \l_@@_functions_coffin }
    \bool_set:Nn \l_@@_long_name_bool
      { \dim_compare_p:nNn \l_@@_trial_width_dim > \marginparwidth }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {\@@_function_descr_start:w, \@@_function_descr_stop:}
%   The last step in \cs{@@_function:nnw} (the beginning of a
%   \env{function} environment) is to open a coffin which will capture
%   the description of the function, namely the body of the
%   \env{function} environment.  This is closed by \cs{@@_function_end:}
%   (the end of a \env{function} environment).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function_descr_start:w
  {
    \vcoffin_set:Nnw \l_@@_descr_coffin { \textwidth }
      \noindent \ignorespaces
  }
\cs_new_protected:Npn \@@_function_descr_stop:
  { \vcoffin_set_end: }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_function_assemble:}
%   The box \cs{g_@@_syntax_box} contains the contents of the syntax
%   environment if it was used.  Now that we have all the pieces, join
%   together the syntax coffin, the names coffin, and the description
%   coffin.  The relative positions depend on whether the names coffin
%   fits in the margin.  Then typeset the combination.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function_assemble:
  {
    \hcoffin_set:Nn  \l_@@_syntax_coffin
      { \box_use_drop:N \g_@@_syntax_box }
    \bool_if:NTF \l_@@_long_name_bool
      {
        \coffin_join:NnnNnnnn
          \l_@@_output_coffin {hc} {vc}
          \l_@@_syntax_coffin {l} {T}
          {0pt} {0pt}
        \coffin_join:NnnNnnnn
          \l_@@_output_coffin {l} {t}
          \l_@@_functions_coffin  {r} {t}
          {-\marginparsep} {0pt}
        \coffin_join:NnnNnnnn
          \l_@@_output_coffin {l} {b}
          \l_@@_descr_coffin  {l} {t}
          {0.75\marginparwidth + \marginparsep} {-\medskipamount}
        \coffin_typeset:Nnnnn \l_@@_output_coffin
          {\l_@@_descr_coffin-l} {\l_@@_descr_coffin-t}
          {0pt} {0pt}
      }
      {
        \coffin_join:NnnNnnnn
          \l_@@_output_coffin {hc} {vc}
          \l_@@_syntax_coffin {l} {t}
          {0pt} {0pt}
        \coffin_join:NnnNnnnn
          \l_@@_output_coffin {l} {b}
          \l_@@_descr_coffin  {l} {t}
          {0pt} {-\medskipamount}
        \coffin_join:NnnNnnnn
          \l_@@_output_coffin {l} {t}
          \l_@@_functions_coffin  {r} {t}
          {-\marginparsep} {0pt}
        \coffin_typeset:Nnnnn \l_@@_output_coffin
          {\l_@@_syntax_coffin-l} {\l_@@_syntax_coffin-T}
          {0pt} {0pt}
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_typeset_functions:}
%   This function builds the \cs{l_@@_functions_coffin} by typesetting the
%   function names (with variants) and the relevant dates in a
%   \env{tabular} environment.  The use of rules \tn{toprule},
%   \tn{midrule} and \tn{bottomrule} requires whatever lies between the
%   last |\\| and the rule to be expandable, making our lives a bit
%   complicated.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_typeset_functions:
  {
    \small\ttfamily
    \@@_target:
    \Hy@MakeCurrentHref { HD. \int_use:N \c@HD@hypercount }
    \begin{tabular} [t] { @{} l @{} >{\hspace{\tabcolsep}} r @{} }
      \toprule
      \@@_function_extra_labels:
      \@@_names_typeset:
      \@@_typeset_dates:
      \bottomrule
    \end{tabular}
    \normalfont\normalsize
  }
%    \end{macrocode}
% \end{macro}
%
% ^^A TODO: collect all index targets from a given function environment in a box and stick it at the top.
% \begin{macro}
%   {\@@_typeset_function_block:nN, \@@_typeset_function_block:eN}
% \begin{macro}{\@@_function_index:n, \@@_function_index:e}
%   |#1| is a csname, |#2| a boolean indicating whether to add |TF| or not.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_typeset_function_block:nN #1#2
  {
    \@@_function_index:e
      { #1 \bool_if:NT #2 { \tl_to_str:n {TF} } }
    \@@_function_label:eN {#1} #2
    #1
    \bool_if:NT #2 { \@@_typeset_TF: }
    \@@_typeset_expandability:
    \seq_if_empty:NF \g_@@_variants_seq
      { \@@_typeset_variant_list:nN {#1} #2 }
    \\
  }
\cs_generate_variant:Nn \@@_typeset_function_block:nN { e }
\cs_new_protected:Npn \@@_function_index:n #1
  {
    \seq_gput_right:Nn \g_doc_functions_seq {#1}
    \@@_special_index:nn {#1} { usage }
  }
\cs_generate_variant:Nn \@@_function_index:n { e }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_typeset_expandability:
  {
    &
    \bool_if:NT \l_@@_macro_EXP_bool  { \@@_typeset_exp: }
    \bool_if:NT \l_@@_macro_rEXP_bool { \@@_typeset_rexp: }
  }
%    \end{macrocode}
%
% |#1| is the function, |#2| whether to add |TF|.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_typeset_variant_list:nN #1#2
  {
    \\
    \@@_typeset_aux:n { \@@_get_function_name:n {#1} }
    :
    \int_compare:nTF { \seq_count:N \g_@@_variants_seq == 1 }
      {
        \seq_use:Nn \g_@@_variants_seq { }
        \bool_if:NT #2 { \@@_typeset_TF: }
      }
      {
        \hbox_set:Nn \l_tmpa_box
          { \seq_use:Nn \g__@@_variants_seq { \textrm| \nolinebreak[2] } }
        \textrm(
%    \end{macrocode}
%
%   Set long variant lists in a parbox, short lists set natural length.
%    \begin{macrocode}
        \dim_compare:nNnTF { \box_wd:N \l_tmpa_box } > { .4\columnwidth }
          {
            \parbox[t]{.4\columnwidth}
              {
                \raggedright
                \hbox_unpack_drop:N \l_tmpa_box
                \textrm)
                \bool_if:NT #2 { \@@_typeset_TF: }
              }
          }
          {
            \hbox_unpack_drop:N \l_tmpa_box
            \textrm)
            \bool_if:NT #2 { \@@_typeset_TF: }
          }
      }
    \@@_typeset_expandability:
  }
%    \end{macrocode}
%
% |#1| is the function name, |#2| whether to add |TF|.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_function_extra_labels:
  {
    \bool_if:NT \l_@@_no_label_bool
      {
        \clist_map_inline:Nn \l_@@_function_label_clist
          {
            \@@_get_hyper_target:oN { \token_to_str:N ##1 }
              \l_@@_tmpa_tl
            \exp_args:No \label { \l_@@_tmpa_tl }
          }
      }
  }
\cs_new_protected:Npn \@@_function_label:nN #1#2
  {
    \bool_if:NF \l_@@_no_label_bool
      {
        \@@_get_hyper_target:eN
          {
            \exp_not:n {#1}
            \bool_if:NT #2 { \tl_to_str:n {TF} }
          }
          \l_@@_tmpa_tl
        \exp_args:No \label { \l_@@_tmpa_tl }
      }
  }
\cs_generate_variant:Nn \@@_function_label:nN { e }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_typeset_dates:}
%   To display metadata for when functions are added/modified.
%   This function must be expandable since it produces rules for use in
%   alignments.
%    \begin{macrocode}
\cs_new:Npn \@@_typeset_dates:
  {
    \bool_lazy_and:nnF
      { \tl_if_empty_p:N \l_@@_date_added_tl }
      { \tl_if_empty_p:N \l_@@_date_updated_tl }
      { \midrule }
    \tl_if_empty:NF \l_@@_date_added_tl
      {
        \multicolumn { 2 } { @{} r @{} }
          { \scriptsize New: \, \l_@@_date_added_tl } \\
      }

    \tl_if_empty:NF \l_@@_date_updated_tl
      {
        \multicolumn { 2 } { @{} r @{} }
          { \scriptsize Updated: \, \l_@@_date_updated_tl } \\
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_syntax:w, \@@_syntax_end:}
%   Implement the \env{syntax} environment.
%    \begin{macrocode}
\dim_new:N \l_@@_syntax_dim
\cs_new_protected:Npn \@@_syntax:w
  {
    \box_if_empty:NF \g_@@_syntax_box
      { \msg_error:nn { l3doc } { multiple-syntax } }
    \dim_set:Nn \l_@@_syntax_dim
      {
        \textwidth
        \bool_if:NT \l_@@_long_name_bool
          { + 0.75 \marginparwidth - \l_@@_trial_width_dim }
      }
    \hbox_gset:Nw \g_@@_syntax_box
      \small \ttfamily
      \arrayrulecolor{white}
      \begin{tabular} { @{} l @{} }
        \toprule
        \begin{minipage}[t]{\l_@@_syntax_dim}
          \raggedright
          \obeyspaces
          \obeylines
  }
\cs_new_protected:Npn \@@_syntax_end:
  {
        \end{minipage}
      \end{tabular}
      \arrayrulecolor{black}
    \hbox_gset_end:
    \bool_if:NF \l_@@_in_function_bool
      {
        \begin{quote}
          \mode_leave_vertical:
          \box_use_drop:N \g_@@_syntax_box
        \end{quote}
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{The \env{macro} environment}
%
% Keyval for the \env{macro} environment.
% TODO: provide document command for documenting keys.
%    \begin{macrocode}
\keys_define:nn { l3doc/macro }
  {
    aux .value_forbidden:n = true ,
    aux .code:n =
      {
        \msg_warning:nnnn { l3doc } { deprecated-option }
          { aux } { function/macro }
      } ,
    deprecated .bool_set:N = \l_@@_macro_deprecated_bool , 
    internal .value_forbidden:n = true ,
    internal .code:n =
      { \bool_set_true:N \l_@@_macro_internal_bool } ,
    int .value_forbidden:n = true ,
    int .code:n =
      { \bool_set_true:N \l_@@_macro_internal_bool } ,
    no-user-doc .bool_set:N = \l_@@_macro_nodoc_bool ,
    var .value_forbidden:n = true ,
    var .code:n =
      { \bool_set_true:N \l_@@_macro_var_bool } ,
    TF .value_forbidden:n = true ,
    TF .code:n =
      { \bool_set_true:N \l_@@_macro_TF_bool } ,
    pTF .value_forbidden:n = true ,
    pTF .code:n =
      {
        \bool_set_true:N \l_@@_macro_TF_bool
        \bool_set_true:N \l_@@_macro_pTF_bool
        \bool_set_true:N \l_@@_macro_EXP_bool
        \bool_set_false:N \l_@@_macro_rEXP_bool
      } ,
    noTF .value_forbidden:n = true ,
    noTF .code:n =
      {
        \bool_set_true:N \l_@@_macro_TF_bool
        \bool_set_true:N \l_@@_macro_noTF_bool
      } ,
    EXP .value_forbidden:n = true ,
    EXP .code:n =
      {
        \bool_set_true:N \l_@@_macro_EXP_bool
        \bool_set_false:N \l_@@_macro_rEXP_bool
      } ,
    rEXP .value_forbidden:n = true ,
    rEXP .code:n =
      {
        \bool_set_false:N \l_@@_macro_EXP_bool
        \bool_set_true:N \l_@@_macro_rEXP_bool
      } ,
    tested .code:n =
      {
        \bool_set_true:N \l_@@_macro_tested_bool
      } ,
    added .code:n = {} , % TODO
    updated .code:n = {} , % TODO
    verb .bool_set:N = \l_@@_names_verb_bool ,
    module .tl_set:N = \l_@@_override_module_tl ,
    documented-as .tl_set:N = \l_@@_macro_documented_tl ,
    do-not-index .value_required:n = true ,
    do-not-index .tl_set:N = \l_@@_macro_do_not_index_tl ,
    % do-not-index .default:n = \q_no_value ,
  }
%    \end{macrocode}
%
% \begin{macro}{\@@_macro:nnw}
%   The arguments are a key--value list of \meta{options} and a
%   comma-list of \meta{names}, read verbatim by \pkg{ltcmd}.  First
%   initialize some variables before applying the \meta{options}, then
%   parse the \meta{names} to get a sequence of macro names, then apply
%   \cs{@@_macro_single:nNN} to each (this step is more subtle than
%   \cs{seq_map_function:NN} because of |TF|/|pTF|/|noTF|).  Finally typeset
%   the macro names in the margin.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro:nnw #1#2
  {
    \@@_macro_init:
    \tl_set:Nn \l_@@_macro_argument_tl {#2}
    \keys_set:nn { l3doc/macro } {#1}
    \@@_names_get_seq:nN {#2} \l_@@_names_seq
    \@@_names_parse:
    \@@_macro_exclude_index:
    \@@_macro_save_names:
    \@@_names_typeset:
    \@@_macro_dump:
    \@@_macro_reset:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_init:}
%   The booleans hold various key--value options,
%   \cs{l_@@_nested_macro_int} counts the number of \env{macro}
%   environments around the current point (is $0$ outside).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_init:
  {
    \int_incr:N \l_@@_nested_macro_int
    \bool_set_false:N \l_@@_macro_deprecated_bool
    \bool_set_false:N \l_@@_macro_internal_bool
    \bool_set_false:N \l_@@_macro_TF_bool
    \bool_set_false:N \l_@@_macro_pTF_bool
    \bool_set_false:N \l_@@_macro_noTF_bool
    \bool_set_false:N \l_@@_macro_EXP_bool
    \bool_set_false:N \l_@@_macro_rEXP_bool
    \bool_set_false:N \l_@@_macro_var_bool
    \bool_set_false:N \l_@@_macro_tested_bool
    \bool_set_false:N \l_@@_names_verb_bool
    \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
    \tl_clear:N \l_@@_macro_documented_tl
    \cs_set_eq:NN \testfile \@@_print_testfile:n
    \box_clear:N \l_@@_macro_index_box
    \vbox_set:Nn \l_@@_macro_box
      {
        \hbox:n
          {
            \strut
            \int_compare:nNnT \l_@@_macro_int = 0 { \@@_target: }
          }
        \vskip \int_eval:n { \l_@@_macro_int - 1 } \baselineskip
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_reset:}
%   We ensure that \cs{cs} commands nested inside a macro whose module
%   is imposed are not affected.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_reset:
  {
    \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_save_names:}
% \begin{macro}[EXP]{\@@_macro_save_names_aux:w}
%   The list of names defined in a set of \env{macro} environments is
%   eventually used to display on which page they are documented.  If
%   the |documented-as| key is given, use that, otherwise find names in
%   \cs{l_@@_names_block_tl}. The |documented-as| needs to be detokenized
%   without adding a space, so it has to be treated in a slightly awkward
%   way.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_save_names:
  {
    \tl_if_empty:NTF \l_@@_macro_documented_tl
      { \@@_names_block_base_map:N \@@_macro_save_names_aux:n }
      {
        \seq_gput_right:Ne \g_@@_nested_names_seq
          {
            \exp_after:wN \@@_macro_save_names_aux:w
              \l_@@_macro_documented_tl \q_@@_stop
          }
      }
  }
\cs_new:Npn \@@_macro_save_names_aux:w #1#2 \q_@@_stop
  { \token_to_str:N #1 \tl_to_str:n {#2} }
\cs_new_protected:Npn \@@_macro_save_names_aux:n #1
  { \seq_gput_right:Nn \g_@@_nested_names_seq {#1} }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_macro_exclude_index:}
%   Some control sequences in a \env{macrocode} environment shouldn't
%   be indexed, for different reasons. This macro parses the argument
%   of the |do-not-index| option and locally removes the given macros
%   from the index.
%
%   The optional argument to \env{macro} is not scanned with verbatim
%   catcodes, so we use \cs{tl_set_rescan:NnV} to rescan the commands
%   with the same catcodes as \cs{DoNotIndex}. The scanned token list
%   contains spaces after control sequences, which are not there when
%   \cs{DoNotIndex} is used. Since \cs{seq_set_from_clist:Nn} removes
%   spaces around the items, we can abuse that and \cs{seq_use:Nn} to
%   normalise each item. After that \cs{DoNotIndex} can do its thing.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_exclude_index:
  {
    \tl_if_empty:NF \l_@@_macro_do_not_index_tl
      {
        \tl_set_rescan:NnV \l_@@_macro_do_not_index_tl
          { \MakePrivateLetters \catcode`\\12 }
          \l_@@_macro_do_not_index_tl
        \exp_args:NNV \seq_set_from_clist:Nn
          \l_@@_tmpa_seq \l_@@_macro_do_not_index_tl
        \__kernel_tl_set:Nx \l_@@_macro_do_not_index_tl
          { \seq_use:Nn \l_@@_tmpa_seq { , } }
        \exp_args:NV \DoNotIndex \l_@@_macro_do_not_index_tl
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_dump:}
%   This calls |\makelabel{}|
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_dump:
  {
    \topsep\MacroTopsep
    \trivlist
    \cs_set:Npn \makelabel ##1
      {
        \llap
          {
            \hbox_unpack_drop:N \l_@@_macro_index_box
            \vtop to \baselineskip
              {
                \vbox_unpack_drop:N \l_@@_macro_box
                \vss
              }
          }
      }
    \item [ ]
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_typeset_block:nN}
%   Used to typeset a macro and its variants.  |#1| is the macro name,
%   |#2| is a boolean controlling whether to add |TF|.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_typeset_block:nN #1#2
  {
    \@@_macro_single:nNN {#1} \c_true_bool #2
    \seq_if_empty:NF \g_@@_variants_seq
      {
        \@@_macro_typeset_variant_list:eN
          { \@@_get_function_name:n {#1} } #2
      }
  }
\cs_new_protected:Npn \@@_macro_typeset_variant_list:nN #1#2
  {
    \seq_map_inline:Nn \g_@@_variants_seq
      { \@@_macro_single:nNN { #1 : ##1 } \c_false_bool #2 }
  }
\cs_generate_variant:Nn \@@_macro_typeset_variant_list:nN { e }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_single:nNN}
%   The arguments are |#1| a macro name (without |TF|), |#2| a boolean
%   determining whether or not to index, and |#3| whether or not to add |TF|.
%   Let's start to mess around with \cls{doc}'s \env{macro} environment.
%   See \file{doc.dtx} for a full explanation of the original
%   environment.  It's rather \emph{enthusiastically} commented.
%   \begin{arguments}
%     \item Macro/function/whatever name; input has already been
%       sanitised.
%   \end{arguments}
%   The assignments to \cs{saved@macroname} and \cs{saved@indexname}
%   are used by \pkg{doc}'s \cs{changes} mechanism.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_single:nNN #1#2#3
  {
    \tl_set:Nn \saved@macroname {#1}
    \@@_macro_typeset_one:nN {#1} #3
    \bool_if:NT #3 { \DoNotIndex {#1} }
    \exp_args:Ne \@@_macro_index:nN
      { #1 \bool_if:NT #3 { \tl_to_str:n { TF } } }
      #2
  }
\cs_new_protected:Npn \@@_macro_index:nN #1#2
  {
    \DoNotIndex {#1}
    \bool_if:NT #2
      {
        \bool_lazy_any:nF
          {
            { \@@_if_macro_internal_p:n {#1} }
            { \l_@@_macro_deprecated_bool }
            { \l_@@_macro_nodoc_bool }
          }
          { \seq_gput_right:Nn \g_doc_macros_seq {#1} }
        \hbox_set:Nw \l_@@_macro_index_box
          \hbox_unpack_drop:N \l_@@_macro_index_box
          \int_gincr:N \c@CodelineNo
          \@@_special_index:nn {#1} { main }
          \int_gdecr:N \c@CodelineNo
        \exp_args:NNNo \hbox_set_end:
          \tl_set:Nn \saved@indexname { \l_@@_index_key_tl }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_typeset_one:nN}
%   For a long time, \cls{l3doc} collected the macro names as labels in
%   the first items of nested \tn{trivlist}, but these were not closed
%   properly with \tn{endtrivlist}.  Also, it interacted in surprising
%   ways with \pkg{hyperref} targets.  Now, we collect typeset macro
%   names by hand in the box \cs{l_@@_macro_box}.  The fixed-size space
%   |\MacroFont\ | could be replaced by an customizable horizontal
%   space; it is important for it to be the same for all macros.
%   |#1| is the macro name, |#2| whether to add |TF|.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_typeset_one:nN #1#2
  {
    \vbox_set:Nn \l_@@_macro_box
      {
        \vbox_unpack_drop:N \l_@@_macro_box
        \hbox { \llap { \@@_print_macroname:nN {#1} #2
            \MacroFont \
        } }
      }
    \int_incr:N \l_@@_macro_int
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_print_macroname:nN}
%   In the name, spaces are replaced by other spaces to ensure they get
%   displayed in case there are any.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_print_macroname:nN #1#2
  {
    \strut
    \@@_get_hyper_target:eN
      {
        \exp_not:n {#1}
        \bool_if:NT #2 { \tl_to_str:n {TF} }
      }
      \l_@@_tmpa_tl
    \cs_if_exist:cTF { r@ \l_@@_tmpa_tl }
      { \exp_last_unbraced:NNo \hyperref [ \l_@@_tmpa_tl ] }
      { \use:n }
      {
        \int_compare:nTF { \str_count:n {#1} <= 28 }
          { \MacroFont } { \MacroLongFont }
        \tl_set:Nn \l_@@_tmpa_tl {#1}
        \tl_replace_all:NnV \l_@@_tmpa_tl
          { ~ } \c_catcode_other_space_tl
        \@@_print_macroname_aux:on
          \l_@@_tmpa_tl { \bool_if:NT #2 { \@@_typeset_TF: } }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_print_macroname_aux:nn}
%  |#1| is prefix, |#2| is optional |TF| suffix.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_print_macroname_aux:nn #1#2
  {
    \@@_if_macro_internal:nTF {#1}
      { \@@_typeset_aux:n { #1 #2 } } { #1 #2 }
  }
\cs_generate_variant:Nn \@@_print_macroname_aux:nn { o }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\MacroLongFont}
%    \begin{macrocode}
\providecommand \MacroLongFont
  {
    \fontfamily{lmtt}\fontseries{lc}\small
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_print_testfile:n, \@@_print_testfile_aux:n}
%   Used to show that a macro has a test, somewhere.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_print_testfile:n #1
  {
    \bool_set_true:N \l_@@_macro_tested_bool
    \tl_if_eq:nnF {#1} {*}
      {
        \seq_if_in:NnF \g_@@_testfiles_seq {#1}
          {
            \seq_gput_right:Nn \g_@@_testfiles_seq {#1}
            \par
            \@@_print_testfile_aux:n {#1}
          }
      }
  }
\cs_new_protected:Npn \@@_print_testfile_aux:n #1
  {
    \footnotesize
    (
    \textit
      {
        The~ test~ suite~ for~ this~ command,~
        and~ others~ in~ this~ file,~ is~ \textsf{#1}
      }.
    )\par
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\TestFiles}
%    \begin{macrocode}
\DeclareDocumentCommand \TestFiles {m}
  {
    \par
    \textit
      {
        The~ following~ test~ files~ are~
        used~ for~ this~ code:~ \textsf{#1}.
      }
    \par \ignorespaces
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\UnitTested}
%    \begin{macrocode}
\DeclareDocumentCommand \UnitTested { } { \testfile* }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\TestMissing}
%    \begin{macrocode}
\DeclareDocumentCommand \TestMissing { m }
  { \@@_test_missing:n {#1} }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_test_missing:n}
%   Keys in \cs{g_@@_missing_tests_prop} are lists of macros given as
%   arguments of one \env{macro} environment.  Values are pairs of a
%   file name and a comment about the missing tests.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_test_missing:n #1
  {
    \@@_test_missing_aux:Nen
      \g_@@_missing_tests_prop
      { \seq_use:Nn \l_@@_names_seq { , } }
      { { \g_file_curr_name_str \c_space_tl (#1) } }
  }
\cs_new_protected:Npn \@@_test_missing_aux:Nnn #1#2#3
  {
    \prop_get:NnNTF #1 {#2} \l_@@_tmpa_tl
      { \tl_put_right:Nn \l_@@_tmpa_tl { , #3 } }
      { \tl_set:Nn \l_@@_tmpa_tl {#3} }
    \prop_put:Nno #1 {#2} \l_@@_tmpa_tl
  }
\cs_generate_variant:Nn \@@_test_missing_aux:Nnn { Ne }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_end:}
%   It is too late for anyone to declare a test file for this macro, so
%   we can check now whether the macro is tested.  If the \env{macro}
%   environment which is being ended is the outermost one, then wrap
%   each macro in \tn{texttt} (with the addition of |TF| if relevant)
%   and typeset two informations: that this ends the definition of some
%   macros, and that they are documented on some page.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_end:
  {
    \endtrivlist
    \@@_macro_end_check_tested:
    \int_compare:nNnT \l_@@_nested_macro_int = 1
      { \@@_macro_end_style:n { \@@_print_end_definition: } }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_end_check_tested:}
%   If the |checktest| option was issued and the macro is not an
%   auxiliary nor a variable (and it does not have a test), then add it
%   to the sequence of non-tested macros.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_end_check_tested:
  {
    \bool_lazy_all:nT
      {
        { \g_@@_checktest_bool }
        { ! \l_@@_macro_var_bool }
        { ! \l_@@_macro_tested_bool }
      }
      {
        \seq_set_filter:NNn \l_@@_tmpa_seq \l_@@_names_seq
          { ! \@@_if_macro_internal_p:n {##1} }
        \seq_gput_right:Ne \g_@@_not_tested_seq
          {
            \seq_use:Nn \l_@@_tmpa_seq { , }
            \bool_if:NTF \l_@@_macro_pTF_bool {~(pTF)}
              { \bool_if:NT \l_@@_macro_TF_bool {~(TF)} }
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_macro_end_style:n}
%   Style for the extra information at the end of a top-level
%   \env{macro} environment.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_end_style:n #1
  {
    \nobreak \noindent
    { \footnotesize ( \emph{#1} ) \par }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \@@_print_end_definition:,
%     \@@_macro_end_wrap_item:n,
%     \@@_print_documented:
%   }
%   Surround each item by \tn{texttt}, replacing |_|
%   by \tn{_} as well.  Then list the
%   macro names through \cs{seq_use:Nnnn}, unless there are too many.
%   Finally, if the macro is neither auxiliary nor internal, add a link
%   to where it is documented.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_macro_end_wrap_item:n #1
  {
    \tl_set:Nn \l_@@_tmpa_tl {#1}
    \tl_replace_all:NVn \l_@@_tmpa_tl
      \c_underscore_str { \_ }
    \texttt { \l_@@_tmpa_tl }
  }
\cs_new_protected:Npn \@@_print_end_definition:
  {
    \seq_set_map:NNn \l_@@_tmpa_seq
      \g_@@_nested_names_seq
      { \@@_macro_end_wrap_item:n {##1} }
    End~ of~ definition~ for~
    \int_compare:nTF { \seq_count:N \l_@@_tmpa_seq <= 3 }
      {
        \seq_use:Nnnn \l_@@_tmpa_seq
          { \,~and~ } { \,,~ } { \,,~and~ }
      }
      { \seq_item:Nn \l_@@_tmpa_seq {1}\,~and~others }
    \@.
    \@@_print_documented:
  }
\cs_new_protected:Npn \@@_print_documented:
  {
    \seq_gset_filter:NNn \g_@@_nested_names_seq
      \g_@@_nested_names_seq
      {
        ! \bool_lazy_any_p:n
          {
            { \@@_if_macro_internal_p:n {##1} }
            { \l_@@_macro_deprecated_bool }
            { \l_@@_macro_nodoc_bool }
          }
      }
    \seq_if_empty:NF \g_@@_nested_names_seq
      {
        \int_set:Nn \l_@@_tmpa_int
          { \seq_count:N \g_@@_nested_names_seq }
        \int_compare:nNnTF \l_@@_tmpa_int = 1 {~This~} {~These~}
        \bool_if:NTF \l_@@_macro_var_bool {variable} {function}
        \int_compare:nNnTF \l_@@_tmpa_int = 1 {~is~} {s~are~}
        documented~on~page~
        \@@_get_hyper_target:eN
          { \seq_item:Nn \g_@@_nested_names_seq { 1 } }
          \l_@@_tmpa_tl
        \exp_args:Ne \pageref { \l_@@_tmpa_tl } .
      }
    \seq_gclear:N \g_@@_nested_names_seq
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Misc}
%
% \begin{macro}{\DescribeOption}
%   For describing package options: retained for consistency, but updated for
%   \pkg{doc}~v3.
%    \begin{macrocode}
\NewDocElement[idxtype = option, idxgroup = options]{Option}{optionenv}  
%    \end{macrocode}
% \end{macro}
%
% Here are some definitions for additional markup that helps to
% structure your documentation.
%
% \begin{environment}{danger}
% \begin{environment}{ddanger}
%   \begin{syntax}
%     |\begin{[d]danger}|\\
%       dangerous code\\
%     |\end{[d]danger}|
%   \end{syntax}
%   \begin{danger}
%     Provides a danger bend, as known from the \TeX{}book.
%   \end{danger}
%   The actual character from the font |manfnt|:
%    \begin{macrocode}
\font \manual = manfnt \scan_stop:
\cs_gset:Npn \dbend { {\manual\char127} }
%    \end{macrocode}
%
% Defines the single danger bend. Use it whenever there is a feature in
% your package that might be tricky to use.  FIXME: Has to be fixed when
% in combination with a macro-definition.
%    \begin{macrocode}
\newenvironment {danger}
  {
    \begin{trivlist}\item[]\noindent
    \begingroup\hangindent=2pc\hangafter=-2
    \cs_set:Npn \par{\endgraf\endgroup}
    \hbox to0pt{\hskip-\hangindent\dbend\hfill}\ignorespaces
  }
  {
    \par\end{trivlist}
  }
%    \end{macrocode}
%
% \begin{ddanger}
%   Use the double danger bend if there is something which could cause
%   serious problems when used in a wrong way. Better the normal user
%   does not know about such things.
% \end{ddanger}
%    \begin{macrocode}
\newenvironment {ddanger}
  {
    \begin{trivlist}\item[]\noindent
    \begingroup\hangindent=3.5pc\hangafter=-2
    \cs_set:Npn \par{\endgraf\endgroup}
    \hbox to0pt{\hskip-\hangindent\dbend\kern2pt\dbend\hfill}\ignorespaces
  }{
      \par\end{trivlist}
  }
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \subsubsection{NB and NOTE}
%
% These macros are intended for additional notes added to the source that are not typeset.
%
% \begin{macro}{\NB}
% \NB{wspr}{this is what I think about this!}
% \begin{verbatim}
%   \NB{wspr}{this is what I think about this!}
% \end{verbatim}
%    \begin{macrocode}
\bool_if:NTF \g_@@_show_notes_bool
  {
    \NewDocumentCommand\NB{mm}
      {
        (\emph{Note}\footnote{\ttfamily [#1]:~\detokenize{#2}})
      }
  }
  {
    \NewDocumentCommand\NB{mm}{}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{NOTE}
% \begin{NOTE}{wspr}
%   this is what I #$%& think about this!
% \end{NOTE}
% \begin{verbatim}
%   \begin{NOTE}{wspr}
%     this is what I #$%& think about this!
%   \end{NOTE}
% \end{verbatim}
%    \begin{macrocode}
\bool_if:NTF \g_@@_show_notes_bool
  {
    \NewDocumentEnvironment{NOTE}{m}
      {
        \par\noindent (\emph{Note}~[\texttt{#1}]:\par
        \verbatim
      }
      {
        \endverbatim
        \par\noindent \emph{Note~end})\par
      }
  }
  {
    \NewDocumentEnvironment{NOTE}{m}{\comment}{\endcomment}
  }
%    \end{macrocode}
% \end{environment}
%
% \subsection{Footnote support}
% The environments \env{function} and \env{variable} are boxes
% and so looses footnotes. The following implements support.
% It relies currently on an internal from hyperref to get the correct targets.
% 
%    \begin{macrocode}
\providecommand\Hy@footnote@currentHref{}
\prop_new:N\g_@@_fnmark_prop
\cs_new_protected:Npn \@@_fn_store: 
  { 
    \prop_gput:Nee\g_@@_fnmark_prop 
      {fn\int_use:N\c@footnote}{{\Hy@footnote@currentHref}{\int_use:N\c@footnote}}
  }
\cs_new_protected:Npn \@@_fn_restore:n  #1
  {
    \prop_get:NnN \g_@@_fnmark_prop {fn#1}\l_@@_tmpa_tl
    \tl_gset:Ne\Hy@footnote@currentHref
      {\exp_last_unbraced:NV\use_i:nn \l_@@_tmpa_tl }
    \setcounter{footnote}{\exp_last_unbraced:NV\use_ii:nn \l_@@_tmpa_tl}
  }  

\cs_generate_variant:Nn \hook_gput_next_code:nn {ne}
\cs_new_protected:Npn \@@_fn_footnote:nn #1 #2
  {
    \footnotemark
    \@@_fn_store: 
    \hook_gput_next_code:ne {env/#1/after}
      {\exp_not:N\@@_fn_restore:n{\int_use:N\c@footnote}{\exp_not:n{\footnotetext{#2}}}}}

\AddToHook{env/function/begin}{\def\footnote{\@@_fn_footnote:nn{function}}}
\AddToHook{env/variable/begin}{\def\footnote{\@@_fn_footnote:nn{variable}}} 
%    \end{macrocode}
%
% \subsection{Documenting templates}
%
%    \begin{macrocode}
\newenvironment{TemplateInterfaceDescription}[1]
  {
    \subsection{The~object~type~`#1'}
    \begingroup
    \@beginparpenalty\@M
    \description
    \def\TemplateArgument##1##2{\item[Arg:~##1]##2\par}
    \def\TemplateSemantics
      {
        \enddescription\endgroup
        \subsubsection*{Semantics:}
      }
  }
  {
    \par\bigskip
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\newenvironment{TemplateDescription}[2]
  {
    \subsection{The~template~`#2'~(object~type~#1)}
    \subsubsection*{Attributes:}
    \begingroup
    \@beginparpenalty\@M
    \description
    \def\TemplateKey##1##2##3##4
      {
        \item[##1~(##2)]##3%
        \ifx\TemplateKey##4\TemplateKey\else
%         \hskip0ptplus3em\penalty-500\hskip 0pt plus 1filll Default:~##4%
          \hfill\penalty500\hbox{}\hfill Default:~##4%
          \nobreak\hskip-\parfillskip\hskip0pt\relax
        \fi
        \par
      }
    \def\TemplateSemantics
      {
        \enddescription\endgroup
        \subsubsection*{Semantics~\&~Comments:}
      }
  }
  { \par \bigskip }
%    \end{macrocode}
%
%    \begin{macrocode}
\newenvironment{InstanceDescription}[4][xxxxxxxxxxxxxxx]
  {
    \subsubsection{The~instance~`#3'~(template~#2/#4)}
    \subsubsection*{Attribute~values:}
    \begingroup
    \@beginparpenalty\@M
    \def\InstanceKey##1##2{\>\textbf{##1}\>##2\\}
    \def\InstanceSemantics{\endtabbing\endgroup
      \vskip-30pt\vskip0pt
      \subsubsection*{Layout~description~\&~Comments:}}
    \tabbing
    xxxx\=#1\=\kill
  }
  { \par \bigskip }
%    \end{macrocode}
%
% \subsection{Inheriting doc}
%
% Code here is taken from \pkg{doc}, stripped of comments and translated
% into \pkg{expl3} syntax. New features are added in various places.
%
% \begin{macro}
%   {\StopEventually, \MaybeStop, \Finale, \AlsoImplementation, \OnlyDescription}
% \begin{variable}{\g_@@_finale_tl}
%   TODO: remove these four commands altogether, document that it is
%   better to use the \env{documentation} and \env{implementation}
%   environments.
%    \begin{macrocode}
\DeclareDocumentCommand \OnlyDescription { }
  { \bool_gset_false:N \g_@@_typeset_implementation_bool }
\DeclareDocumentCommand \AlsoImplementation { }
  { \bool_gset_true:N \g_@@_typeset_implementation_bool }
\DeclareDocumentCommand \StopEventually { m }
  {
    \bool_if:NTF \g_@@_typeset_implementation_bool
      {
        \@bsphack
        \tl_gset:Nn \g_@@_finale_tl { #1 \check@checksum }
        \init@checksum
        \@esphack
      }
      { #1 \endinput }
  }
%    \end{macrocode}
%    We also need to support doc V3 \cs{MaybeStop} if it is around
%    (which may not be the case).
%    \begin{macrocode}
\cs_if_exist:NT \MaybeStop  
  { \RenewCommandCopy \MaybeStop \StopEventually }
%    \end{macrocode}
%
%    \begin{macrocode}
\DeclareDocumentCommand \Finale { }
  { \tl_use:N \g_@@_finale_tl }
\tl_new:N \g_@@_finale_tl
%    \end{macrocode}
% \end{variable}
% \end{macro}
%
% \begin{macro}{\@@_input:n}
%   Inputting a file, with some setup: the module name should be empty
%   before the first |<@@=|\meta{module}|>| line in the file.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_input:n #1
  {
    \tl_gclear:N \g_@@_module_name_tl
    \MakePercentIgnore
    \input{#1}
    \MakePercentComment
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DocInput}
%   Modified from \pkg{doc} to accept comma-list input (who has commas
%   in filenames?).
%    \begin{macrocode}
\DeclareDocumentCommand \DocInput { m }
  {
    \clist_map_inline:nn {#1}
      {
        \clist_put_right:Nn \g_docinput_clist {##1}
        \@@_input:n {##1}
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DocInputAgain}
%   Uses \cs{g_docinput_clist} to re-input whatever's already been
%   \tn{DocInput}-ed until now.  May be used multiple times.
%    \begin{macrocode}
\DeclareDocumentCommand \DocInputAgain { }
  { \clist_map_function:NN \g_docinput_clist \@@_input:n }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DocInclude}
%   More or less exactly the same as \tn{include}, but uses
%   \tn{DocInput} on a \file{.fdd} or \file{.dtx} file (without file
%   extension), not \tn{input} on a \file{.tex} file.
%
%    \begin{macrocode}
\msg_new:nnn { l3doc } { missing-endgroup }
  {
    \str_if_eq:VnTF \@currenvir { document }
      {
        There~are~\int_use:N \tex_currentgrouplevel:D
        \c_space_tl unclosed~groups~in~#1.
      }
      {
        The~\@currenvir \c_space_tl environment~on~line~\@currenvline
        \c_space_tl doesn't~have~a~matching~\iow_char:N\\end{\@currenvir}.
      }
  }
\NewDocumentCommand \DocInclude { m }
  {
    \relax\clearpage
    \docincludeaux
    \IfFileExists{#1.fdd}
      { \cs_set:Npn \currentfile{#1.fdd} }
      { \cs_set:Npn \currentfile{#1.dtx} }
    \int_compare:nNnTF \@auxout = \@partaux
      { \@latexerr{\string\include\space cannot~be~nested}\@eha }
      { \@docinclude {#1} }
    % check missing \endgroup, e.g., missing "\end{macro}" in time
    \int_compare:nNnF { \tex_currentgrouplevel:D } = { 0 }
      {
        \int_compare:nNnT { \tex_interactionmode:D } = { 0 }
          { \int_gset:Nn \tex_interactionmode:D { 1 } }
        \msg_fatal:nne { l3doc } { missing-endgroup } { \currentfile }
      }
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_gset:Npn \@docinclude #1
  {
    \clearpage
    \immediate\write\@mainaux{\string\@input{#1.aux}}
    \@tempswatrue
    \if@partsw
      \@tempswafalse
      \cs_set:Npe \@tempb {#1}
      \clist_map_inline:Nn \@partlist
        {
          \if_meaning:w \@tempa \@tempb
            \@tempswatrue
          \fi:
        }
    \fi
    \if@tempswa
      \cs_set_eq:NN \@auxout                 \@partaux
      \immediate\openout\@partaux #1.aux
      \immediate\write\@partaux{\relax}
      \cs_set_eq:NN \@ltxdoc@PrintIndex      \PrintIndex
      \cs_set_eq:NN \PrintIndex              \relax
      \cs_set_eq:NN \@ltxdoc@PrintChanges    \PrintChanges
      \cs_set_eq:NN \PrintChanges            \relax
      \cs_set_eq:NN \@ltxdoc@theglossary     \theglossary
      \cs_set_eq:NN \@ltxdoc@endtheglossary  \endtheglossary
      \part{\currentfile}
      {
        \cs_set_eq:NN \ttfamily\relax
        \cs_gset:Npe \filekey
          { \filekey,~ \thepart = { \ttfamily \currentfile } }
      }
      \DocInput{\currentfile}
      \cs_set_eq:NN \PrintIndex              \@ltxdoc@PrintIndex
      \cs_set_eq:NN \PrintChanges            \@ltxdoc@PrintChanges
      \cs_set_eq:NN \theglossary             \@ltxdoc@theglossary
      \cs_set_eq:NN \endtheglossary          \@ltxdoc@endtheglossary
      \clearpage
      \@writeckpt{#1}
      \immediate \closeout \@partaux
    \else
      \@nameuse{cp@#1}
    \fi
    \cs_set_eq:NN \@auxout \@mainaux
  }
%    \end{macrocode}
%
% Here, |MMMMI| (for page references) and |MMMMV| (for codeline
% references) are interpreted by |makeindex| as an uppercase Roman
% number pages, and should be large enough to avoid collisions with
% other uses of uppercase Roman number pages.  Two subtle differences
% between \cs{@wrindex} and \cs{codeline@wrindex} are that the first
% must be a delayed write because the page number is not known yet, and
% it must close a group and finish some space-hack.
%
% We also provide versions for our use that refer
%    \begin{macrocode}
\cs_gset_protected:Npn \@wrindex #1
  {
    \protected@write \@indexfile {}
      { \string \indexentry {#1} { MMMMI - \thepage } }
    \endgroup \@esphack
  }
\cs_gset_protected:Npn \codeline@wrindex #1
  {
    \immediate\write\@indexfile
      {
        \string\indexentry{#1}
          { MMMMV - \filesep \int_use:N \c@CodelineNo }
      }
  }
\tl_gclear:N \filesep
\cs_new_protected:Npn \@@_index_page_hc:nn #1#2
  {
    \protected@write \@indexfile {}
      {
        \string \indexentry { #1 \encapchar hdpindex{#2} }
          { MMMMI - \thepage }
      }
  }
\cs_new_protected:Npn \@@_index_codeline_hc:nn #1#2
  {
    \immediate\write\@indexfile
      {
        \string \indexentry { #1 \encapchar hdclindex{\the\c@HD@hypercount}{#2} }
          { MMMMV - \filesep \int_use:N \c@CodelineNo - MMMD - \the\c@HD@hypercount - M }
      }
  }
%    \end{macrocode}
% We already have a single |HD.xx| target per code line.  It would be
% better to have a target |CL.\the\c@CodelineNo| per code line and
% change |hdclindex{\the\c@HD@hypercount}| to a mechanism closer to
% |hdpindex|, but we need to understand better the different types of
% indexings, and there are subtleties with indexing |\{| and |\}|.
% \end{macro}
%
% \begin{macro}{\docincludeaux}
%    \begin{macrocode}
\cs_gset:Npn \docincludeaux
  {
    \tl_set:Nn \thepart { \alphalph { part } }
    \tl_set:Nn \filesep { \thepart - }
    \cs_set_eq:NN \filekey \use_none:n
    \tl_gput_right:Nn \index@prologue
      {
        \cs_gset:Npn \@oddfoot
          {
            \parbox { \textwidth }
              {
                \strut \footnotesize
                \raggedright { \bfseries File~Key: } ~ \filekey
              }
          }
        \cs_set_eq:NN \@evenfoot \@oddfoot
      }
    \cs_gset_eq:NN \docincludeaux \relax
    \cs_gset:Npn \@oddfoot
      {
        \cs_if_exist:cTF { ver @ \currentfile }
          { File~\thepart :~{\ttfamily\currentfile}~ }
          {
            \GetFileInfo{\currentfile}
            File~\thepart :~{\ttfamily\filename}~
            Date:~\ExplFileDate\ % space
            Version~\ExplFileVersion
          }
        \hfill \thepage
      }
    \cs_set_eq:NN \@evenfoot \@oddfoot
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{The \env{macrocode} environment}
%
% \begin{macro}{\xmacro@code, \@@_xmacro_code:n, \@@_xmacro_code:w}
%   Hook into the \texttt{macrocode} environment in a dirty way:
%   \tn{xmacro@code} is responsible for grabbing (and tokenizing) the
%   body of the environment.  Redefine it to pass what it grabs to
%   \cs{@@_xmacro_code:n}.  This new macro replaces all |@@| by the
%   appropriate module name.  One exceptional case is the
%   |<@@=|\meta{module}|>| lines themselves, where |@@| should not be
%   modified.  Actually, we search for such lines, to set the module
%   name automatically.  We need to be careful: no |<@@=| should appear
%   as such in the code below since \pkg{l3doc} is also typeset using
%   this code.
%   At each |<@@=| found, replace the \meta{module} in the code behind
%   it, update the \meta{module}, and loop to check for further
%   occurrences of |<@@=|.
%    \begin{macrocode}
\group_begin:
  \char_set_catcode_other:N \^^A
  \char_set_catcode_active:N \^^S
  \char_set_catcode_active:N \^^B
  \char_set_catcode_other:N \^^L
  \char_set_catcode_other:N \^^R
  \char_set_lccode:nn { `\^^A } { `\% }
  \char_set_lccode:nn { `\^^S } { `\  }
  \char_set_lccode:nn { `\^^B } { `\\ }
  \char_set_lccode:nn { `\^^L } { `\{ }
  \char_set_lccode:nn { `\^^R } { `\} }
  \tex_lowercase:D
    {
      \group_end:
      \cs_set_protected:Npn \xmacro@code
          #1 ^^A ^^S^^S^^S^^S ^^Bend ^^Lmacrocode^^R
        { \@@_xmacro_code:n {#1} \end{macrocode} }
    }
\group_begin:
  \char_set_catcode_active:N \<
  \char_set_catcode_active:N \>
  \cs_new_protected:Npn \@@_xmacro_code:n #1
    {
      \tl_clear:N \l_@@_tmpa_tl
      \tl_if_in:nnTF {#1} { < @ @ = }
        { \@@_xmacro_code:w #1 < @ @ = \q_recursion_tail > \q_recursion_stop }
        {
          \tl_set:Nn \l_@@_tmpa_tl {#1}
          \@@_detect_internals:N \l_@@_tmpa_tl
          \@@_replace_at_at:N \l_@@_tmpa_tl
          \tl_use:N \l_@@_tmpa_tl
        }
    }
  \cs_new_protected:Npn \@@_xmacro_code:w #1 < @ @ = #2 >
    {
      % Add code before <@@@@=...>
      \tl_set:Nn \l_@@_tmpb_tl {#1}
      \@@_detect_internals:N \l_@@_tmpb_tl
      \@@_replace_at_at:N \l_@@_tmpb_tl
      \tl_put_right:NV \l_@@_tmpa_tl \l_@@_tmpb_tl
      % Check for \q_recursion_tail
      \quark_if_recursion_tail_stop_do:nn {#2}
        { \tl_use:N \l_@@_tmpa_tl }
      % Change module name and add <@@@@=#2> to typeset output
      \tl_gset:Nn \g_@@_module_name_tl {#2}
      \tl_put_right:Nn \l_@@_tmpa_tl { < \text { \verbatim@font @ @ = #2 } > }
      % Loop
      \@@_xmacro_code:w
    }
\group_end:
%    \end{macrocode}
% \end{macro}
%
% \subsection{At end document}
%
% Print all defined and documented macros/functions.
%
%    \begin{macrocode}
\iow_new:N \g_@@_func_iow
%    \end{macrocode}
%
%    \begin{macrocode}
\tl_new:N \l_@@_doc_def_tl
\tl_new:N \l_@@_doc_undef_tl
\tl_new:N \l_@@_undoc_def_tl
\tl_const:Nn \c_@@_iow_separator_tl { ---- }
\tl_const:Nn \c_@@_iow_midrule_tl  { -- }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_show_functions_defined:
  {
    \bool_lazy_and:nnT
      { \g_@@_typeset_implementation_bool } { \g_@@_checkfunc_bool }
      {
        \iow_term:e { \c_@@_iow_separator_tl \iow_newline: }
        \iow_open:Nn \g_@@_func_iow { \c_sys_jobname_str .cmds }

        \tl_clear:N \l_@@_doc_def_tl
        \tl_clear:N \l_@@_doc_undef_tl
        \tl_clear:N \l_@@_undoc_def_tl
        \seq_gremove_duplicates:N \g_doc_functions_seq
        \seq_gremove_duplicates:N \g_doc_macros_seq
        \seq_map_inline:Nn \g_doc_functions_seq
          {
            \seq_if_in:NnTF \g_doc_macros_seq {##1}
              {
                \tl_put_right:Ne \l_@@_doc_def_tl
                  { \iow_newline: > ~ ##1 }
              }
              {
                \tl_put_right:Ne \l_@@_doc_undef_tl
                  { \iow_newline: ! ~ ##1 }
              }
          }
        \seq_map_inline:Nn \g_doc_macros_seq
          {
            \seq_if_in:NnF \g_doc_functions_seq {##1}
              {
                \tl_put_right:Ne \l_@@_undoc_def_tl
                  { \iow_newline: ? ~ ##1 }
              }
          }
        \@@_functions_typeout:nN
          {
            Functions~both~documented~and~defined: \iow_newline:
            (In~order~of~being~documented)
          }
          \l_@@_doc_def_tl
        \@@_functions_typeout:nN
          { Functions~documented~but~not~defined: }
          \l_@@_doc_undef_tl
        \@@_functions_typeout:nN
          { Functions~defined~but~not~documented: }
          \l_@@_undoc_def_tl

        \iow_close:N \g_@@_func_iow
        \iow_term:e { \c_@@_iow_separator_tl }
      }
  }
\AtEndDocument { \@@_show_functions_defined: }
%    \end{macrocode}
%
% TODO: use \cs{iow_term:e}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_functions_typeout:nN #1#2
  {
    \tl_if_empty:NF #2
      {
        \iow_now:Ne \g_@@_func_iow
          {
            \c_@@_iow_midrule_tl \iow_newline:
            #1 \iow_newline:
            \c_@@_iow_midrule_tl
            #2
          }
        \tl_clear:N #2
      }
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_show_not_tested:
  {
    \bool_if:NT \g_@@_checktest_bool
      {
        \tl_clear:N \l_@@_tmpa_tl
        \prop_if_empty:NF \g_@@_missing_tests_prop
          {
            \cs_set:Npn \@@_tmpa:w ##1##2
              {
                \iow_newline:
                \space\space\space\space \exp_not:n {##1}
                \clist_map_function:nN {##2} \@@_tmpb:w
              }
            \cs_set:Npn \@@_tmpb:w ##1
              {
                \iow_newline:
                \space\space\space\space\space\space * ~ ##1
              }
            \tl_put_right:Ne \l_@@_tmpa_tl
              {
                \iow_newline: \iow_newline:
                The~ following~ macro(s)~ have~ incomplete~ tests:
                \iow_newline:
                \prop_map_function:NN
                  \g_@@_missing_tests_prop \@@_tmpa:w
              }
          }
        \seq_if_empty:NF \g_@@_not_tested_seq
          {
            \cs_set:Npn \@@_tmpa:w ##1
              { \clist_map_function:nN {##1} \@@_tmpb:w }
            \cs_set:Npn \@@_tmpb:w ##1
              {
                \iow_newline:
                \space\space\space\space ##1
              }
            \tl_put_right:Ne \l_@@_tmpa_tl
              {
                \iow_newline:
                \iow_newline:
                The~ following~ macro(s)~ do~ not~ have~ any~ tests:
                \iow_newline:
                \seq_map_function:NN
                  \g_@@_not_tested_seq \@@_tmpa:w
              }
          }
        \tl_if_empty:NF \l_@@_tmpa_tl
          {
            \int_set:Nn \l_@@_tmpa_int { \tex_interactionmode:D }
            \errorstopmode
            \ClassError { l3doc } { \l_@@_tmpa_tl } { }
            \int_gset:Nn \tex_interactionmode:D { \l_@@_tmpa_int }
          }
      }
  }
\AtEndDocument { \@@_show_not_tested: }
%    \end{macrocode}
%
% \subsection{Indexing}
%
% \subsubsection{Necessary patching}
%
% The following is useful to set up \pkg{hyperref} targets, for instance
% for the purpose of indexing.  Contrarily to \pkg{hypdoc} we do not try
% to save pdf destinations, as this leads to too many \pdfTeX{} warnings
% on early runs.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_target:
  {
    \mode_leave_vertical:
    \group_begin:
      \HD@savedestfalse \HD@target
    \group_end:
  }
%    \end{macrocode}
% Force targets on every code line.
%    \begin{macrocode}
\cs_set_nopar:Npe \theCodelineNo
  {
    \group_begin:
      \exp_not:N \HD@savedestfalse
      \exp_not:o \theCodelineNo
    \group_end:
  }
%    \end{macrocode}
%
% Inside the table of contents (and other similar lists introduced by
% \cs{@starttoc}), we suppress indexing.  This is because \cs{cmd},
% \cs{cs}, or \cs{tn} appearing in titles only gets typeset in the
% second run, and getting their indexing right would require even more
% runs than we already need.  Besides, it is not useful to index uses of
% some command in the table of contents.
%    \begin{macrocode}
\bool_new:N \l_@@_allow_indexing_bool
\bool_set_true:N \l_@@_allow_indexing_bool
\use:e
  {
    \exp_not:n { \cs_set_nopar:Npn \@starttoc #1 }
      {
        \group_begin:
          \bool_set_false:N \l_@@_allow_indexing_bool
          \exp_not:o { \@starttoc {#1} }
        \group_end:
      }
  }
%    \end{macrocode}
%
% \subsubsection{Userspace commands}
%
% Fix index (for now):
%    \begin{macrocode}
\g@addto@macro \theindex { \MakePrivateLetters }
\cs_gset:Npn \verbatimchar {&}
%    \end{macrocode}
%
%    \begin{macrocode}
\setcounter { IndexColumns } { 2 }
%    \end{macrocode}
%
% Set up the Index to use \tn{part}
%    \begin{macrocode}
\IndexPrologue
  {
    \part*{Index}
    \markboth{Index}{Index}
    \addcontentsline{toc}{part}{Index}
    The~italic~numbers~denote~the~pages~where~the~
    corresponding~entry~is~described,~
    numbers~underlined~point~to~the~definition,~
    all~others~indicate~the~places~where~it~is~used.
  }
%    \end{macrocode}
%
% \begin{macro}{\SpecialIndex}
%   An attempt at affecting how commands which appear within the
%   \env{macrocode} environment are treated in the index.
%    \begin{macrocode}
\cs_gset_protected:Npn \SpecialIndex #1
  {
    \@bsphack
    \@@_special_index:nn {#1} { }
    \@esphack
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\msg_new:nnn { l3doc } { print-index-howto }
  {
    Generate~the~index~by~executing\\
    \iow_indent:n
      { makeindex~-s~gind.ist~-o~\c_sys_jobname_str.ind~\c_sys_jobname_str.idx }
  }
\tl_gput_right:Nn \PrintIndex
  { \AtEndDocument { \msg_info:nn { l3doc } { print-index-howto } } }
%    \end{macrocode}
%
% \subsubsection{Internal index commands}
%
% \begin{macro}{\it@is@a}
%   The index of one-character commands within the \env{macrocode}
%   environment is produced using \tn{it@is@a} \meta{char}.  Alter that
%   command.
%    \begin{macrocode}
\cs_gset_protected:Npn \it@is@a #1
  {
    \use:e
      {
        \@@_special_index_module:nnnnN
          {#1}
          { \bslash #1 }
          { }
          { }
          \c_false_bool
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_special_index:nn}
% ^^A TODO this override is somewhat a hack
%    \begin{macrocode}
\cs_new_protected:Npn \@@_special_index:nn #1#2
  {
    \@@_key_get:n {#1}
    \quark_if_no_value:NF \l_@@_override_module_tl
      { \tl_set_eq:NN \l_@@_index_module_tl \l_@@_override_module_tl }
    \@@_special_index_module:ooonN
      { \l_@@_index_key_tl }
      { \l_@@_index_macro_tl }
      { \l_@@_index_module_tl }
      {#2}
      \l_@@_index_internal_bool
  }
\cs_generate_variant:Nn \@@_special_index:nn { o }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \@@_special_index_module:nnnnN,
%     \@@_special_index_module:ooonN,
%     \@@_special_index_aux:nnnnnn,
%     \@@_special_index_set:Nn,
%   }
%   Remotely based on Heiko's replacement to play nicely with
%   \pkg{hypdoc}.  We use \tn{verb} or a \tn{verbatim@font} construction
%   depending on whether the number of tokens in |#2| is equal to its
%   number of characters: if it is not then that suggests that there is
%   a construct such as |\meta{...}|.
%    \begin{macrocode}
\tl_new:N \l_@@_index_escaped_macro_tl
\tl_new:N \l_@@_index_escaped_key_tl
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_special_index_module:nnnnN #1#2#3#4#5
%    \end{macrocode}
% \begin{arguments}
% \item key
% \item macro
% \item module
% \item index `type' (\texttt{main}/\texttt{usage}/\emph{etc.})
% \item boolean whether internal command
% \end{arguments}
%    \begin{macrocode}
  {
    \use:e
      {
        \exp_not:n { \@@_special_index_aux:nnnnnn {#1} {#2} }
          \tl_if_empty:nTF {#3}
            { { } { } { } }
            {
              \str_if_eq:nnTF {#3} { TeX }
                {
                  { TeX~and~LaTeX2e }
                  { \string\TeX{}~and~\string\LaTeXe{} }
                }
                {
                  {#3}
                  { \string\pkg{#3} }
                }
              { \bool_if:NT #5 { ~internal } ~commands: }
            }
      }
          {#4}
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_generate_variant:Nn \@@_special_index_module:nnnnN { ooo }
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_special_index_aux:nnnnnn #1#2#3#4#5#6
%    \end{macrocode}
% \begin{arguments}
% \item key
% \item macro
% \item index subheading string
% \item index subheading text
% \item index subheading suffix (appended to both arg 3 and 4)
% \item index `type' (\texttt{main}/\texttt{usage}/\emph{etc.})
% \end{arguments}
%    \begin{macrocode}
  {
    \tl_set:Nn \l_@@_index_escaped_key_tl {#1}
    \@@_quote_special_char:N \l_@@_index_escaped_key_tl
    \@@_special_index_set:Nn \l_@@_index_escaped_macro_tl {#2}
    \str_if_eq:onTF { \@currenvir } { macrocode }
      { \@@_index_codeline_hc:nn }
      {
        \str_case:nnF {#6}
          {
            { main }  { \@@_index_codeline_hc:nn }
            { usage } { \@@_index_page_hc:nn }
          }
          { \@@_target: \@@_index_page_hc:nn }
      }
      {
        \tl_if_empty:nF { #3 #4 #5 }
          { #3 #5 \actualchar #4 #5 \levelchar }
        \l_@@_index_escaped_key_tl
        \actualchar
        {
          \token_to_str:N \verbatim@font \c_space_tl
          \l_@@_index_escaped_macro_tl
        }
      }
      {#6}
  }
%    \end{macrocode}
%
% \begin{macro}{\hdpindex, \@@_old_hdpindex:nn, \hdclindex, \@@_old_hdclindex:nnn, \@@_hdindex:nn, \c_@@_active_minus_tl, \@@_hdindex_aux:nn, \@@_hdindex_aux:w}
%   Note that |#3| here could contain |MMMMI-| or |MMMMV-| more than once
%   if several successive code lines have been merged into a range
%   somehow.  Note incidentally that the dash is active in some of our
%   sources, like |interface3.tex| or |source2e.tex|.
%    \begin{macrocode}
\group_begin:
\char_set_active_eq:NN - \scan_stop:
\tl_const:Ne \c_@@_active_minus_tl { \char_generate:nn { `- } { 13 } }
\group_end:
\cs_new_eq:NN \@@_old_hdpindex:nn \hdpindex
\cs_new_eq:NN \@@_old_hdclindex:nnn \hdclindex
\cs_gset_protected:Npn \hdpindex #1
  { \@@_hdindex:nn { \@@_old_hdpindex:nn {#1} } }
\cs_gset_protected:Npn \hdclindex #1#2
  { \@@_hdindex:nn { \@@_old_hdclindex:nnn {#1} {#2} } }
\cs_new_protected:Npn \@@_hdindex:nn #1#2
  {
    \tl_set:Nn \l_@@_tmpa_tl {#2}
    \tl_replace_all:Nen \l_@@_tmpa_tl
      { \exp_not:V \c_@@_active_minus_tl \exp_not:V \c_@@_active_minus_tl }
      { -- }
    \seq_set_split:NnV \l_@@_tmpa_seq { -- } \l_@@_tmpa_tl
    \seq_set_map:NNn \l_@@_tmpa_seq \l_@@_tmpa_seq
      { \@@_hdindex_aux:nn {#1} {##1} }
    \seq_use:Nn \l_@@_tmpa_seq { -- }
  }
\cs_new_protected:Npn \@@_hdindex_aux:nn #1#2
  {
    \tl_set:Nn \l_@@_tmpa_tl {#2}
    \tl_replace_all:Nnn \l_@@_tmpa_tl { MMMM } { \use_none:nn }
    \tl_if_in:NnT \l_@@_tmpa_tl { MMMD }
      {
        \tl_replace_all:Nen \l_@@_tmpa_tl
          { \exp_not:V \c_@@_active_minus_tl MMMD } { - MMMD }
        \tl_replace_all:Nnn \l_@@_tmpa_tl { - MMMD } { \@@_hdindex_aux:w }
      }
    \use:e { \exp_not:n {#1} { \exp_not:V \l_@@_tmpa_tl } }
  }
\cs_new_protected:Npn \@@_hdindex_aux:w #1 M { }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_special_index_set:Nn #1#2
  {
    \__kernel_tl_set:Nx #1 { \tl_to_str:n {#2} }
    \@@_if_almost_str:nTF {#2}
      {
        \tl_replace_all:Nen #1 { \tl_to_str:n { __ } }
          {
            \verbatimchar
            \token_to_str:N \_ \token_to_str:N \_
            \token_to_str:N \verb * \verbatimchar
          }
        \exp_args:Ne \tl_map_inline:nn
          { \tl_to_str:N \verbatimchar \token_to_str:N _ }
          {
            \tl_replace_all:Nnn #1 {##1}
              {
                \verbatimchar \c_backslash_str ##1
                \token_to_str:N \verb * \verbatimchar
              }
          }
        \__kernel_tl_set:Nx #1
          {
            \token_to_str:N \verb * \verbatimchar
            #1 \verbatimchar
          }
      }
      {
        \tl_set:Nn #1 {#2}
        \tl_replace_all:NVn #1
          \c_backslash_str
          { \token_to_str:N \bslash \c_space_tl }
      }
    \@@_quote_special_char:N #1
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_quote_special_char:N}
% Quote some special characters.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_quote_special_char:N #1
  {
    \tl_map_inline:nn { \quotechar \actualchar \encapchar \levelchar \bslash }
      {
        \tl_replace_all:Nen #1
          { \tl_to_str:N ##1 } { \quotechar \tl_to_str:N ##1 }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Finding sort-key and module}
%
% \begin{macro}{\@@_key_get:n}
%   Sets \cs{l_@@_index_macro_tl}, \cs{l_@@_index_key_tl}, and
%   \cs{l_@@_index_module_tl} from |#1|.  The base function is stored by
%   \cs{@@_key_get_base:nN} in \cs{l_@@_index_macro_tl}, falling back to
%   |#1| if it contains markup or has no signature.
%
%   The starting point for the \meta{key} is \cs{l_@@_index_key_tl} as a
%   string.  If it the first character is a backslash, remove
%   it.  Then recognize |expl| functions and variables by the presence
%   of |:| or~|_| and \TeX{}/\LaTeXe{} commands by the presence of~|@|.
%   For |expl| names, we call \cs{@@_key_func:} or \cs{@@_key_var:},
%   which are responsible for removing some characters and finding the
%   module name, while for \TeX{}/\LaTeXe{} commands the module name is
%   |TeX|, and others have an empty module name.
%    \begin{macrocode}
\cs_new_protected:Npe \@@_key_get:n #1
  {
    \exp_not:N \@@_key_get_base:nN {#1} \exp_not:N \l_@@_index_macro_tl
    \__kernel_tl_set:Nx \exp_not:N \l_@@_index_key_tl
      { \exp_not:N \tl_to_str:N \exp_not:N \l_@@_index_macro_tl }
    \tl_clear:N \exp_not:N \l_@@_index_module_tl
    \tl_if_in:NnTF \exp_not:N \l_@@_index_key_tl { \tl_to_str:n { __ } }
      { \bool_set_true:N \exp_not:N \l_@@_index_internal_bool }
      { \bool_set_false:N \exp_not:N \l_@@_index_internal_bool }
    \exp_not:N \tl_if_head_eq_charcode:VNT
      \exp_not:N \l_@@_index_key_tl \c_backslash_str
      { \exp_not:N \@@_key_pop: }
    \tl_if_in:NnTF \exp_not:N \l_@@_index_key_tl { \token_to_str:N : }
      { \exp_not:N \@@_key_func: }
      {
        \tl_if_in:NnTF \exp_not:N \l_@@_index_key_tl { \token_to_str:N _ }
          { \exp_not:N \@@_key_var: }
          {
            \tl_if_in:NnT \exp_not:N \l_@@_index_key_tl { \token_to_str:N @ }
              { \tl_set:Nn \exp_not:N \l_@@_index_module_tl { TeX } }
          }
      }
  }
\cs_new_protected:Npn \@@_key_pop:
  {
    \__kernel_tl_set:Nx \l_@@_index_key_tl
      { \tl_tail:N \l_@@_index_key_tl }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_key_trim_module:n, \@@_key_drop_underscores:}
%   Helper that removes from \cs{l_@@_index_module_tl} everything after
%   the first occurence of |#1|.  Helper that removes any leading
%   underscore from \cs{l_@@_index_key_tl}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_key_trim_module:n #1
  {
    \cs_set:Npn \@@_tmpa:w ##1 #1 ##2 \q_stop
      { \exp_not:n {##1} }
    \__kernel_tl_set:Nx \l_@@_index_module_tl
      { \exp_after:wN \@@_tmpa:w \l_@@_index_module_tl #1 \q_stop }
  }
\cs_new_protected:Npn \@@_key_drop_underscores:
  {
    \tl_if_head_eq_charcode:VNT \l_@@_index_key_tl _
      { \@@_key_pop: \@@_key_drop_underscores: }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_key_func:}
%   The function \cs{@@_key_func:} is used if there is a colon, so
%   either for usual \pkg{expl3} functions or for keys from
%   \pkg{l3keys}.  After removing from the key a leading dot (for the
%   latter case), and any leading underscore, the module name is the
%   part before any colon or underscore.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_key_func:
  {
    \tl_if_head_eq_charcode:VNT \l_@@_index_key_tl .
      { \@@_key_pop: }
    \@@_key_drop_underscores:
    \tl_set_eq:NN \l_@@_index_module_tl \l_@@_index_key_tl
    \exp_args:No \@@_key_trim_module:n { \token_to_str:N : }
    \exp_args:No \@@_key_trim_module:n { \token_to_str:N _ }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_key_var:, \@@_key_get_module:}
%   The function \cs{@@_key_var:} covers cases with no~|:| but with~|_|,
%   typically variables but occasionally non-\pkg{expl3} functions such
%   as \Lua{} function with underscores.  First test the second
%   character: if that is~|_| then assume we have a proper variable,
%   otherwise use the part before any underscore as the module name.
%   For variables, distinguish quarks and scan marks (starting with |q|
%   and~|s|), then drop the first letter (local/global/constant marker)
%   and underscores to improve the index sorting.
%   Then get the module as the first (underscore-delimited) \enquote{word}.
%   In the past, we distinguished according to how many such words there
%   were, to detect commands like \cs[no-index]{c_zero}, which should be
%   sorted as |int| variables, and \cs[no-index]{l_tmpa_dim}, which should
%   be sorted in the |dim| and not the |tmpa| module.
%   Now the first case has been deprecated for some time, while |tmpa| and
%   similar are special-cased through an explicit list given below.
%   The way it works is that if the module is in a list of special names
%   that are not valid modules, then we try the last word, and if that
%   also fails (for instance in the deprecated \cs[no-index]{c_one_hundred})
%   we empty the module completely.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_key_var:
  {
    \exp_args:Ne \tl_if_head_eq_charcode:nNTF
      { \exp_args:No \str_tail:n \l_@@_index_key_tl } _
      {
        \str_case:en { \str_head:N \l_@@_index_key_tl }
          {
            { q } { \tl_set:Nn \l_@@_index_module_tl { quark } }
            { s } { \tl_set:Nn \l_@@_index_module_tl { scan } }
          }
        \@@_key_pop:
        \@@_key_pop:
        \@@_key_drop_underscores:
        \tl_if_empty:NT \l_@@_index_module_tl
          {
            \seq_set_split:NoV \l_@@_tmpa_seq
              { \token_to_str:N _ } \l_@@_index_key_tl
            \seq_get_left:NN \l_@@_tmpa_seq \l_@@_index_module_tl
            \clist_if_in:NoT \g_@@_non_modules_clist \l_@@_index_module_tl
              {
                \seq_get_right:NN \l_@@_tmpa_seq \l_@@_index_module_tl
                \clist_if_in:NoT \g_@@_non_modules_clist \l_@@_index_module_tl
                  {
                    \tl_clear:N \l_@@_index_module_tl
                  }
              }
          }
      }
      {
        \tl_set_eq:NN \l_@@_index_module_tl \l_@@_index_key_tl
        \exp_args:No \@@_key_trim_module:n { \token_to_str:N _ }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{variable}{\g_@@_non_modules_clist}
%   List of names that appear as the first word in an \pkg{expl3}
%   command, but that are not true modules, so that they should be
%   sorted differently in an index.
%    \begin{macrocode}
\clist_new:N \g_@@_non_modules_clist
\clist_gset:Ne \g_@@_non_modules_clist
  {
    \tl_to_str:n
      {

        alignment, ampersand, atsign, backslash, catcode, circumflex,
        code, colon, document, dollar, e, empty, false, hash, inf,
        initex, job, left, log, math, mark, max, minus, nan, nil, no,
        novalue, other, parameter, percent, pi, recursion, right, space,
        stop, term, tilde, tmpa, tmpb, true, underscore, zero, one, two,
        three, four, five, six, seven, eight, nine, ten, eleven, twelve,
        thirteen, fourteen, fifteen, sixteen, thirty, hundred

      }
  }
%    \end{macrocode}
% \end{variable}
%
% \subsection{Change history}
%
% Set the change history to use \tn{part}.
% Allow control names to be hyphenated in here\dots
%    \begin{macrocode}
\GlossaryPrologue
  {
    \part*{Change~History}
    {\GlossaryParms\ttfamily\hyphenchar\font=`\-}
    \markboth{Change~History}{Change~History}
    \addcontentsline{toc}{part}{Change~History}
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\msg_new:nnn { l3doc } { print-changes-howto }
  {
    Generate~the~change~list~by~executing\\
    \iow_indent:n
      { makeindex~-s~gglo.ist~-o~\c_sys_jobname_str.gls~\c_sys_jobname_str.glo }
  }
\tl_gput_right:Nn \PrintChanges
  { \AtEndDocument { \msg_info:nn { l3doc } { print-changes-howto } } }
%    \end{macrocode}
%
%^^A The standard \changes command modified slightly to better cope with
%^^A this multiple file document.
%^^A\def\changes@#1#2#3{%
%^^A  \let\protect\@unexpandable@protect
%^^A  \edef\@tempa{\noexpand\glossary{#2\space\currentfile\space#1\levelchar
%^^A                                 \ifx\saved@macroname\@empty
%^^A                                   \space
%^^A                                   \actualchar
%^^A                                   \generalname
%^^A                                 \else
%^^A                                   \expandafter\@gobble
%^^A                                   \saved@macroname
%^^A                                   \actualchar
%^^A                                   \string\verb\quotechar*%
%^^A                                   \verbatimchar\saved@macroname
%^^A                                   \verbatimchar
%^^A                                 \fi
%^^A                                 :\levelchar #3}}%
%^^A  \@tempa\endgroup\@esphack}
%
% \subsection{Default configuration}
%
%    \begin{macrocode}
\bool_if:NTF \g_@@_typeset_implementation_bool
  {
    \RecordChanges
    \CodelineIndex
    \EnableCrossrefs
    \AlsoImplementation
  }
  {
    \CodelineNumbered
    \DisableCrossrefs
    \OnlyDescription
  }
%    \end{macrocode}
%
%
%    \begin{macrocode}
%</class>
%    \end{macrocode}
%
% \subsection{Internal macros for \LaTeX3 sources}
%
% These definitions are only used by the \LaTeX3 documentation; they are
% not necessary for third-party users of \cls{l3doc}.  In time this will
% be broken into a separate package that is specifically loaded in the
% various \pkg{expl3} modules, \emph{etc.}
%
%    \begin{macrocode}
%<*cfg>
%    \end{macrocode}
%
% The Guilty Parties.
%    \begin{macrocode}
\tl_const:Nn \Team
  {
    The~\LaTeX3~Project\thanks
      {\url{https://www.latex-project.org/latex3/}}
  }
%    \end{macrocode}
%
%    \begin{macrocode}
\NewDocumentCommand{\ExplMakeTitle}{mm}
  {
    \title
      {
        The~\pkg{#1}~package \\ #2
      }
    \author
      {
        The~\LaTeX3~Project\thanks{E-mail:~
        \href{mailto:latex-l@listserv.uni-heidelberg.de}
             {latex-l@listserv.uni-heidelberg.de}}
      }
    \date{Released~\ExplFileDate}
    \maketitle
  }
%    \end{macrocode}
%
% \subsection{Math extras}
%
% For \pkg{l3fp}.
%
%    \begin{macrocode}
\AtBeginDocument
  {
    \clist_map_inline:nn
      {
        asin, acos, atan, acot,
        asinh, acosh, atanh, acoth, round, floor, ceil
      }
      { \exp_args:Nc \DeclareMathOperator{#1}{#1} }
  }
%    \end{macrocode}
%
% \begin{macro}{\nan}
%    \begin{macrocode}
\NewDocumentCommand { \nan } { } { \text { \texttt { nan } } }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</cfg>
%    \end{macrocode}
%
%
% \subsection{Makeindex configuration}
%
%    \begin{macrocode}
%<*docist>
%    \end{macrocode}
%
% The makeindex style \file{l3doc.ist} is used in place of the usual
% \file{gind.ist} to ensure that |I| is used in the sequence |I J K| not
% |I II II|, which would be the default makeindex behaviour.
%
% Will: Do we need this?
%
% Frank: at the moment we do not distribute or generate this file.
%        \file{gind.ist} is used instead.
%
% \begin{macro}[do-not-index={\\,\n}]{}
%    \begin{macrocode}
actual '='
quote '!'
level '>'
preamble
"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
postamble
"\n\n \\end{theindex}\n"
item_x1   "\\efill \n \\subitem "
item_x2   "\\efill \n \\subsubitem "
delim_0   "\\pfill "
delim_1   "\\pfill "
delim_2   "\\pfill "
% The next lines will produce some warnings when
% running Makeindex as they try to cover two different
% versions of the program:
lethead_prefix   "{\\bfseries\\hfil "
lethead_suffix   "\\hfil}\\nopagebreak\n"
lethead_flag       1
heading_prefix   "{\\bfseries\\hfil "
heading_suffix   "\\hfil}\\nopagebreak\n"
headings_flag       1

% and just for source3:
% Remove R so I is treated in sequence I J K not I II III
page_precedence "rnaA"
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</docist>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex