summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3doc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3doc.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3doc.dtx4800
1 files changed, 0 insertions, 4800 deletions
diff --git a/macros/latex/contrib/l3kernel/l3doc.dtx b/macros/latex/contrib/l3kernel/l3doc.dtx
deleted file mode 100644
index a48a24df23..0000000000
--- a/macros/latex/contrib/l3kernel/l3doc.dtx
+++ /dev/null
@@ -1,4800 +0,0 @@
-% \iffalse meta-comment
-%
-%% File: l3doc.dtx
-%
-% Copyright (C) 1990-2024 The LaTeX Project
-%
-% It may be distributed and/or modified under the conditions of the
-% LaTeX Project Public License (LPPL), either version 1.3c of this
-% license or (at your option) any later version. The latest version
-% of this license is in the file
-%
-% https://www.latex-project.org/lppl.txt
-%
-% This file is part of the "l3kernel bundle" (The Work in LPPL)
-% and all files in that bundle must be distributed together.
-%
-% -----------------------------------------------------------------------
-%
-% The development version of the bundle can be found at
-%
-% https://github.com/latex3/latex3
-%
-% for those people who are interested.
-%
-%<*driver>
-\def\nameofplainTeX{plain}
-\ifx\fmtname\nameofplainTeX\else
- \expandafter\begingroup
-\fi
-\input docstrip %
-\askforoverwritefalse
-\preamble
-
-Copyright (C) 1990-2024 The LaTeX Project
-
-It may be distributed and/or modified under the conditions of
-the LaTeX Project Public License (LPPL), either version 1.3c of
-this license or (at your option) any later version. The latest
-version of this license is in the file:
-
- https://www.latex-project.org/lppl.txt
-
-This file is part of the "l3kernel bundle" (The Work in LPPL)
-and all files in that bundle must be distributed together.
-
-\endpreamble
-% stop docstrip adding \endinput
-\postamble
-\endpostamble
-\generate{\file{l3doc.cls}{\from{l3doc.dtx}{class,cfg}}}
-%\generate{\file{l3doc.ist}{\from{l3doc.dtx}{docist}}}
-\ifx\fmtname\nameofplainTeX
- \expandafter\endbatchfile
-\else
- \expandafter\endgroup
-\fi
-%</driver>
-%
-%<*driver|class>
-\RequirePackage{calc}
-%</driver|class>
-%
-%<*driver>
-\documentclass{l3doc}
-\usepackage{framed}
-\begin{document}
- \DocInput{l3doc.dtx}
-\end{document}
-%</driver>
-%
-% This isn't included in the typeset documentation because it's a bit
-% ugly:
-%<*class>
-\ProvidesExplClass{l3doc}{2024-03-14}{}
- {L3 Experimental documentation class}
-%</class>
-% \fi
-%
-% \title{The \cls{l3doc} class -- experimental\thanks{%
-% On popular request we now distribute the document for this
-% experimental class. However, please note that it is by no means
-% in final state and is \emph{likely} to undergo modifications,
-% even \emph{incompatible ones}! Thus, using it might therefore
-% require you to do updates, if the class changes.}}
-%
-% \author{\Team}
-% \date{Released 2024-03-14}
-% \maketitle
-% \tableofcontents
-%
-% \begin{documentation}
-%
-%
-% \section{Introduction}
-%
-% Code and documentation for this class have been written prior to the
-% change of \pkg{doc} from version 2 to version 3, which already shows
-% how far behind this class currently is. So take the following
-% warning seriously please:
-%
-% \begin{quote}
-% \textbf{It is much less stable than the main \pkg{expl3} packages.\\
-% Use at own risk!}
-% \end{quote}
-%
-% This is an ad-hoc class for documenting the \pkg{expl3} bundle, a
-% collection of modules or packages that make up \LaTeX3's programming
-% environment. Eventually it will replace the \cls{ltxdoc} class for
-% \LaTeX3, but not before the good ideas in \pkg{hypdoc}, \cls{xdoc2},
-% \pkg{docmfp}, and \cls{gmdoc} are incorporated.
-%
-% It is written as a \enquote{self-contained} docstrip file: executing
-% |latex l3doc.dtx| generates the \file{l3doc.cls} file and typesets
-% this documentation; execute |tex l3doc.dtx| to only generate
-% \file{l3doc.cls}.
-%
-% \section{Features of other packages}
-%
-% This class builds on the \pkg{ltxdoc} class and the \pkg{doc} package,
-% but in the time since they were originally written some improvements
-% and replacements have appeared that we would like to use as
-% inspiration.
-%
-% These packages or classes are \pkg{hypdoc}, \pkg{docmfp}, \pkg{gmdoc},
-% and \pkg{xdoc}. I have summarised them below in order to work out
-% what sort of features we should aim at a minimum for \pkg{l3doc}.
-%
-% \subsection{The \pkg{hypdoc} package}
-%
-% This package provides hyperlink support for the \pkg{doc} package. I
-% have included it in this list to remind me that cross-referencing
-% between documentation and implementation of methods is not very
-% good. (\emph{E.g.}, it would be nice to be able to automatically
-% hyperlink the documentation for a function from its implementation and
-% vice-versa.)
-%
-% \subsection{The \pkg{docmfp} package}
-%
-% \begin{itemize}
-% \item Provides \cs{DescribeRoutine} and the \env{routine}
-% environment (\emph{etc.}) for MetaFont and MetaPost code.
-% \item Provides \cs{DescribeVariable} and the \env{variable}
-% environment (\emph{etc.}) for more general code.
-% \item Provides \cs{Describe} and the \env{Code} environment
-% (\emph{etc.}) as a generalisation of the above two
-% instantiations.
-% \item Small tweaks to the DocStrip system to aid non-\LaTeX{} use.
-% \end{itemize}
-%
-% \subsection{The \pkg{xdoc2} package}
-%
-% \begin{itemize}
-% \item Two-sided printing.
-% \item \cs{NewMacroEnvironment}, \cs{NewDescribeEnvironment}; similar
-% idea to \pkg{docmfp} but more comprehensive.
-% \item Tons of small improvements.
-% \end{itemize}
-%
-% \subsection{The \pkg{gmdoc} package}
-%
-% Radical re-implementation of \pkg{doc} as a package or class.
-% \begin{itemize}
-% \item Requires no |\begin{macrocode}| blocks!
-% \item Automatically inserts |\begin{macro}| blocks!
-% \item And a whole bunch of other little things.
-% \end{itemize}
-%
-% \section{Problems \& Todo}
-%
-% Problems at the moment:
-% (1)~not flexible in the types of things that can be documented;
-% (2)~no obvious link between the |\begin{function}| environment for
-% documenting things to the |\begin{macro}| function that's used
-% analogously in the implementation.
-%
-% The \env{macro} should probably be renamed to \env{function} when it
-% is used within an implementation section. But they should have the
-% same syntax before that happens!
-%
-% Furthermore, we need another \enquote{layer} of documentation commands
-% to account for \enquote{user-macro} as opposed to
-% \enquote{code-functions}; the \pkg{expl3} functions should be
-% documented differently, probably, to the \pkg{ltcmd} user macros (at
-% least in terms of indexing).
-%
-% In no particular order, a list of things to do:
-% \begin{itemize}
-% \item Rename \env{function}/\env{macro} environments to better
-% describe their use.
-% \item Generalise \env{function}/\env{macro} for documenting
-% \enquote{other things}, such as environment names, package
-% options, even keyval options.
-% \item New function like \tn{part} but for files (remove awkward
-% \enquote{File} as \tn{partname}).
-% \item Something better to replace \cs{StopEventually}; I'm thinking
-% two environments \env{documentation} and \env{implementation} that
-% can conditionally typeset/ignore their material. (This has been
-% implemented but needs further consideration.)
-% \item Hyperlink documentation and implementation of macros (see the
-% \textsc{dtx} file of \pkg{svn-multi} v2 as an example). This is
-% partially done, now, but should be improved.
-% \end{itemize}
-%
-% \section{Documentation}
-%
-% \subsection{Configuration}
-%
-% Before class options are processed, \pkg{l3doc} loads a configuration
-% file \file{l3doc.cfg} if it exists, allowing you to customise the
-% behaviour of the class without having to change the documentation
-% source files.
-%
-% For example, to produce documentation on letter-sized paper instead of
-% the default A4 size, create \file{l3doc.cfg} and include the line
-% \begin{verbatim}
-% \PassOptionsToClass{letterpaper}{l3doc}
-% \end{verbatim}
-%
-% By default, \pkg{l3doc} selects the |T1| font encoding and loads the
-% Latin Modern fonts. To prevent this, use the class option
-% |cm-default|.
-%
-% \subsection{Class options}
-%
-% The class recognises a number of options, some of which are generally
-% useful and some of which are aimed squarely at use by the kernel team only.
-%
-% \DescribeOption{full}
-% \DescribeOption{onlydoc}
-% When the \texttt{full} option is set (the standard setting), both the
-% documentation and implementation parts of the source are typeset. If on the
-% other hand the \texttt{onlydoc} option is set, only the documentation part
-% is typeset.
-%
-% \DescribeOption{lm-default}
-% Selects whether the standard font set up is Latin Modern in the \texttt{T1}
-% encoding (the standard setting) or leaves the font setup unchanged.
-%
-% \DescribeOption{kernel}
-% Determines whether \pkg{l3doc} treats internal functions and variables
-% belonging to |kernel| module as allowable in code, for instance
-% \cs{__kernel_tl_to_str:w}, \cs{c__kernel_expl_date_tl}, and
-% \cs{l__kernel_expl_bool}. In general,
-% \emph{no} internal material from outside the current module is allowed.
-% However, for bootstrapping the \pkg{expl3} kernel, a small number of
-% cross-module functions are needed. To suppress the error message that
-% would otherwise arise, the class option \texttt{kernel} may be given.
-%
-% \DescribeOption{check}
-% When the \texttt{check} option is given, the class will record all commands
-% defined and documented in a \texttt{\meta{name}.cmds} file. This will show
-% which are both documented and defined, which are only documented and which
-% are only defined. (Here, \enquote{defined} means listed using a
-% \texttt{macro} or \texttt{variable} environment in the implementation part of
-% the source file).
-%
-% \DescribeOption{checktest}
-% When \texttt{checktest} is given as an option, the class will check that each
-% function entry in the implementation part of the source is marked using
-% \cs{UnitTest}.
-%
-% \DescribeOption{show-notes}
-% \DescribeOption{hide-notes}
-% These complementary options determine if the information given using the
-% \cs{NB} and \cs{NOTE} commands is printed.
-%
-% \DescribeOption{cs-break}
-% \DescribeOption{cs-break-nohyphen}
-% The commands \cs{cmd} and \cs{cs} allow hyphenation of control sequences
-% after (most) underscores. By default, a hyphen is used to mark the
-% hyphenation, but this can be changed with the \texttt{cs-break-nohyphen}
-% class option. To disable hyphenation of control sequences entirely, use
-% \texttt{cs-break = false}.
-%
-% By default, class options
-% \begin{verbatim}
-% full , check = false , checktest = false , lm-default
-% \end{verbatim}
-% are set.
-%
-% \subsection{Partitioning documentation and implementation}
-%
-% \pkg{doc} uses the \cs{OnlyDocumentation}/\cs{AlsoImplementation}
-% macros to guide the use of \cs{StopEventually}|{}|, which is intended
-% to be placed to partition the documentation and implementation within
-% a single \file{.dtx} file.
-%
-% This isn't very flexible, since it assumes that we \emph{always} want
-% to print the documentation. For the \pkg{expl3} sources, I wanted to
-% be able to input \file{.dtx} files in two modes: only displaying
-% the documentation, and only displaying the implementation. For
-% example:
-% \begin{verbatim}
-% \DisableImplementation
-% \DocInput{l3basics,l3prg,...}
-% \EnableImplementation
-% \DisableDocumentation
-% \DocInputAgain
-% \end{verbatim}
-%
-% The idea being that the entire \pkg{expl3} bundle can be documented,
-% with the implementation included at the back. Now, this isn't
-% perfect, but it's a start.
-%
-% Use |\begin{documentation}...\end{documentation}| around the
-% documentation, and |\begin{implementation}...\end{implementation}|
-% around the implementation. The
-% \cs{EnableDocumentation}/\cs{EnableImplementation} causes them to
-% be typeset when the \file{.dtx} file is \cs{DocInput}; use
-% \cs{DisableDocumentation}/\cs{DisableImplementation} to omit the
-% contents of those environments.
-%
-% Note that \cs{DocInput} now takes comma-separated arguments, and
-% \cs{DocInputAgain} can be used to re-input all \file{.dtx} files
-% previously input in this way.
-%
-% \subsection{General text markup}
-%
-% Many of the commands in this section come from \pkg{ltxdoc} with some
-% improvements.
-%
-% \begin{function}{\cmd, \cs}
-% \begin{syntax}
-% \cmd{\cmd} \oarg{options} \meta{control sequence}\\
-% \cs{cs} \oarg{options} \marg{csname}
-% \end{syntax}
-% These commands are provided to typeset control sequences.
-% |\cmd\foo| produces \enquote{\cmd\foo} and |\cs{foo}| produces the
-% same. In general, \cs{cs} is more robust since
-% it doesn't rely on catcodes being \enquote{correct} and is therefore
-% recommended.
-%
-% These commands are aware of the |@@| \pkg{DocStrip} syntax and
-% replace such instances correctly in the typeset documentation.
-% This only happens after a |%<@@=|\meta{module}|>| declaration.
-%
-% Additionally, commands can be used in the argument of \cs{cs}. For
-% instance, |\cs{\meta{name}:\meta{signature}}| produces
-% \cs[no-index]{\meta{name}:\meta{signature}}.
-%
-% The \meta{options} are a key--value list which can contain the
-% following keys:
-% \begin{itemize}
-% \item |index=|\meta{name}: the \meta{csname} is indexed as if
-% one had written \cs{cs}\Arg{name}.
-% \item |no-index|: the \meta{csname} is not indexed.
-% \item |module=|\meta{module}: the \meta{csname} is indexed in
-% the list of commands from the \meta{module}; the \meta{module}
-% can in particular be |TeX| for \enquote{\TeX{} and \LaTeXe{}}
-% commands, or empty for commands which should be placed in the
-% main index. By default, the \meta{module} is deduced
-% automatically from the command name.
-% \item |replace| is a boolean key (\texttt{true} by default) which
-% indicates whether to replace |@@| as \pkg{DocStrip} does.
-% \end{itemize}
-% These commands allow hyphenation of control sequences after (most) underscores.
-% By default, a hyphen is used to mark the hyphenation, but this can be changed with
-% the \texttt{cs-break-nohyphen} class option.
-% To disable hyphenation of control sequences entirely, use
-% \texttt{cs-break = false}.
-% \end{function}
-%
-%
-% \begin{function}{\tn}
-% \begin{syntax}
-% \cs{tn} \oarg{options} \marg{csname}
-% \end{syntax}
-% Analoguous to \cs{cs} but intended for \enquote{traditional} \TeX{}
-% or \LaTeXe{} commands; they are indexed accordingly. This is in
-% fact equivalent to \cs{cs} |[module=TeX, replace=false,|
-% \meta{options}|]| \Arg{csname}.
-% \end{function}
-%
-% \begin{function}{\meta}
-% \begin{syntax}
-% \cs{meta} \Arg{name}
-% \end{syntax}
-% \cs{meta} typesets the \meta{name} italicised in \meta{angle
-% brackets}. Within a \env{function} environment or similar, angle
-% brackets |<...>| are set up to be a shorthand for |\meta{...}|.
-%
-% This function has additional functionality over its \pkg{ltxdoc}
-% versions; underscores can be used to subscript material as in math
-% mode. For example, |\meta{arg_{xy}}| produces
-% \enquote{\meta{arg_{xy}}}.
-% \end{function}
-%
-% \begin{function}{\Arg, \marg, \oarg, \parg}
-% \begin{syntax}
-% |\Arg| \Arg{name}
-% \end{syntax}
-% Typesets the \meta{name} as for \cs{meta} and wraps it in braces.
-%
-% The \cs{marg}/\cs{oarg}/\cs{parg} versions follow from \pkg{ltxdoc}
-% in being used for \enquote{mandatory} or \enquote{optional} or
-% \enquote{picture} brackets as per \LaTeXe{} syntax.
-% \end{function}
-%
-% \begin{function}{\file, \env, \pkg, \cls}
-% \begin{syntax}
-% \cs{pkg} \Arg{name}
-% \end{syntax}
-% These all take one argument and are intended to be used as semantic
-% commands for representing files, environments, package names, and
-% class names, respectively.
-% \end{function}
-%
-% \begin{function}{\NB, \NOTE}
-% \begin{syntax}
-% \cs{NB} \marg{tag} \marg{comments}
-% \verb|\begin{NOTE}| \marg{tag}
-% \qquad\meta{comments}
-% \verb|\end{NOTE}|
-% \end{syntax}
-% Make notes in the source that are not typeset by default. When the \verb|show-notes|
-% class option is active, the comments are typeset in a detokenized and verbatim mode, respectively.
-% \end{function}
-%
-% \subsection{Describing functions in the documentation}
-%
-% \DescribeEnv{function}
-% \DescribeEnv{variable}
-% Two heavily-used environments are defined to describe \pkg{expl3} functions
-% and variables. If describing a variable, use the latter environment; it
-% behaves identically to the \env{function} environment.
-% \DescribeEnv{syntax}
-% Both of the above environments are typically combined with the \env{syntax}
-% environment, to describe their syntax.
-% \begin{framed}
-% \vspace{-\baselineskip}
-% \begin{verbatim}
-% \begin{function}{\package_function_one:N, \package_function_two:n}
-% \begin{syntax}
-% \cs{package_function_one:N} \meta{cs}
-% \cs{package_function_two:n} \marg{Argument}
-% \end{syntax}
-% Descriptive text here ...
-% \end{function}
-% \end{verbatim}
-% \hrulefill
-% \par
-% \hspace*{0.25\textwidth}
-% \begin{minipage}{0.5\textwidth}
-% \begin{function}{\package_function_one:N, \package_function_two:n}
-% \begin{syntax}
-% \cs[no-index]{package_function_one:N} \meta{cs}
-% \cs[no-index]{package_function_two:n} \marg{Argument}
-% \end{syntax}
-% \emph{Descriptive text here …}
-% \end{function}
-% \end{minipage}
-% \end{framed}
-%
-% Function environments take an optional argument to indicate whether
-% the function(s) it describes are expandable (use |EXP|) or
-% restricted-expandable (use |rEXP|) or defined in conditional forms
-% (use |TF|, |pTF|, or |noTF|). Note that |pTF| implies |EXP| since
-% predicates must always be expandable, and that |noTF| means that the
-% function without |TF| should be documented in addition to |TF|. For
-% the conditional forms |TF| and |pTF|, the argument of the
-% \env{function} environment is \emph{not} in fact a command that
-% exists: in the example below, \cs[no-index]{tl_if_empty:N} does not
-% exist, but its conditional forms \cs{tl_if_empty:NT},
-% \cs{tl_if_empty:NF}, \cs{tl_if_empty:NTF} and predicate form
-% \cs{tl_if_empty_p:N} exist:
-% \begin{framed}
-% \vspace{-\baselineskip}
-% \begin{verbatim}
-% \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c}
-% \begin{syntax}
-% \cs{tl_if_empty_p:N} \meta{tl~var}
-% \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the \meta{token list variable} is entirely empty
-% (\emph{i.e.}~contains no tokens at all).
-% \end{function}
-% \end{verbatim}
-% \hrulefill
-% \par
-% \hspace*{0.25\textwidth}
-% \begin{minipage}{0.5\textwidth}
-% \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c}
-% \begin{syntax}
-% \cs{tl_if_empty_p:N} \meta{tl~var}
-% \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the \meta{token list variable} is entirely empty
-% (\emph{i.e.}~contains no tokens at all).
-% \end{function}
-% \end{minipage}
-% \end{framed}
-%
-% \DescribeEnv{texnote}
-% This environment is used to call out sections within \env{function}
-% and similar environments that are only of interest to seasoned
-% \TeX{} developers.
-%
-% \subsection{Describing functions in the implementation}
-%
-% \DescribeEnv{macro}
-% The well-used environment from \LaTeXe{} for marking up the
-% implementation of macros/functions remains the \env{macro}
-% environment. Some changes in \pkg{l3doc}: it now accepts
-% comma-separated lists of functions, to avoid a very large number of
-% consecutive |\end{macro}| statements.
-% Spaces and new lines are ignored (the option |[verb]| prevents this).
-% \begin{verbatim}
-% % \begin{macro}{\foo:N, \foo:c}
-% % \begin{macrocode}
-% ... code for \foo:N and \foo:c ...
-% % \end{macrocode}
-% % \end{macro}
-% \end{verbatim}
-% If you are documenting an auxiliary macro, it's generally not
-% necessary to highlight it as much and you also don't need to check it
-% for, say, having a test function and having a documentation chunk
-% earlier in a \env{function} environment. \pkg{l3doc} will pick up these
-% cases from the presence of |__| in the name, or you may force marking
-% as internal by using |\begin{macro}[int]| to mark it as such. The margin
-% call-out is then printed in grey for such cases.
-%
-% For documenting \pkg{expl3}-type conditionals, you may also pass this
-% environment a |TF| option (and omit it from the function name) to
-% denote that the function is provided with |T|, |F|, and |TF| suffixes.
-% A similar |pTF| option prints both |TF| and |_p| predicate forms.
-% An option |noTF| prints both the |TF| forms and a form with neither
-% |T| nor |F|, to document functions such as \cs[no-index]{prop_get:NN}
-% which also have conditional forms (\cs[no-index]{prop_get:NNTF}).
-%
-% In a very small number of cases, there is no user documentation for
-% a \enquote{public} function. In these rare cases, the option
-% |no-user-doc| may be added to suppress the undefined reference that
-% would otherwise then arises.
-%
-% \DescribeMacro{\TestFiles}
-% \cs{TestFiles}\marg{list of files} is used to indicate which test
-% files are used for the current code; they are printed in the
-% documentation.
-%
-% \DescribeMacro{\UnitTested}
-% Within a \env{macro} environment, it is a good idea to mark whether a
-% unit test has been created for the commands it defines. This is
-% indicated by writing \cs{UnitTested} anywhere within |\begin{macro}|
-% \dots |\end{macro}|.
-%
-% If the class option |checktest| is enabled, then it is an \emph{error}
-% to have a \env{macro} environment without a call to
-% \file{Testfiles}. This is intended for large packages such as
-% \pkg{expl3} that should have absolutely comprehensive tests suites and
-% whose authors may not always be as sharp at adding new tests with new
-% code as they should be.
-%
-% \DescribeMacro{\TestMissing}
-% If a function is missing a test, this may be flagged by writing (as
-% many times as needed) \cs{TestMissing} \marg{explanation of test
-% required}. These missing tests are summarised in the listing
-% printed at the end of the compilation run.
-%
-% \DescribeEnv{variable}
-% When documenting variable definitions, use the \env{variable}
-% environment instead. Here it behaves identically to the
-% \env{macro} environment, except that if the class option |checktest|
-% is enabled, variables are not required to have a test file.
-%
-% \DescribeEnv{arguments}
-% Within a \env{macro} environment, you may use the \env{arguments}
-% environment to describe the arguments taken by the function(s). It
-% behaves like a modified enumerate environment.
-% \begin{verbatim}
-% % \begin{macro}{\foo:nn, \foo:VV}
-% % \begin{arguments}
-% % \item Name of froozle to be frazzled
-% % \item Name of muble to be jubled
-% % \end{arguments}
-% % \begin{macrocode}
-% ... code for \foo:nn and \foo:VV ...
-% % \end{macrocode}
-% % \end{macro}
-% \end{verbatim}
-%
-%
-% \subsection{Keeping things consistent}
-%
-% Whenever a function is either documented or defined with
-% \env{function} and \env{macro} respectively, its name is stored in a
-% sequence for later processing.
-%
-% At the end of the document (\emph{i.e.}, after the \file{.dtx} file
-% has finished processing), the list of names is analysed to check
-% whether all defined functions have been documented and vice versa. The
-% results are printed in the console output.
-%
-% If you need to do more serious work with these lists of names, take a
-% look at the implementation for the data structures and methods used to
-% store and access them directly.
-%
-% \subsection{Documenting templates}
-%
-% The following macros are provided for documenting templates; might end
-% up being something completely different but who knows.
-% \begin{quote}\parskip=0pt\obeylines
-% |\begin{TemplateInterfaceDescription}| \Arg{template type name}
-% | \TemplateArgument{none}{---}|
-% \textsc{or one or more of these:}
-% | \TemplateArgument| \Arg{arg no} \Arg{meaning}
-% \textsc{and}
-% |\TemplateSemantics|
-% | | \meta{text describing the template type semantics}
-% |\end{TemplateInterfaceDescription}|
-% \end{quote}
-%
-% \begin{quote}\parskip=0pt\obeylines
-% |\begin{TemplateDescription}| \Arg{template type name} \Arg{name}
-% \textsc{one or more of these:}
-% | \TemplateKey| \marg{key name} \marg{type of key}
-% | |\marg{textual description of meaning}
-% | |\marg{default value if any}
-% \textsc{and}
-% |\TemplateSemantics|
-% | | \meta{text describing special additional semantics of the template}
-% |\end{TemplateDescription}|
-% \end{quote}
-%
-% \begin{quote}\parskip=0pt\obeylines
-% |\begin{InstanceDescription}| \oarg{text to specify key column width (optional)}
-% \hfill\marg{template type name}\marg{instance name}\marg{template name}
-% \textsc{one or more of these:}
-% | \InstanceKey| \marg{key name} \marg{value}
-% \textsc{and}
-% |\InstanceSemantics|
-% | | \meta{text describing the result of this instance}
-% |\end{InstanceDescription}|
-% \end{quote}
-%
-% \end{documentation}
-%
-% \begin{implementation}
-%
-% \section{\pkg{l3doc} implementation}
-%
-% \begin{macrocode}
-%<*class>
-% \end{macrocode}
-%
-% \begin{macrocode}
-%<@@=codedoc>
-% \end{macrocode}
-%
-% \subsection{Variables}
-%
-% \begin{variable}{\g_docinput_clist}
-% The list of files which have been input through \cs{DocInput}.
-% \begin{macrocode}
-\clist_new:N \g_docinput_clist
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\g_doc_functions_seq, \g_doc_macros_seq}
-% All functions documented through \env{function}, and all macros
-% introduced through \env{macro}. They can be compared to see what
-% documentation or code is missing.
-% \begin{macrocode}
-\seq_new:N \g_doc_functions_seq
-\seq_new:N \g_doc_macros_seq
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_detect_internals_bool, \l_@@_detect_internals_tl}
-% If \texttt{true}, \pkg{l3doc} will check for use of internal
-% commands \cs[no-index]{__\meta{pkg}_\ldots{}} from other packages in
-% the argument of the \texttt{macro} environment, and in the code typeset in
-% \texttt{macrocode} environments, but not in~\cs{cs}. Also a token list
-% to store temporary data for this purpose.
-% \begin{macrocode}
-\bool_new:N \l_@@_detect_internals_bool
-\bool_set_true:N \l_@@_detect_internals_bool
-\tl_new:N \l_@@_detect_internals_tl
-\tl_new:N \l_@@_detect_internals_cs_tl
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_output_coffin}
-% The \env{function} environment is typeset by combining coffins
-% containing various pieces (function names, description, \emph{etc.})
-% into this coffin.
-% \begin{macrocode}
-\coffin_new:N \l_@@_output_coffin
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {\l_@@_functions_coffin, \l_@@_descr_coffin, \l_@@_syntax_coffin}
-% These coffins contain respectively the list of function names
-% (argument of the \env{function} environment), the text between
-% |\begin{function}| and |\end{function}|, and the syntax given in the
-% \env{syntax} environment.
-% \begin{macrocode}
-\coffin_new:N \l_@@_functions_coffin
-\coffin_new:N \l_@@_descr_coffin
-\coffin_new:N \l_@@_syntax_coffin
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\g_@@_syntax_box}
-% The contents of the \env{syntax} environment are typeset in this box
-% before being transferred to \cs{l_@@_syntax_coffin}.
-% \begin{macrocode}
-\box_new:N \g_@@_syntax_box
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_in_function_bool}
-% True when inside a \texttt{function} or \texttt{variable}
-% environment. Used by the \texttt{syntax} environment to determine
-% its behaviour.
-% \begin{macrocode}
-\bool_new:N \l_@@_in_function_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_long_name_bool, \l_@@_trial_width_dim}
-% The boolean \cs{l_@@_long_name_bool} is \texttt{true} if the width
-% \cs{l_@@_trial_width_dim} of the coffin \cs{l_@@_functions_coffin}
-% (containing the current function names) is bigger than the space
-% available in the margin.
-% \begin{macrocode}
-\bool_new:N \l_@@_long_name_bool
-\dim_new:N \l_@@_trial_width_dim
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_nested_macro_int}
-% The nesting of \env{macro} environments (this is now~$0$ outside a
-% \env{macro} environment).
-% \begin{macrocode}
-\int_new:N \l_@@_nested_macro_int
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {
-% \l_@@_macro_tested_bool,
-% \g_@@_missing_tests_prop,
-% \g_@@_not_tested_seq,
-% \g_@@_testfiles_seq,
-% }
-% A boolean describing whether the current macro has tests, and some
-% global structures which contain information about test files and
-% which tests are missing.
-% \begin{macrocode}
-\bool_new:N \l_@@_macro_tested_bool
-\prop_new:N \g_@@_missing_tests_prop
-\seq_new:N \g_@@_not_tested_seq
-\seq_new:N \g_@@_testfiles_seq
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {
-% \l_@@_macro_deprecated_bool ,
-% \l_@@_macro_internal_bool,
-% \l_@@_macro_nodoc_bool ,
-% \l_@@_macro_TF_bool,
-% \l_@@_macro_pTF_bool,
-% \l_@@_macro_noTF_bool,
-% \l_@@_macro_EXP_bool,
-% \l_@@_macro_rEXP_bool,
-% \l_@@_macro_var_bool,
-% \l_@@_override_module_tl,
-% \l_@@_macro_documented_tl,
-% }
-% Contain information about some options of function/macro
-% environments. We initialize \cs{l_@@_override_module_tl} to avoid
-% overriding module names by an empty name (meaning no module).
-% \begin{macrocode}
-\bool_new:N \l_@@_macro_deprecated_bool
-\bool_new:N \l_@@_macro_internal_bool
-\bool_new:N \l_@@_macro_nodoc_bool
-\bool_new:N \l_@@_macro_TF_bool
-\bool_new:N \l_@@_macro_pTF_bool
-\bool_new:N \l_@@_macro_noTF_bool
-\bool_new:N \l_@@_macro_EXP_bool
-\bool_new:N \l_@@_macro_rEXP_bool
-\bool_new:N \l_@@_macro_var_bool
-\tl_new:N \l_@@_override_module_tl
-\tl_set:Nn \l_@@_override_module_tl { \q_no_value }
-\tl_new:N \l_@@_macro_documented_tl
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {
-% \g_@@_lmodern_bool,
-% \g_@@_checkfunc_bool,
-% \g_@@_checktest_bool,
-% \g_@@_cs_break_bool,
-% \g_@@_show_notes_bool,
-% \g_@@_kernel_bool
-% }
-% Information about package options.
-% \begin{macrocode}
-\bool_new:N \g_@@_lmodern_bool
-\bool_new:N \g_@@_checkfunc_bool
-\bool_new:N \g_@@_checktest_bool
-\bool_new:N \g_@@_kernel_bool
-\bool_new:N \g_@@_cs_break_bool
-\bool_new:N \g_@@_show_notes_bool
-\bool_gset_true:N \g_@@_cs_break_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_tmpa_tl, \l_@@_tmpb_tl, \l_@@_tmpa_int, \l_@@_tmpa_seq}
-% Some temporary variables.
-% \begin{macrocode}
-\tl_new:N \l_@@_tmpa_tl
-\tl_new:N \l_@@_tmpb_tl
-\int_new:N \l_@@_tmpa_int
-\int_new:N \l_@@_tmpa_seq
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_names_block_tl}
-% List of local sequence variables (produced through
-% \cs{@@_lseq_name:n}), one for each set of variants in a
-% \env{function} or \env{macro} environment. More precisely these
-% sequences are named after the base forms, such as \cs{clist_count:n}
-% or \cs{clist_count:N} (which are not variants). Each of these
-% sequences have the base name (without any signature) as their first
-% item, followed by the list of variant's signatures, or
-% \cs{scan_stop:} to denote the absence of signature (no colon).
-% \begin{macrocode}
-\tl_new:N \l_@@_names_block_tl
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\g_@@_variants_seq}
-% Stores rather temporarily the list of variants (signatures only) of
-% a function/macro that is being documented. It is global because we
-% need it to keep its value throughout cells of an alignment.
-% \begin{macrocode}
-\seq_new:N \g_@@_variants_seq
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_names_verb_bool}
-% Set to |true| if the main argument of a macro/function environment
-% should be used as is, without removing any comma or space.
-% \begin{macrocode}
-\bool_new:N \l_@@_names_verb_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_names_seq}
-% List of functions/environments/\ldots{} appearing as arguments of a
-% given \env{function} or \env{macro} environment. These are the
-% names after conversion of |_@@| and |@@| to |__|\meta{module name}
-% and other sanitizing.
-% \begin{macrocode}
-\seq_new:N \l_@@_names_seq
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\g_@@_nested_names_seq}
-% Collects all macros in nested \env{macro} environments, to use them
-% in the \enquote{End definition} text.
-% \begin{macrocode}
-\seq_new:N \g_@@_nested_names_seq
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {
-% \l_@@_index_macro_tl, \l_@@_index_key_tl,
-% \l_@@_index_module_tl, \l_@@_index_internal_bool,
-% \l_@@_macro_do_not_index_tl
-% }
-% When analyzing a control sequence found within a \env{macrocode}
-% environment, \cs{l_@@_index_macro_tl} holds the control sequence
-% (partially a string), \cs{l_@@_index_key_tl} holds the future
-% sort key in the index, and \cs{l_@@_index_module_tl} is the
-% subindex in which the control sequence should be listed.
-% \cs{l_@@_index_internal_bool} indicates when the control sequence is
-% internal and should be indexed in a slightly different subindex.
-% Finally, \cs{l_@@_macro_do_not_index_tl} indicates control sequences
-% which should not be indexed in a specifiv \env{macro} envronment.
-% \begin{macrocode}
-\tl_new:N \l_@@_index_macro_tl
-\tl_new:N \l_@@_index_key_tl
-\tl_new:N \l_@@_index_module_tl
-\tl_new:N \l_@@_macro_do_not_index_tl
-\bool_new:N \l_@@_index_internal_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\g_@@_module_name_tl}
-% The module name, set when reading a line |<@@=|\meta{module}|>|.
-% \begin{macrocode}
-\tl_new:N \g_@@_module_name_tl
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\c_@@_iow_rule_tl, \c_@@_iow_midrule_tl}
-% $40$~equal signs.
-% \begin{macrocode}
-\tl_const:Nn \c_@@_iow_rule_tl
- { ======================================== }
-\tl_const:Nn \c_@@_iow_mid_rule_tl
- { -------------------------------------- }
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {\l_@@_macro_box, \l_@@_macro_index_box, \l_@@_macro_int}
-% A vertical box in which the names given to the macro environment are
-% typeset, a horizontal box in which we store the targets created by
-% indexing commands, and the number of macros so far (including those
-% from surrounding \env{macro} environments).
-% \begin{macrocode}
-\box_new:N \l_@@_macro_box
-\box_new:N \l_@@_macro_index_box
-\int_new:N \l_@@_macro_int
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {
-% \l_@@_cmd_tl,
-% \l_@@_cmd_index_tl,
-% \l_@@_cmd_module_tl,
-% \l_@@_cmd_noindex_bool,
-% \l_@@_cmd_replace_bool,
-% }
-% Variables used to control the behaviour of \cs{cmd}, \cs{cs} and
-% \cs{tn}.
-% \begin{macrocode}
-\tl_new:N \l_@@_cmd_tl
-\tl_new:N \l_@@_cmd_index_tl
-\tl_new:N \l_@@_cmd_module_tl
-\bool_new:N \l_@@_cmd_noindex_bool
-\bool_new:N \l_@@_cmd_replace_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_in_implementation_bool}
-% This boolean is \texttt{true} within the \env{implementation}
-% environment, and \texttt{false} anywhere else.
-% \begin{macrocode}
-\bool_new:N \l_@@_in_implementation_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}
-% {
-% \g_@@_typeset_documentation_bool,
-% \g_@@_typeset_implementation_bool
-% }
-% These booleans control whether the documentation/implementation
-% should be typeset. By default both should be.
-% \begin{macrocode}
-\bool_new:N \g_@@_typeset_documentation_bool
-\bool_new:N \g_@@_typeset_implementation_bool
-\bool_set_true:N \g_@@_typeset_documentation_bool
-\bool_set_true:N \g_@@_typeset_implementation_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\g_@@_base_name_tl, \l_@@_variants_prop}
-% The name of the macro which is being documented (without its
-% signature), and a property list mapping base forms of variants to
-% all variants which have the same base form.
-% \begin{macrocode}
-\tl_new:N \g_@@_base_name_tl
-\prop_new:N \l_@@_variants_prop
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_function_label_clist, \l_@@_no_label_bool}
-% Option of a \env{function} environment which replaces the label that
-% would normally be inserted by labels for the given list of control
-% sequences. This is only useful to avoid duplicate labels when a
-% function's documentation appears multiple times.
-% \begin{macrocode}
-\clist_new:N \l_@@_function_label_clist
-\bool_new:N \l_@@_no_label_bool
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_date_added_tl, \l_@@_date_updated_tl}
-% Values of some options of the \env{function} environment.
-% \begin{macrocode}
-\tl_new:N \l_@@_date_added_tl
-\tl_new:N \l_@@_date_updated_tl
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\l_@@_macro_argument_tl}
-% Save the argument of a \env{macro} or \env{function} environment for
-% use in error messages.
-% \begin{macrocode}
-\tl_new:N \l_@@_macro_argument_tl
-% \end{macrocode}
-% \end{variable}
-%
-% ^^A Bruno: what does the next line do?
-% \begin{macrocode}
-% \int_new:N \c@CodelineNo
-% \end{macrocode}
-%
-% \subsection{Variants and helpers}
-%
-% \begin{macro}{\@@_tmpa:w, \@@_tmpb:w}
-% Auxiliary macros for temporary use.
-% \begin{macrocode}
-\cs_new_eq:NN \@@_tmpa:w ?
-\cs_new_eq:NN \@@_tmpb:w ?
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \seq_set_split:NoV,
-% \tl_to_str:f
-% }
-% A few missing variants.
-% \begin{macrocode}
-\cs_generate_variant:Nn \seq_set_split:Nnn { NoV }
-\cs_generate_variant:Nn \tl_to_str:n { f }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[TF]{\@@_if_almost_str:n}
-% Used to test if the argument of |\cmd| or other macros to be indexed
-% is almost a string or not: for instance this is \texttt{false} if |#1|
-% contains |\meta{...}|. The surprising |f|-expansion is there to
-% cope with the case of |#1| starting with \cs{c_backslash_str}
-% which should be expanded and considered to be \enquote{normal}.
-% \begin{macrocode}
-\prg_new_protected_conditional:Npnn \@@_if_almost_str:n #1 { TF , T , F }
- {
- \int_compare:nNnTF
- { \tl_count:n {#1} }
- < { \tl_count:e { \tl_to_str:f {#1} } }
- { \prg_return_false: }
- { \prg_return_true: }
- }
-\prg_generate_conditional_variant:Nnn \@@_if_almost_str:n { V } { T }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_trim_right:Nn, \@@_trim_right:No}
-% Removes all material after |#2| in the token list variable~|#1|.
-% Perhaps combine with \cs{@@_key_trim_module:n}?
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_trim_right:Nn #1#2
- {
- \cs_set:Npn \@@_tmp:w ##1 #2 ##2 \q_stop { \exp_not:n {##1} }
- \__kernel_tl_set:Nx #1 { \exp_after:wN \@@_tmp:w #1 #2 \q_stop }
- }
-\cs_generate_variant:Nn \@@_trim_right:Nn { No }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[TF]{\@@_str_if_begin:nn, \@@_str_if_begin:oo}
-% True if the first string starts with the second.
-% \begin{macrocode}
-\prg_new_protected_conditional:Npnn \@@_str_if_begin:nn #1#2 { TF , T , F }
- {
- \tl_if_in:ooTF
- { \exp_after:wN \scan_stop: \tl_to_str:n {#1} }
- { \exp_after:wN \scan_stop: \tl_to_str:n {#2} }
- { \prg_return_true: }
- { \prg_return_false: }
- }
-\prg_generate_conditional_variant:Nnn \@@_str_if_begin:nn
- { oo } { TF , T , F }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_replace_at_at:N}
-% \begin{macro}{\@@_replace_at_at_aux:Nn}
-% The goal is to replace |@@| by the current module name. We take
-% advantage of this function to also detect internal macros. If there is
-% no \meta{module~name}, do nothing. Otherwise, sanitize the catcodes
-% of |@| and~|_|, temporarily change |@@@@| to |aa| with different catcodes and later to |@@|, and replace |__@@| and |_@@| and |@@| by
-% |__|\meta{module~name}. The result contains |_| with category
-% code letter because this is what the |macrocode| environment
-% expects. Other use cases can apply \cs{tl_to_str:n} if needed.
-% Note that we include spaces between the
-% |@| in the code below, since it is also processed through the same
-% replacement rules.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_replace_at_at:N #1
- {
- \tl_if_empty:NF \g_@@_module_name_tl
- {
- \exp_args:NNo \@@_replace_at_at_aux:Nn
- #1 \g_@@_module_name_tl
- }
- }
-\cs_new_protected:Npe \@@_replace_at_at_aux:Nn #1#2
- {
- \tl_replace_all:Nnn #1 { \token_to_str:N @ } { @ }
- \tl_replace_all:Nnn #1 { \token_to_str:N _ } { _ }
- \tl_replace_all:Nnn #1 { @ @ @ @ } { \token_to_str:N a a }
- \tl_replace_all:Nnn #1 { _ _ @ @ } { _ _ #2 }
- \tl_replace_all:Nnn #1 { _ @ @ } { _ _ #2 }
- \tl_replace_all:Nnn #1 { @ @ } { _ _ #2 }
- \tl_replace_all:Nnn #1 { \token_to_str:N a a } { @ @ }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \@@_detect_internals:N,
-% \@@_detect_internals_aux:N,
-% \@@_if_detect_internals_ok:NF
-% }
-% After splitting at each |__| and removing the leading item from the
-% sequence (since it does not follow |__|), remove everything after
-% any space or end-of-line to get a good approximation of the control
-% sequence (for the warning message). Then check if that starts with
-% something allowed: |@@| module name and |:| or |_|, or if the
-% relevant boolean is set |kernel_| (it seems safe to assume we will
-% not define a |\__kernel:...| command). For the message itself
-% remove anything after any |_| or |:| (with either catcode) to get a
-% guess of the module name.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_detect_internals:N #1
- {
- \bool_if:NT \l_@@_detect_internals_bool
- { \@@_detect_internals_aux:N #1 }
- }
-\group_begin:
- \char_set_catcode_active:N \^^M
- \cs_new_protected:Npn \@@_detect_internals_aux:N #1
- {
- \tl_set_eq:NN \l_@@_detect_internals_tl #1
- \tl_replace_all:NVn \l_@@_detect_internals_tl \c_underscore_str { _ }
- \seq_set_split:NnV \l_@@_tmpa_seq { _ _ } \l_@@_detect_internals_tl
- \seq_pop_left:NN \l_@@_tmpa_seq \l_@@_detect_internals_tl
- \seq_map_variable:NNn \l_@@_tmpa_seq \l_@@_detect_internals_tl
- {
- \@@_trim_right:No \l_@@_detect_internals_tl
- \c_catcode_active_space_tl
- \@@_trim_right:Nn \l_@@_detect_internals_tl ^^M
- \@@_if_detect_internals_ok:NF \l_@@_detect_internals_tl
- {
- \tl_set_eq:NN \l_@@_detect_internals_cs_tl \l_@@_detect_internals_tl
- \@@_trim_right:Nn \l_@@_detect_internals_tl _
- \@@_trim_right:Nn \l_@@_detect_internals_tl :
- \@@_trim_right:No \l_@@_detect_internals_tl { \token_to_str:N : }
- \msg_warning:nneee { l3doc } { foreign-internal }
- { \tl_to_str:N \l_@@_detect_internals_cs_tl }
- { \tl_to_str:N \l_@@_detect_internals_tl }
- { \tl_to_str:N \g_@@_module_name_tl }
- }
- }
- }
-\group_end:
-\prg_new_protected_conditional:Npnn \@@_if_detect_internals_ok:N #1 { F }
- {
- \@@_str_if_begin:ooTF {#1} { \g_@@_module_name_tl _ }
- { \prg_return_true: }
- {
- \@@_str_if_begin:ooTF {#1} { \g_@@_module_name_tl : }
- { \prg_return_true: }
- {
- \bool_if:NTF \g_@@_kernel_bool
- {
- \@@_str_if_begin:ooTF {#1} { kernel _ }
- { \prg_return_true: }
- { \prg_return_false: }
- }
- { \prg_return_false: }
- }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[rEXP]{\@@_signature_base_form:n}
-% \begin{macro}
-% {\@@_signature_base_form_aux:n, \@@_signature_base_form_aux:w}
-% Expands to the \enquote{base form} of the signature. For instance,
-% given |noxcfvV| it would obtain |nnnNnnn|, or given |ow| it would
-% obtain |nw|. The loop stops at the first token that is not
-% recognized; the rest is enclosed in \cs{exp_not:n}.
-% \begin{macrocode}
-\cs_new:Npn \@@_signature_base_form:n #1
- { \@@_signature_base_form_aux:n #1 \q_stop }
-\cs_new:Npn \@@_signature_base_form_aux:n #1
- {
- \str_case:nnTF {#1}
- {
- { N } { N }
- { c } { N }
- { n } { n }
- { o } { n }
- { f } { n }
- { e } { n }
- { x } { n }
- { V } { n }
- { v } { n }
- }
- { \@@_signature_base_form_aux:n }
- { \@@_signature_base_form_aux:w #1 }
- }
-\cs_new:Npn \@@_signature_base_form_aux:w #1 \q_stop
- { \exp_not:n {#1} }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\@@_predicate_from_base:n}
-% Get predicate from a function's base name. The code is not broken
-% by functions with no signature. The |n|-type version can be used
-% for keys and other non-control sequences. The output after
-% |e|-expansion is a string.
-% \begin{macrocode}
-\cs_new:Npn \@@_predicate_from_base:n #1
- {
- \@@_get_function_name:n {#1}
- \tl_to_str:n { _p: }
- \@@_get_function_signature:n {#1}
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_split_function_do:nn, \@@_split_function_do:on}
-% \begin{macro}{\@@_get_function_name:n, \@@_get_function_signature:n}
-% \begin{macro}{\@@_split_function_auxi:w, \@@_split_function_auxii:w}
-% Similar to internal functions defined in \pkg{l3basics}, but here we
-% operate on strings directly rather than control sequences.
-% \begin{macrocode}
-\cs_new:Npn \@@_get_function_name:n #1
- { \@@_split_function_do:nn {#1} { \use_i:nnn } }
-\cs_new:Npn \@@_get_function_signature:n #1
- { \@@_split_function_do:nn {#1} { \use_ii:nnn } }
-\cs_set_protected:Npn \@@_tmpa:w #1
- {
- \cs_new:Npn \@@_split_function_do:nn ##1
- {
- \exp_after:wN \@@_split_function_auxi:w
- \tl_to_str:n {##1} \q_mark \c_true_bool
- #1 \q_mark \c_false_bool
- \q_stop
- }
- \cs_new:Npn \@@_split_function_auxi:w
- ##1 #1 ##2 \q_mark ##3##4 \q_stop ##5
- { \@@_split_function_auxii:w {##5} ##1 \q_mark \q_stop {##2} ##3 }
- \cs_new:Npn \@@_split_function_auxii:w
- ##1##2 \q_mark ##3 \q_stop
- { ##1 {##2} }
- }
-\exp_args:No \@@_tmpa:w { \token_to_str:N : }
-\cs_generate_variant:Nn \@@_split_function_do:nn { o }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}[rEXP]{\@@_key_get_base:nN}
-% Get the base form of a function and store it. As part of getting
-% the base form, change trailing |T| or |F| to |TF|, skipping that
-% change if the function contains no colon to avoid changing for
-% instance some names ending in \texttt{PDF} or similar. The various
-% letters |z| serve as end-delimiters different from any outcome of
-% \cs{tl_to_str:n}.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_key_get_base:nN #1#2
- {
- \@@_if_almost_str:nTF {#1}
- {
- \@@_key_get_base_TF:nN {#1} \l_@@_tmpa_tl
- \__kernel_tl_set:Nx #2
- { \@@_split_function_do:on \l_@@_tmpa_tl { \@@_base_form_aux:nnN } }
- }
- { \tl_set:Nn #2 {#1} }
- }
-\cs_new:Npe \@@_key_get_base_TF:nN #1#2
- {
- \__kernel_tl_set:Nx #2 { \exp_not:N \tl_to_str:n {#1} }
- \tl_if_in:NoF #2 { \tl_to_str:n {:} }
- { \exp_not:N \prg_break: }
- \tl_if_in:onT { #2 z } { \tl_to_str:n {TF} z }
- { \exp_not:N \prg_break: }
- \tl_if_in:onT { #2 z } { \tl_to_str:n {T} z }
- {
- \tl_put_right:Nn #2 { \tl_to_str:n {F} }
- \exp_not:N \prg_break:
- }
- \tl_if_in:onT { #2 z } { \tl_to_str:n {F} z }
- {
- \tl_put_right:Nn #2 { z }
- \tl_replace_once:Nnn #2 { \tl_to_str:n {F} z } { \tl_to_str:n {TF} }
- \exp_not:N \prg_break:
- }
- \exp_not:N \prg_break_point:
- }
-\cs_new:Npn \@@_base_form_aux:nnN #1#2#3
- {
- \exp_not:n {#1}
- \bool_if:NT #3
- {
- \token_to_str:N :
- \bool_lazy_or:nnTF
- { \str_if_eq_p:nn { #1 ~ } { \exp_args } }
- { \str_if_eq_p:nn { #1 ~ } { \exp_last_unbraced } }
- { \exp_not:n {#2} }
- { \@@_signature_base_form:n {#2} }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_base_form_signature_do:nnn}
-% Do |#2{#1}| if there is no signature, or if |#1| contains two colons
-% in a row (this covers the weird function |\::N| and so on).
-% Otherwise apply |#3| with the following two arguments: the base form
-% of |#1|, and the original signature with an extra pair of braces.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_base_form_signature_do:nnn #1#2#3
- {
- \@@_split_function_do:nn {#1}
- { \@@_base_form_aux:nnnnnN {#1} {#2} {#3} }
- }
-\cs_new_protected:Npn \@@_base_form_aux:nnnnnN #1#2#3#4#5#6
- {
- \bool_if:NTF #6
- {
- \tl_if_head_eq_charcode:nNTF {#4} :
- { #2 {#1} }
- {
- \use:e
- {
- \exp_not:n {#3}
- { \@@_base_form_aux:nnN {#4} {#5} #6 }
- }
- {#4} {#5}
- }
- }
- { #2 {#1} }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[pTF]{\@@_date_compare:nNn}
-% \begin{macro}{\@@_date_compare_aux:nnnNnnn, \@@_date_compare_aux:w}
-% Expects |#1| and |#3| to be dates in the format YYYY-MM-DD (but
-% accepts YYYY or YYYY-MM too). Compares them using |#2| (one of |<|,
-% |=|, |>|), filling in zeros for missing data.
-% \begin{macrocode}
-\prg_new_conditional:Npnn \@@_date_compare:nNn #1#2#3 { TF , T , F , p }
- { \@@_date_compare_aux:w #1--- \q_mark #2 #3--- \q_stop }
-\cs_new:Npn \@@_date_compare_aux:w
- #1 - #2 - #3 - #4 \q_mark #5 #6 - #7 - #8 - #9 \q_stop
- {
- \@@_date_compare_aux:nnnNnnn
- { \tl_if_empty:nTF {#1} { 0 } {#1} }
- { \tl_if_empty:nTF {#2} { 0 } {#2} }
- { \tl_if_empty:nTF {#3} { 0 } {#3} }
- #5
- { \tl_if_empty:nTF {#6} { 0 } {#6} }
- { \tl_if_empty:nTF {#7} { 0 } {#7} }
- { \tl_if_empty:nTF {#8} { 0 } {#8} }
- }
-\cs_new:Npn \@@_date_compare_aux:nnnNnnn #1#2#3#4#5#6#7
- {
- \int_compare:nNnTF {#1} = {#5}
- {
- \int_compare:nNnTF {#2} = {#6}
- {
- \int_compare:nNnTF {#3} #4 {#7}
- { \prg_return_true: } { \prg_return_false: }
- }
- {
- \int_compare:nNnTF {#2} #4 {#6}
- { \prg_return_true: } { \prg_return_false: }
- }
- }
- {
- \int_compare:nNnTF {#1} #4 {#5}
- { \prg_return_true: } { \prg_return_false: }
- }
- \use_none:n
- \q_stop
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\@@_gprop_name:n, \@@_lseq_name:n}
-% We need to keep track of some information about control sequences
-% (and other strings) that are being (or have been) documented. Some
-% is stored into global props and some into local seqs, whose name
-% does not follow conventions: it is \cs[no-index]{g_@@} or
-% \cs[no-index]{l_@@} followed by a space and by the string, which can
-% be arbitrary. We cannot reasonably use a single big |prop| for
-% speed reasons.
-% \begin{macrocode}
-\cs_new:Npn \@@_gprop_name:n #1 { g_@@ ~ \tl_to_str:n {#1} }
-\cs_new:Npn \@@_lseq_name:n #1 { l_@@ ~ \tl_to_str:n {#1} }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Messages}
-%
-% \begin{macrocode}
-\msg_new:nnnn { l3doc } { no-signature-TF }
- { Function/macro~'#1'~cannot~be~turned~into~a~conditional. }
- {
- A~function~or~macro~environment~with~option~pTF,~TF~or~noTF~
- received~the~argument~'#1'.~This~function's~name~has~no~
- ':'~hence~it~is~not~clear~where~to~add~'_p'~or~'TF'.~
- Please~follow~expl3~naming~conventions.
- }
-\msg_new:nnn { l3doc } { date-format }
- { The~date~'#1'~should~be~given~in~YYYY-MM-DD~format. }
-\msg_new:nnn { l3doc } { future-date }
- { The~added/updated~date~'#2'~of~'#1'~is~in~the~future. }
-\msg_new:nnn { l3doc } { syntax-nested-function }
- {
- The~'syntax'~environment~should~be~used~in~the~
- innermost~'function'~environment.
- }
-\msg_new:nnn { l3doc } { multiple-syntax }
- {
- The~'syntax'~environment~should~only~be~used~once~in~
- a~'function'~environment.
- }
-\msg_new:nnn { l3doc } { deprecated-option }
- { The~option~'#1'~has~been~deprecated~for~'#2'. }
-\msg_new:nnn { l3doc } { foreign-internal }
- {
- A~control~sequence~of~the~form~'...__#1'~was~used.~
- It~should~only~be~used~in~the~module~'#2'
- \tl_if_empty:nF {#3} { ,~not~in~'#3' } .
- }
-% \end{macrocode}
-%
-% \subsection{Options and configuration}
-%
-% \begin{macrocode}
-\DeclareKeys [ l3doc / options ]
- {
- a5paper .code:n = \@latexerr { Option~not~supported } { } ,
- full .code:n =
- {
- \bool_gset_true:N \g_@@_typeset_documentation_bool
- \bool_gset_true:N \g_@@_typeset_implementation_bool
- } ,
- onlydoc .code:n =
- {
- \bool_gset_true:N \g_@@_typeset_documentation_bool
- \bool_gset_false:N \g_@@_typeset_implementation_bool
- } ,
- check .bool_gset:N = \g_@@_checkfunc_bool ,
- checktest .bool_gset:N = \g_@@_checktest_bool ,
- kernel .bool_gset:N = \g_@@_kernel_bool ,
- stdmodule .bool_gset_inverse:N = \g_@@_kernel_bool ,
- lm-default .bool_gset:N = \g_@@_lmodern_bool ,
- cs-break .bool_gset_inverse:N = \g_@@_cs_break_bool ,
- cs-break-nohyphen .code:n = \PassOptionsToPackage{nohyphen}{underscore} ,
- show-notes .bool_gset:N = \g_@@_show_notes_bool,
- hide-notes .bool_gset_inverse:N = \g_@@_show_notes_bool
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\DeclareUnknownKeyHandler [ l3doc / options ]
- { \PassOptionsToClass { \CurrentOption } { article } }
-\SetKeys [ l3doc / options ]
- { full , check = false , checktest = false , lm-default }
-\PassOptionsToClass { a4paper } { article }
-% \end{macrocode}
-%
-% Input a local configuration file, if it exists, with a message to the
-% console that this has happened. Since we distribute a \file{.cfg} file
-% with the class, this should usually always be true. Therefore, check
-% for \cs{ExplMakeTitle} (defined in \enquote{our} \file{.cfg} file) and
-% only output the informational message if it's not found.
-%
-% \begin{macrocode}
-\msg_new:nnn { l3doc } { input-cfg }
- { Local~config~file~l3doc.cfg~loaded. }
-\file_if_exist:nT { l3doc.cfg }
- {
- \file_input:n { l3doc.cfg }
- \cs_if_exist:cF { ExplMakeTitle }
- { \msg_info:nn { l3doc } { input-cfg } }
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\ProcessKeyOptions [ l3doc / options ]
-% \end{macrocode}
-%
-%
-% \subsection{Class and package loading}
-%
-% \begin{macrocode}
-\LoadClass{article}
-\RequirePackage{doc}
-\RequirePackage
- {
- array,
- alphalph,
- amsmath,
- amssymb,
- booktabs,
- color,
- colortbl,
- hologo,
- enumitem,
- pifont,
- textcomp,
- trace,
- csquotes,
- fancyvrb,
- underscore,
- verbatim
- }
-\raggedbottom
-% \end{macrocode}
-%
-% Depending on the option, load the package \pkg{lmodern} to set the
-% font. Then replace the italic typewriter font with the oblique shape
-% instead; the former makes my skin crawl. (Will, Aug 2011)
-% \begin{macrocode}
-\bool_if:NT \g_@@_lmodern_bool
- {
- \RequirePackage[T1]{fontenc}
- \RequirePackage{lmodern}
- \group_begin:
- \ttfamily
- \DeclareFontShape{T1}{lmtt}{m}{it}{<->ec-lmtto10}{}
- \group_end:
- }
-% \end{macrocode}
-%
-% Must be last, as usual.
-% \begin{macrocode}
-\RequirePackage{hypdoc}
-% \end{macrocode}
-%
-% \subsection{Configuration and tweaks}
-%
-% \begin{macro}{\MakePrivateLetters}
-% A few more letters are \enquote{private} in a \LaTeX3 programming
-% environment.
-% \begin{macrocode}
-\cs_gset:Npn \MakePrivateLetters
- {
- \char_set_catcode_letter:N \@
- \char_set_catcode_letter:N \_
- \char_set_catcode_letter:N \:
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{CodelineNo}
-% Some configurations which have to do with line numbering.
-% \begin{macrocode}
-\setcounter{StandardModuleDepth}{1}
-\@addtoreset{CodelineNo}{part}
-\tl_replace_once:Nnn \theCodelineNo
- { \HDorg@theCodelineNo }
- { \textcolor[gray]{0.5} { \sffamily\tiny\arabic{CodelineNo} } }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\verbatim, \endverbatim}
-% In \file{.dtx} documents, the \env{verbatim} environment adds extra
-% space because it only removes the first \enquote{\%} sign, and not
-% the indentation (typically a space). Fix it with \pkg{fancyvrb}:
-% \begin{macrocode}
-\fvset{gobble=2}
-\cs_gset_eq:NN \verbatim \Verbatim
-\cs_gset_eq:NN \endverbatim \endVerbatim
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\ifnot@excluded}
-% This function tests whether a macro name stored in
-% \tn{macro@namepart} was excluded from indexing by \tn{DoNotIndex}.
-% Rather than trying to fix catcodes that come into here, turn
-% everything to string catcodes. This is slightly inefficient as we
-% could have ensured that \tn{index@excludelist} has string catcodes
-% in the first place.
-% \begin{macrocode}
-\cs_set_protected:Npn \ifnot@excluded
- {
- \exp_args:Nee \expanded@notin
- { \c_backslash_str \tl_to_str:N \macro@namepart , }
- { \exp_args:NV \tl_to_str:n \index@excludelist }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\pdfstringnewline}
-% \begin{macro}{\@@_pdfstring_newline:w}
-% We avoid some hyperref warnings by making |\\| (almost) trivial in
-% bookmarks: more precisely it might be used with a star and an
-% optional argument, which we thus remove using an \pkg{ltcmd}
-% expandable command. Since there cannot be trailing optional
-% arguments, pick up an extra mandatory one and put it back.
-% \begin{macrocode}
-\cs_new:Npn \pdfstringnewline { : ~ }
-\DeclareExpandableDocumentCommand
- { \@@_pdfstring_newline:w } { s o m } { \pdfstringnewline #3 }
-\pdfstringdefDisableCommands
- { \cs_set_eq:NN \\ \@@_pdfstring_newline:w }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Design}
-%
-% Increase the text width slightly so that width the standard fonts
-% 72~columns of code may appear in a \env{macrocode} environment.
-% Increase the marginpar width slightly, for long command names. And
-% increase the left margin by a similar amount.
-% \begin{macrocode}
-\setlength \textwidth { 385pt }
-\addtolength \marginparwidth { 30pt }
-\addtolength \oddsidemargin { 20pt }
-\addtolength \evensidemargin { 20pt }
-% \end{macrocode}
-% (These were introduced when \cls{article} was the documentclass, but
-% I've left them here for now to remind me to do something about them
-% later.)
-%
-% \begin{macro}{\list}
-% \begin{macro}{\@@_oldlist:nn}
-% Customise lists.
-% \begin{macrocode}
-\cs_new_eq:NN \@@_oldlist:nn \list
-\cs_gset:Npn \list #1 #2
- { \@@_oldlist:nn {#1} { #2 \dim_zero:N \listparindent } }
-\setlength \parindent { 2em }
-\setlength \itemindent { 0pt }
-\setlength \parskip { 0pt plus 3pt minus 0pt }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\partname}
-% Use \enquote{File} as a name in Part titles.
-% \begin{macrocode}
-\tl_gset:Nn \partname {File}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\l@section, \l@subsection}
-% Customise the table of contents (as we have so many sections).
-% Different design and/or structure is called for.
-% \begin{macrocode}
-\@addtoreset{section}{part}
-\cs_gset:Npn \l@section #1#2
- {
- \ifnum \c@tocdepth >\z@
- \addpenalty\@secpenalty
- \addvspace{1.0em \@plus\p@}
- \setlength\@tempdima{2.5em} % was 1.5em
- \begingroup
- \parindent \z@ \rightskip \@pnumwidth
- \parfillskip -\@pnumwidth
- \leavevmode \bfseries
- \advance\leftskip\@tempdima
- \hskip -\leftskip
- #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
- \endgroup
- \fi
- }
-\cs_gset:Npn \l@subsection
- { \@dottedtocline{2}{2.5em}{2.3em} } % #2 = 1.5em
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Text markup}
-%
-% Make "|" and |"| be \enquote{short verb} characters, but not in the
-% document preamble, where an active character may interfere with
-% packages that are loaded. Remove these short-hands at the end of the
-% document before reading the \file{.aux} file, as they may appear in
-% labels (for instance, \pkg{l3fp} documents an operation "||").
-% \begin{macrocode}
-\AtBeginDocument
- {
- \MakeShortVerb \"
- \MakeShortVerb \|
- }
-\AtEndDocument
- {
- \DeleteShortVerb \"
- \DeleteShortVerb \|
- }
-% \end{macrocode}
-%
-% \begin{macro}{\eTeX, \IniTeX, \Lua, \LuaTeX, \pdfTeX, \XeTeX,
-% \pTeX, \upTeX, \epTeX, \eupTeX}
-% Some commands for logos.
-% \begin{macrocode}
-\providecommand*\eTeX{\hologo{eTeX}}
-\providecommand*\IniTeX{\hologo{iniTeX}}
-\providecommand*\Lua{Lua}
-\providecommand*\LuaTeX{\hologo{LuaTeX}}
-\providecommand*\pdfTeX{\hologo{pdfTeX}}
-\providecommand*\XeTeX{\hologo{XeTeX}}
-\providecommand*\pTeX{p\kern-.2em\hologo{TeX}}
-\providecommand*\upTeX{up\kern-.2em\hologo{TeX}}
-\providecommand*\epTeX{$\varepsilon$-\pTeX}
-\providecommand*\eupTeX{$\varepsilon$-\upTeX}
-\providecommand*\ConTeXt{\hologo{ConTeXt}}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\cmd, \cs, \tn}
-% They rely on a common auxiliary \cs{@@_cmd:nn} which receives as
-% arguments the options and some tokens whose string representation
-% starts with a backslash (to support cases such as |\cs{pkg_\ldots}|,
-% we do not turn the whole argument into a string).
-% \begin{macrocode}
-\DeclareDocumentCommand \cmd { O{} m }
- { \@@_cmd:no {#1} { \token_to_str:N #2 } }
-\DeclareDocumentCommand \cs { O{} m }
- { \@@_cmd:no {#1} { \c_backslash_str #2 } }
-\DeclareDocumentCommand \tn { O{} m }
- {
- \@@_cmd:no
- { module = TeX , replace = false , #1 }
- { \c_backslash_str #2 }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\meta}
-% A document-level command.
-% \begin{macrocode}
-\DeclareDocumentCommand \meta { m }
- { \texttt{ \@@_meta:n {#1} } }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \@@_pdfstring_cmd:w,
-% \@@_pdfstring_cs:w,
-% \@@_pdfstring_meta:w
-% }
-% To work within a bookmark, these commands must be expandable.
-% \begin{macrocode}
-\DeclareExpandableDocumentCommand
- { \@@_pdfstring_cmd:w } { o m } { \token_to_str:N #2 }
-\DeclareExpandableDocumentCommand
- { \@@_pdfstring_cs:w } { o m } { \textbackslash \tl_to_str:n {#2} }
-\cs_new:Npn \@@_pdfstring_meta:w #1
- { < \tl_to_str:n {#1} > }
-\pdfstringdefDisableCommands
- {
- \cs_set_eq:NN \cmd \@@_pdfstring_cmd:w
- \cs_set_eq:NN \cs \@@_pdfstring_cs:w
- \cs_set_eq:NN \tn \@@_pdfstring_cs:w
- \cs_set_eq:NN \meta \@@_pdfstring_meta:w
- \cs_set_eq:NN \@@_meta:n \@@_pdfstring_meta:w
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\Arg, \marg, \oarg, \parg}
-% |\marg{text}| prints \marg{text}, \enquote{mandatory argument}.\\
-% |\oarg{text}| prints \oarg{text}, \enquote{optional argument}.\\
-% |\parg{te,xt}| prints \parg{te,xt}, \enquote{picture mode argument}.
-% Finally, \cs{Arg} is the same as \cs{marg}.
-% \begin{macrocode}
-\newcommand\Arg[1]
- { \texttt{\char`\{} \@@_meta:n {#1} \texttt{\char`\}} }
-\providecommand\marg[1]{ \Arg{#1} }
-\providecommand\oarg[1]{ \texttt[ \@@_meta:n {#1} \texttt] }
-\providecommand\parg[1]{ \texttt( \@@_meta:n {#1} \texttt) }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\file, \env, \pkg, \cls}
-% This list may change\dots this is just my preference for markup.
-% \begin{macrocode}
-\DeclareRobustCommand \file {\nolinkurl}
-\DeclareRobustCommand \env {\texttt}
-\DeclareRobustCommand \pkg {\textsf}
-\DeclareRobustCommand \cls {\textsf}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\EnableDocumentation, \EnableImplementation}
-% \begin{macro}{\DisableDocumentation, \DisableImplementation}
-% Control whether to typeset the documentation/implementation or not.
-% These simply set two switches.
-% \begin{macrocode}
-\NewDocumentCommand \EnableDocumentation { }
- { \bool_gset_true:N \g_@@_typeset_documentation_bool }
-\NewDocumentCommand \EnableImplementation { }
- { \bool_gset_true:N \g_@@_typeset_implementation_bool }
-\NewDocumentCommand \DisableDocumentation { }
- { \bool_gset_false:N \g_@@_typeset_documentation_bool }
-\NewDocumentCommand \DisableImplementation { }
- { \bool_gset_false:N \g_@@_typeset_implementation_bool }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{environment}{documentation}
-% \begin{environment}{implementation}
-% If the documentation/implementation should be typeset, then simply
-% set the boolean \cs{l_@@_in_implementation_bool} which indicates
-% whether we are within the implementation section. Otherwise use
-% \cs{comment} (and a paired \cs{endcomment}).
-% \begin{macrocode}
-\NewDocumentEnvironment { documentation } { }
- {
- \bool_if:NTF \g_@@_typeset_documentation_bool
- { \bool_set_false:N \l_@@_in_implementation_bool }
- { \comment }
- }
- { \bool_if:NF \g_@@_typeset_documentation_bool { \endcomment } }
-\NewDocumentEnvironment { implementation } { }
- {
- \bool_if:NTF \g_@@_typeset_implementation_bool
- { \bool_set_true:N \l_@@_in_implementation_bool }
- { \comment }
- }
- { \bool_if:NF \g_@@_typeset_implementation_bool { \endcomment } }
-% \end{macrocode}
-% \end{environment}
-% \end{environment}
-%
-% \begin{environment}{variable}
-% The \env{variable} environment behaves as a \env{function} or
-% \env{macro} environment depending on the part of the document.
-% \begin{macrocode}
-\DeclareDocumentEnvironment { variable } { O{} +v }
- {
- \bool_if:NTF \l_@@_in_implementation_bool
- { \@@_macro:nnw { var , #1 } {#2} }
- { \@@_function:nnw {#1} {#2} }
- }
- {
- \bool_if:NTF \l_@@_in_implementation_bool
- { \@@_macro_end: }
- { \@@_function_end: }
- }
-% \end{macrocode}
-% \end{environment}
-%
-% \begin{environment}{function}
-% \begin{environment}{macro}
-% Environment for documenting function(s), and environment for
-% documenting the implementation of a macro.
-% \begin{macrocode}
-\DeclareDocumentEnvironment { function } { O{} +v }
- { \@@_function:nnw {#1} {#2} }
- { \@@_function_end: }
-\DeclareDocumentEnvironment { macro } { O{} +v }
- { \@@_macro:nnw {#1} {#2} }
- { \@@_macro_end: }
-% \end{macrocode}
-% \end{environment}
-% \end{environment}
-%
-% \begin{environment}{syntax}
-% Syntax block placed next to the list of functions to illustrate
-% their use. TODO: test that the \env{syntax} environment is only
-% used inside the \env{function} environment, and that it only appears
-% once.
-% \begin{macrocode}
-\NewDocumentEnvironment { syntax } { }
- { \@@_syntax:w }
- {
- \@@_syntax_end:
- \ignorespacesafterend
- }
-% \end{macrocode}
-% \end{environment}
-%
-% \begin{environment}{texnote}
-% Used to describe information destined to \TeX{} experts only.
-% \begin{macrocode}
-\NewDocumentEnvironment { texnote } { }
- {
- \endgraf
- \vspace{3mm}
- \small\textbf{\TeX~hackers~note:}
- }
- {
- \vspace{3mm}
- }
-% \end{macrocode}
-% \end{environment}
-%
-% \begin{environment}{arguments}
-% This environment is designed to be used within a \env{macro}
-% environment to describe the arguments of the macro/function.
-% \begin{macrocode}
-\NewDocumentEnvironment { arguments } { }
- {
- \enumerate [
- nolistsep ,
- label = \texttt{\#\arabic*} ~ : ,
- labelsep = * ,
- ]
- }
- {
- \endenumerate
- }
-% \end{macrocode}
-% \end{environment}
-%
-% \begin{macro}{\CodedocExplain, \CodedocExplainEXP, \CodedocExplainREXP, \CodedocExplainTF}
-% Explanation of stars and |TF| notations, for use in third-party
-% packages.
-% \begin{macrocode}
-\NewDocumentCommand { \CodedocExplain } { }
- { \CodedocExplainEXP \ \CodedocExplainREXP \ \CodedocExplainTF }
-\NewDocumentCommand { \CodedocExplainEXP } { }
- {
- \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{expstar}{}}%
- \write \@auxout { \def \string \Codedoc@expstar { } }
- \@@_typeset_exp:\ indicates~fully~expandable~functions,~which~
- can~be~used~within~an~\texttt{e}-type~argument~(inside~an~\tn{expanded}),~
- \texttt{x}-type~argument~(in~plain~\TeX{}~terms,~inside~an~\tn{edef}),~
- as~well~as~within~an~\texttt{f}-type~argument.
- }
-\NewDocumentCommand { \CodedocExplainREXP } { }
- {
- \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{rexpstar}{}}%
- \write \@auxout { \def \string \Codedoc@rexpstar { } }
- \@@_typeset_rexp:\ indicates~
- restricted~expandable~functions,~which~can~be~used~within~an~
- \texttt{x}-type~argument~or~an~\texttt{e}-type~argument,~
- but~cannot~be~fully~expanded~within~an~\texttt{f}-type~argument.
- }
-\NewDocumentCommand { \CodedocExplainTF } { }
- {
- \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{explTF}{}}%
- \write \@auxout { \def \string \Codedoc@explTF { } }
- \@@_typeset_TF:\ indicates~conditional~(\texttt{if})~functions~
- whose~variants~with~\texttt{T},~\texttt{F}~and~\texttt{TF}~
- argument~specifiers~expect~different~
- \enquote{true}/\enquote{false}~branches.
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Implementing text markup}
-%
-% Keys for \cs{cmd}, \cs{cs} and \cs{tn}.
-% \begin{macrocode}
-\keys_define:nn { l3doc/cmd }
- {
- index .tl_set:N = \l_@@_cmd_index_tl ,
- module .tl_set:N = \l_@@_cmd_module_tl ,
- no-index .bool_set:N = \l_@@_cmd_noindex_bool ,
- replace .bool_set:N = \l_@@_cmd_replace_bool ,
- }
-% \end{macrocode}
-%
-% \begin{macro}[do-not-index={\\,\_,\1,\c,\2}]{\@@_cmd:nn, \@@_cmd:no}
-% Apply the key--value \meta{options}~|#1| after setting some
-% default values. Then (unless |replace=false|) replace |@@| in~|#2|,
-% which is a bit tricky: the |_| must be given the catcode expected by
-% \cs{@@_replace_at_at:N}, but should be reverted to their original
-% catcode (normally active, needed for line-breaking) without
-% rescanning the whole argument. Then typeset the command in
-% \tn{verbatim@font}, after turning it to harmless characters if
-% needed (and keeping the underscore breakable); in any case, spaces
-% must be turned into \tn{@xobeysp} and we must use \tn{@} to avoid
-% longer spaces after a control sequence that ends for instance with a
-% colon (empty signature). Finally, produce an index entry.
-% Indexing is suppressed when \cs{l_@@_cmd_noindex_bool} is true.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_cmd:nn #1#2
- {
- \bool_set_false:N \l_@@_cmd_noindex_bool
- \bool_set_true:N \l_@@_cmd_replace_bool
- \tl_set:Nn \l_@@_cmd_index_tl { \q_no_value }
- \tl_set:Nn \l_@@_cmd_module_tl { \q_no_value }
- \keys_set:nn { l3doc/cmd } {#1}
- \tl_set:Nn \l_@@_cmd_tl {#2}
- \bool_if:NT \l_@@_cmd_replace_bool
- {
- \tl_set_rescan:Nnn \l_@@_tmpb_tl { } { _ }
- \tl_replace_all:NVn \l_@@_cmd_tl \l_@@_tmpb_tl { _ }
- \@@_replace_at_at:N \l_@@_cmd_tl
- \tl_replace_all:NnV \l_@@_cmd_tl { _ } \l_@@_tmpb_tl
- }
-% \end{macrocode}
-% Typesetting.
-% Note the replacement for the underscore is to permit linebreaks.
-% The \texttt{underscore} package adds the linebreak,
-% and the regex results in applying the breakable underscore only to the \emph{last}
-% of a run of underscores, and not if the underscore follows a backslash.
-% \begin{macrocode}
- \mode_if_math:T { \mbox }
- {
- \bool_if:NT \l_@@_allow_indexing_bool { \@@_target: }
- \verbatim@font
- \@@_if_almost_str:VT \l_@@_cmd_tl
- {
- \__kernel_tl_set:Nx \l_@@_cmd_tl { \tl_to_str:N \l_@@_cmd_tl }
- \bool_if:NT \g_@@_cs_break_bool
- {
- \regex_replace_all:nnN
- { ([^\\\_]\_*) \_ ([^\_]) }
- { \1 \c{BreakableUnderscore} \2 }
- \l_@@_cmd_tl
- }
- }
- \tl_replace_all:Nnn \l_@@_cmd_tl { ~ } { \@xobeysp }
- \l_@@_cmd_tl
- \@
- }
-% \end{macrocode}
-% Indexing.
-% \begin{macrocode}
- \bool_if:NT \l_@@_allow_indexing_bool
- {
- \bool_if:NF \l_@@_cmd_noindex_bool
- {
- \quark_if_no_value:NF \l_@@_cmd_index_tl
- {
- \__kernel_tl_set:Nx \l_@@_cmd_tl
- { \c_backslash_str \exp_not:o { \l_@@_cmd_index_tl } }
- }
- \exp_args:No \@@_key_get:n { \l_@@_cmd_tl }
- \quark_if_no_value:NF \l_@@_cmd_module_tl
- {
- \__kernel_tl_set:Nx \l_@@_index_module_tl
- { \tl_to_str:N \l_@@_cmd_module_tl }
- }
- \@@_special_index_module:ooonN
- { \l_@@_index_key_tl }
- { \l_@@_index_macro_tl }
- { \l_@@_index_module_tl }
- { usage }
- \l_@@_index_internal_bool
- }
- }
- }
-\cs_generate_variant:Nn \@@_cmd:nn { no }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \@@_meta:n,
-% \@@_ensuremath_sb:n,
-% \@@_meta_original:n
-% }
-% Store |#1| in \cs{l_@@_tmpa_tl} and replaces every underscore,
-% regardless of its category (\enquote{math toggle},
-% \enquote{alignment}, \enquote{superscript}, \enquote{subscript},
-% \enquote{letter}, \enquote{other}, or \enquote{active}) by
-% \cs{@@_ensuremath_sb:n} (which creates math subscripts), then runs
-% the code used for \tn{meta} in \pkg{doc.sty}.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_meta:n #1
- {
- \tl_set:Nn \l_@@_tmpa_tl {#1}
- \tl_map_inline:nn
- { { 3 } { 4 } { 7 } { 8 } { 11 } { 12 } { 13 } }
- {
- \tl_set_rescan:Nnn \l_@@_tmpb_tl
- { \char_set_catcode:nn { `_ } {##1} } { _ }
- \tl_replace_all:NVn \l_@@_tmpa_tl \l_@@_tmpb_tl
- { \@@_ensuremath_sb:n }
- }
- \exp_args:NV \@@_meta_original:n \l_@@_tmpa_tl
- }
-\cs_new_protected:Npn \@@_ensuremath_sb:n #1
- { \ensuremath { \sb {#1} } }
-\cs_new_protected:Npn \@@_meta_original:n #1
- {
- \ensuremath \langle
- \mode_if_math:T { \nfss@text }
- {
- \meta@font@select
- \edef \meta@hyphen@restore
- { \hyphenchar \the \font \the \hyphenchar \font }
- \hyphenchar \font \m@ne
- \language \l@nohyphenation
- #1 \/
- \meta@hyphen@restore
- }
- \ensuremath \rangle
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsubsection{Common between \env{macro} and \env{function}}
-%
-% \begin{macro}
-% {
-% \@@_typeset_exp:, \@@_typeset_rexp:,
-% \@@_typeset_TF:, \@@_typeset_aux:n
-% }
-% Used by \cs{@@_macro_single:nNN} and in the \env{function} environment
-% to typeset conditionals and auxiliary functions.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_typeset_exp:
- {
- \cs_if_exist:NTF \Codedoc@expstar
- { \hyperlink { expstar } }
- { \mbox }
- {$\star$}
- }
-\cs_new_protected:Npn \@@_typeset_rexp:
- {
- \cs_if_exist:NTF \Codedoc@rexpstar
- { \hyperlink { rexpstar } }
- { \mbox }
- { \ding { 73 } } % hollow star
- }
-\cs_new_protected:Npn \@@_typeset_TF:
- {
- \cs_if_exist:NTF \Codedoc@explTF
- { \hyperlink { explTF } }
- { \mbox }
- {
- \itshape TF
- \makebox[0pt][r]
- {
- \underline { \phantom{\itshape TF} \kern-0.1em }
- }
- }
- }
-\cs_new_protected:Npn \@@_typeset_aux:n #1
- {
- { \color[gray]{0.5} #1 }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {\@@_get_hyper_target:nN, \@@_get_hyper_target:oN, \@@_get_hyper_target:eN}
-% Create a \pkg{hyperref} anchor from a macro name~|#1| and stores it
-% in the token list variable~|#2|. For instance, |\prg_replicate:nn|
-% gives |doc/function//prg/replicate:nn|.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_get_hyper_target:nN #1#2
- {
- \__kernel_tl_set:Nx #2 { \tl_to_str:n {#1} }
- \tl_replace_all:NVn #2 \c_underscore_str { / }
- \tl_remove_all:NV #2 \c_backslash_str
- \tl_put_left:Nn #2 { doc/function// }
- }
-\cs_generate_variant:Nn \@@_get_hyper_target:nN { o , e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_names_get_seq:nN}
-% The argument~|#1| (argument of a |function| or |macro| environment)
-% has catcodes $10$ (space), $12$ (other) and $13$ (active). Sanitize
-% catcodes. If the |verb| option was used, output a one-item
-% sequence. Otherwise, remove any \enquote{\%} character at the
-% beginning of a line. Remove tabs and newlines. Finally, convert
-% |_@@| and |@@| to |__|\meta{module name} (if it is non-empty). At
-% this point, \cs{l_@@_tmpa_tl} contains a comma-delimited list of
-% names, where |@| and~|_| have category code letter. Turn it to a
-% string, parse it as a comma-delimited list (in particular this
-% removes spaces), and output a sequence of function/macro names.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_names_get_seq:nN #1#2
- {
- \__kernel_tl_set:Nx \l_@@_tmpa_tl { \tl_to_str:n {#1} }
- \bool_if:NTF \l_@@_names_verb_bool
- {
- \seq_clear:N #2
- \seq_put_right:NV #2 \l_@@_tmpa_tl
- }
- {
- \tl_remove_all:Ne \l_@@_tmpa_tl
- { \iow_char:N \^^M \c_percent_str }
- \tl_remove_all:Ne \l_@@_tmpa_tl { \tl_to_str:n { ^ ^ A } }
- \tl_remove_all:Ne \l_@@_tmpa_tl { \iow_char:N \^^I }
- \tl_remove_all:Ne \l_@@_tmpa_tl { \iow_char:N \^^M }
- \@@_detect_internals:N \l_@@_tmpa_tl
- \@@_replace_at_at:N \l_@@_tmpa_tl
- \exp_args:NNe \seq_set_from_clist:Nn #2
- { \tl_to_str:N \l_@@_tmpa_tl }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_names_parse:, \@@_names_parse_one:n}
-% The goal is to group variants together. We populate
-% \cs{l_@@_names_block_tl} with local sequence variable named with
-% \cs{@@_lseq_name:n} after the base forms. When encountering a new
-% base form, set the corresponding local sequence to hold the
-% \meta{base name} (stripped of the signature) and add the local
-% sequence to the list \cs{l_@@_names_block_tl}. In all cases append
-% the signature to the local sequence, which thus takes the form
-% \meta{base name}, \meta{signature_1}, \meta{signature_2} and so on.
-% If the original function had no signature (no colon) then use
-% \cs{scan_stop:} as the signature (there can be no variant). We
-% special case commands |#1| starting with |\::|, namely weird
-% functions named |\::N| and the like.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_names_parse:
- {
- \tl_clear:N \l_@@_names_block_tl
- \seq_map_function:NN
- \l_@@_names_seq
- \@@_names_parse_one:n
- }
-\cs_new_protected:Npn \@@_names_parse_one:n #1
- {
- \@@_split_function_do:nn {#1}
- { \@@_names_parse_one_aux:nnNn }
- {#1}
- }
-\cs_new_protected:Npn \@@_names_parse_one_aux:nnNn #1#2#3#4
- {
- \bool_if:NTF #3
- {
- \tl_if_head_eq_charcode:nNTF {#2} :
- { \@@_names_parse_aux:nnn {#4} {#4} { \scan_stop: } }
- {
- \exp_args:Ne \@@_names_parse_aux:nnn
- { \@@_base_form_aux:nnN {#1} {#2} #3 }
- {#1} {#2}
- }
- }
- {
- \bool_if:NT \l_@@_macro_TF_bool
- { \msg_error:nne { l3doc } { no-signature-TF } {#4} }
- \@@_names_parse_aux:nnn {#4} {#4} { \scan_stop: }
- }
- }
-\cs_new_protected:Npn \@@_names_parse_aux:nnn #1
- { \exp_args:Nc \@@_names_parse_aux:Nnn { \@@_lseq_name:n {#1} } }
-\cs_new_protected:Npn \@@_names_parse_aux:Nnn #1#2#3
- {
- \tl_if_in:NnF \l_@@_names_block_tl {#1}
- {
- \tl_put_right:Nn \l_@@_names_block_tl {#1}
- \seq_clear_new:N #1
- \seq_put_right:Nn #1 {#2}
- }
- \seq_put_right:Nn #1 {#3}
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_names_typeset:}
-% \begin{macro}{\@@_names_typeset_auxi:n}
-% This code is in particular used when typesetting function names in a
-% \env{function} environment. The mapping over \cs{l_@@_names_block_tl}
-% cannot use \cs{tl_map_inline:Nn} because the code following |\\|
-% would not be expandable, thus breaking \tn{bottomrule}.
-%
-% Call \cs{@@_names_typeset_auxi:n} on each local sequence (which
-% holds a set of variants). The first step is to pop the base form
-% and change spaces to category other so
-% that they get displayed eventually. Then store the variants in
-% \cs{g_@@_variants_seq}, remove the first, which will be displayed
-% more prominently, and reconstruct the actual name, passing it to
-% \cs{@@_names_typeset_auxii:n}.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_names_typeset:
- {
- \tl_map_function:NN \l_@@_names_block_tl
- \@@_names_typeset_auxi:n
- }
-\cs_new_protected:Npn \@@_names_typeset_auxi:n #1
- {
- \seq_pop:NN #1 \l_@@_tmpa_tl
- \tl_gset_eq:NN \g_@@_base_name_tl \l_@@_tmpa_tl
- \tl_greplace_all:NnV \g_@@_base_name_tl
- { ~ } \c_catcode_other_space_tl
- \seq_get:NN #1 \l_@@_tmpa_tl
- \str_if_eq:VnTF \l_@@_tmpa_tl { \scan_stop: }
- {
- \seq_gclear:N \g_@@_variants_seq
- \@@_names_typeset_auxii:e { \g_@@_base_name_tl }
- }
- {
- \seq_gset_eq:NN \g_@@_variants_seq #1
- \seq_gpop:NN \g_@@_variants_seq \l_@@_tmpb_tl
- \@@_names_typeset_auxii:e
- { \g_@@_base_name_tl : \l_@@_tmpb_tl }
- }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}
-% {\@@_names_typeset_auxii:n, \@@_names_typeset_auxii:e}
-% In case the option |pTF| was given, typeset predicates before the
-% |TF| functions. In case the option |noTF| was given, typeset the
-% non-|TF| function as well. Pass the relevant boolean in both cases
-% to control whether to append |TF|.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_names_typeset_auxii:n #1
- {
- \bool_if:NT \l_@@_macro_pTF_bool
- {
- \@@_names_typeset_block:eN
- { \@@_predicate_from_base:n {#1} }
- \c_false_bool
- }
- \bool_if:NT \l_@@_macro_noTF_bool
- { \@@_names_typeset_block:nN {#1} \c_false_bool }
- \@@_names_typeset_block:nN {#1} \l_@@_macro_TF_bool
- }
-\cs_generate_variant:Nn \@@_names_typeset_auxii:n { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_names_typeset_block:nN, \@@_names_typeset_block:eN}
-% Names in \env{function} and \env{macro} environments are typeset
-% differently. To distinguish the two note that
-% \cs{l_@@_nested_macro_int} is at least one when in an \env{macro}
-% environment (we assume \env{function} is not nested inside it). A
-% block is a function with all its variants.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_names_typeset_block:nN
- {
- \int_compare:nNnTF \l_@@_nested_macro_int = 0
- { \@@_typeset_function_block:nN }
- { \@@_macro_typeset_block:nN }
- }
-\cs_generate_variant:Nn \@@_names_typeset_block:nN { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[pTF]{\@@_if_macro_internal:n}
-% \begin{macro}[EXP]{\@@_if_macro_internal_aux:w}
-% Determines whether the given macro should be considered internal or
-% public. If an option such as |int| was given then the answer is
-% \cs{l_@@_macro_internal_bool}, otherwise check for whether the macro
-% name contains~|__|.
-% \begin{macrocode}
-\prg_new_conditional:Npnn \@@_if_macro_internal:n #1 { p , T , F , TF }
- {
- \bool_if:NTF \l_@@_macro_internal_bool
- { \prg_return_true: }
- {
- \tl_if_empty:eTF
- {
- \exp_after:wN \@@_if_macro_internal_aux:w
- \tl_to_str:n { #1 ~ __ }
- }
- { \prg_return_false: } { \prg_return_true: }
- }
- }
-\exp_last_unbraced:NNNNo
- \cs_new:Npn \@@_if_macro_internal_aux:w #1 { \tl_to_str:n { __ } } { }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\@@_names_block_base_map:N}
-% The \cs{l_@@_names_block_tl} contains sequence variables
-% corresponding to different base functions and their variants. For
-% each such sequence, put the first and second items in
-% \cs{l_@@_tmpa_tl} and \cs{l_@@_tmpb_tl} and build the base
-% function's name.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_names_block_base_map:N #1
- {
- \tl_map_inline:Nn \l_@@_names_block_tl
- {
- \group_begin:
- \seq_set_eq:NN \l_@@_tmpa_seq ##1
- \seq_pop:NN \l_@@_tmpa_seq \l_@@_tmpa_tl
- \seq_get:NN \l_@@_tmpa_seq \l_@@_tmpb_tl
- \exp_args:NNe
- \group_end:
- #1
- {
- \l_@@_tmpa_tl
- \str_if_eq:VnF \l_@@_tmpb_tl { \scan_stop: }
- { : \l_@@_tmpb_tl }
- \bool_if:NT \l_@@_macro_TF_bool { TF }
- }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsubsection{The \env{function} environment}
-%
-% \begin{macrocode}
-\keys_define:nn { l3doc/function }
- {
- TF .value_forbidden:n = true ,
- TF .code:n =
- {
- \bool_set_true:N \l_@@_macro_TF_bool
- } ,
- EXP .value_forbidden:n = true ,
- EXP .code:n =
- {
- \bool_set_true:N \l_@@_macro_EXP_bool
- \bool_set_false:N \l_@@_macro_rEXP_bool
- } ,
- rEXP .value_forbidden:n = true ,
- rEXP .code:n =
- {
- \bool_set_false:N \l_@@_macro_EXP_bool
- \bool_set_true:N \l_@@_macro_rEXP_bool
- } ,
- pTF .value_forbidden:n = true ,
- pTF .code:n =
- {
- \bool_set_true:N \l_@@_macro_pTF_bool
- \bool_set_true:N \l_@@_macro_TF_bool
- \bool_set_true:N \l_@@_macro_EXP_bool
- \bool_set_false:N \l_@@_macro_rEXP_bool
- } ,
- noTF .value_forbidden:n = true ,
- noTF .code:n =
- {
- \bool_set_true:N \l_@@_macro_noTF_bool
- \bool_set_true:N \l_@@_macro_TF_bool
- } ,
- added .code:n = { \@@_date_set_past:Nn \l_@@_date_added_tl {#1} },
- updated .code:n = { \@@_date_set_past:Nn \l_@@_date_updated_tl {#1} } ,
- deprecated .bool_set:N = \l_@@_macro_deprecated_bool ,
- no-user-doc .bool_set:N = \l_@@_macro_nodoc_bool ,
- tested .code:n = { } ,
- label .code:n =
- {
- \clist_set:Nn \l_@@_function_label_clist {#1}
- \bool_set_true:N \l_@@_no_label_bool
- } ,
- verb .value_forbidden:n = true ,
- verb .bool_set:N = \l_@@_names_verb_bool ,
- module .tl_set:N = \l_@@_override_module_tl ,
- }
-% \end{macrocode}
-%
-% \begin{macro}[do-not-index={\A,\Z,\d,\1,\2,\3}]
-% {\@@_date_set:Nn,\@@_date_set_past:Nn}
-% Normalize the date into the format \texttt{YYYY-MM-DD}; more
-% precisely month and day are allowed to be single digits. The
-% \cs{@@_date_set_past:Nn} function only allows dates in the past (or
-% same day).
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_date_set:Nn #1#2
- {
- \tl_set:Nn #1 {#2}
- \regex_replace_once:nnNF
- { \A(\d\d\d\d)[-/](\d\d?)[-/](\d\d?)\Z } { \1-\2-\3 } #1
- {
- \msg_error:nnn { l3doc } { date-format } {#2}
- \tl_set:Nn #1 { 1970-01-01 }
- }
- }
-\cs_new_protected:Npn \@@_date_set_past:Nn #1#2
- {
- \@@_date_set:Nn #1 {#2}
- \exp_args:No \@@_date_compare:nNnT
- {#1} > { \c_sys_year_int - \c_sys_month_int - \c_sys_day_int }
- {
- \msg_error:nnee { l3doc } { future-date }
- { \tl_to_str:N \l_@@_macro_argument_tl }
- {#1}
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_function:nnw}
-% \begin{arguments}
-% \item Key--value list.
-% \item Comma-separated list of functions; input has already been
-% sanitised by catcode changes before reading the argument.
-% \end{arguments}
-% \begin{macro}{\@@_function_end:}
-% Make sure any paragraph is finished, and similar safe practices at
-% the beginning of an environment which will typeset material.
-% Initialize some variables. Parse the key--value list. Clean up the
-% list of functions, then go through them to extract some data. After
-% this, typeset the function names in the coffin
-% \cs{l_@@_functions_coffin} and measure it to know if it fits in the
-% margin. Finally, start a vertical coffin for the main part of the
-% environment. This coffin stops when the environment ends, then all
-% the pieces are assembled into a single coffin, which is typeset.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function:nnw #1#2
- {
- \@@_function_typeset_start:
- \@@_function_init:
- \tl_set:Nn \l_@@_macro_argument_tl {#2}
- \keys_set:nn { l3doc/function } {#1}
- \@@_names_get_seq:nN {#2} \l_@@_names_seq
- \@@_names_parse:
- \@@_function_typeset:
- \@@_function_reset:
- \@@_function_descr_start:w
- }
-\cs_new_protected:Npn \@@_function_end:
- {
- \@@_function_descr_stop:
- \@@_function_assemble:
- \@@_function_typeset_stop:
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}
-% {\@@_function_typeset_start:, \@@_function_typeset_stop:}
-% At the start of the \env{function} environment, before performing
-% any assignment, close the last paragraph, and set up the typesetting
-% scene. Further code typesets a coffin, so we end the paragraph and
-% allow a page break.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function_typeset_start:
- {
- \par \bigskip \noindent
- }
-\cs_new_protected:Npn \@@_function_typeset_stop:
- {
- \par
- \dim_set:Nn \prevdepth { \box_dp:N \l_@@_descr_coffin }
- \allowbreak
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_function_init:}
-% Complain if \texttt{function} environments are nested. Clear
-% various variables.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function_init:
- {
- \box_if_empty:NF \g_@@_syntax_box
- { \msg_error:nn { l3doc } { syntax-nested-function } }
- \coffin_clear:N \l_@@_descr_coffin
- \box_gclear:N \g_@@_syntax_box
- \coffin_clear:N \l_@@_syntax_coffin
- \coffin_clear:N \l_@@_functions_coffin
- \bool_set_false:N \l_@@_macro_TF_bool
- \bool_set_false:N \l_@@_macro_pTF_bool
- \bool_set_false:N \l_@@_macro_noTF_bool
- \bool_set_false:N \l_@@_macro_EXP_bool
- \bool_set_false:N \l_@@_macro_rEXP_bool
- \bool_set_false:N \l_@@_no_label_bool
- \bool_set_false:N \l_@@_names_verb_bool
- \bool_set_true:N \l_@@_in_function_bool
- \clist_clear:N \l_@@_function_label_clist
- \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
- \char_set_active_eq:NN \< \@@_shorthand_meta:
- \char_set_catcode_active:N \<
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_shorthand_meta:, \@@_shorthand_meta:w}
-% Allow |<...>| to be used as markup for |\meta{...}|.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_shorthand_meta:
- { \mode_if_math:TF { < } { \@@_shorthand_meta:w } }
-\cs_new_protected_nopar:Npn \@@_shorthand_meta:w #1 > { \meta {#1} }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_function_reset:}
-% Clear some variables.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function_reset:
- {
- \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_function_typeset:}
-% Typeset in the coffin \cs{l_@@_functions_coffin} the functions listed in
-% \cs{l_@@_names_block_tl} and the relevant dates, then set
-% \cs{l_@@_long_name_bool} to be \texttt{true} if this coffin is
-% larger than the available width in the margin. The function
-% \cs{@@_typeset_functions:} is quite involved hence given later.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function_typeset:
- {
- \dim_zero:N \l_@@_trial_width_dim
- \hcoffin_set:Nn \l_@@_functions_coffin { \@@_typeset_functions: }
- \dim_set:Nn \l_@@_trial_width_dim
- { \box_wd:N \l_@@_functions_coffin }
- \bool_set:Nn \l_@@_long_name_bool
- { \dim_compare_p:nNn \l_@@_trial_width_dim > \marginparwidth }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {\@@_function_descr_start:w, \@@_function_descr_stop:}
-% The last step in \cs{@@_function:nnw} (the beginning of a
-% \env{function} environment) is to open a coffin which will capture
-% the description of the function, namely the body of the
-% \env{function} environment. This is closed by \cs{@@_function_end:}
-% (the end of a \env{function} environment).
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function_descr_start:w
- {
- \vcoffin_set:Nnw \l_@@_descr_coffin { \textwidth }
- \noindent \ignorespaces
- }
-\cs_new_protected:Npn \@@_function_descr_stop:
- { \vcoffin_set_end: }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_function_assemble:}
-% The box \cs{g_@@_syntax_box} contains the contents of the syntax
-% environment if it was used. Now that we have all the pieces, join
-% together the syntax coffin, the names coffin, and the description
-% coffin. The relative positions depend on whether the names coffin
-% fits in the margin. Then typeset the combination.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function_assemble:
- {
- \hcoffin_set:Nn \l_@@_syntax_coffin
- { \box_use_drop:N \g_@@_syntax_box }
- \bool_if:NTF \l_@@_long_name_bool
- {
- \coffin_join:NnnNnnnn
- \l_@@_output_coffin {hc} {vc}
- \l_@@_syntax_coffin {l} {T}
- {0pt} {0pt}
- \coffin_join:NnnNnnnn
- \l_@@_output_coffin {l} {t}
- \l_@@_functions_coffin {r} {t}
- {-\marginparsep} {0pt}
- \coffin_join:NnnNnnnn
- \l_@@_output_coffin {l} {b}
- \l_@@_descr_coffin {l} {t}
- {0.75\marginparwidth + \marginparsep} {-\medskipamount}
- \coffin_typeset:Nnnnn \l_@@_output_coffin
- {\l_@@_descr_coffin-l} {\l_@@_descr_coffin-t}
- {0pt} {0pt}
- }
- {
- \coffin_join:NnnNnnnn
- \l_@@_output_coffin {hc} {vc}
- \l_@@_syntax_coffin {l} {t}
- {0pt} {0pt}
- \coffin_join:NnnNnnnn
- \l_@@_output_coffin {l} {b}
- \l_@@_descr_coffin {l} {t}
- {0pt} {-\medskipamount}
- \coffin_join:NnnNnnnn
- \l_@@_output_coffin {l} {t}
- \l_@@_functions_coffin {r} {t}
- {-\marginparsep} {0pt}
- \coffin_typeset:Nnnnn \l_@@_output_coffin
- {\l_@@_syntax_coffin-l} {\l_@@_syntax_coffin-T}
- {0pt} {0pt}
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_typeset_functions:}
-% This function builds the \cs{l_@@_functions_coffin} by typesetting the
-% function names (with variants) and the relevant dates in a
-% \env{tabular} environment. The use of rules \tn{toprule},
-% \tn{midrule} and \tn{bottomrule} requires whatever lies between the
-% last |\\| and the rule to be expandable, making our lives a bit
-% complicated.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_typeset_functions:
- {
- \small\ttfamily
- \@@_target:
- \Hy@MakeCurrentHref { HD. \int_use:N \c@HD@hypercount }
- \begin{tabular} [t] { @{} l @{} >{\hspace{\tabcolsep}} r @{} }
- \toprule
- \@@_function_extra_labels:
- \@@_names_typeset:
- \@@_typeset_dates:
- \bottomrule
- \end{tabular}
- \normalfont\normalsize
- }
-% \end{macrocode}
-% \end{macro}
-%
-% ^^A TODO: collect all index targets from a given function environment in a box and stick it at the top.
-% \begin{macro}
-% {\@@_typeset_function_block:nN, \@@_typeset_function_block:eN}
-% \begin{macro}{\@@_function_index:n, \@@_function_index:e}
-% |#1| is a csname, |#2| a boolean indicating whether to add |TF| or not.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_typeset_function_block:nN #1#2
- {
- \@@_function_index:e
- { #1 \bool_if:NT #2 { \tl_to_str:n {TF} } }
- \@@_function_label:eN {#1} #2
- #1
- \bool_if:NT #2 { \@@_typeset_TF: }
- \@@_typeset_expandability:
- \seq_if_empty:NF \g_@@_variants_seq
- { \@@_typeset_variant_list:nN {#1} #2 }
- \\
- }
-\cs_generate_variant:Nn \@@_typeset_function_block:nN { e }
-\cs_new_protected:Npn \@@_function_index:n #1
- {
- \seq_gput_right:Nn \g_doc_functions_seq {#1}
- \@@_special_index:nn {#1} { usage }
- }
-\cs_generate_variant:Nn \@@_function_index:n { e }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_typeset_expandability:
- {
- &
- \bool_if:NT \l_@@_macro_EXP_bool { \@@_typeset_exp: }
- \bool_if:NT \l_@@_macro_rEXP_bool { \@@_typeset_rexp: }
- }
-% \end{macrocode}
-%
-% |#1| is the function, |#2| whether to add |TF|.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_typeset_variant_list:nN #1#2
- {
- \\
- \@@_typeset_aux:n { \@@_get_function_name:n {#1} }
- :
- \int_compare:nTF { \seq_count:N \g_@@_variants_seq == 1 }
- {
- \seq_use:Nn \g_@@_variants_seq { }
- \bool_if:NT #2 { \@@_typeset_TF: }
- }
- {
- \hbox_set:Nn \l_tmpa_box
- { \seq_use:Nn \g__@@_variants_seq { \textrm| \nolinebreak[2] } }
- \textrm(
-% \end{macrocode}
-%
-% Set long variant lists in a parbox, short lists set natural length.
-% \begin{macrocode}
- \dim_compare:nNnTF { \box_wd:N \l_tmpa_box } > { .4\columnwidth }
- {
- \parbox[t]{.4\columnwidth}
- {
- \raggedright
- \hbox_unpack_drop:N \l_tmpa_box
- \textrm)
- \bool_if:NT #2 { \@@_typeset_TF: }
- }
- }
- {
- \hbox_unpack_drop:N \l_tmpa_box
- \textrm)
- \bool_if:NT #2 { \@@_typeset_TF: }
- }
- }
- \@@_typeset_expandability:
- }
-% \end{macrocode}
-%
-% |#1| is the function name, |#2| whether to add |TF|.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_function_extra_labels:
- {
- \bool_if:NT \l_@@_no_label_bool
- {
- \clist_map_inline:Nn \l_@@_function_label_clist
- {
- \@@_get_hyper_target:oN { \token_to_str:N ##1 }
- \l_@@_tmpa_tl
- \exp_args:No \label { \l_@@_tmpa_tl }
- }
- }
- }
-\cs_new_protected:Npn \@@_function_label:nN #1#2
- {
- \bool_if:NF \l_@@_no_label_bool
- {
- \@@_get_hyper_target:eN
- {
- \exp_not:n {#1}
- \bool_if:NT #2 { \tl_to_str:n {TF} }
- }
- \l_@@_tmpa_tl
- \exp_args:No \label { \l_@@_tmpa_tl }
- }
- }
-\cs_generate_variant:Nn \@@_function_label:nN { e }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\@@_typeset_dates:}
-% To display metadata for when functions are added/modified.
-% This function must be expandable since it produces rules for use in
-% alignments.
-% \begin{macrocode}
-\cs_new:Npn \@@_typeset_dates:
- {
- \bool_lazy_and:nnF
- { \tl_if_empty_p:N \l_@@_date_added_tl }
- { \tl_if_empty_p:N \l_@@_date_updated_tl }
- { \midrule }
- \tl_if_empty:NF \l_@@_date_added_tl
- {
- \multicolumn { 2 } { @{} r @{} }
- { \scriptsize New: \, \l_@@_date_added_tl } \\
- }
-
- \tl_if_empty:NF \l_@@_date_updated_tl
- {
- \multicolumn { 2 } { @{} r @{} }
- { \scriptsize Updated: \, \l_@@_date_updated_tl } \\
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_syntax:w, \@@_syntax_end:}
-% Implement the \env{syntax} environment.
-% \begin{macrocode}
-\dim_new:N \l_@@_syntax_dim
-\cs_new_protected:Npn \@@_syntax:w
- {
- \box_if_empty:NF \g_@@_syntax_box
- { \msg_error:nn { l3doc } { multiple-syntax } }
- \dim_set:Nn \l_@@_syntax_dim
- {
- \textwidth
- \bool_if:NT \l_@@_long_name_bool
- { + 0.75 \marginparwidth - \l_@@_trial_width_dim }
- }
- \hbox_gset:Nw \g_@@_syntax_box
- \small \ttfamily
- \arrayrulecolor{white}
- \begin{tabular} { @{} l @{} }
- \toprule
- \begin{minipage}[t]{\l_@@_syntax_dim}
- \raggedright
- \obeyspaces
- \obeylines
- }
-\cs_new_protected:Npn \@@_syntax_end:
- {
- \end{minipage}
- \end{tabular}
- \arrayrulecolor{black}
- \hbox_gset_end:
- \bool_if:NF \l_@@_in_function_bool
- {
- \begin{quote}
- \mode_leave_vertical:
- \box_use_drop:N \g_@@_syntax_box
- \end{quote}
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsubsection{The \env{macro} environment}
-%
-% Keyval for the \env{macro} environment.
-% TODO: provide document command for documenting keys.
-% \begin{macrocode}
-\keys_define:nn { l3doc/macro }
- {
- aux .value_forbidden:n = true ,
- aux .code:n =
- {
- \msg_warning:nnnn { l3doc } { deprecated-option }
- { aux } { function/macro }
- } ,
- deprecated .bool_set:N = \l_@@_macro_deprecated_bool ,
- internal .value_forbidden:n = true ,
- internal .code:n =
- { \bool_set_true:N \l_@@_macro_internal_bool } ,
- int .value_forbidden:n = true ,
- int .code:n =
- { \bool_set_true:N \l_@@_macro_internal_bool } ,
- no-user-doc .bool_set:N = \l_@@_macro_nodoc_bool ,
- var .value_forbidden:n = true ,
- var .code:n =
- { \bool_set_true:N \l_@@_macro_var_bool } ,
- TF .value_forbidden:n = true ,
- TF .code:n =
- { \bool_set_true:N \l_@@_macro_TF_bool } ,
- pTF .value_forbidden:n = true ,
- pTF .code:n =
- {
- \bool_set_true:N \l_@@_macro_TF_bool
- \bool_set_true:N \l_@@_macro_pTF_bool
- \bool_set_true:N \l_@@_macro_EXP_bool
- \bool_set_false:N \l_@@_macro_rEXP_bool
- } ,
- noTF .value_forbidden:n = true ,
- noTF .code:n =
- {
- \bool_set_true:N \l_@@_macro_TF_bool
- \bool_set_true:N \l_@@_macro_noTF_bool
- } ,
- EXP .value_forbidden:n = true ,
- EXP .code:n =
- {
- \bool_set_true:N \l_@@_macro_EXP_bool
- \bool_set_false:N \l_@@_macro_rEXP_bool
- } ,
- rEXP .value_forbidden:n = true ,
- rEXP .code:n =
- {
- \bool_set_false:N \l_@@_macro_EXP_bool
- \bool_set_true:N \l_@@_macro_rEXP_bool
- } ,
- tested .code:n =
- {
- \bool_set_true:N \l_@@_macro_tested_bool
- } ,
- added .code:n = {} , % TODO
- updated .code:n = {} , % TODO
- verb .bool_set:N = \l_@@_names_verb_bool ,
- module .tl_set:N = \l_@@_override_module_tl ,
- documented-as .tl_set:N = \l_@@_macro_documented_tl ,
- do-not-index .value_required:n = true ,
- do-not-index .tl_set:N = \l_@@_macro_do_not_index_tl ,
- % do-not-index .default:n = \q_no_value ,
- }
-% \end{macrocode}
-%
-% \begin{macro}{\@@_macro:nnw}
-% The arguments are a key--value list of \meta{options} and a
-% comma-list of \meta{names}, read verbatim by \pkg{ltcmd}. First
-% initialize some variables before applying the \meta{options}, then
-% parse the \meta{names} to get a sequence of macro names, then apply
-% \cs{@@_macro_single:nNN} to each (this step is more subtle than
-% \cs{seq_map_function:NN} because of |TF|/|pTF|/|noTF|). Finally typeset
-% the macro names in the margin.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro:nnw #1#2
- {
- \@@_macro_init:
- \tl_set:Nn \l_@@_macro_argument_tl {#2}
- \keys_set:nn { l3doc/macro } {#1}
- \@@_names_get_seq:nN {#2} \l_@@_names_seq
- \@@_names_parse:
- \@@_macro_exclude_index:
- \@@_macro_save_names:
- \@@_names_typeset:
- \@@_macro_dump:
- \@@_macro_reset:
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_init:}
-% The booleans hold various key--value options,
-% \cs{l_@@_nested_macro_int} counts the number of \env{macro}
-% environments around the current point (is $0$ outside).
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_init:
- {
- \int_incr:N \l_@@_nested_macro_int
- \bool_set_false:N \l_@@_macro_deprecated_bool
- \bool_set_false:N \l_@@_macro_internal_bool
- \bool_set_false:N \l_@@_macro_TF_bool
- \bool_set_false:N \l_@@_macro_pTF_bool
- \bool_set_false:N \l_@@_macro_noTF_bool
- \bool_set_false:N \l_@@_macro_EXP_bool
- \bool_set_false:N \l_@@_macro_rEXP_bool
- \bool_set_false:N \l_@@_macro_var_bool
- \bool_set_false:N \l_@@_macro_tested_bool
- \bool_set_false:N \l_@@_names_verb_bool
- \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
- \tl_clear:N \l_@@_macro_documented_tl
- \cs_set_eq:NN \testfile \@@_print_testfile:n
- \box_clear:N \l_@@_macro_index_box
- \vbox_set:Nn \l_@@_macro_box
- {
- \hbox:n
- {
- \strut
- \int_compare:nNnT \l_@@_macro_int = 0 { \@@_target: }
- }
- \vskip \int_eval:n { \l_@@_macro_int - 1 } \baselineskip
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_reset:}
-% We ensure that \cs{cs} commands nested inside a macro whose module
-% is imposed are not affected.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_reset:
- {
- \tl_set:Nn \l_@@_override_module_tl { \q_no_value }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_save_names:}
-% \begin{macro}[EXP]{\@@_macro_save_names_aux:w}
-% The list of names defined in a set of \env{macro} environments is
-% eventually used to display on which page they are documented. If
-% the |documented-as| key is given, use that, otherwise find names in
-% \cs{l_@@_names_block_tl}. The |documented-as| needs to be detokenized
-% without adding a space, so it has to be treated in a slightly awkward
-% way.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_save_names:
- {
- \tl_if_empty:NTF \l_@@_macro_documented_tl
- { \@@_names_block_base_map:N \@@_macro_save_names_aux:n }
- {
- \seq_gput_right:Ne \g_@@_nested_names_seq
- {
- \exp_after:wN \@@_macro_save_names_aux:w
- \l_@@_macro_documented_tl \q_@@_stop
- }
- }
- }
-\cs_new:Npn \@@_macro_save_names_aux:w #1#2 \q_@@_stop
- { \token_to_str:N #1 \tl_to_str:n {#2} }
-\cs_new_protected:Npn \@@_macro_save_names_aux:n #1
- { \seq_gput_right:Nn \g_@@_nested_names_seq {#1} }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_exclude_index:}
-% Some control sequences in a \env{macrocode} environment shouldn't
-% be indexed, for different reasons. This macro parses the argument
-% of the |do-not-index| option and locally removes the given macros
-% from the index.
-%
-% The optional argument to \env{macro} is not scanned with verbatim
-% catcodes, so we use \cs{tl_set_rescan:NnV} to rescan the commands
-% with the same catcodes as \cs{DoNotIndex}. The scanned token list
-% contains spaces after control sequences, which are not there when
-% \cs{DoNotIndex} is used. Since \cs{seq_set_from_clist:Nn} removes
-% spaces around the items, we can abuse that and \cs{seq_use:Nn} to
-% normalise each item. After that \cs{DoNotIndex} can do its thing.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_exclude_index:
- {
- \tl_if_empty:NF \l_@@_macro_do_not_index_tl
- {
- \tl_set_rescan:NnV \l_@@_macro_do_not_index_tl
- { \MakePrivateLetters \catcode`\\12 }
- \l_@@_macro_do_not_index_tl
- \exp_args:NNV \seq_set_from_clist:Nn
- \l_@@_tmpa_seq \l_@@_macro_do_not_index_tl
- \__kernel_tl_set:Nx \l_@@_macro_do_not_index_tl
- { \seq_use:Nn \l_@@_tmpa_seq { , } }
- \exp_args:NV \DoNotIndex \l_@@_macro_do_not_index_tl
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_dump:}
-% This calls |\makelabel{}|
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_dump:
- {
- \topsep\MacroTopsep
- \trivlist
- \cs_set:Npn \makelabel ##1
- {
- \llap
- {
- \hbox_unpack_drop:N \l_@@_macro_index_box
- \vtop to \baselineskip
- {
- \vbox_unpack_drop:N \l_@@_macro_box
- \vss
- }
- }
- }
- \item [ ]
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_typeset_block:nN}
-% Used to typeset a macro and its variants. |#1| is the macro name,
-% |#2| is a boolean controlling whether to add |TF|.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_typeset_block:nN #1#2
- {
- \@@_macro_single:nNN {#1} \c_true_bool #2
- \seq_if_empty:NF \g_@@_variants_seq
- {
- \@@_macro_typeset_variant_list:eN
- { \@@_get_function_name:n {#1} } #2
- }
- }
-\cs_new_protected:Npn \@@_macro_typeset_variant_list:nN #1#2
- {
- \seq_map_inline:Nn \g_@@_variants_seq
- { \@@_macro_single:nNN { #1 : ##1 } \c_false_bool #2 }
- }
-\cs_generate_variant:Nn \@@_macro_typeset_variant_list:nN { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_single:nNN}
-% The arguments are |#1| a macro name (without |TF|), |#2| a boolean
-% determining whether or not to index, and |#3| whether or not to add |TF|.
-% Let's start to mess around with \cls{doc}'s \env{macro} environment.
-% See \file{doc.dtx} for a full explanation of the original
-% environment. It's rather \emph{enthusiastically} commented.
-% \begin{arguments}
-% \item Macro/function/whatever name; input has already been
-% sanitised.
-% \end{arguments}
-% The assignments to \cs{saved@macroname} and \cs{saved@indexname}
-% are used by \pkg{doc}'s \cs{changes} mechanism.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_single:nNN #1#2#3
- {
- \tl_set:Nn \saved@macroname {#1}
- \@@_macro_typeset_one:nN {#1} #3
- \bool_if:NT #3 { \DoNotIndex {#1} }
- \exp_args:Ne \@@_macro_index:nN
- { #1 \bool_if:NT #3 { \tl_to_str:n { TF } } }
- #2
- }
-\cs_new_protected:Npn \@@_macro_index:nN #1#2
- {
- \DoNotIndex {#1}
- \bool_if:NT #2
- {
- \bool_lazy_any:nF
- {
- { \@@_if_macro_internal_p:n {#1} }
- { \l_@@_macro_deprecated_bool }
- { \l_@@_macro_nodoc_bool }
- }
- { \seq_gput_right:Nn \g_doc_macros_seq {#1} }
- \hbox_set:Nw \l_@@_macro_index_box
- \hbox_unpack_drop:N \l_@@_macro_index_box
- \int_gincr:N \c@CodelineNo
- \@@_special_index:nn {#1} { main }
- \int_gdecr:N \c@CodelineNo
- \exp_args:NNNo \hbox_set_end:
- \tl_set:Nn \saved@indexname { \l_@@_index_key_tl }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_typeset_one:nN}
-% For a long time, \cls{l3doc} collected the macro names as labels in
-% the first items of nested \tn{trivlist}, but these were not closed
-% properly with \tn{endtrivlist}. Also, it interacted in surprising
-% ways with \pkg{hyperref} targets. Now, we collect typeset macro
-% names by hand in the box \cs{l_@@_macro_box}. The fixed-size space
-% |\MacroFont\ | could be replaced by an customizable horizontal
-% space; it is important for it to be the same for all macros.
-% |#1| is the macro name, |#2| whether to add |TF|.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_typeset_one:nN #1#2
- {
- \vbox_set:Nn \l_@@_macro_box
- {
- \vbox_unpack_drop:N \l_@@_macro_box
- \hbox { \llap { \@@_print_macroname:nN {#1} #2
- \MacroFont \
- } }
- }
- \int_incr:N \l_@@_macro_int
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_print_macroname:nN}
-% In the name, spaces are replaced by other spaces to ensure they get
-% displayed in case there are any.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_print_macroname:nN #1#2
- {
- \strut
- \@@_get_hyper_target:eN
- {
- \exp_not:n {#1}
- \bool_if:NT #2 { \tl_to_str:n {TF} }
- }
- \l_@@_tmpa_tl
- \cs_if_exist:cTF { r@ \l_@@_tmpa_tl }
- { \exp_last_unbraced:NNo \hyperref [ \l_@@_tmpa_tl ] }
- { \use:n }
- {
- \int_compare:nTF { \str_count:n {#1} <= 28 }
- { \MacroFont } { \MacroLongFont }
- \tl_set:Nn \l_@@_tmpa_tl {#1}
- \tl_replace_all:NnV \l_@@_tmpa_tl
- { ~ } \c_catcode_other_space_tl
- \@@_print_macroname_aux:on
- \l_@@_tmpa_tl { \bool_if:NT #2 { \@@_typeset_TF: } }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_print_macroname_aux:nn}
-% |#1| is prefix, |#2| is optional |TF| suffix.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_print_macroname_aux:nn #1#2
- {
- \@@_if_macro_internal:nTF {#1}
- { \@@_typeset_aux:n { #1 #2 } } { #1 #2 }
- }
-\cs_generate_variant:Nn \@@_print_macroname_aux:nn { o }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\MacroLongFont}
-% \begin{macrocode}
-\providecommand \MacroLongFont
- {
- \fontfamily{lmtt}\fontseries{lc}\small
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_print_testfile:n, \@@_print_testfile_aux:n}
-% Used to show that a macro has a test, somewhere.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_print_testfile:n #1
- {
- \bool_set_true:N \l_@@_macro_tested_bool
- \tl_if_eq:nnF {#1} {*}
- {
- \seq_if_in:NnF \g_@@_testfiles_seq {#1}
- {
- \seq_gput_right:Nn \g_@@_testfiles_seq {#1}
- \par
- \@@_print_testfile_aux:n {#1}
- }
- }
- }
-\cs_new_protected:Npn \@@_print_testfile_aux:n #1
- {
- \footnotesize
- (
- \textit
- {
- The~ test~ suite~ for~ this~ command,~
- and~ others~ in~ this~ file,~ is~ \textsf{#1}
- }.
- )\par
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\TestFiles}
-% \begin{macrocode}
-\DeclareDocumentCommand \TestFiles {m}
- {
- \par
- \textit
- {
- The~ following~ test~ files~ are~
- used~ for~ this~ code:~ \textsf{#1}.
- }
- \par \ignorespaces
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\UnitTested}
-% \begin{macrocode}
-\DeclareDocumentCommand \UnitTested { } { \testfile* }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\TestMissing}
-% \begin{macrocode}
-\DeclareDocumentCommand \TestMissing { m }
- { \@@_test_missing:n {#1} }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_test_missing:n}
-% Keys in \cs{g_@@_missing_tests_prop} are lists of macros given as
-% arguments of one \env{macro} environment. Values are pairs of a
-% file name and a comment about the missing tests.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_test_missing:n #1
- {
- \@@_test_missing_aux:Nen
- \g_@@_missing_tests_prop
- { \seq_use:Nn \l_@@_names_seq { , } }
- { { \g_file_curr_name_str \c_space_tl (#1) } }
- }
-\cs_new_protected:Npn \@@_test_missing_aux:Nnn #1#2#3
- {
- \prop_get:NnNTF #1 {#2} \l_@@_tmpa_tl
- { \tl_put_right:Nn \l_@@_tmpa_tl { , #3 } }
- { \tl_set:Nn \l_@@_tmpa_tl {#3} }
- \prop_put:Nno #1 {#2} \l_@@_tmpa_tl
- }
-\cs_generate_variant:Nn \@@_test_missing_aux:Nnn { Ne }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_end:}
-% It is too late for anyone to declare a test file for this macro, so
-% we can check now whether the macro is tested. If the \env{macro}
-% environment which is being ended is the outermost one, then wrap
-% each macro in \tn{texttt} (with the addition of |TF| if relevant)
-% and typeset two informations: that this ends the definition of some
-% macros, and that they are documented on some page.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_end:
- {
- \endtrivlist
- \@@_macro_end_check_tested:
- \int_compare:nNnT \l_@@_nested_macro_int = 1
- { \@@_macro_end_style:n { \@@_print_end_definition: } }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_end_check_tested:}
-% If the |checktest| option was issued and the macro is not an
-% auxiliary nor a variable (and it does not have a test), then add it
-% to the sequence of non-tested macros.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_end_check_tested:
- {
- \bool_lazy_all:nT
- {
- { \g_@@_checktest_bool }
- { ! \l_@@_macro_var_bool }
- { ! \l_@@_macro_tested_bool }
- }
- {
- \seq_set_filter:NNn \l_@@_tmpa_seq \l_@@_names_seq
- { ! \@@_if_macro_internal_p:n {##1} }
- \seq_gput_right:Ne \g_@@_not_tested_seq
- {
- \seq_use:Nn \l_@@_tmpa_seq { , }
- \bool_if:NTF \l_@@_macro_pTF_bool {~(pTF)}
- { \bool_if:NT \l_@@_macro_TF_bool {~(TF)} }
- }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_macro_end_style:n}
-% Style for the extra information at the end of a top-level
-% \env{macro} environment.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_end_style:n #1
- {
- \nobreak \noindent
- { \footnotesize ( \emph{#1} ) \par }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \@@_print_end_definition:,
-% \@@_macro_end_wrap_item:n,
-% \@@_print_documented:
-% }
-% Surround each item by \tn{texttt}, replacing |_|
-% by \tn{_} as well. Then list the
-% macro names through \cs{seq_use:Nnnn}, unless there are too many.
-% Finally, if the macro is neither auxiliary nor internal, add a link
-% to where it is documented.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_end_wrap_item:n #1
- {
- \tl_set:Nn \l_@@_tmpa_tl {#1}
- \tl_replace_all:NVn \l_@@_tmpa_tl
- \c_underscore_str { \_ }
- \texttt { \l_@@_tmpa_tl }
- }
-\cs_new_protected:Npn \@@_print_end_definition:
- {
- \seq_set_map:NNn \l_@@_tmpa_seq
- \g_@@_nested_names_seq
- { \@@_macro_end_wrap_item:n {##1} }
- End~ of~ definition~ for~
- \int_compare:nTF { \seq_count:N \l_@@_tmpa_seq <= 3 }
- {
- \seq_use:Nnnn \l_@@_tmpa_seq
- { \,~and~ } { \,,~ } { \,,~and~ }
- }
- { \seq_item:Nn \l_@@_tmpa_seq {1}\,~and~others }
- \@.
- \@@_print_documented:
- }
-\cs_new_protected:Npn \@@_print_documented:
- {
- \seq_gset_filter:NNn \g_@@_nested_names_seq
- \g_@@_nested_names_seq
- {
- ! \bool_lazy_any_p:n
- {
- { \@@_if_macro_internal_p:n {##1} }
- { \l_@@_macro_deprecated_bool }
- { \l_@@_macro_nodoc_bool }
- }
- }
- \seq_if_empty:NF \g_@@_nested_names_seq
- {
- \int_set:Nn \l_@@_tmpa_int
- { \seq_count:N \g_@@_nested_names_seq }
- \int_compare:nNnTF \l_@@_tmpa_int = 1 {~This~} {~These~}
- \bool_if:NTF \l_@@_macro_var_bool {variable} {function}
- \int_compare:nNnTF \l_@@_tmpa_int = 1 {~is~} {s~are~}
- documented~on~page~
- \@@_get_hyper_target:eN
- { \seq_item:Nn \g_@@_nested_names_seq { 1 } }
- \l_@@_tmpa_tl
- \exp_args:Ne \pageref { \l_@@_tmpa_tl } .
- }
- \seq_gclear:N \g_@@_nested_names_seq
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsubsection{Misc}
-%
-% \begin{macro}{\DescribeOption}
-% For describing package options: retained for consistency, but updated for
-% \pkg{doc}~v3.
-% \begin{macrocode}
-\NewDocElement[idxtype = option, idxgroup = options]{Option}{optionenv}
-% \end{macrocode}
-% \end{macro}
-%
-% Here are some definitions for additional markup that helps to
-% structure your documentation.
-%
-% \begin{environment}{danger}
-% \begin{environment}{ddanger}
-% \begin{syntax}
-% |\begin{[d]danger}|\\
-% dangerous code\\
-% |\end{[d]danger}|
-% \end{syntax}
-% \begin{danger}
-% Provides a danger bend, as known from the \TeX{}book.
-% \end{danger}
-% The actual character from the font |manfnt|:
-% \begin{macrocode}
-\font \manual = manfnt \scan_stop:
-\cs_gset:Npn \dbend { {\manual\char127} }
-% \end{macrocode}
-%
-% Defines the single danger bend. Use it whenever there is a feature in
-% your package that might be tricky to use. FIXME: Has to be fixed when
-% in combination with a macro-definition.
-% \begin{macrocode}
-\newenvironment {danger}
- {
- \begin{trivlist}\item[]\noindent
- \begingroup\hangindent=2pc\hangafter=-2
- \cs_set:Npn \par{\endgraf\endgroup}
- \hbox to0pt{\hskip-\hangindent\dbend\hfill}\ignorespaces
- }
- {
- \par\end{trivlist}
- }
-% \end{macrocode}
-%
-% \begin{ddanger}
-% Use the double danger bend if there is something which could cause
-% serious problems when used in a wrong way. Better the normal user
-% does not know about such things.
-% \end{ddanger}
-% \begin{macrocode}
-\newenvironment {ddanger}
- {
- \begin{trivlist}\item[]\noindent
- \begingroup\hangindent=3.5pc\hangafter=-2
- \cs_set:Npn \par{\endgraf\endgroup}
- \hbox to0pt{\hskip-\hangindent\dbend\kern2pt\dbend\hfill}\ignorespaces
- }{
- \par\end{trivlist}
- }
-% \end{macrocode}
-% \end{environment}
-% \end{environment}
-%
-% \subsubsection{NB and NOTE}
-%
-% These macros are intended for additional notes added to the source that are not typeset.
-%
-% \begin{macro}{\NB}
-% \NB{wspr}{this is what I think about this!}
-% \begin{verbatim}
-% \NB{wspr}{this is what I think about this!}
-% \end{verbatim}
-% \begin{macrocode}
-\bool_if:NTF \g_@@_show_notes_bool
- {
- \NewDocumentCommand\NB{mm}
- {
- (\emph{Note}\footnote{\ttfamily [#1]:~\detokenize{#2}})
- }
- }
- {
- \NewDocumentCommand\NB{mm}{}
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{environment}{NOTE}
-% \begin{NOTE}{wspr}
-% this is what I #$%& think about this!
-% \end{NOTE}
-% \begin{verbatim}
-% \begin{NOTE}{wspr}
-% this is what I #$%& think about this!
-% \end{NOTE}
-% \end{verbatim}
-% \begin{macrocode}
-\bool_if:NTF \g_@@_show_notes_bool
- {
- \NewDocumentEnvironment{NOTE}{m}
- {
- \par\noindent (\emph{Note}~[\texttt{#1}]:\par
- \verbatim
- }
- {
- \endverbatim
- \par\noindent \emph{Note~end})\par
- }
- }
- {
- \NewDocumentEnvironment{NOTE}{m}{\comment}{\endcomment}
- }
-% \end{macrocode}
-% \end{environment}
-%
-% \subsection{Footnote support}
-% The environments \env{function} and \env{variable} are boxes
-% and so looses footnotes. The following implements support.
-% It relies currently on an internal from hyperref to get the correct targets.
-%
-% \begin{macrocode}
-\providecommand\Hy@footnote@currentHref{}
-\prop_new:N\g_@@_fnmark_prop
-\cs_new_protected:Npn \@@_fn_store:
- {
- \prop_gput:Nee\g_@@_fnmark_prop
- {fn\int_use:N\c@footnote}{{\Hy@footnote@currentHref}{\int_use:N\c@footnote}}
- }
-\cs_new_protected:Npn \@@_fn_restore:n #1
- {
- \prop_get:NnN \g_@@_fnmark_prop {fn#1}\l_@@_tmpa_tl
- \tl_gset:Ne\Hy@footnote@currentHref
- {\exp_last_unbraced:NV\use_i:nn \l_@@_tmpa_tl }
- \setcounter{footnote}{\exp_last_unbraced:NV\use_ii:nn \l_@@_tmpa_tl}
- }
-
-\cs_generate_variant:Nn \hook_gput_next_code:nn {ne}
-\cs_new_protected:Npn \@@_fn_footnote:nn #1 #2
- {
- \footnotemark
- \@@_fn_store:
- \hook_gput_next_code:ne {env/#1/after}
- {\exp_not:N\@@_fn_restore:n{\int_use:N\c@footnote}{\exp_not:n{\footnotetext{#2}}}}}
-
-\AddToHook{env/function/begin}{\def\footnote{\@@_fn_footnote:nn{function}}}
-\AddToHook{env/variable/begin}{\def\footnote{\@@_fn_footnote:nn{variable}}}
-% \end{macrocode}
-%
-% \subsection{Documenting templates}
-%
-% \begin{macrocode}
-\newenvironment{TemplateInterfaceDescription}[1]
- {
- \subsection{The~object~type~`#1'}
- \begingroup
- \@beginparpenalty\@M
- \description
- \def\TemplateArgument##1##2{\item[Arg:~##1]##2\par}
- \def\TemplateSemantics
- {
- \enddescription\endgroup
- \subsubsection*{Semantics:}
- }
- }
- {
- \par\bigskip
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\newenvironment{TemplateDescription}[2]
- {
- \subsection{The~template~`#2'~(object~type~#1)}
- \subsubsection*{Attributes:}
- \begingroup
- \@beginparpenalty\@M
- \description
- \def\TemplateKey##1##2##3##4
- {
- \item[##1~(##2)]##3%
- \ifx\TemplateKey##4\TemplateKey\else
-% \hskip0ptplus3em\penalty-500\hskip 0pt plus 1filll Default:~##4%
- \hfill\penalty500\hbox{}\hfill Default:~##4%
- \nobreak\hskip-\parfillskip\hskip0pt\relax
- \fi
- \par
- }
- \def\TemplateSemantics
- {
- \enddescription\endgroup
- \subsubsection*{Semantics~\&~Comments:}
- }
- }
- { \par \bigskip }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\newenvironment{InstanceDescription}[4][xxxxxxxxxxxxxxx]
- {
- \subsubsection{The~instance~`#3'~(template~#2/#4)}
- \subsubsection*{Attribute~values:}
- \begingroup
- \@beginparpenalty\@M
- \def\InstanceKey##1##2{\>\textbf{##1}\>##2\\}
- \def\InstanceSemantics{\endtabbing\endgroup
- \vskip-30pt\vskip0pt
- \subsubsection*{Layout~description~\&~Comments:}}
- \tabbing
- xxxx\=#1\=\kill
- }
- { \par \bigskip }
-% \end{macrocode}
-%
-% \subsection{Inheriting doc}
-%
-% Code here is taken from \pkg{doc}, stripped of comments and translated
-% into \pkg{expl3} syntax. New features are added in various places.
-%
-% \begin{macro}
-% {\StopEventually, \MaybeStop, \Finale, \AlsoImplementation, \OnlyDescription}
-% \begin{variable}{\g_@@_finale_tl}
-% TODO: remove these four commands altogether, document that it is
-% better to use the \env{documentation} and \env{implementation}
-% environments.
-% \begin{macrocode}
-\DeclareDocumentCommand \OnlyDescription { }
- { \bool_gset_false:N \g_@@_typeset_implementation_bool }
-\DeclareDocumentCommand \AlsoImplementation { }
- { \bool_gset_true:N \g_@@_typeset_implementation_bool }
-\DeclareDocumentCommand \StopEventually { m }
- {
- \bool_if:NTF \g_@@_typeset_implementation_bool
- {
- \@bsphack
- \tl_gset:Nn \g_@@_finale_tl { #1 \check@checksum }
- \init@checksum
- \@esphack
- }
- { #1 \endinput }
- }
-% \end{macrocode}
-% We also need to support doc V3 \cs{MaybeStop} if it is around
-% (which may not be the case).
-% \begin{macrocode}
-\cs_if_exist:NT \MaybeStop
- { \RenewCommandCopy \MaybeStop \StopEventually }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\DeclareDocumentCommand \Finale { }
- { \tl_use:N \g_@@_finale_tl }
-\tl_new:N \g_@@_finale_tl
-% \end{macrocode}
-% \end{variable}
-% \end{macro}
-%
-% \begin{macro}{\@@_input:n}
-% Inputting a file, with some setup: the module name should be empty
-% before the first |<@@=|\meta{module}|>| line in the file.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_input:n #1
- {
- \tl_gclear:N \g_@@_module_name_tl
- \MakePercentIgnore
- \input{#1}
- \MakePercentComment
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\DocInput}
-% Modified from \pkg{doc} to accept comma-list input (who has commas
-% in filenames?).
-% \begin{macrocode}
-\DeclareDocumentCommand \DocInput { m }
- {
- \clist_map_inline:nn {#1}
- {
- \clist_put_right:Nn \g_docinput_clist {##1}
- \@@_input:n {##1}
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\DocInputAgain}
-% Uses \cs{g_docinput_clist} to re-input whatever's already been
-% \tn{DocInput}-ed until now. May be used multiple times.
-% \begin{macrocode}
-\DeclareDocumentCommand \DocInputAgain { }
- { \clist_map_function:NN \g_docinput_clist \@@_input:n }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\DocInclude}
-% More or less exactly the same as \tn{include}, but uses
-% \tn{DocInput} on a \file{.fdd} or \file{.dtx} file (without file
-% extension), not \tn{input} on a \file{.tex} file.
-%
-% \begin{macrocode}
-\msg_new:nnn { l3doc } { missing-endgroup }
- {
- \str_if_eq:VnTF \@currenvir { document }
- {
- There~are~\int_use:N \tex_currentgrouplevel:D
- \c_space_tl unclosed~groups~in~#1.
- }
- {
- The~\@currenvir \c_space_tl environment~on~line~\@currenvline
- \c_space_tl doesn't~have~a~matching~\iow_char:N\\end{\@currenvir}.
- }
- }
-\NewDocumentCommand \DocInclude { m }
- {
- \relax\clearpage
- \docincludeaux
- \IfFileExists{#1.fdd}
- { \cs_set:Npn \currentfile{#1.fdd} }
- { \cs_set:Npn \currentfile{#1.dtx} }
- \int_compare:nNnTF \@auxout = \@partaux
- { \@latexerr{\string\include\space cannot~be~nested}\@eha }
- { \@docinclude {#1} }
- % check missing \endgroup, e.g., missing "\end{macro}" in time
- \int_compare:nNnF { \tex_currentgrouplevel:D } = { 0 }
- {
- \int_compare:nNnT { \tex_interactionmode:D } = { 0 }
- { \int_gset:Nn \tex_interactionmode:D { 1 } }
- \msg_fatal:nne { l3doc } { missing-endgroup } { \currentfile }
- }
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_gset:Npn \@docinclude #1
- {
- \clearpage
- \immediate\write\@mainaux{\string\@input{#1.aux}}
- \@tempswatrue
- \if@partsw
- \@tempswafalse
- \cs_set:Npe \@tempb {#1}
- \clist_map_inline:Nn \@partlist
- {
- \if_meaning:w \@tempa \@tempb
- \@tempswatrue
- \fi:
- }
- \fi
- \if@tempswa
- \cs_set_eq:NN \@auxout \@partaux
- \immediate\openout\@partaux #1.aux
- \immediate\write\@partaux{\relax}
- \cs_set_eq:NN \@ltxdoc@PrintIndex \PrintIndex
- \cs_set_eq:NN \PrintIndex \relax
- \cs_set_eq:NN \@ltxdoc@PrintChanges \PrintChanges
- \cs_set_eq:NN \PrintChanges \relax
- \cs_set_eq:NN \@ltxdoc@theglossary \theglossary
- \cs_set_eq:NN \@ltxdoc@endtheglossary \endtheglossary
- \part{\currentfile}
- {
- \cs_set_eq:NN \ttfamily\relax
- \cs_gset:Npe \filekey
- { \filekey,~ \thepart = { \ttfamily \currentfile } }
- }
- \DocInput{\currentfile}
- \cs_set_eq:NN \PrintIndex \@ltxdoc@PrintIndex
- \cs_set_eq:NN \PrintChanges \@ltxdoc@PrintChanges
- \cs_set_eq:NN \theglossary \@ltxdoc@theglossary
- \cs_set_eq:NN \endtheglossary \@ltxdoc@endtheglossary
- \clearpage
- \@writeckpt{#1}
- \immediate \closeout \@partaux
- \else
- \@nameuse{cp@#1}
- \fi
- \cs_set_eq:NN \@auxout \@mainaux
- }
-% \end{macrocode}
-%
-% Here, |MMMMI| (for page references) and |MMMMV| (for codeline
-% references) are interpreted by |makeindex| as an uppercase Roman
-% number pages, and should be large enough to avoid collisions with
-% other uses of uppercase Roman number pages. Two subtle differences
-% between \cs{@wrindex} and \cs{codeline@wrindex} are that the first
-% must be a delayed write because the page number is not known yet, and
-% it must close a group and finish some space-hack.
-%
-% We also provide versions for our use that refer
-% \begin{macrocode}
-\cs_gset_protected:Npn \@wrindex #1
- {
- \protected@write \@indexfile {}
- { \string \indexentry {#1} { MMMMI - \thepage } }
- \endgroup \@esphack
- }
-\cs_gset_protected:Npn \codeline@wrindex #1
- {
- \immediate\write\@indexfile
- {
- \string\indexentry{#1}
- { MMMMV - \filesep \int_use:N \c@CodelineNo }
- }
- }
-\tl_gclear:N \filesep
-\cs_new_protected:Npn \@@_index_page_hc:nn #1#2
- {
- \protected@write \@indexfile {}
- {
- \string \indexentry { #1 \encapchar hdpindex{#2} }
- { MMMMI - \thepage }
- }
- }
-\cs_new_protected:Npn \@@_index_codeline_hc:nn #1#2
- {
- \immediate\write\@indexfile
- {
- \string \indexentry { #1 \encapchar hdclindex{\the\c@HD@hypercount}{#2} }
- { MMMMV - \filesep \int_use:N \c@CodelineNo - MMMD - \the\c@HD@hypercount - M }
- }
- }
-% \end{macrocode}
-% We already have a single |HD.xx| target per code line. It would be
-% better to have a target |CL.\the\c@CodelineNo| per code line and
-% change |hdclindex{\the\c@HD@hypercount}| to a mechanism closer to
-% |hdpindex|, but we need to understand better the different types of
-% indexings, and there are subtleties with indexing |\{| and |\}|.
-% \end{macro}
-%
-% \begin{macro}{\docincludeaux}
-% \begin{macrocode}
-\cs_gset:Npn \docincludeaux
- {
- \tl_set:Nn \thepart { \alphalph { part } }
- \tl_set:Nn \filesep { \thepart - }
- \cs_set_eq:NN \filekey \use_none:n
- \tl_gput_right:Nn \index@prologue
- {
- \cs_gset:Npn \@oddfoot
- {
- \parbox { \textwidth }
- {
- \strut \footnotesize
- \raggedright { \bfseries File~Key: } ~ \filekey
- }
- }
- \cs_set_eq:NN \@evenfoot \@oddfoot
- }
- \cs_gset_eq:NN \docincludeaux \relax
- \cs_gset:Npn \@oddfoot
- {
- \cs_if_exist:cTF { ver @ \currentfile }
- { File~\thepart :~{\ttfamily\currentfile}~ }
- {
- \GetFileInfo{\currentfile}
- File~\thepart :~{\ttfamily\filename}~
- Date:~\ExplFileDate\ % space
- Version~\ExplFileVersion
- }
- \hfill \thepage
- }
- \cs_set_eq:NN \@evenfoot \@oddfoot
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsubsection{The \env{macrocode} environment}
-%
-% \begin{macro}{\xmacro@code, \@@_xmacro_code:n, \@@_xmacro_code:w}
-% Hook into the \texttt{macrocode} environment in a dirty way:
-% \tn{xmacro@code} is responsible for grabbing (and tokenizing) the
-% body of the environment. Redefine it to pass what it grabs to
-% \cs{@@_xmacro_code:n}. This new macro replaces all |@@| by the
-% appropriate module name. One exceptional case is the
-% |<@@=|\meta{module}|>| lines themselves, where |@@| should not be
-% modified. Actually, we search for such lines, to set the module
-% name automatically. We need to be careful: no |<@@=| should appear
-% as such in the code below since \pkg{l3doc} is also typeset using
-% this code.
-% At each |<@@=| found, replace the \meta{module} in the code behind
-% it, update the \meta{module}, and loop to check for further
-% occurrences of |<@@=|.
-% \begin{macrocode}
-\group_begin:
- \char_set_catcode_other:N \^^A
- \char_set_catcode_active:N \^^S
- \char_set_catcode_active:N \^^B
- \char_set_catcode_other:N \^^L
- \char_set_catcode_other:N \^^R
- \char_set_lccode:nn { `\^^A } { `\% }
- \char_set_lccode:nn { `\^^S } { `\ }
- \char_set_lccode:nn { `\^^B } { `\\ }
- \char_set_lccode:nn { `\^^L } { `\{ }
- \char_set_lccode:nn { `\^^R } { `\} }
- \tex_lowercase:D
- {
- \group_end:
- \cs_set_protected:Npn \xmacro@code
- #1 ^^A ^^S^^S^^S^^S ^^Bend ^^Lmacrocode^^R
- { \@@_xmacro_code:n {#1} \end{macrocode} }
- }
-\group_begin:
- \char_set_catcode_active:N \<
- \char_set_catcode_active:N \>
- \cs_new_protected:Npn \@@_xmacro_code:n #1
- {
- \tl_clear:N \l_@@_tmpa_tl
- \tl_if_in:nnTF {#1} { < @ @ = }
- { \@@_xmacro_code:w #1 < @ @ = \q_recursion_tail > \q_recursion_stop }
- {
- \tl_set:Nn \l_@@_tmpa_tl {#1}
- \@@_detect_internals:N \l_@@_tmpa_tl
- \@@_replace_at_at:N \l_@@_tmpa_tl
- \tl_use:N \l_@@_tmpa_tl
- }
- }
- \cs_new_protected:Npn \@@_xmacro_code:w #1 < @ @ = #2 >
- {
- % Add code before <@@@@=...>
- \tl_set:Nn \l_@@_tmpb_tl {#1}
- \@@_detect_internals:N \l_@@_tmpb_tl
- \@@_replace_at_at:N \l_@@_tmpb_tl
- \tl_put_right:NV \l_@@_tmpa_tl \l_@@_tmpb_tl
- % Check for \q_recursion_tail
- \quark_if_recursion_tail_stop_do:nn {#2}
- { \tl_use:N \l_@@_tmpa_tl }
- % Change module name and add <@@@@=#2> to typeset output
- \tl_gset:Nn \g_@@_module_name_tl {#2}
- \tl_put_right:Nn \l_@@_tmpa_tl { < \text { \verbatim@font @ @ = #2 } > }
- % Loop
- \@@_xmacro_code:w
- }
-\group_end:
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{At end document}
-%
-% Print all defined and documented macros/functions.
-%
-% \begin{macrocode}
-\iow_new:N \g_@@_func_iow
-% \end{macrocode}
-%
-% \begin{macrocode}
-\tl_new:N \l_@@_doc_def_tl
-\tl_new:N \l_@@_doc_undef_tl
-\tl_new:N \l_@@_undoc_def_tl
-\tl_const:Nn \c_@@_iow_separator_tl { ---- }
-\tl_const:Nn \c_@@_iow_midrule_tl { -- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_show_functions_defined:
- {
- \bool_lazy_and:nnT
- { \g_@@_typeset_implementation_bool } { \g_@@_checkfunc_bool }
- {
- \iow_term:e { \c_@@_iow_separator_tl \iow_newline: }
- \iow_open:Nn \g_@@_func_iow { \c_sys_jobname_str .cmds }
-
- \tl_clear:N \l_@@_doc_def_tl
- \tl_clear:N \l_@@_doc_undef_tl
- \tl_clear:N \l_@@_undoc_def_tl
- \seq_gremove_duplicates:N \g_doc_functions_seq
- \seq_gremove_duplicates:N \g_doc_macros_seq
- \seq_map_inline:Nn \g_doc_functions_seq
- {
- \seq_if_in:NnTF \g_doc_macros_seq {##1}
- {
- \tl_put_right:Ne \l_@@_doc_def_tl
- { \iow_newline: > ~ ##1 }
- }
- {
- \tl_put_right:Ne \l_@@_doc_undef_tl
- { \iow_newline: ! ~ ##1 }
- }
- }
- \seq_map_inline:Nn \g_doc_macros_seq
- {
- \seq_if_in:NnF \g_doc_functions_seq {##1}
- {
- \tl_put_right:Ne \l_@@_undoc_def_tl
- { \iow_newline: ? ~ ##1 }
- }
- }
- \@@_functions_typeout:nN
- {
- Functions~both~documented~and~defined: \iow_newline:
- (In~order~of~being~documented)
- }
- \l_@@_doc_def_tl
- \@@_functions_typeout:nN
- { Functions~documented~but~not~defined: }
- \l_@@_doc_undef_tl
- \@@_functions_typeout:nN
- { Functions~defined~but~not~documented: }
- \l_@@_undoc_def_tl
-
- \iow_close:N \g_@@_func_iow
- \iow_term:e { \c_@@_iow_separator_tl }
- }
- }
-\AtEndDocument { \@@_show_functions_defined: }
-% \end{macrocode}
-%
-% TODO: use \cs{iow_term:e}.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_functions_typeout:nN #1#2
- {
- \tl_if_empty:NF #2
- {
- \iow_now:Ne \g_@@_func_iow
- {
- \c_@@_iow_midrule_tl \iow_newline:
- #1 \iow_newline:
- \c_@@_iow_midrule_tl
- #2
- }
- \tl_clear:N #2
- }
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_show_not_tested:
- {
- \bool_if:NT \g_@@_checktest_bool
- {
- \tl_clear:N \l_@@_tmpa_tl
- \prop_if_empty:NF \g_@@_missing_tests_prop
- {
- \cs_set:Npn \@@_tmpa:w ##1##2
- {
- \iow_newline:
- \space\space\space\space \exp_not:n {##1}
- \clist_map_function:nN {##2} \@@_tmpb:w
- }
- \cs_set:Npn \@@_tmpb:w ##1
- {
- \iow_newline:
- \space\space\space\space\space\space * ~ ##1
- }
- \tl_put_right:Ne \l_@@_tmpa_tl
- {
- \iow_newline: \iow_newline:
- The~ following~ macro(s)~ have~ incomplete~ tests:
- \iow_newline:
- \prop_map_function:NN
- \g_@@_missing_tests_prop \@@_tmpa:w
- }
- }
- \seq_if_empty:NF \g_@@_not_tested_seq
- {
- \cs_set:Npn \@@_tmpa:w ##1
- { \clist_map_function:nN {##1} \@@_tmpb:w }
- \cs_set:Npn \@@_tmpb:w ##1
- {
- \iow_newline:
- \space\space\space\space ##1
- }
- \tl_put_right:Ne \l_@@_tmpa_tl
- {
- \iow_newline:
- \iow_newline:
- The~ following~ macro(s)~ do~ not~ have~ any~ tests:
- \iow_newline:
- \seq_map_function:NN
- \g_@@_not_tested_seq \@@_tmpa:w
- }
- }
- \tl_if_empty:NF \l_@@_tmpa_tl
- {
- \int_set:Nn \l_@@_tmpa_int { \tex_interactionmode:D }
- \errorstopmode
- \ClassError { l3doc } { \l_@@_tmpa_tl } { }
- \int_gset:Nn \tex_interactionmode:D { \l_@@_tmpa_int }
- }
- }
- }
-\AtEndDocument { \@@_show_not_tested: }
-% \end{macrocode}
-%
-% \subsection{Indexing}
-%
-% \subsubsection{Necessary patching}
-%
-% The following is useful to set up \pkg{hyperref} targets, for instance
-% for the purpose of indexing. Contrarily to \pkg{hypdoc} we do not try
-% to save pdf destinations, as this leads to too many \pdfTeX{} warnings
-% on early runs.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_target:
- {
- \mode_leave_vertical:
- \group_begin:
- \HD@savedestfalse \HD@target
- \group_end:
- }
-% \end{macrocode}
-% Force targets on every code line.
-% \begin{macrocode}
-\cs_set_nopar:Npe \theCodelineNo
- {
- \group_begin:
- \exp_not:N \HD@savedestfalse
- \exp_not:o \theCodelineNo
- \group_end:
- }
-% \end{macrocode}
-%
-% Inside the table of contents (and other similar lists introduced by
-% \cs{@starttoc}), we suppress indexing. This is because \cs{cmd},
-% \cs{cs}, or \cs{tn} appearing in titles only gets typeset in the
-% second run, and getting their indexing right would require even more
-% runs than we already need. Besides, it is not useful to index uses of
-% some command in the table of contents.
-% \begin{macrocode}
-\bool_new:N \l_@@_allow_indexing_bool
-\bool_set_true:N \l_@@_allow_indexing_bool
-\use:e
- {
- \exp_not:n { \cs_set_nopar:Npn \@starttoc #1 }
- {
- \group_begin:
- \bool_set_false:N \l_@@_allow_indexing_bool
- \exp_not:o { \@starttoc {#1} }
- \group_end:
- }
- }
-% \end{macrocode}
-%
-% \subsubsection{Userspace commands}
-%
-% Fix index (for now):
-% \begin{macrocode}
-\g@addto@macro \theindex { \MakePrivateLetters }
-\cs_gset:Npn \verbatimchar {&}
-% \end{macrocode}
-%
-% \begin{macrocode}
-\setcounter { IndexColumns } { 2 }
-% \end{macrocode}
-%
-% Set up the Index to use \tn{part}
-% \begin{macrocode}
-\IndexPrologue
- {
- \part*{Index}
- \markboth{Index}{Index}
- \addcontentsline{toc}{part}{Index}
- The~italic~numbers~denote~the~pages~where~the~
- corresponding~entry~is~described,~
- numbers~underlined~point~to~the~definition,~
- all~others~indicate~the~places~where~it~is~used.
- }
-% \end{macrocode}
-%
-% \begin{macro}{\SpecialIndex}
-% An attempt at affecting how commands which appear within the
-% \env{macrocode} environment are treated in the index.
-% \begin{macrocode}
-\cs_gset_protected:Npn \SpecialIndex #1
- {
- \@bsphack
- \@@_special_index:nn {#1} { }
- \@esphack
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-\msg_new:nnn { l3doc } { print-index-howto }
- {
- Generate~the~index~by~executing\\
- \iow_indent:n
- { makeindex~-s~gind.ist~-o~\c_sys_jobname_str.ind~\c_sys_jobname_str.idx }
- }
-\tl_gput_right:Nn \PrintIndex
- { \AtEndDocument { \msg_info:nn { l3doc } { print-index-howto } } }
-% \end{macrocode}
-%
-% \subsubsection{Internal index commands}
-%
-% \begin{macro}{\it@is@a}
-% The index of one-character commands within the \env{macrocode}
-% environment is produced using \tn{it@is@a} \meta{char}. Alter that
-% command.
-% \begin{macrocode}
-\cs_gset_protected:Npn \it@is@a #1
- {
- \use:e
- {
- \@@_special_index_module:nnnnN
- {#1}
- { \bslash #1 }
- { }
- { }
- \c_false_bool
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_special_index:nn}
-% ^^A TODO this override is somewhat a hack
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_special_index:nn #1#2
- {
- \@@_key_get:n {#1}
- \quark_if_no_value:NF \l_@@_override_module_tl
- { \tl_set_eq:NN \l_@@_index_module_tl \l_@@_override_module_tl }
- \@@_special_index_module:ooonN
- { \l_@@_index_key_tl }
- { \l_@@_index_macro_tl }
- { \l_@@_index_module_tl }
- {#2}
- \l_@@_index_internal_bool
- }
-\cs_generate_variant:Nn \@@_special_index:nn { o }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \@@_special_index_module:nnnnN,
-% \@@_special_index_module:ooonN,
-% \@@_special_index_aux:nnnnnn,
-% \@@_special_index_set:Nn,
-% }
-% Remotely based on Heiko's replacement to play nicely with
-% \pkg{hypdoc}. We use \tn{verb} or a \tn{verbatim@font} construction
-% depending on whether the number of tokens in |#2| is equal to its
-% number of characters: if it is not then that suggests that there is
-% a construct such as |\meta{...}|.
-% \begin{macrocode}
-\tl_new:N \l_@@_index_escaped_macro_tl
-\tl_new:N \l_@@_index_escaped_key_tl
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_special_index_module:nnnnN #1#2#3#4#5
-% \end{macrocode}
-% \begin{arguments}
-% \item key
-% \item macro
-% \item module
-% \item index `type' (\texttt{main}/\texttt{usage}/\emph{etc.})
-% \item boolean whether internal command
-% \end{arguments}
-% \begin{macrocode}
- {
- \use:e
- {
- \exp_not:n { \@@_special_index_aux:nnnnnn {#1} {#2} }
- \tl_if_empty:nTF {#3}
- { { } { } { } }
- {
- \str_if_eq:nnTF {#3} { TeX }
- {
- { TeX~and~LaTeX2e }
- { \string\TeX{}~and~\string\LaTeXe{} }
- }
- {
- {#3}
- { \string\pkg{#3} }
- }
- { \bool_if:NT #5 { ~internal } ~commands: }
- }
- }
- {#4}
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_generate_variant:Nn \@@_special_index_module:nnnnN { ooo }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_special_index_aux:nnnnnn #1#2#3#4#5#6
-% \end{macrocode}
-% \begin{arguments}
-% \item key
-% \item macro
-% \item index subheading string
-% \item index subheading text
-% \item index subheading suffix (appended to both arg 3 and 4)
-% \item index `type' (\texttt{main}/\texttt{usage}/\emph{etc.})
-% \end{arguments}
-% \begin{macrocode}
- {
- \tl_set:Nn \l_@@_index_escaped_key_tl {#1}
- \@@_quote_special_char:N \l_@@_index_escaped_key_tl
- \@@_special_index_set:Nn \l_@@_index_escaped_macro_tl {#2}
- \str_if_eq:onTF { \@currenvir } { macrocode }
- { \@@_index_codeline_hc:nn }
- {
- \str_case:nnF {#6}
- {
- { main } { \@@_index_codeline_hc:nn }
- { usage } { \@@_index_page_hc:nn }
- }
- { \@@_target: \@@_index_page_hc:nn }
- }
- {
- \tl_if_empty:nF { #3 #4 #5 }
- { #3 #5 \actualchar #4 #5 \levelchar }
- \l_@@_index_escaped_key_tl
- \actualchar
- {
- \token_to_str:N \verbatim@font \c_space_tl
- \l_@@_index_escaped_macro_tl
- }
- }
- {#6}
- }
-% \end{macrocode}
-%
-% \begin{macro}{\hdpindex, \@@_old_hdpindex:nn, \hdclindex, \@@_old_hdclindex:nnn, \@@_hdindex:nn, \c_@@_active_minus_tl, \@@_hdindex_aux:nn, \@@_hdindex_aux:w}
-% Note that |#3| here could contain |MMMMI-| or |MMMMV-| more than once
-% if several successive code lines have been merged into a range
-% somehow. Note incidentally that the dash is active in some of our
-% sources, like |interface3.tex| or |source2e.tex|.
-% \begin{macrocode}
-\group_begin:
-\char_set_active_eq:NN - \scan_stop:
-\tl_const:Ne \c_@@_active_minus_tl { \char_generate:nn { `- } { 13 } }
-\group_end:
-\cs_new_eq:NN \@@_old_hdpindex:nn \hdpindex
-\cs_new_eq:NN \@@_old_hdclindex:nnn \hdclindex
-\cs_gset_protected:Npn \hdpindex #1
- { \@@_hdindex:nn { \@@_old_hdpindex:nn {#1} } }
-\cs_gset_protected:Npn \hdclindex #1#2
- { \@@_hdindex:nn { \@@_old_hdclindex:nnn {#1} {#2} } }
-\cs_new_protected:Npn \@@_hdindex:nn #1#2
- {
- \tl_set:Nn \l_@@_tmpa_tl {#2}
- \tl_replace_all:Nen \l_@@_tmpa_tl
- { \exp_not:V \c_@@_active_minus_tl \exp_not:V \c_@@_active_minus_tl }
- { -- }
- \seq_set_split:NnV \l_@@_tmpa_seq { -- } \l_@@_tmpa_tl
- \seq_set_map:NNn \l_@@_tmpa_seq \l_@@_tmpa_seq
- { \@@_hdindex_aux:nn {#1} {##1} }
- \seq_use:Nn \l_@@_tmpa_seq { -- }
- }
-\cs_new_protected:Npn \@@_hdindex_aux:nn #1#2
- {
- \tl_set:Nn \l_@@_tmpa_tl {#2}
- \tl_replace_all:Nnn \l_@@_tmpa_tl { MMMM } { \use_none:nn }
- \tl_if_in:NnT \l_@@_tmpa_tl { MMMD }
- {
- \tl_replace_all:Nen \l_@@_tmpa_tl
- { \exp_not:V \c_@@_active_minus_tl MMMD } { - MMMD }
- \tl_replace_all:Nnn \l_@@_tmpa_tl { - MMMD } { \@@_hdindex_aux:w }
- }
- \use:e { \exp_not:n {#1} { \exp_not:V \l_@@_tmpa_tl } }
- }
-\cs_new_protected:Npn \@@_hdindex_aux:w #1 M { }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_special_index_set:Nn #1#2
- {
- \__kernel_tl_set:Nx #1 { \tl_to_str:n {#2} }
- \@@_if_almost_str:nTF {#2}
- {
- \tl_replace_all:Nen #1 { \tl_to_str:n { __ } }
- {
- \verbatimchar
- \token_to_str:N \_ \token_to_str:N \_
- \token_to_str:N \verb * \verbatimchar
- }
- \exp_args:Ne \tl_map_inline:nn
- { \tl_to_str:N \verbatimchar \token_to_str:N _ }
- {
- \tl_replace_all:Nnn #1 {##1}
- {
- \verbatimchar \c_backslash_str ##1
- \token_to_str:N \verb * \verbatimchar
- }
- }
- \__kernel_tl_set:Nx #1
- {
- \token_to_str:N \verb * \verbatimchar
- #1 \verbatimchar
- }
- }
- {
- \tl_set:Nn #1 {#2}
- \tl_replace_all:NVn #1
- \c_backslash_str
- { \token_to_str:N \bslash \c_space_tl }
- }
- \@@_quote_special_char:N #1
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_quote_special_char:N}
-% Quote some special characters.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_quote_special_char:N #1
- {
- \tl_map_inline:nn { \quotechar \actualchar \encapchar \levelchar \bslash }
- {
- \tl_replace_all:Nen #1
- { \tl_to_str:N ##1 } { \quotechar \tl_to_str:N ##1 }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsubsection{Finding sort-key and module}
-%
-% \begin{macro}{\@@_key_get:n}
-% Sets \cs{l_@@_index_macro_tl}, \cs{l_@@_index_key_tl}, and
-% \cs{l_@@_index_module_tl} from |#1|. The base function is stored by
-% \cs{@@_key_get_base:nN} in \cs{l_@@_index_macro_tl}, falling back to
-% |#1| if it contains markup or has no signature.
-%
-% The starting point for the \meta{key} is \cs{l_@@_index_key_tl} as a
-% string. If it the first character is a backslash, remove
-% it. Then recognize |expl| functions and variables by the presence
-% of |:| or~|_| and \TeX{}/\LaTeXe{} commands by the presence of~|@|.
-% For |expl| names, we call \cs{@@_key_func:} or \cs{@@_key_var:},
-% which are responsible for removing some characters and finding the
-% module name, while for \TeX{}/\LaTeXe{} commands the module name is
-% |TeX|, and others have an empty module name.
-% \begin{macrocode}
-\cs_new_protected:Npe \@@_key_get:n #1
- {
- \exp_not:N \@@_key_get_base:nN {#1} \exp_not:N \l_@@_index_macro_tl
- \__kernel_tl_set:Nx \exp_not:N \l_@@_index_key_tl
- { \exp_not:N \tl_to_str:N \exp_not:N \l_@@_index_macro_tl }
- \tl_clear:N \exp_not:N \l_@@_index_module_tl
- \tl_if_in:NnTF \exp_not:N \l_@@_index_key_tl { \tl_to_str:n { __ } }
- { \bool_set_true:N \exp_not:N \l_@@_index_internal_bool }
- { \bool_set_false:N \exp_not:N \l_@@_index_internal_bool }
- \exp_not:N \tl_if_head_eq_charcode:VNT
- \exp_not:N \l_@@_index_key_tl \c_backslash_str
- { \exp_not:N \@@_key_pop: }
- \tl_if_in:NnTF \exp_not:N \l_@@_index_key_tl { \token_to_str:N : }
- { \exp_not:N \@@_key_func: }
- {
- \tl_if_in:NnTF \exp_not:N \l_@@_index_key_tl { \token_to_str:N _ }
- { \exp_not:N \@@_key_var: }
- {
- \tl_if_in:NnT \exp_not:N \l_@@_index_key_tl { \token_to_str:N @ }
- { \tl_set:Nn \exp_not:N \l_@@_index_module_tl { TeX } }
- }
- }
- }
-\cs_new_protected:Npn \@@_key_pop:
- {
- \__kernel_tl_set:Nx \l_@@_index_key_tl
- { \tl_tail:N \l_@@_index_key_tl }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_key_trim_module:n, \@@_key_drop_underscores:}
-% Helper that removes from \cs{l_@@_index_module_tl} everything after
-% the first occurence of |#1|. Helper that removes any leading
-% underscore from \cs{l_@@_index_key_tl}.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_key_trim_module:n #1
- {
- \cs_set:Npn \@@_tmpa:w ##1 #1 ##2 \q_stop
- { \exp_not:n {##1} }
- \__kernel_tl_set:Nx \l_@@_index_module_tl
- { \exp_after:wN \@@_tmpa:w \l_@@_index_module_tl #1 \q_stop }
- }
-\cs_new_protected:Npn \@@_key_drop_underscores:
- {
- \tl_if_head_eq_charcode:VNT \l_@@_index_key_tl _
- { \@@_key_pop: \@@_key_drop_underscores: }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_key_func:}
-% The function \cs{@@_key_func:} is used if there is a colon, so
-% either for usual \pkg{expl3} functions or for keys from
-% \pkg{l3keys}. After removing from the key a leading dot (for the
-% latter case), and any leading underscore, the module name is the
-% part before any colon or underscore.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_key_func:
- {
- \tl_if_head_eq_charcode:VNT \l_@@_index_key_tl .
- { \@@_key_pop: }
- \@@_key_drop_underscores:
- \tl_set_eq:NN \l_@@_index_module_tl \l_@@_index_key_tl
- \exp_args:No \@@_key_trim_module:n { \token_to_str:N : }
- \exp_args:No \@@_key_trim_module:n { \token_to_str:N _ }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@@_key_var:, \@@_key_get_module:}
-% The function \cs{@@_key_var:} covers cases with no~|:| but with~|_|,
-% typically variables but occasionally non-\pkg{expl3} functions such
-% as \Lua{} function with underscores. First test the second
-% character: if that is~|_| then assume we have a proper variable,
-% otherwise use the part before any underscore as the module name.
-% For variables, distinguish quarks and scan marks (starting with |q|
-% and~|s|), then drop the first letter (local/global/constant marker)
-% and underscores to improve the index sorting.
-% Then get the module as the first (underscore-delimited) \enquote{word}.
-% In the past, we distinguished according to how many such words there
-% were, to detect commands like \cs[no-index]{c_zero}, which should be
-% sorted as |int| variables, and \cs[no-index]{l_tmpa_dim}, which should
-% be sorted in the |dim| and not the |tmpa| module.
-% Now the first case has been deprecated for some time, while |tmpa| and
-% similar are special-cased through an explicit list given below.
-% The way it works is that if the module is in a list of special names
-% that are not valid modules, then we try the last word, and if that
-% also fails (for instance in the deprecated \cs[no-index]{c_one_hundred})
-% we empty the module completely.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_key_var:
- {
- \exp_args:Ne \tl_if_head_eq_charcode:nNTF
- { \exp_args:No \str_tail:n \l_@@_index_key_tl } _
- {
- \str_case:en { \str_head:N \l_@@_index_key_tl }
- {
- { q } { \tl_set:Nn \l_@@_index_module_tl { quark } }
- { s } { \tl_set:Nn \l_@@_index_module_tl { scan } }
- }
- \@@_key_pop:
- \@@_key_pop:
- \@@_key_drop_underscores:
- \tl_if_empty:NT \l_@@_index_module_tl
- {
- \seq_set_split:NoV \l_@@_tmpa_seq
- { \token_to_str:N _ } \l_@@_index_key_tl
- \seq_get_left:NN \l_@@_tmpa_seq \l_@@_index_module_tl
- \clist_if_in:NoT \g_@@_non_modules_clist \l_@@_index_module_tl
- {
- \seq_get_right:NN \l_@@_tmpa_seq \l_@@_index_module_tl
- \clist_if_in:NoT \g_@@_non_modules_clist \l_@@_index_module_tl
- {
- \tl_clear:N \l_@@_index_module_tl
- }
- }
- }
- }
- {
- \tl_set_eq:NN \l_@@_index_module_tl \l_@@_index_key_tl
- \exp_args:No \@@_key_trim_module:n { \token_to_str:N _ }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{variable}{\g_@@_non_modules_clist}
-% List of names that appear as the first word in an \pkg{expl3}
-% command, but that are not true modules, so that they should be
-% sorted differently in an index.
-% \begin{macrocode}
-\clist_new:N \g_@@_non_modules_clist
-\clist_gset:Ne \g_@@_non_modules_clist
- {
- \tl_to_str:n
- {
-
- alignment, ampersand, atsign, backslash, catcode, circumflex,
- code, colon, document, dollar, e, empty, false, hash, inf,
- initex, job, left, log, math, mark, max, minus, nan, nil, no,
- novalue, other, parameter, percent, pi, recursion, right, space,
- stop, term, tilde, tmpa, tmpb, true, underscore, zero, one, two,
- three, four, five, six, seven, eight, nine, ten, eleven, twelve,
- thirteen, fourteen, fifteen, sixteen, thirty, hundred
-
- }
- }
-% \end{macrocode}
-% \end{variable}
-%
-% \subsection{Change history}
-%
-% Set the change history to use \tn{part}.
-% Allow control names to be hyphenated in here\dots
-% \begin{macrocode}
-\GlossaryPrologue
- {
- \part*{Change~History}
- {\GlossaryParms\ttfamily\hyphenchar\font=`\-}
- \markboth{Change~History}{Change~History}
- \addcontentsline{toc}{part}{Change~History}
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\msg_new:nnn { l3doc } { print-changes-howto }
- {
- Generate~the~change~list~by~executing\\
- \iow_indent:n
- { makeindex~-s~gglo.ist~-o~\c_sys_jobname_str.gls~\c_sys_jobname_str.glo }
- }
-\tl_gput_right:Nn \PrintChanges
- { \AtEndDocument { \msg_info:nn { l3doc } { print-changes-howto } } }
-% \end{macrocode}
-%
-%^^A The standard \changes command modified slightly to better cope with
-%^^A this multiple file document.
-%^^A\def\changes@#1#2#3{%
-%^^A \let\protect\@unexpandable@protect
-%^^A \edef\@tempa{\noexpand\glossary{#2\space\currentfile\space#1\levelchar
-%^^A \ifx\saved@macroname\@empty
-%^^A \space
-%^^A \actualchar
-%^^A \generalname
-%^^A \else
-%^^A \expandafter\@gobble
-%^^A \saved@macroname
-%^^A \actualchar
-%^^A \string\verb\quotechar*%
-%^^A \verbatimchar\saved@macroname
-%^^A \verbatimchar
-%^^A \fi
-%^^A :\levelchar #3}}%
-%^^A \@tempa\endgroup\@esphack}
-%
-% \subsection{Default configuration}
-%
-% \begin{macrocode}
-\bool_if:NTF \g_@@_typeset_implementation_bool
- {
- \RecordChanges
- \CodelineIndex
- \EnableCrossrefs
- \AlsoImplementation
- }
- {
- \CodelineNumbered
- \DisableCrossrefs
- \OnlyDescription
- }
-% \end{macrocode}
-%
-%
-% \begin{macrocode}
-%</class>
-% \end{macrocode}
-%
-% \subsection{Internal macros for \LaTeX3 sources}
-%
-% These definitions are only used by the \LaTeX3 documentation; they are
-% not necessary for third-party users of \cls{l3doc}. In time this will
-% be broken into a separate package that is specifically loaded in the
-% various \pkg{expl3} modules, \emph{etc.}
-%
-% \begin{macrocode}
-%<*cfg>
-% \end{macrocode}
-%
-% The Guilty Parties.
-% \begin{macrocode}
-\tl_const:Nn \Team
- {
- The~\LaTeX3~Project\thanks
- {\url{https://www.latex-project.org/latex3/}}
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\NewDocumentCommand{\ExplMakeTitle}{mm}
- {
- \title
- {
- The~\pkg{#1}~package \\ #2
- }
- \author
- {
- The~\LaTeX3~Project\thanks{E-mail:~
- \href{mailto:latex-l@listserv.uni-heidelberg.de}
- {latex-l@listserv.uni-heidelberg.de}}
- }
- \date{Released~\ExplFileDate}
- \maketitle
- }
-% \end{macrocode}
-%
-% \subsection{Math extras}
-%
-% For \pkg{l3fp}.
-%
-% \begin{macrocode}
-\AtBeginDocument
- {
- \clist_map_inline:nn
- {
- asin, acos, atan, acot,
- asinh, acosh, atanh, acoth, round, floor, ceil
- }
- { \exp_args:Nc \DeclareMathOperator{#1}{#1} }
- }
-% \end{macrocode}
-%
-% \begin{macro}{\nan}
-% \begin{macrocode}
-\NewDocumentCommand { \nan } { } { \text { \texttt { nan } } }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%</cfg>
-% \end{macrocode}
-%
-%
-% \subsection{Makeindex configuration}
-%
-% \begin{macrocode}
-%<*docist>
-% \end{macrocode}
-%
-% The makeindex style \file{l3doc.ist} is used in place of the usual
-% \file{gind.ist} to ensure that |I| is used in the sequence |I J K| not
-% |I II II|, which would be the default makeindex behaviour.
-%
-% Will: Do we need this?
-%
-% Frank: at the moment we do not distribute or generate this file.
-% \file{gind.ist} is used instead.
-%
-% \begin{macro}[do-not-index={\\,\n}]{}
-% \begin{macrocode}
-actual '='
-quote '!'
-level '>'
-preamble
-"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
-postamble
-"\n\n \\end{theindex}\n"
-item_x1 "\\efill \n \\subitem "
-item_x2 "\\efill \n \\subsubitem "
-delim_0 "\\pfill "
-delim_1 "\\pfill "
-delim_2 "\\pfill "
-% The next lines will produce some warnings when
-% running Makeindex as they try to cover two different
-% versions of the program:
-lethead_prefix "{\\bfseries\\hfil "
-lethead_suffix "\\hfil}\\nopagebreak\n"
-lethead_flag 1
-heading_prefix "{\\bfseries\\hfil "
-heading_suffix "\\hfil}\\nopagebreak\n"
-headings_flag 1
-
-% and just for source3:
-% Remove R so I is treated in sequence I J K not I II III
-page_precedence "rnaA"
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%</docist>
-% \end{macrocode}
-%
-% \end{implementation}
-%
-% \PrintIndex