[latex3-commits] [l3svn] r6683 - l3doc: Keep track of TF as an argument of auxiliaries (fixes #116)
noreply at latex-project.org
noreply at latex-project.org
Fri Aug 19 17:20:36 CEST 2016
Author: bruno
Date: 2016-08-19 17:20:36 +0200 (Fri, 19 Aug 2016)
New Revision: 6683
Modified:
trunk/l3kernel/l3doc.dtx
Log:
l3doc: Keep track of TF as an argument of auxiliaries (fixes #116)
Earlier, TF was appended to macro/function names according to
the value of some local boolean. To typeset predicates this
boolean was locally set to false, but since functions are
typeset in a tabular, the setting did not last long enough,
leading to absurd displays like \bool_if_p:cTF. Using a
global variable would be messy so I decided to carry the
boolean as an argument of every auxiliary that needs the info.
Modified: trunk/l3kernel/l3doc.dtx
===================================================================
--- trunk/l3kernel/l3doc.dtx 2016-08-19 07:54:39 UTC (rev 6682)
+++ trunk/l3kernel/l3doc.dtx 2016-08-19 15:20:36 UTC (rev 6683)
@@ -714,6 +714,9 @@
% signatures, or no signature) and the associated value is a comma
% list of variants or \cs{scan_stop:} to denote the absence of
% signature.
+% The reason we use base functions rather than their base name is to
+% avoid treating \cs{clist_count:n} and \cs{clist_count:N} as
+% variants.
% \begin{macrocode}
\prop_new:N \l_@@_names_block_prop
% \end{macrocode}
@@ -739,7 +742,7 @@
%
% \begin{variable}[int]{\g_@@_nested_names_seq}
% Collects all macros in nested \env{macro} environments, to use them
-% in the ``End definition'' text.
+% in the \enquote{End definition} text.
% \begin{macrocode}
\seq_new:N \g_@@_nested_names_seq
% \end{macrocode}
@@ -1844,7 +1847,7 @@
% \subsubsection{Common between \env{macro} and \env{function}}
%
% \begin{macro}{\@@_typeset_TF:, \@@_typeset_aux:n}
-% Used by \cs{@@_macro_single:nN} and in the \env{function} environment
+% 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_TF:
@@ -1867,22 +1870,20 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_get_hyper_target:nN}
+% \begin{macro}[int]
+% {\@@_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|
% gives |doc/function//prg/replicate:nn|.
% \begin{macrocode}
\cs_new_protected:Npn \@@_get_hyper_target:nN #1#2
{
- \tl_set:Nx #2
- {
- \tl_to_str:n {#1}
- \bool_if:NT \l_@@_macro_TF_bool { \tl_to_str:n {TF} }
- }
+ \tl_set:Nx #2 { \tl_to_str:n {#1} }
\tl_replace_all:Nxn #2 { \iow_char:N \_ } { / }
\tl_remove_all:Nx #2 { \iow_char:N \\ }
\tl_put_left:Nn #2 { doc/function// }
}
+\cs_generate_variant:Nn \@@_get_hyper_target:nN { o , x }
% \end{macrocode}
% \end{macro}
%
@@ -1957,7 +1958,11 @@
\cs_new_protected:Npn \@@_names_parse_one:n #1
{
\@@_base_form_signature_do:nnn {#1}
- { \prop_put:Nnn \l_@@_names_block_prop }
+ {
+ \bool_if:NT \l_@@_macro_TF_bool
+ { \msg_error:nnn { l3doc } { no-signature-TF } {#1} }
+ \prop_put:Nnn \l_@@_names_block_prop
+ }
{ \@@_clist_prop_put_right:Nxn \l_@@_names_block_prop }
}
% \end{macrocode}
@@ -1996,12 +2001,8 @@
{ ~ } { \c_catcode_other_space_tl }
\tl_if_eq:nnTF {#2} { \scan_stop: }
{
- \bool_if:NTF \l_@@_macro_TF_bool
- { \msg_error:nnn { l3doc } { no-signature-TF } {#1} }
- {
- \clist_gclear:N \g_@@_variants_clist
- \@@_names_typeset_auxii:x { \g_@@_base_name_tl }
- }
+ \clist_gclear:N \g_@@_variants_clist
+ \@@_names_typeset_auxii:x { \g_@@_base_name_tl }
}
{
\clist_gset:Nn \g_@@_variants_clist {#2}
@@ -2021,28 +2022,27 @@
{
\bool_if:NT \l_@@_macro_pTF_bool
{
- \bool_set_false:N \l_@@_macro_TF_bool
- \@@_names_typeset_block:x
+ \@@_names_typeset_block:xN
{ \@@_predicate_from_base:n {#1} }
- \bool_set_true:N \l_@@_macro_TF_bool
+ \c_false_bool
}
- \@@_names_typeset_block:n {#1}
+ \@@_names_typeset_block:nN {#1} \l_@@_macro_TF_bool
}
\cs_generate_variant:Nn \@@_names_typeset_auxii:n { x }
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_names_typeset_block:n, \@@_names_typeset_block:x}
+% \begin{macro}[aux]{\@@_names_typeset_block:nN, \@@_names_typeset_block:xN}
% Names in \env{function} and \env{macro} environments are typeset
% differently. A block is a function with all its variants.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_names_typeset_block:n
+\cs_new_protected:Npn \@@_names_typeset_block:nN
{
\int_compare:nNnTF \l_@@_nested_macro_int = 0
- { \@@_typeset_function_block:n }
- { \@@_macro_typeset_block:n }
+ { \@@_typeset_function_block:nN }
+ { \@@_macro_typeset_block:nN }
}
-\cs_generate_variant:Nn \@@_names_typeset_block:n { x }
+\cs_generate_variant:Nn \@@_names_typeset_block:nN { x }
% \end{macrocode}
% \end{macro}
%
@@ -2317,23 +2317,23 @@
%
% ^^A TODO: collect all index targets from a given function environment in a box and stick it at the top.
% \begin{macro}[int]
-% {\@@_typeset_function_block:n, \@@_typeset_function_block:x}
+% {\@@_typeset_function_block:nN, \@@_typeset_function_block:xN}
% \begin{macro}[aux]{\@@_function_index:n, \@@_function_index:x}
-% The argument is a csname.
+% |#1| is a csname, |#2| a boolean indicating whether to add |TF| or not.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_typeset_function_block:n #1
+\cs_new_protected:Npn \@@_typeset_function_block:nN #1#2
{
\@@_function_index:x
- { #1 \bool_if:NT \l_@@_macro_TF_bool { \tl_to_str:n {TF} } }
- \@@_function_label:x {#1}
+ { #1 \bool_if:NT #2 { \tl_to_str:n {TF} } }
+ \@@_function_label:xN {#1} #2
#1
- \bool_if:NT \l_@@_macro_TF_bool { \@@_typeset_TF: }
+ \bool_if:NT #2 { \@@_typeset_TF: }
\@@_typeset_expandability:
\clist_if_empty:NF \g_@@_variants_clist
- { \@@_typeset_variant_list:n {#1} }
+ { \@@_typeset_variant_list:nN {#1} #2 }
\\
}
-\cs_generate_variant:Nn \@@_typeset_function_block:n { x }
+\cs_generate_variant:Nn \@@_typeset_function_block:nN { x }
\cs_new_protected:Npn \@@_function_index:n #1
{
\seq_gput_right:Nn \g_doc_functions_seq {#1}
@@ -2359,8 +2359,9 @@
}
% \end{macrocode}
%
+% |#1| is the function, |#2| whether to add |TF|.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_typeset_variant_list:n #1
+\cs_new_protected:Npn \@@_typeset_variant_list:nN #1#2
{
\\
\@@_typeset_aux:n { \@@_get_function_name:n {#1} }
@@ -2372,11 +2373,12 @@
\clist_use:Nn \g_@@_variants_clist { \textrm| }
\textrm)
}
- \bool_if:NT \l_@@_macro_TF_bool { \@@_typeset_TF: }
+ \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:
{
@@ -2384,21 +2386,26 @@
{
\clist_map_inline:Nn \l_@@_function_label_clist
{
- \exp_args:No \@@_get_hyper_target:nN
- { \token_to_str:N ##1 } \l_@@_tmpa_tl
+ \@@_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:n #1
+\cs_new_protected:Npn \@@_function_label:nN #1#2
{
\bool_if:NF \l_@@_no_label_bool
{
- \@@_get_hyper_target:nN {#1} \l_@@_tmpa_tl
+ \@@_get_hyper_target:xN
+ {
+ \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:n { x }
+\cs_generate_variant:Nn \@@_function_label:nN { x }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2523,7 +2530,7 @@
% comma-list of \meta{names}, read verbatim by \pkg{xparse}. 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:nN} to each (this step is more subtle than
+% \cs{@@_macro_single:nNN} to each (this step is more subtle than
% \cs{seq_map_function:NN} because of |TF|/|pTF|). Finally typeset
% the macro names in the margin.
% \begin{macrocode}
@@ -2535,6 +2542,7 @@
\@@_names_get_seq:nN {#2} \l_@@_names_seq
\@@_names_parse:
\@@_macro_adjust_internal:
+ \@@_macro_save_names:
\@@_names_typeset:
\@@_macro_dump:
\@@_macro_reset:
@@ -2611,6 +2619,21 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}[aux]{\@@_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.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_macro_save_names:
+ {
+ \prop_map_inline:Nn \l_@@_names_block_prop
+ {
+ \seq_gput_right:Nx \g_@@_nested_names_seq
+ { ##1 \bool_if:NT \l_@@_macro_TF_bool { TF } }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}[aux]{\@@_macro_dump:}
% This calls |\makelabel{}|
% \begin{macrocode}
@@ -2635,31 +2658,32 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_macro_typeset_block:n}
-% Used to typeset a macro and its variants.
+% \begin{macro}[aux]{\@@_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:n #1
+\cs_new_protected:Npn \@@_macro_typeset_block:nN #1#2
{
- \@@_macro_single:nN {#1} \c_true_bool
+ \@@_macro_single:nNN {#1} \c_true_bool #2
\clist_if_empty:NF \g_@@_variants_clist
{
- \@@_macro_typeset_variant_list:x
- { \@@_get_function_name:n {#1} }
+ \@@_macro_typeset_variant_list:xN
+ { \@@_get_function_name:n {#1} } #2
}
}
-\cs_generate_variant:Nn \@@_macro_typeset_block:n { x }
-\cs_new_protected:Npn \@@_macro_typeset_variant_list:n #1
+\cs_generate_variant:Nn \@@_macro_typeset_block:nN { x }
+\cs_new_protected:Npn \@@_macro_typeset_variant_list:nN #1#2
{
\clist_map_inline:Nn \g_@@_variants_clist
- { \@@_macro_single:nN { #1 : ##1 } \c_false_bool }
+ { \@@_macro_single:nNN { #1 : ##1 } \c_false_bool #2 }
}
-\cs_generate_variant:Nn \@@_macro_typeset_variant_list:n { x }
+\cs_generate_variant:Nn \@@_macro_typeset_variant_list:nN { x }
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_macro_single:nN}
-% The arguments are a macro name (without |TF|) and a boolean
-% determining whether or not to index.
+% \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.
@@ -2670,21 +2694,17 @@
% The assignments to \cs{saved at macroname} and \cs{saved at indexname}
% are used by \pkg{doc}'s \cs{changes} mechanism.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_single:nN #1#2
+\cs_new_protected:Npn \@@_macro_single:nNN #1#2#3
{
\tl_set:Nn \saved at macroname {#1}
- \@@_macro_typeset_one:n {#1}
- \bool_if:NT \l_@@_macro_TF_bool { \DoNotIndex {#1} }
+ \@@_macro_typeset_one:nN {#1} #3
+ \bool_if:NT #3 { \DoNotIndex {#1} }
\exp_args:Nx \@@_macro_index:nN
- {
- #1
- \bool_if:NT \l_@@_macro_TF_bool { \tl_to_str:n { TF } }
- }
+ { #1 \bool_if:NT #3 { \tl_to_str:n { TF } } }
#2
}
\cs_new_protected:Npn \@@_macro_index:nN #1#2
{
- \seq_gput_right:Nn \g_@@_nested_names_seq {#1}
\DoNotIndex {#1}
\bool_if:NT #2
{
@@ -2702,33 +2722,39 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_macro_typeset_one:n}
+% \begin{macro}[aux]{\@@_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}. Note the space |\ |.
+% |#1| is the macro name, |#2| whether to add |TF|.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_macro_typeset_one:n #1
+\cs_new_protected:Npn \@@_macro_typeset_one:nN #1#2
{
\vbox_set:Nn \l_@@_macro_box
{
\vbox_unpack_clear:N \l_@@_macro_box
- \hbox { \llap { \@@_print_macroname:n {#1} \ } }
+ \hbox { \llap { \@@_print_macroname:nN {#1} #2 \ } }
}
\int_incr:N \l_@@_macro_int
}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_print_macroname:n}
+% \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:n #1
+\cs_new_protected:Npn \@@_print_macroname:nN #1#2
{
\strut
- \@@_get_hyper_target:nN {#1} \l_@@_tmpa_tl
+ \@@_get_hyper_target:xN
+ {
+ \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 }
@@ -2739,7 +2765,7 @@
\tl_replace_all:Nno \l_@@_tmpa_tl
{ ~ } { \c_catcode_other_space_tl }
\@@_macroname_prefix:o \l_@@_tmpa_tl
- \@@_macroname_suffix:
+ \@@_macroname_suffix:N #2
}
}
\cs_new_protected:Npn \@@_macroname_prefix:n #1
@@ -2748,8 +2774,8 @@
{ \@@_typeset_aux:n {#1} } {#1}
}
\cs_generate_variant:Nn \@@_macroname_prefix:n { o }
-\cs_new_protected:Npn \@@_macroname_suffix:
- { \bool_if:NTF \l_@@_macro_TF_bool { \@@_typeset_TF: } { } }
+\cs_new_protected:Npn \@@_macroname_suffix:N #1
+ { \bool_if:NTF #1 { \@@_typeset_TF: } { } }
% \end{macrocode}
% \end{macro}
%
@@ -2954,8 +2980,7 @@
\bool_if:NTF \l_@@_macro_var_bool {variable} {function}
\int_compare:nNnTF \l_@@_tmpa_int = 1 {~is~} {s~are~}
documented~on~page~
- \bool_set_false:N \l_@@_macro_TF_bool
- \exp_args:No \@@_get_hyper_target:nN
+ \@@_get_hyper_target:oN
\l_@@_macro_documented_tl
\l_@@_tmpa_tl
\exp_args:Nx \pageref { \l_@@_tmpa_tl } .
More information about the latex3-commits
mailing list