summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3doc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3doc.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3doc.dtx195
1 files changed, 83 insertions, 112 deletions
diff --git a/macros/latex/contrib/l3kernel/l3doc.dtx b/macros/latex/contrib/l3kernel/l3doc.dtx
index 731748faf4..b6f98aa366 100644
--- a/macros/latex/contrib/l3kernel/l3doc.dtx
+++ b/macros/latex/contrib/l3kernel/l3doc.dtx
@@ -85,7 +85,7 @@ and all files in that bundle must be distributed together.
% require you to do updates, if the class changes.}}
%
% \author{\Team}
-% \date{Released 2023-11-09}
+% \date{Released 2023-12-08}
% \maketitle
% \tableofcontents
%
@@ -469,6 +469,10 @@ and all files in that bundle must be distributed together.
% |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
@@ -695,8 +699,9 @@ and all files in that bundle must be distributed together.
%
% \begin{variable}
% {
-% \l_@@_macro_internal_set_bool,
+% \l_@@_macro_deprecated_bool ,
% \l_@@_macro_internal_bool,
+% \l_@@_macro_nodoc_bool ,
% \l_@@_macro_TF_bool,
% \l_@@_macro_pTF_bool,
% \l_@@_macro_noTF_bool,
@@ -710,8 +715,9 @@ 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_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
@@ -955,56 +961,19 @@ and all files in that bundle must be distributed together.
% \begin{macro}
% {
% \seq_set_split:NoV,
-% \str_case:fn,
-% \tl_count:f,
-% \tl_greplace_all:Nen,
-% \tl_greplace_all:Nno,
-% \tl_if_head_eq_charcode:oNTF,
-% \tl_if_head_eq_charcode:oNT,
-% \tl_if_head_eq_charcode:oNF,
-% \tl_if_head_eq_meaning:VNF,
-% \tl_if_in:noTF,
-% \tl_if_in:ooTF,
-% \tl_if_in:NoTF,
-% \tl_if_in:NoT,
-% \tl_if_in:NoF,
-% \tl_remove_all:Ne,
-% \tl_replace_all:Nen,
-% \tl_replace_all:Nne,
-% \tl_replace_all:Non,
-% \tl_replace_all:Nno,
-% \tl_replace_once:Noo,
-% \tl_to_str:f,
-% \tl_to_str:o,
+% \tl_to_str:f
% }
% 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 }
-\cs_generate_variant:Nn \tl_if_head_eq_meaning:nNF { V }
-\cs_generate_variant:Nn \tl_if_in:nnTF { no , oo }
-\cs_generate_variant:Nn \tl_if_in:NnTF { No }
-\cs_generate_variant:Nn \tl_if_in:NnT { No }
-\cs_generate_variant:Nn \tl_if_in:NnF { No }
-\cs_generate_variant:Nn \tl_remove_all:Nn { Nx }
-\cs_generate_variant:Nn \tl_replace_all:Nnn { Nx , Nnx, No , Nno }
-\cs_generate_variant:Nn \tl_replace_once:Nnn { Noo }
-\cs_generate_variant:Nn \tl_set_rescan:Nnn { NnV }
-\cs_generate_variant:Nn \tl_to_str:n { f , o }
+\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 are there to
+% 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}
@@ -1012,11 +981,11 @@ and all files in that bundle must be distributed together.
{
\int_compare:nNnTF
{ \tl_count:n {#1} }
- < { \tl_count:f { \tl_to_str:f {#1} } }
+ < { \tl_count:e { \tl_to_str:f {#1} } }
{ \prg_return_false: }
{ \prg_return_true: }
}
-\cs_generate_variant:Nn \@@_if_almost_str:nT { V }
+\prg_generate_conditional_variant:Nnn \@@_if_almost_str:n { V } { T }
% \end{macrocode}
% \end{macro}
%
@@ -1110,7 +1079,7 @@ and all files in that bundle must be distributed together.
\cs_new_protected:Npn \@@_detect_internals_aux:N #1
{
\tl_set_eq:NN \l_@@_detect_internals_tl #1
- \tl_replace_all:Non \l_@@_detect_internals_tl { \token_to_str:N _ } { _ }
+ \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
@@ -1993,9 +1962,9 @@ and all files in that bundle must be distributed together.
\bool_if:NT \l_@@_cmd_replace_bool
{
\tl_set_rescan:Nnn \l_@@_tmpb_tl { } { _ }
- \tl_replace_all:Non \l_@@_cmd_tl \l_@@_tmpb_tl { _ }
+ \tl_replace_all:NVn \l_@@_cmd_tl \l_@@_tmpb_tl { _ }
\@@_replace_at_at:N \l_@@_cmd_tl
- \tl_replace_all:Nno \l_@@_cmd_tl { _ } \l_@@_tmpb_tl
+ \tl_replace_all:NnV \l_@@_cmd_tl { _ } \l_@@_tmpb_tl
}
% \end{macrocode}
% Typesetting.
@@ -2075,7 +2044,7 @@ and all files in that bundle must be distributed together.
{
\tl_set_rescan:Nnn \l_@@_tmpb_tl
{ \char_set_catcode:nn { `_ } {##1} } { _ }
- \tl_replace_all:Non \l_@@_tmpa_tl \l_@@_tmpb_tl
+ \tl_replace_all:NVn \l_@@_tmpa_tl \l_@@_tmpb_tl
{ \@@_ensuremath_sb:n }
}
\exp_args:NV \@@_meta_original:n \l_@@_tmpa_tl
@@ -2155,8 +2124,8 @@ and all files in that bundle must be distributed together.
\cs_new_protected:Npn \@@_get_hyper_target:nN #1#2
{
\__kernel_tl_set:Ne #2 { \tl_to_str:n {#1} }
- \tl_replace_all:Nen #2 { \c_underscore_str } { / }
- \tl_remove_all:Ne #2 { \c_backslash_str }
+ \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 }
@@ -2282,8 +2251,8 @@ and all files in that bundle must be distributed together.
{
\seq_pop:NN #1 \l_@@_tmpa_tl
\tl_gset_eq:NN \g_@@_base_name_tl \l_@@_tmpa_tl
- \tl_greplace_all:Nno \g_@@_base_name_tl
- { ~ } { \c_catcode_other_space_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: }
{
@@ -2350,13 +2319,10 @@ and all files in that bundle must be distributed together.
% \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: }
- }
+ \bool_if:NTF \l_@@_macro_internal_bool
+ { \prg_return_true: }
{
- \tl_if_empty:fTF
+ \tl_if_empty:eTF
{
\exp_after:wN \@@_if_macro_internal_aux:w
\tl_to_str:n { #1 ~ __ }
@@ -2437,7 +2403,8 @@ and all files in that bundle must be distributed together.
} ,
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 .code:n = {} , % A stub
+ deprecated .bool_set:N = \l_@@_macro_deprecated_bool ,
+ no-user-doc .bool_set:N = \l_@@_macro_nodoc_bool ,
tested .code:n = { } ,
label .code:n =
{
@@ -2884,18 +2851,14 @@ and all files in that bundle must be distributed together.
\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
- \bool_set_true:N \l_@@_macro_internal_set_bool
- } ,
+ { \bool_set_true:N \l_@@_macro_internal_bool } ,
int .value_forbidden:n = true ,
int .code:n =
- {
- \bool_set_true:N \l_@@_macro_internal_bool
- \bool_set_true:N \l_@@_macro_internal_set_bool
- } ,
+ { \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 } ,
@@ -2934,7 +2897,6 @@ and all files in that bundle must be distributed together.
} ,
added .code:n = {} , % TODO
updated .code:n = {} , % TODO
- deprecated .code:n = {} , % A stub
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 ,
@@ -2977,8 +2939,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_deprecated_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
@@ -3026,8 +2988,8 @@ and all files in that bundle must be distributed together.
\tl_if_empty:NTF \l_@@_macro_documented_tl
{ \@@_names_block_base_map:N \@@_macro_save_names_aux:n }
{
- \seq_gput_right:Nf \g_@@_nested_names_seq
- { \exp_after:wN \token_to_str:N \l_@@_macro_documented_tl }
+ \seq_gput_right:Ne \g_@@_nested_names_seq
+ { \tl_to_str:N \l_@@_macro_documented_tl }
}
}
\cs_new_protected:Npn \@@_macro_save_names_aux:n #1
@@ -3103,7 +3065,6 @@ and all files in that bundle must be distributed together.
{ \@@_get_function_name:n {#1} } #2
}
}
-\cs_generate_variant:Nn \@@_macro_typeset_block:nN { x }
\cs_new_protected:Npn \@@_macro_typeset_variant_list:nN #1#2
{
\seq_map_inline:Nn \g_@@_variants_seq
@@ -3140,7 +3101,12 @@ and all files in that bundle must be distributed together.
\DoNotIndex {#1}
\bool_if:NT #2
{
- \@@_if_macro_internal:nF {#1}
+ \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
@@ -3198,8 +3164,8 @@ and all files in that bundle must be distributed together.
\int_compare:nTF { \str_count:n {#1} <= 28 }
{ \MacroFont } { \MacroLongFont }
\tl_set:Nn \l_@@_tmpa_tl {#1}
- \tl_replace_all:Nno \l_@@_tmpa_tl
- { ~ } { \c_catcode_other_space_tl }
+ \tl_replace_all:NnV \l_@@_tmpa_tl
+ { ~ } \c_catcode_other_space_tl
\@@_macroname_prefix:o \l_@@_tmpa_tl
\@@_macroname_suffix:N #2
}
@@ -3377,8 +3343,8 @@ and all files in that bundle must be distributed together.
\cs_new_protected:Npn \@@_macro_end_wrap_item:n #1
{
\tl_set:Nn \l_@@_tmpa_tl {#1}
- \tl_replace_all:Non \l_@@_tmpa_tl
- { \token_to_str:N _ } { \_ }
+ \tl_replace_all:NVn \l_@@_tmpa_tl
+ \c_underscore_str { \_ }
\texttt { \l_@@_tmpa_tl }
}
\cs_new_protected:Npn \@@_print_end_definition:
@@ -3400,7 +3366,14 @@ and all files in that bundle must be distributed together.
{
\seq_gset_filter:NNn \g_@@_nested_names_seq
\g_@@_nested_names_seq
- { ! \@@_if_macro_internal_p:n {##1} }
+ {
+ ! \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
@@ -3963,18 +3936,18 @@ and all files in that bundle must be distributed together.
\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
- { ##1 \iow_newline: }
- \iow_now:Nn \g_@@_func_iow { > ~ ##1 }
+ { \iow_newline: > ~ ##1 }
}
{
\tl_put_right:Ne \l_@@_doc_undef_tl
- { ##1 \iow_newline: }
- \iow_now:Nn \g_@@_func_iow { ! ~ ##1 }
+ { \iow_newline: ! ~ ##1 }
}
}
\seq_map_inline:Nn \g_doc_macros_seq
@@ -3982,8 +3955,7 @@ and all files in that bundle must be distributed together.
\seq_if_in:NnF \g_doc_functions_seq {##1}
{
\tl_put_right:Ne \l_@@_undoc_def_tl
- { ##1 \iow_newline: }
- \iow_now:Nn \g_@@_func_iow { ? ~ ##1 }
+ { \iow_newline: ? ~ ##1 }
}
}
\@@_functions_typeout:nN
@@ -4012,11 +3984,11 @@ and all files in that bundle must be distributed together.
{
\tl_if_empty:NF #2
{
- \typeout
+ \iow_now:Ne \g_@@_func_iow
{
\c_@@_iow_midrule_tl \iow_newline:
#1 \iow_newline:
- \c_@@_iow_midrule_tl \iow_newline:
+ \c_@@_iow_midrule_tl
#2
}
\tl_clear:N #2
@@ -4367,7 +4339,7 @@ and all files in that bundle must be distributed together.
\__kernel_tl_set:Ne #1 { \tl_to_str:n {#2} }
\@@_if_almost_str:nTF {#2}
{
- \tl_replace_all:Non #1 { \tl_to_str:n { __ } }
+ \tl_replace_all:Nen #1 { \tl_to_str:n { __ } }
{
\verbatimchar
\token_to_str:N \_ \token_to_str:N \_
@@ -4390,8 +4362,8 @@ and all files in that bundle must be distributed together.
}
{
\tl_set:Nn #1 {#2}
- \tl_replace_all:Non #1
- { \c_backslash_str }
+ \tl_replace_all:NVn #1
+ \c_backslash_str
{ \token_to_str:N \bslash \c_space_tl }
}
\@@_quote_special_char:N #1
@@ -4430,27 +4402,26 @@ and all files in that bundle must be distributed together.
% module name, while for \TeX{}/\LaTeXe{} commands the module name is
% |TeX|, and others have an empty module name.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_key_get:n #1
- {
- \@@_key_get_base:nN {#1} \l_@@_index_macro_tl
- \__kernel_tl_set:Ne \l_@@_index_key_tl
- { \tl_to_str:N \l_@@_index_macro_tl }
- \tl_clear:N \l_@@_index_module_tl
- \tl_if_in:NoTF \l_@@_index_key_tl { \tl_to_str:n { __ } }
- { \bool_set_true:N \l_@@_index_internal_bool }
- { \bool_set_false:N \l_@@_index_internal_bool }
- \exp_last_unbraced:NNo
- \tl_if_head_eq_charcode:oNT
- { \l_@@_index_key_tl } \c_backslash_str
- { \@@_key_pop: }
- \tl_if_in:NoTF \l_@@_index_key_tl { \token_to_str:N : }
- { \@@_key_func: }
+\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:Ne \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:NoTF \l_@@_index_key_tl { \token_to_str:N _ }
- { \@@_key_var: }
+ \tl_if_in:NnTF \exp_not:N \l_@@_index_key_tl { \token_to_str:N _ }
+ { \exp_not:N \@@_key_var: }
{
- \tl_if_in:NoT \l_@@_index_key_tl { \token_to_str:N @ }
- { \tl_set:Nn \l_@@_index_module_tl { TeX } }
+ \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 } }
}
}
}
@@ -4476,7 +4447,7 @@ and all files in that bundle must be distributed together.
}
\cs_new_protected:Npn \@@_key_drop_underscores:
{
- \tl_if_head_eq_charcode:oNT { \l_@@_index_key_tl } _
+ \tl_if_head_eq_charcode:VNT \l_@@_index_key_tl _
{ \@@_key_pop: \@@_key_drop_underscores: }
}
% \end{macrocode}
@@ -4491,7 +4462,7 @@ and all files in that bundle must be distributed together.
% \begin{macrocode}
\cs_new_protected:Npn \@@_key_func:
{
- \tl_if_head_eq_charcode:oNT { \l_@@_index_key_tl } .
+ \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
@@ -4527,7 +4498,7 @@ and all files in that bundle must be distributed together.
\exp_args:Ne \tl_if_head_eq_charcode:nNTF
{ \exp_args:No \str_tail:n \l_@@_index_key_tl } _
{
- \str_case:fn { \str_head: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 } }