From cc862e582aa0dd7c0dee16bb5475394338a07641 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Wed, 6 Dec 2017 23:56:06 +0000
Subject: l3 (7dec17)

git-svn-id: svn://tug.org/texlive/trunk@46003 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/source/latex/l3kernel/l3doc.dtx | 403 ++++++++++++----------
 1 file changed, 229 insertions(+), 174 deletions(-)

(limited to 'Master/texmf-dist/source/latex/l3kernel/l3doc.dtx')

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx
index 2f02cd2c37a..280cb751886 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx
@@ -7,7 +7,7 @@
 % license or (at your option) any later version.  The latest version
 % of this license is in the file
 %
-%    http://www.latex-project.org/lppl.txt
+%    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.
@@ -36,7 +36,7 @@ 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:
 
-   http://www.latex-project.org/lppl.txt
+   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.
@@ -70,14 +70,14 @@ and all files in that bundle must be distributed together.
 % This isn't included in the typeset documentation because it's a bit
 % ugly:
 %<*class>
-\ProvidesExplClass{l3doc}{2017/11/14}{}
+\ProvidesExplClass{l3doc}{2017/12/05}{}
   {L3 Experimental documentation class}
 %</class>
 % \fi
 %
 % \title{The \cls{l3doc} class}
 % \author{\Team}
-% \date{Released 2017/11/14}
+% \date{Released 2017/12/05}
 % \maketitle
 % \tableofcontents
 %
@@ -414,13 +414,10 @@ and all files in that bundle must be distributed together.
 % 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.  In this case, write
-% |\begin{macro}[aux]| to mark it as such; its margin
-% call-out is then printed in grey.
-%
-% Similarly, an internal package function still requires documentation
-% but usually is not documented for users to see; these can be
-% marked as such with |\begin{macro}[int]|.
+% earlier in a \env{function} environment.  \pkg{l3doc} will pick up these
+% cases form 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
@@ -564,7 +561,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_detect_internals_bool, \l_@@_detect_internals_tl}
+% \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
 %   \texttt{macrocode} environments and in~\cs{cs}.  Also a token list
@@ -577,7 +574,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_output_coffin}
+% \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.
@@ -586,7 +583,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]
+% \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
@@ -599,7 +596,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\g_@@_syntax_box}
+% \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}
@@ -607,7 +604,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_in_function_bool}
+% \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.
@@ -616,7 +613,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_long_name_bool, \l_@@_trial_width_dim}
+% \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
@@ -627,7 +624,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_nested_macro_int}
+% \begin{variable}{\l_@@_nested_macro_int}
 %   The nesting of \env{macro} environments (this is now~$0$ outside a
 %   \env{macro} environment).
 %    \begin{macrocode}
@@ -635,7 +632,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]
+% \begin{variable}
 %   {
 %     \l_@@_macro_tested_bool,
 %     \g_@@_missing_tests_prop,
@@ -653,10 +650,10 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[aux]
+% \begin{variable}
 %   {
+%     \l_@@_macro_internal_set_bool,
 %     \l_@@_macro_internal_bool,
-%     \l_@@_macro_aux_bool,
 %     \l_@@_macro_TF_bool,
 %     \l_@@_macro_pTF_bool,
 %     \l_@@_macro_noTF_bool,
@@ -670,8 +667,8 @@ and all files in that bundle must be distributed together.
 %   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_internal_set_bool
 \bool_new:N \l_@@_macro_internal_bool
-\bool_new:N \l_@@_macro_aux_bool
 \bool_new:N \l_@@_macro_TF_bool
 \bool_new:N \l_@@_macro_pTF_bool
 \bool_new:N \l_@@_macro_noTF_bool
@@ -684,21 +681,23 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[aux]
+% \begin{variable}
 %   {
 %     \g_@@_lmodern_bool,
 %     \g_@@_checkfunc_bool,
 %     \g_@@_checktest_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
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_tmpa_tl, \l_@@_tmpb_tl, \l_@@_tmpa_int, \l_@@_tmpa_seq}
+% \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
@@ -708,7 +707,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_names_block_tl}
+% \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
@@ -722,7 +721,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\g_@@_variants_seq}
+% \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.
@@ -731,7 +730,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_names_verb_bool}
+% \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}
@@ -739,7 +738,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_names_seq}
+% \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}
@@ -749,7 +748,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\g_@@_nested_names_seq}
+% \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}
@@ -757,7 +756,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\c_@@_backslash_tl, \c_@@_backslash_token}
+% \begin{variable}{\c_@@_backslash_tl, \c_@@_backslash_token}
 %   A single backslash, as a token list, or as an implicit character
 %   token.
 %    \begin{macrocode}
@@ -817,7 +816,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]
+% \begin{variable}
 %   {
 %     \l_@@_cmd_tl,
 %     \l_@@_cmd_index_tl,
@@ -869,7 +868,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_function_label_clist, \l_@@_no_label_bool}
+% \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
@@ -880,7 +879,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_date_added_tl, \l_@@_date_updated_tl}
+% \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
@@ -888,7 +887,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{variable}[int]{\l_@@_macro_argument_tl}
+% \begin{variable}{\l_@@_macro_argument_tl}
 %   Save the argument of a \env{macro} or \env{function} environment for
 %   use in error messages.
 %    \begin{macrocode}
@@ -903,7 +902,7 @@ and all files in that bundle must be distributed together.
 %
 % \subsection{Variants and helpers}
 %
-% \begin{macro}[aux]{\@@_tmpa:w, \@@_tmpb:w}
+% \begin{macro}{\@@_tmpa:w, \@@_tmpb:w}
 %   Auxiliary macros for temporary use.
 %    \begin{macrocode}
 \cs_new_eq:NN \@@_tmpa:w ?
@@ -941,9 +940,11 @@ and all files in that bundle must be distributed together.
 %   A few missing variants.
 %    \begin{macrocode}
 \cs_generate_variant:Nn \seq_set_split:Nnn { NoV }
+\cs_generate_variant:Nn \seq_gput_right:Nn { Nf }
 \cs_generate_variant:Nn \str_case:nn { fn }
 \cs_generate_variant:Nn \tl_count:n { f }
 \cs_generate_variant:Nn \tl_greplace_all:Nnn { Nx , Nno }
+\cs_generate_variant:Nn \tl_if_empty:nTF { f }
 \cs_generate_variant:Nn \tl_if_head_eq_charcode:nNTF { o }
 \cs_generate_variant:Nn \tl_if_head_eq_charcode:nNT  { o }
 \cs_generate_variant:Nn \tl_if_head_eq_charcode:nNF  { o }
@@ -962,7 +963,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int,TF]{\@@_if_almost_str:n}
+% \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 are there to
@@ -981,7 +982,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int]{\@@_trim_right:Nn, \@@_trim_right:No}
+% \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}
@@ -994,8 +995,8 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int]{\@@_replace_at_at:N}
-% \begin{macro}[aux]{\@@_replace_at_at_aux:Nn}
+% \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
@@ -1034,7 +1035,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_detect_internals:N}
+% \begin{macro}{\@@_detect_internals:N}
 %   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
@@ -1064,10 +1065,19 @@ and all files in that bundle must be distributed together.
             {
               \str_if_eq:NNF \l_@@_detect_internals_tl \g_@@_module_name_tl
                 {
-                  \msg_warning:nnxxx { 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 }
+                  \bool_lazy_and:nnF
+                    { \g_@@_kernel_bool }
+                    {
+                      \str_if_eq_x_p:nn
+                        { \tl_to_str:N \l_@@_detect_internals_tl }
+                        { kernel }
+                    }
+                    {
+                      \msg_warning:nnxxx { 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 }
+                    }
                 }
             }
         }
@@ -1076,8 +1086,8 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux,rEXP]{\@@_signature_base_form:n}
-% \begin{macro}[aux]
+% \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
@@ -1108,7 +1118,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_predicate_from_base:n}
+% \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
@@ -1123,9 +1133,9 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_split_function_do:nn, \@@_split_function_do:on}
-% \begin{macro}[aux]{\@@_get_function_name:n, \@@_get_function_signature:n}
-% \begin{macro}[aux]{\@@_split_function_auxi:w, \@@_split_function_auxii:w}
+% \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}
@@ -1156,7 +1166,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[aux, rEXP]{\@@_key_get_base:nN}
+% \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|.
 %    \begin{macrocode}
@@ -1203,7 +1213,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_base_form_signature_do:nnn}
+% \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
@@ -1234,8 +1244,8 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int, pTF]{\@@_date_compare:nNn}
-% \begin{macro}[aux]{\@@_date_compare_aux:nnnNnnn, \@@_date_compare_aux:w}
+% \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.
@@ -1279,7 +1289,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_gprop_name:n, \@@_lseq_name:n}
+% \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
@@ -1318,6 +1328,8 @@ and all files in that bundle must be distributed together.
     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.~
@@ -1360,6 +1372,13 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 %
 %    \begin{macrocode}
+\DeclareOption { kernel }
+  { \bool_gset_true:N \g_@@_kernel_bool }
+\DeclareOption { stdmodule }
+  { \bool_gset_false:N \g_@@_kernel_bool }
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \DeclareOption { cm-default }
   { \bool_gset_false:N \g_@@_lmodern_bool }
 \DeclareOption { lm-default }
@@ -1368,7 +1387,7 @@ and all files in that bundle must be distributed together.
 %
 %    \begin{macrocode}
 \DeclareOption* { \PassOptionsToClass { \CurrentOption } { article } }
-\ExecuteOptions { full, nocheck, nochecktest, lm-default }
+\ExecuteOptions { full, kernel, nocheck, nochecktest, lm-default }
 \PassOptionsToClass { a4paper } { article }
 %    \end{macrocode}
 %
@@ -1480,7 +1499,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int]{\ifnot@excluded}
+% \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
@@ -1498,7 +1517,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 %
 % \begin{macro}{\pdfstringnewline}
-% \begin{macro}[aux]{\@@_pdfstring_newline:w}
+% \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{xparse}
@@ -1531,7 +1550,7 @@ and all files in that bundle must be distributed together.
 % later.)
 %
 % \begin{macro}{\list}
-% \begin{macro}[aux]{\@@_oldlist:nn}
+% \begin{macro}{\@@_oldlist:nn}
 %   Customise lists.
 %    \begin{macrocode}
 \cs_new_eq:NN \@@_oldlist:nn \list
@@ -1641,7 +1660,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]
+% \begin{macro}
 %   {
 %     \@@_pdfstring_cmd:w,
 %     \@@_pdfstring_cs:w,
@@ -1858,7 +1877,7 @@ and all files in that bundle must be distributed together.
   }
 %    \end{macrocode}
 %
-% \begin{macro}[int]{\@@_cmd:nn, \@@_cmd:no}
+% \begin{macro}{\@@_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
@@ -1867,7 +1886,9 @@ and all files in that bundle must be distributed together.
 %   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}.  Finally, produce an index entry.
+%   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
@@ -1896,11 +1917,16 @@ and all files in that bundle must be distributed together.
         }
       \tl_replace_all:Nnn \l_@@_cmd_tl { ~ } { \@xobeysp }
       \l_@@_cmd_tl
+      \@
     }
     \bool_if:NF \l_@@_cmd_noindex_bool
       {
         \quark_if_no_value:NF \l_@@_cmd_index_tl
-          { \tl_set_eq:NN \l_@@_cmd_tl \l_@@_cmd_index_tl }
+          {
+            \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
           {
@@ -1994,12 +2020,12 @@ and all files in that bundle must be distributed together.
   }
 \cs_new_protected:Npn \@@_typeset_aux:n #1
   {
-    { \color[gray]{0.7} #1 }
+    { \color[gray]{0.5} #1 }
   }
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int]
+% \begin{macro}
 %   {\@@_get_hyper_target:nN, \@@_get_hyper_target:oN, \@@_get_hyper_target:xN}
 %   Create a \pkg{hyperref} anchor from a macro name~|#1| and stores it
 %   in the token list variable~|#2|.  For instance, |\prg_replicate:nn|
@@ -2016,7 +2042,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_names_get_seq:nN}
+% \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
@@ -2050,7 +2076,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_names_parse:, \@@_names_parse_one:n}
+% \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
@@ -2110,8 +2136,8 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_names_typeset:}
-% \begin{macro}[aux]{\@@_names_typeset_auxi:n}
+% \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 to \cs{l_@@_names_block_tl}
 %   cannot use \cs{tl_map_inline:Nn} because the code following |\\|
@@ -2153,7 +2179,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[aux]
+% \begin{macro}
 %   {\@@_names_typeset_auxii:n, \@@_names_typeset_auxii:x}
 %   In case the option |pTF| was given, typeset predicates before the
 %   |TF| functions.  In case the option |noTF| was given, typeset the
@@ -2176,7 +2202,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_names_typeset_block:nN, \@@_names_typeset_block:xN}
+% \begin{macro}{\@@_names_typeset_block:nN, \@@_names_typeset_block:xN}
 %   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}
@@ -2193,6 +2219,64 @@ and all files in that bundle must be distributed together.
 %    \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_set_bool
+      {
+        \bool_if:NTF \l_@@_macro_internal_bool
+          { \prg_return_true: } { \prg_return_false: }
+      }
+      {
+        \tl_if_empty:fTF
+          {
+            \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:NNx
+        \group_end:
+        #1
+          {
+            \l_@@_tmpa_tl
+            \str_if_eq_x:nnF { \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}
@@ -2244,7 +2328,7 @@ and all files in that bundle must be distributed together.
   }
 %    \end{macrocode}
 %
-% \begin{macro}[aux]{\@@_date_set:Nn}
+% \begin{macro}{\@@_date_set:Nn}
 %   Normalize the date into the format \texttt{YYYY-MM-DD}; more
 %   precisely month and day are allowed to be single digits.
 %    \begin{macrocode}
@@ -2261,7 +2345,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_deprecated_on:n}
+% \begin{macro}{\@@_deprecated_on:n}
 %   The date comparison function expects two dates in the YYYY-MM-DD
 %   format (|-|~is not subtraction here).
 %   Complain if a deprecated function should have been removed earlier.
@@ -2279,17 +2363,18 @@ and all files in that bundle must be distributed together.
           { \l_@@_tmpa_tl }
       }
     \bool_set_true:N \l_@@_macro_internal_bool
+    \bool_set_true:N \l_@@_macro_internal_set_bool
   }
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int]{\@@_function:nnw}
+% \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}[int]{\@@_function_end:}
+% \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
@@ -2322,7 +2407,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[aux]
+% \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
@@ -2341,7 +2426,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_function_init:}
+% \begin{macro}{\@@_function_init:}
 %   Complain if \texttt{function} environments are nested.  Clear
 %   various variables.
 %    \begin{macrocode}
@@ -2369,7 +2454,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_shorthand_meta:, \@@_shorthand_meta:w}
+% \begin{macro}{\@@_shorthand_meta:, \@@_shorthand_meta:w}
 %   Allow |<...>| to be used as markup for |\meta{...}|.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_shorthand_meta:
@@ -2378,7 +2463,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_function_reset:}
+% \begin{macro}{\@@_function_reset:}
 %   Clear some variables.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_function_reset:
@@ -2388,7 +2473,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_function_typeset:}
+% \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
@@ -2407,7 +2492,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]
+% \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
@@ -2425,7 +2510,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_function_assemble:}
+% \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
@@ -2475,7 +2560,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_typeset_functions:}
+% \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},
@@ -2502,9 +2587,9 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 %
 % ^^A TODO: collect all index targets from a given function environment in a box and stick it at the top.
-% \begin{macro}[int]
+% \begin{macro}
 %   {\@@_typeset_function_block:nN, \@@_typeset_function_block:xN}
-% \begin{macro}[aux]{\@@_function_index:n, \@@_function_index:x}
+% \begin{macro}{\@@_function_index:n, \@@_function_index:x}
 %   |#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
@@ -2588,7 +2673,7 @@ and all files in that bundle must be distributed together.
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}[internal]{\@@_typeset_dates:}
+% \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.
@@ -2614,7 +2699,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_syntax:w, \@@_syntax_end:}
+% \begin{macro}{\@@_syntax:w, \@@_syntax_end:}
 %   Implement the \env{syntax} environment.
 %    \begin{macrocode}
 \dim_new:N \l_@@_syntax_dim
@@ -2664,13 +2749,22 @@ and all files in that bundle must be distributed together.
   {
     aux .value_forbidden:n = true ,
     aux .code:n =
-      { \bool_set_true:N \l_@@_macro_aux_bool } ,
+      {
+        \msg_warning:nnnn { l3doc } { deprecated-option }
+          { aux } { function/macro }
+      } ,
     internal .value_forbidden:n = true ,
     internal .code:n =
-      { \bool_set_true:N \l_@@_macro_internal_bool } ,
+      {
+        \bool_set_true:N \l_@@_macro_internal_bool
+        \bool_set_true:N \l_@@_macro_internal_set_bool
+      } ,
     int .value_forbidden:n = true ,
     int .code:n =
-      { \bool_set_true:N \l_@@_macro_internal_bool } ,
+      {
+        \bool_set_true:N \l_@@_macro_internal_bool
+        \bool_set_true:N \l_@@_macro_internal_set_bool
+      } ,
     var .value_forbidden:n = true ,
     var .code:n =
       { \bool_set_true:N \l_@@_macro_var_bool } ,
@@ -2716,7 +2810,7 @@ and all files in that bundle must be distributed together.
   }
 %    \end{macrocode}
 %
-% \begin{macro}[int]{\@@_macro:nnw}
+% \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{xparse}.  First
 %   initialize some variables before applying the \meta{options}, then
@@ -2732,7 +2826,6 @@ and all files in that bundle must be distributed together.
     \keys_set:nn { l3doc/macro } {#1}
     \@@_names_get_seq:nN {#2} \l_@@_names_seq
     \@@_names_parse:
-    \@@_macro_adjust_internal:
     \@@_macro_save_names:
     \@@_names_typeset:
     \@@_macro_dump:
@@ -2741,7 +2834,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_init:}
+% \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).
@@ -2749,8 +2842,8 @@ and all files in that bundle must be distributed together.
 \cs_new_protected:Npn \@@_macro_init:
   {
     \int_incr:N \l_@@_nested_macro_int
-    \bool_set_false:N \l_@@_macro_aux_bool
     \bool_set_false:N \l_@@_macro_internal_bool
+    \bool_set_false:N \l_@@_macro_internal_set_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
@@ -2777,7 +2870,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_reset:}
+% \begin{macro}{\@@_macro_reset:}
 %   We ensure that \cs{cs} commands nested inside a macro whose module
 %   is imposed are not affected.
 %    \begin{macrocode}
@@ -2788,53 +2881,27 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_adjust_internal:}
-%   If the macros are neither marked as internal nor auxiliary, and all
-%   macros in \cs{l_@@_names_seq} contain |__| then mark them as being
-%   internal.
-%    \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_adjust_internal:
-  {
-    \bool_if:NF \l_@@_macro_internal_bool
-      {
-        \bool_if:NF \l_@@_macro_aux_bool
-          {
-            \bool_set_true:N \l_@@_macro_internal_bool
-            \seq_map_inline:Nn \l_@@_names_seq
-              {
-                \tl_if_in:noF {##1} { \tl_to_str:n { __ } }
-                  { \bool_set_false:N \l_@@_macro_internal_bool }
-              }
-          }
-      }
-  }
-%    \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[aux]{\@@_macro_save_names:}
+% \begin{macro}{\@@_macro_save_names:}
 %   The list of names defined in a set of \env{macro} environments is
-%   eventually used to display on which page they are documented.
+%   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}.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_macro_save_names:
   {
-    \tl_map_inline:Nn \l_@@_names_block_tl
+    \tl_if_empty:NTF \l_@@_macro_documented_tl
+      { \@@_names_block_base_map:N \@@_macro_save_names_aux:n }
       {
-        \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
-        \seq_gput_right:Nx \g_@@_nested_names_seq
-          {
-            \l_@@_tmpa_tl
-            \str_if_eq_x:nnF { \l_@@_tmpb_tl } { \scan_stop: }
-              { : \l_@@_tmpb_tl }
-            \bool_if:NT \l_@@_macro_TF_bool { TF }
-          }
+        \seq_gput_right:Nf \g_@@_nested_names_seq
+          { \exp_after:wN \token_to_str:N \l_@@_macro_documented_tl }
       }
   }
+\cs_new_protected:Npn \@@_macro_save_names_aux:n #1
+  { \seq_gput_right:Nn \g_@@_nested_names_seq {#1} }
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_dump:}
+% \begin{macro}{\@@_macro_dump:}
 %   This calls |\makelabel{}|
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_macro_dump:
@@ -2858,7 +2925,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_typeset_block:nN}
+% \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}
@@ -2908,7 +2975,7 @@ and all files in that bundle must be distributed together.
     \DoNotIndex {#1}
     \bool_if:NT #2
       {
-        \bool_if:NF \l_@@_macro_aux_bool
+        \@@_if_macro_internal:nF {#1}
           { \seq_gput_right:Nn \g_doc_macros_seq {#1} }
         \hbox_set:Nw \l_@@_macro_index_box
           \hbox_unpack_clear:N \l_@@_macro_index_box
@@ -2922,7 +2989,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_typeset_one:nN}
+% \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
@@ -2970,7 +3037,7 @@ and all files in that bundle must be distributed together.
   }
 \cs_new_protected:Npn \@@_macroname_prefix:n #1
   {
-    \bool_if:NTF \l_@@_macro_aux_bool
+    \@@_if_macro_internal:nTF {#1}
       { \@@_typeset_aux:n {#1} } {#1}
   }
 \cs_generate_variant:Nn \@@_macroname_prefix:n { o }
@@ -3046,7 +3113,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_test_missing:n}
+% \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.
@@ -3069,7 +3136,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_end:}
+% \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
@@ -3082,15 +3149,12 @@ and all files in that bundle must be distributed together.
     \endtrivlist
     \@@_macro_end_check_tested:
     \int_compare:nNnT \l_@@_nested_macro_int = 1
-      {
-        \@@_macro_end_style:n { \@@_print_end_definition: }
-        \seq_gclear:N \g_@@_nested_names_seq
-      }
+      { \@@_macro_end_style:n { \@@_print_end_definition: } }
   }
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_end_check_tested:}
+% \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.
@@ -3100,14 +3164,15 @@ and all files in that bundle must be distributed together.
     \bool_lazy_all:nT
      {
        { \g_@@_checktest_bool }
-       { ! \l_@@_macro_aux_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:Nx \g_@@_not_tested_seq
          {
-           \seq_use:Nn \l_@@_names_seq { , }
+           \seq_use:Nn \l_@@_tmpa_seq { , }
            \bool_if:NTF \l_@@_macro_pTF_bool {~(pTF)}
              { \bool_if:NT \l_@@_macro_TF_bool {~(TF)} }
          }
@@ -3116,7 +3181,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_macro_end_style:n}
+% \begin{macro}{\@@_macro_end_style:n}
 %   Style for the extra information at the end of a top-level
 %   \env{macro} environment.
 %    \begin{macrocode}
@@ -3128,7 +3193,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]
+% \begin{macro}
 %   {
 %     \@@_print_end_definition:,
 %     \@@_macro_end_wrap_item:n,
@@ -3164,33 +3229,23 @@ and all files in that bundle must be distributed together.
   }
 \cs_new_protected:Npn \@@_print_documented:
   {
-    \bool_lazy_or:nnF
-      { \l_@@_macro_aux_bool }
-      { \l_@@_macro_internal_bool }
+    \seq_gset_filter:NNn \g_@@_nested_names_seq
+      \g_@@_nested_names_seq
+      { ! \@@_if_macro_internal_p:n {##1} }
+    \seq_if_empty:NF \g_@@_nested_names_seq
       {
         \int_set:Nn \l_@@_tmpa_int
           { \seq_count:N \g_@@_nested_names_seq }
-        \tl_if_empty:NTF \l_@@_macro_documented_tl
-          {
-            \tl_set:Nx \l_@@_macro_documented_tl
-              { \seq_item:Nn \g_@@_nested_names_seq { 1 } }
-          }
-          {
-            \tl_set:Nf \l_@@_macro_documented_tl
-              {
-                \exp_after:wN \token_to_str:N
-                \l_@@_macro_documented_tl
-              }
-          }
         \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:oN
-          \l_@@_macro_documented_tl
+        \@@_get_hyper_target:xN
+          { \seq_item:Nn \g_@@_nested_names_seq { 1 } }
           \l_@@_tmpa_tl
         \exp_args:Nx \pageref { \l_@@_tmpa_tl } .
       }
+    \seq_gclear:N \g_@@_nested_names_seq
   }
 %    \end{macrocode}
 % \end{macro}
@@ -3378,7 +3433,7 @@ and all files in that bundle must be distributed together.
 %
 % \begin{macro}
 %   {\StopEventually, \Finale, \AlsoImplementation, \OnlyDescription}
-% \begin{variable}[aux]{\g_@@_finale_tl}
+% \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.
@@ -3405,7 +3460,7 @@ and all files in that bundle must be distributed together.
 % \end{variable}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_input:n}
+% \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}
@@ -3559,7 +3614,7 @@ and all files in that bundle must be distributed together.
 %
 % \subsubsection{The \env{macrocode} environment}
 %
-% \begin{macro}[aux]{\xmacro@code, \@@_xmacro_code:n, \@@_xmacro_code:w}
+% \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
@@ -3823,7 +3878,7 @@ and all files in that bundle must be distributed together.
 %
 % \subsubsection{Internal index commands}
 %
-% \begin{macro}[int]{\it@is@a}
+% \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.
@@ -3843,7 +3898,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_special_index:nn}
+% \begin{macro}{\@@_special_index:nn}
 % ^^A TODO this override is somewhat a hack
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_special_index:nn #1#2
@@ -3996,7 +4051,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_quote_special_char:N}
+% \begin{macro}{\@@_quote_special_char:N}
 % Quote some special characters.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_quote_special_char:N #1
@@ -4012,7 +4067,7 @@ and all files in that bundle must be distributed together.
 %
 % \subsubsection{Finding sort-key and module}
 %
-% \begin{macro}[aux]{\@@_key_get:n}
+% \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
@@ -4058,7 +4113,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_key_trim_module:n, \@@_key_drop_underscores:}
+% \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}.
@@ -4078,7 +4133,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_key_func:}
+% \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
@@ -4097,7 +4152,7 @@ and all files in that bundle must be distributed together.
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[aux]{\@@_key_var:, \@@_key_get_module:}
+% \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
-- 
cgit v1.2.3

