[latex3-commits] [l3svn] r6651 - Add key "verb" to document macros with weird names
noreply at latex-project.org
noreply at latex-project.org
Sun Aug 14 17:41:10 CEST 2016
Author: bruno
Date: 2016-08-14 17:41:10 +0200 (Sun, 14 Aug 2016)
New Revision: 6651
Modified:
trunk/l3kernel/l3doc.dtx
Log:
Add key "verb" to document macros with weird names
Modified: trunk/l3kernel/l3doc.dtx
===================================================================
--- trunk/l3kernel/l3doc.dtx 2016-08-14 12:17:20 UTC (rev 6650)
+++ trunk/l3kernel/l3doc.dtx 2016-08-14 15:41:10 UTC (rev 6651)
@@ -282,7 +282,7 @@
% \end{syntax}
% These commands are provided to typeset control sequences.
% |\cmd\foo| produces \enquote{\cmd\foo} and |\cs{foo}| produces the
-% same (\enquote{\texttt{\string\foo|}}). In general, \cs{cs} is more robust since
+% same. In general, \cs{cs} is more robust since
% it doesn't rely on catcodes being \enquote{correct} and is therefore
% recommended.
%
@@ -426,6 +426,7 @@
% environment. Some changes in \pkg{l3doc}: it now accepts
% comma-separated lists of functions, to avoid a very large number of
% consecutive |\end{macro}| statements.
+% Spaces and new lines are ignored (the option |[verb]| prevents this).
% \begin{verbatim}
% % \begin{macro}{\foo:N, \foo:c}
% % \begin{macrocode}
@@ -570,6 +571,7 @@
% {
% \tl_count:f,
% \tl_greplace_all:Nxn,
+% \tl_greplace_all:Nno,
% \tl_if_head_eq_charcode:oNTF,
% \tl_if_head_eq_charcode:oNT,
% \tl_if_head_eq_charcode:oNF,
@@ -589,7 +591,7 @@
% A few missing variants.
% \begin{macrocode}
\cs_generate_variant:Nn \tl_count:n { f }
-\cs_generate_variant:Nn \tl_greplace_all:Nnn { Nx }
+\cs_generate_variant:Nn \tl_greplace_all:Nnn { Nx , Nno }
\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 }
@@ -607,10 +609,10 @@
%
% \begin{macro}[int]{\@@_replace_at_at:N}
% \begin{macro}[aux]{\@@_replace_at_at_aux:Nn}
-% If there is no \meta{module~name}, do nothing. Otherwise replace
-% all other-|@| by letter-|@| and all other-|_| by letter-|_|, then
-% replace |_@@| by |__|\meta{module~name} and |@@| by
-% |__|\meta{module~name} too. The result contains |_| with category
+% The goal is to replace |@@| by the current module name. If there is
+% no \meta{module~name}, do nothing. Otherwise, sanitize the catcodes
+% of |@| and~|_| and replace both |_@@| and |@@| by
+% |__|\meta{module~name}. The result contains |_| with category
% code letter because this is what the |macrocode| environment
% expects. Other use cases can apply \cs{tl_to_str:n} if needed.
% Note that we include spaces between the
@@ -637,26 +639,35 @@
% \end{macro}
%
% \begin{macro}[aux]{\@@_verb_get_seq:nN}
-% The argument~|#1| is given with catcodes $10$ (space), $12$ (other)
-% and $13$ (active). Turn active characters to other. Remove any
-% \enquote{\%} character at the beginning of a line. Remove tabs and
-% newlines. Finally, convert |_@@| and |@@| to |__|\meta{module name}
-% (if it is non-empty). At this point, \cs{l_@@_tmpa_tl} contains a
-% comma-delimited list of names, where |@| and~|_| have category code
-% letter. Turn it to a string, parse it as a comma-delimited list,
-% and turn the result into a sequence of function/macro names.
+% The argument~|#1| (argument of a |function| or |macro| environment)
+% has catcodes $10$ (space), $12$ (other) and $13$ (active). Sanitize
+% catcodes. If the |verb| option was used, output a one-item
+% sequence. Otherwise, remove any \enquote{\%} character at the
+% beginning of a line. Remove tabs and newlines. Finally, convert
+% |_@@| and |@@| to |__|\meta{module name} (if it is non-empty). At
+% this point, \cs{l_@@_tmpa_tl} contains a comma-delimited list of
+% names, where |@| and~|_| have category code letter. Turn it to a
+% string, parse it as a comma-delimited list (in particular this
+% removes spaces), and output a sequence of function/macro names.
% \begin{macrocode}
\cs_new_protected:Npn \@@_verb_get_seq:nN #1#2
{
\tl_set:Nx \l_@@_tmpa_tl { \tl_to_str:n {#1} }
- \tl_remove_all:Nx \l_@@_tmpa_tl
- { \iow_char:N \^^M \iow_char:N \% }
- \tl_remove_all:Nx \l_@@_tmpa_tl { \tl_to_str:n { ^ ^ A } }
- \tl_remove_all:Nx \l_@@_tmpa_tl { \iow_char:N \^^I }
- \tl_remove_all:Nx \l_@@_tmpa_tl { \iow_char:N \^^M }
- \@@_replace_at_at:N \l_@@_tmpa_tl
- \exp_args:NNx \seq_set_from_clist:Nn #2
- { \tl_to_str:N \l_@@_tmpa_tl }
+ \bool_if:NTF \l_@@_verb_name_bool
+ {
+ \seq_clear:N #2
+ \seq_put_right:NV #2 \l_@@_tmpa_tl
+ }
+ {
+ \tl_remove_all:Nx \l_@@_tmpa_tl
+ { \iow_char:N \^^M \iow_char:N \% }
+ \tl_remove_all:Nx \l_@@_tmpa_tl { \tl_to_str:n { ^ ^ A } }
+ \tl_remove_all:Nx \l_@@_tmpa_tl { \iow_char:N \^^I }
+ \tl_remove_all:Nx \l_@@_tmpa_tl { \iow_char:N \^^M }
+ \@@_replace_at_at:N \l_@@_tmpa_tl
+ \exp_args:NNx \seq_set_from_clist:Nn #2
+ { \tl_to_str:N \l_@@_tmpa_tl }
+ }
}
% \end{macrocode}
% \end{macro}
@@ -712,7 +723,7 @@
% \end{macro}
%
% \begin{macro}[int]{\CodedocUnexpandedTokens}
-% \begin{macro}[aux]{\CodedocUnexpandedTokens }
+% \begin{macro}[aux,verb]{\CodedocUnexpandedTokens }
% \begin{macro}[aux]{\@@_exp_not:n}
% Function used as \cs{CodedocUnexpandedTokens} \meta{junk}
% \Arg{argument}. The braces are necessary, and \meta{junk}, ignored,
@@ -873,6 +884,14 @@
% \end{macrocode}
% \end{variable}
%
+% \begin{variable}[int]{\l_@@_verb_name_bool}
+% Set to |true| if the main argument of a macro/function environment
+% should be used as is, without removing any comma or space.
+% \begin{macrocode}
+\bool_new:N \l_@@_verb_name_bool
+% \end{macrocode}
+% \end{variable}
+%
% \begin{variable}[int]{\l_@@_function_input_seq, \l_@@_macro_input_seq}
% Both the \env{function} and the \env{macro} environments read their
% argument verbatim, then remove percent signs (at the beginning of
@@ -1014,7 +1033,7 @@
% \end{macrocode}
% \end{macro}
%
-% Bruno: can I delete this next line?
+% ^^A Bruno: what does the next line do?
% \begin{macrocode}
% \int_new:N \c at CodelineNo
% \end{macrocode}
@@ -1610,6 +1629,7 @@
updated .tl_set:N = \l_@@_date_updated_tl ,
tested .code:n = { } ,
no-label .bool_set:N = \l_@@_no_label_bool ,
+ verb .bool_set:N = \l_@@_verb_name_bool ,
}
% \end{macrocode}
%
@@ -1688,6 +1708,7 @@
\bool_set_false:N \l_@@_macro_EXP_bool
\bool_set_false:N \l_@@_macro_rEXP_bool
\bool_set_false:N \l_@@_no_label_bool
+ \bool_set_false:N \l_@@_verb_name_bool
\char_set_catcode_active:N \<
\cs_set_protected:Npn < ##1 > { \meta {##1} }
}
@@ -1898,6 +1919,9 @@
% the \cs{@@_typeset_functions_auxiii:N} auxiliary.
%
% Braces around |##1| are crucial since this item can be empty.
+%
+% In the base name, spaces are replaced by other spaces to ensure they
+% get displayed in case there are any.
% \begin{macrocode}
\cs_new_protected:Npn \@@_typeset_functions:
{
@@ -1907,6 +1931,8 @@
\cs_new_protected:Npn \@@_typeset_functions_auxi:nn #1#2
{
\tl_gset:Nn \g_@@_base_name_tl {#1}
+ \tl_greplace_all:Nno \g_@@_base_name_tl
+ { ~ } { \c_catcode_other_space_tl }
\prop_clear:N \l_@@_variants_prop
\clist_map_inline:nn {#2}
{
@@ -2146,6 +2172,7 @@
} ,
added .code:n = {} , % TODO
updated .code:n = {} , % TODO
+ verb .bool_set:N = \l_@@_verb_name_bool ,
}
% \end{macrocode}
%
@@ -2185,6 +2212,7 @@
\bool_set_false:N \l_@@_macro_rEXP_bool
\bool_set_false:N \l_@@_macro_var_bool
\bool_set_false:N \l_@@_macro_tested_bool
+ \bool_set_false:N \l_@@_verb_name_bool
\cs_set_eq:NN \testfile \@@_print_testfile:n
\box_clear:N \l_@@_macro_index_box
\vbox_set:Nn \l_@@_macro_box
@@ -2302,6 +2330,8 @@
% \end{macro}
%
% \begin{macro}{\@@_print_macroname:n}
+% 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
{
@@ -2317,9 +2347,13 @@
}
{ \use:n }
{
- \int_compare:nTF { \tl_count:n {#1} <= 28 }
+ \int_compare:nTF { \str_count:n {#1} <= 28 }
{ \MacroFont } { \MacroLongFont }
- \@@_macroname_prefix:n {#1} \@@_macroname_suffix:
+ \tl_set:Nn \l_@@_tmpa_tl {#1}
+ \tl_replace_all:Nno \l_@@_tmpa_tl
+ { ~ } { \c_catcode_other_space_tl }
+ \@@_macroname_prefix:o \l_@@_tmpa_tl
+ \@@_macroname_suffix:
}
}
\cs_new_protected:Npn \@@_macroname_prefix:n #1
@@ -2327,6 +2361,7 @@
\bool_if:NTF \l_@@_macro_aux_bool
{ \@@_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: } { } }
% \end{macrocode}
More information about the latex3-commits
mailing list