summaryrefslogtreecommitdiff
path: root/macros/latex-dev/required/l3kernel/l3doc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/required/l3kernel/l3doc.dtx')
-rw-r--r--macros/latex-dev/required/l3kernel/l3doc.dtx4802
1 files changed, 4802 insertions, 0 deletions
diff --git a/macros/latex-dev/required/l3kernel/l3doc.dtx b/macros/latex-dev/required/l3kernel/l3doc.dtx
new file mode 100644
index 0000000000..9156bd385e
--- /dev/null
+++ b/macros/latex-dev/required/l3kernel/l3doc.dtx
@@ -0,0 +1,4802 @@
+% \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-04-11}{}
+ {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-04-11}
+% \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
+ { \token_to_str:N \obeyedline \c_space_tl \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