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