diff options
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3doc.dtx')
-rw-r--r-- | macros/latex/contrib/l3kernel/l3doc.dtx | 4800 |
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 |