diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3doc.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3doc.dtx | 468 |
1 files changed, 257 insertions, 211 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx index f6aac3cc544..67d073be832 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx @@ -78,7 +78,7 @@ Do not distribute a modified version of this file. % \end{macrocode} % %<*driver|class> -\GetIdInfo$Id: l3doc.dtx 3255 2012-01-28 20:31:12Z joseph $ +\GetIdInfo$Id: l3doc.dtx 3464 2012-02-26 15:30:29Z bruno $ {L3 Experimental documentation class} %</driver|class> % @@ -122,7 +122,7 @@ Do not distribute a modified version of this file. % but not before the good ideas in \pkg{hypdoc}, \cls{xdoc2}, \pkg{docmfp}, and % \cls{gmdoc} are incorporated. % -% \textbf{It is even less stable than the main \pkg{expl3} packages. Use at own risk!} +% \textbf{It is much less stable than the main \pkg{expl3} packages. Use at own risk!} % % It is written as a `self-contained' docstrip file: executing % "latex l3doc.dtx" @@ -200,7 +200,6 @@ Do not distribute a modified version of this file. % their use. % \item Generalise \env{function}/\env{macro} for documenting `other things', % such as environment names, package options, even keyval options. -% \item Use \pkg{xparse}. % \item New function like "\part" but for files (remove awkward `File' as "\partname"). % \item Something better to replace "\StopEventually"; I'm thinking two % environments \env{documentation} and \env{implementation} that can @@ -208,6 +207,7 @@ Do not distribute a modified version of this file. % (This has been implemented but needs further consideration.) % \item Hyperlink documentation and implementation of macros (see % the \textsc{dtx} file of \pkg{svn-multi} v2 as an example). +% This is partially done, now, but should be improved. % \end{itemize} % % \section{Bugs} @@ -277,21 +277,24 @@ Do not distribute a modified version of this file. % \begin{framed} % \vspace{-\baselineskip} % \begin{verbatim} -% \begin{function}{ \function_one: , \function_two: } +% \begin{function}{ \function_one , \function_two: } % \begin{syntax} -% "\foo_bar:" \Arg{meta} <test1> +% "\foo_bar:" \Arg{meta} <test_1> % \end{syntax} % <description> % \end{function} % \end{verbatim} -% \vspace{-2\baselineskip} % \hrulefill +% \par +% \hspace*{0.25\textwidth} +% \begin{minipage}{0.5\textwidth} % \begin{function}{ \function_one: , \function_two: } % \begin{syntax} -% "\foo_bar:" \Arg{meta} <test1> +% "\foo_bar:" \Arg{meta} <test_1> % \end{syntax} % <description> % \end{function} +% \end{minipage} % \end{framed} % % Function environments take an optional argument to indicate whether the function(s) it @@ -308,24 +311,19 @@ Do not distribute a modified version of this file. % <description> % \end{function} % \end{verbatim} -% \vspace{-2\baselineskip} % \hrulefill +% \par +% \hspace*{0.25\textwidth} +% \begin{minipage}{0.5\textwidth} % \begin{function}[pTF]{ \cs_if_exist:N } % \begin{syntax} % "\cs_if_exist_p:N" <cs> % \end{syntax} % <description> % \end{function} +% \end{minipage} % \end{framed} % -% Note that the list of functions used to use "|" as a separator instead, -% and this syntax is \textbf{no longer} supported. -% -% In the old syntax, individual functions could be suffixed by an optional flag or -% two to indicate the same information given in the optional argument. -% This is still supported; use "/" to separate the function name -% from the flag(s) and then add any of "(EXP)", "(rEXP)", "(TF)", or "(pTF)". -% % \DescribeEnv{variable} % If you are documenting a variable instead of a function, use the "variable" environment instead; it behaves identically to the "function" environment above. % @@ -401,18 +399,6 @@ Do not distribute a modified version of this file. % % \end{macro} % \end{verbatim} % -% \bigskip -% \textbf{OPTIONS FOR THE FUTURE}\qquad Any improvements to the markup -% for the \env{function} environment would be good to mirror in \env{macro}. -% -% Perhaps this would be a better syntax for describing arguments? -% \begin{verbatim} -% \begin{macro}{\foo:nn,foo:VV} -% \dArg{Name of froozle to be frazzled} -% \dArg{Name of mumble to be jumbled} -% ... -% \end{verbatim} -% I.e., get rid of the environment and do things like in, say, \pkg{fontspec}. % % \subsection{Keeping things consistent} % @@ -607,7 +593,22 @@ Do not distribute a modified version of this file. % \begin{macrocode} \LoadClass{article} \RequirePackage{doc} -\RequirePackage{array,alphalph,booktabs,color,colortbl,fixltx2e,enumitem,pifont,textcomp,trace,underscore,csquotes,fancyvrb} +\RequirePackage + { + array, + alphalph, + booktabs, + color, + colortbl, + fixltx2e, + enumitem, + pifont, + textcomp, + trace, + underscore, + csquotes, + fancyvrb + } \raggedbottom % \end{macrocode} % @@ -900,8 +901,8 @@ Do not distribute a modified version of this file. % \begin{environment}{function} % \begin{environment}{variabledoc} % Environment for documenting function(s). -% Stick the function names in a box. Use a "|" as delimiter and -% allow |<...>| to be used as markup for |\meta{...}|. +% Stick the function names in a box. +% Allow |<...>| to be used as markup for |\meta{...}|. % Ignore spaces and sanitize with catcodes before reading argument. % \begin{macrocode} \char_set_catcode_active:N \< @@ -914,15 +915,14 @@ Do not distribute a modified version of this file. \coffin_clear:N \l_doc_syntax_coffin \coffin_clear:N \l_doc_names_coffin - \bool_gset_false:N \l_doc_meta_TF_bool - \bool_gset_false:N \l_doc_meta_pTF_bool - \bool_gset_false:N \l_doc_meta_EXP_bool - \bool_gset_false:N \l_doc_meta_rEXP_bool + \bool_set_false:N \l_doc_meta_TF_bool + \bool_set_false:N \l_doc_meta_pTF_bool + \bool_set_false:N \l_doc_meta_EXP_bool + \bool_set_false:N \l_doc_meta_rEXP_bool \keys_set:nn { l3doc/function } {#1} - \char_set_catcode_active:N \< - \cs_set_eq:NN < \doc_open_meta:n + \char_set_active_eq:NN < \doc_open_meta:w \group_begin: \MakePrivateLetters @@ -936,10 +936,6 @@ Do not distribute a modified version of this file. } { \vcoffin_set_end: - \hcoffin_set:Nn \l_doc_names_coffin - { - \exp_args:NV \function_typeset:n \l_doc_function_input_tl - } \bool_if:NTF \l_doc_long_name_bool { \coffin_join:NnnNnnnn @@ -1009,40 +1005,32 @@ Do not distribute a modified version of this file. } \cs_gset_nopar:Npn \function_typeset:n #1 { - - \cs_set_nopar:Npn \nextnewline{\cs_gset_nopar:Npn\nextnewline{\\}} \tl_gclear:N \g_doc_macro_tl - \prop_clear:N \l_doc_functions_block_prop - + % populate "\l_doc_functions_block_prop" with info on the functions present: \clist_map_function:nN {#1} \doc_parse_functions:n \small\ttfamily \begin{tabular}{ @{} l @{} r @{} } \toprule - \prop_map_function:NN \l_doc_functions_block_prop \doc_show_functions:nn - \\ - - \bool_if:nF { \tl_if_empty_p:N \l_doc_date_added_tl && - \tl_if_empty_p:N \l_doc_date_updated_tl } - { \midrule } - - \tl_if_empty:NF \l_doc_date_added_tl - { - \multicolumn{2}{@{}r@{}} - { \scriptsize New:\,\l_doc_date_added_tl } \\ - } - - \tl_if_empty:NF \l_doc_date_updated_tl - { - \multicolumn{2}{@{}r@{}} - { \scriptsize Updated:\,\l_doc_date_updated_tl } \\ - } + \prop_map_function:NN \l_doc_functions_block_prop \doc_typeset_functions:nn + \doc_typeset_dates: \bottomrule \end{tabular} \normalfont\normalsize } - +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\doc_parse_functions:n} +% The idea here is to populate "\l_doc_functions_block_prop" with information +% about the functions being typeset and their variants. +% The property list uses a specific format: the keys contained are the function `names' (stripped of signature) with values specified by a comma-separated list containing two brace groups per item: +% \begin{center} +% "> {my_function} => { {" \meta{Nargs 1} "}{" \meta{sig.\ 1} "} , {" \meta{Nargs 2} "}{" \meta{sig.\ 2} "} , ... }" +% \end{center} +% This somewhat arcane syntax is chosen to distinguish between all variants of control sequence that may be being documented here. (With or without \textsf{expl3} function syntax.) +% \begin{macrocode} \prop_new:N \l_doc_functions_block_prop \cs_generate_variant:Nn \prop_put:Nnn {Nxx} \cs_new:Nn \doc_parse_functions:n @@ -1051,10 +1039,10 @@ Do not distribute a modified version of this file. { \tl_gset_eq:NN \l_doc_function_name_prefix_tl \@backslashchar % for the weird functions named "\::N" and so on: - \exp_args:Nx \tl_if_head_eq_charcode:nNTF { \cs_to_str:N #1 } {:} + \exp_args:Nx \tl_if_head_eq_charcode:nNTF { \cs_to_str:N #1 } { : } { % again, no variants: - \prop_put:Nxx \l_doc_functions_block_prop { \cs_to_str:N #1 } { } + \prop_put:Nxx \l_doc_functions_block_prop { \cs_to_str:N #1 } { {-1} {} } } { % finally, for regular old csnames: @@ -1064,12 +1052,19 @@ Do not distribute a modified version of this file. { \prop_put:Nxx \l_doc_functions_block_prop { \cs_get_function_name:N #1 } - { \l_doc_tmp_tl , \cs_get_function_signature:N #1 } + { + \l_doc_tmp_tl , + {\cs_get_arg_count_from_signature:N #1} + {\cs_get_function_signature:N #1} + } } { \prop_put:Nxx \l_doc_functions_block_prop { \cs_get_function_name:N #1 } - { \cs_get_function_signature:N #1 } + { + {\cs_get_arg_count_from_signature:N #1} + {\cs_get_function_signature:N #1} + } } } } @@ -1077,7 +1072,7 @@ Do not distribute a modified version of this file. { % for now don't bother splitting into variants: \tl_gclear:N \l_doc_function_name_prefix_tl - \prop_put:Nxx \l_doc_functions_block_prop { #1 } { } + \prop_put:Nxx \l_doc_functions_block_prop { #1 } { {-1} {} } } } @@ -1087,124 +1082,134 @@ Do not distribute a modified version of this file. % \end{environment} % % -% \begin{macro}{\doc_showmacro:n} -% This macro is passed one of: -% \begin{quote} -% "\abc:cnx / (EXP) / \q_stop" \\ -% "\abc:cnx / \q_stop" \\ -% \end{quote} -% We also have some code here to print out every documented macro at the end -% of the document. +% \begin{macro}{\doc_typeset_functions:nn} % \begin{arguments} -% \item Function/macro/variable name \item Metadata tags (if any) +% \item Function/macro/variable name (stripped of signature in the first case, if any) +% \item Comma-list containing information about the signature variants being documented (if any) % \end{arguments} % \begin{macrocode} -\cs_new:Nn \doc_show_functions:nn +\cs_new:Nn \doc_typeset_functions:nn { \clist_gset:Nn \l_doc_variants_clist {#2} \clist_gpop:NN \l_doc_variants_clist \l_doc_tmp_tl - \exp_args:Nx \doc_showmacro:n - { \exp_not:c {#1 \tl_if_empty:NF \l_doc_tmp_tl { : \l_doc_tmp_tl } } } + \exp_args:Nc \doc_typeset_functions_aux:N + { + #1 + \int_compare:nT { \exp_after:wN \use_i:nn \l_doc_tmp_tl > -1 } {:} + \int_compare:nT { \exp_after:wN \use_i:nn \l_doc_tmp_tl > 0 } + { \exp_after:wN \use_ii:nn \l_doc_tmp_tl } + } + \\ } -\cs_new_nopar:Nn \doc_showmacro:n { +\cs_new_nopar:Nn \doc_typeset_functions_aux:N +{ \bool_if:NT \l_doc_meta_pTF_bool { \tl_set:Nx \l_doc_pTF_name_tl { \doc_predicate_from_base:N #1 } - \doc_special_main_index:o { \token_to_str:N \l_doc_pTF_name_tl } - \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:N \l_doc_pTF_name_tl } + \doc_special_main_index:o { \tl_to_str:N \l_doc_pTF_name_tl } + \seq_gput_right:Nx \g_doc_functions_seq { \l_doc_function_name_prefix_tl \l_doc_pTF_name_tl } } \bool_if:NTF \l_doc_meta_TF_bool { \doc_special_main_index:o { \token_to_str:N #1 TF } - \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:n { #1 TF } } - \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:n { #1 T } } - \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:n { #1 F } } + \seq_gput_right:Nx \g_doc_functions_seq { \token_to_str:N #1 TF } }{ \doc_special_main_index:o { \token_to_str:N #1 } - \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:n { #1 } } + \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:n {#1} } } \bool_if:NTF \l_doc_meta_pTF_bool { + \bool_gset_false:N \l_doc_meta_TF_bool - \exp_args:Nc \doc_showmacro_aux_ii:N \l_doc_pTF_name_tl + \exp_args:Nc \doc_typeset_function_block:N { \l_doc_pTF_name_tl } \bool_gset_true:N \l_doc_meta_TF_bool - \exp_args:Nc \doc_showmacro_aux_ii:N { \cs_to_str:N #1 } + + \\ + \doc_typeset_function_block:N #1 + }{ \exp_args:Nx \tl_if_head_eq_charcode:nNTF { \exp_after:wN \use_none:n \token_to_str:N #1 } {:} - { \doc_showmacro_aux_iii:N #1 } - { \doc_showmacro_aux_ii:N #1 } + { \doc_show_macro_unusual:N #1 } + { \doc_typeset_function_block:N #1 } } } % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\doc_showmacro_aux_ii:N} +% \begin{macro}[internal]{\doc_typeset_function_block:N} % \begin{macrocode} -\cs_set_nopar:Nn \doc_showmacro_aux_ii:N { - \nextnewline +\cs_set_nopar:Nn \doc_typeset_function_block:N { \tl_gset:Nx \l_doc_function_name_tl { \cs_get_function_name:N #1 } \tl_gset:Nx \l_doc_function_sig_tl { \cs_get_function_signature:N #1 } \tl_gset:Nx \g_doc_macro_tl { \l_doc_function_name_prefix_tl \l_doc_function_name_tl } - \g_doc_macro_tl - \int_compare:nT { \cs_get_arg_count_from_signature:N #1 >= 0 } - { : \l_doc_function_sig_tl } - + \doc_typeset_function_basename:N #1 \bool_if:NT \l_doc_meta_TF_bool { \doc_typeset_TF: } + \doc_typeset_expandability: + \clist_if_empty:NF \l_doc_variants_clist { \doc_typeset_variants: } + \bool_if:NT \g_doc_full_bool { \doc_label_function: } - & - \bool_if:NT \l_doc_meta_EXP_bool { - \hspace{\tabcolsep} - \hyperlink{expstar} {$\star$} - } - \bool_if:NT \l_doc_meta_rEXP_bool { - \hspace{\tabcolsep} - \hyperlink{rexpstar} {\ding{73}} % hollow star - } - - \clist_if_empty:NF \l_doc_variants_clist - { - \\ - \doc_typeset_aux:n \g_doc_macro_tl : - \int_compare:nTF { \clist_length:N \l_doc_variants_clist == 1 } - { \l_doc_variants_clist } - { - \textrm( - \clist_pop:NN \l_doc_variants_clist \l_doc_tmp_tl - \l_doc_tmp_tl - \clist_map_inline:Nn \l_doc_variants_clist {\textrm|##1} - \textrm) - } - \bool_if:NT \l_doc_meta_TF_bool { \doc_typeset_TF: } - & - \bool_if:NT \l_doc_meta_EXP_bool { - \hspace{\tabcolsep} - \hyperlink{expstar} {$\star$} +} +\cs_set:Nn \doc_typeset_function_basename:N + { + \g_doc_macro_tl + \int_compare:nT { \cs_get_arg_count_from_signature:N #1 > -1 } { : } + \int_compare:nT { \cs_get_arg_count_from_signature:N #1 > 0 } + { \l_doc_function_sig_tl } } - \bool_if:NT \l_doc_meta_rEXP_bool { - \hspace{\tabcolsep} - \hyperlink{rexpstar} {\ding{73}} % hollow star +\cs_set:Nn \doc_typeset_expandability: + { + & + \bool_if:NT \l_doc_meta_EXP_bool { + \hspace{\tabcolsep} + \hyperlink{expstar} {$\star$} + } + \bool_if:NT \l_doc_meta_rEXP_bool { + \hspace{\tabcolsep} + \hyperlink{rexpstar} {\ding{73}} % hollow star + } } +\cs_set:Nn \doc_typeset_variants: + { + \\ + \doc_typeset_aux:n \g_doc_macro_tl : + \int_compare:nTF { \clist_length:N \l_doc_variants_clist == 1 } + { \exp_after:wN \use_ii:nn \l_doc_variants_clist } + { + \textrm( + \clist_pop:NN \l_doc_variants_clist \l_doc_tmp_tl + \exp_after:wN \use_ii:nn \l_doc_tmp_tl + \clist_map_inline:Nn \l_doc_variants_clist {\textrm| \use_ii:nn ##1} + \textrm) + } + \bool_if:NT \l_doc_meta_TF_bool { \doc_typeset_TF: } + & + \bool_if:NT \l_doc_meta_EXP_bool { + \hspace{\tabcolsep} + \hyperlink{expstar} {$\star$} } - - \exp_args:NNf \tl_replace_all:Nnn \g_doc_macro_tl {\token_to_str:N _} {/} - \exp_args:NNf \tl_replace_all:Nnn \g_doc_macro_tl {\@backslashchar} {} - \bool_if:NT \g_doc_full_bool { + \bool_if:NT \l_doc_meta_rEXP_bool { + \hspace{\tabcolsep} + \hyperlink{rexpstar} {\ding{73}} % hollow star + } + } +\cs_set:Nn \doc_label_function: + { + \exp_args:NNf \tl_replace_all:Nnn \g_doc_macro_tl {\token_to_str:N _} {/} + \exp_args:NNf \tl_replace_all:Nnn \g_doc_macro_tl {\@backslashchar} {} \exp_args:Nx \label { doc/function//\g_doc_macro_tl \tl_if_empty:NF \l_doc_function_sig_tl { : \l_doc_function_sig_tl } } } -} % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\doc_showmacro_aux_iii:N} +% \begin{macro}[aux]{\doc_show_macro_unusual:N} % This is for the case when the function is one of the weird ones like \cs{::N}. % \begin{macrocode} -\cs_set_nopar:Nn \doc_showmacro_aux_iii:N { - \nextnewline +\cs_set_nopar:Nn \doc_show_macro_unusual:N { \tl_gset:Nx \g_doc_macro_tl { \token_to_str:N #1} \token_to_str:N #1 & @@ -1217,6 +1222,30 @@ Do not distribute a modified version of this file. % \end{macrocode} % \end{macro} % +% \begin{macro}[internal]{\doc_typeset_dates:} +% To display metadata for when functions are added/modified. +% \begin{macrocode} +\cs_set:Nn \doc_typeset_dates: + { + \bool_if:nF { \tl_if_empty_p:N \l_doc_date_added_tl && + \tl_if_empty_p:N \l_doc_date_updated_tl } + { \midrule } + + \tl_if_empty:NF \l_doc_date_added_tl + { + \multicolumn{2}{@{}r@{}} + { \scriptsize New:\,\l_doc_date_added_tl } \\ + } + + \tl_if_empty:NF \l_doc_date_updated_tl + { + \multicolumn{2}{@{}r@{}} + { \scriptsize Updated:\,\l_doc_date_updated_tl } \\ + } + } +% \end{macrocode} +% \end{macro} +% % \begin{environment}{syntax} % Syntax block placed next to the list of functions to illustrate their use. % \begin{macrocode} @@ -1251,55 +1280,68 @@ Do not distribute a modified version of this file. % \end{macrocode} % \end{environment} % -% Perhaps these belong in \file{l3token}? +% \begin{macro}{\doc_ensuremath_sb:n} % \begin{macrocode} -\tl_map_inline:nn {0123456789} { \cs_gset_eq:cN {char_other_#1} #1 } +\cs_new:Npn \doc_ensuremath_sb:n #1 + { + \ensuremath{\sb{#1}} + } % \end{macrocode} +% \end{macro} % -% \begin{macro}{\doc_open_meta:n,\doc_close_meta:n} -% This code turns all numbers within "<...>" markup to be set as subscripts. -% You can use escaped numbers to get the real thing (e.g., "\1" = `1'). +% \begin{macro}{\doc_open_meta:w,\doc_close_meta:n} % \begin{macrocode} -\group_begin: - \tl_map_inline:nn {0123456789} { \char_set_catcode_active:N #1 } - \cs_new:Npn \doc_open_meta:n { +\cs_set_eq:NN \doc_meta:n \meta +\cs_set:Npn \meta + { \group_begin: - \tl_map_function:nN {0123456789} \doc_assign_num:n + \char_set_active_eq:NN _ \doc_ensuremath_sb:n + \doc_close_meta:n + } +\cs_new:Npn \doc_open_meta:w + { + \group_begin: + \char_set_active_eq:NN _ \doc_ensuremath_sb:n \doc_close_meta:w } - \cs_new:Npn \Arg { +\cs_new:Npn \Arg + { \texttt{ \char`\{ } \group_begin: - \tl_map_function:nN {0123456789} \doc_assign_num:n + \char_set_active_eq:NN _ \doc_ensuremath_sb:n \doc_close_Arg:n } -\group_end: -\cs_new_nopar:Npn \doc_close_meta:w #1> { \meta {#1} \group_end: } +\cs_new_nopar:Npn \doc_close_meta:n #1 { \doc_meta:n {#1} \group_end: } +\cs_new_nopar:Npn \doc_close_meta:w #1> { \doc_meta:n {#1} \group_end: } \cs_new_nopar:Npn \doc_close_Arg:n #1 { - \meta {#1} + \doc_meta:n {#1} \group_end: \texttt{ \char`\} } } % \end{macrocode} % \end{macro} % -% \begin{macro}{\doc_assign_num:n} -% This function takes a numeral (`0'), defines its escaped self to be equal -% to itself ("\0" $\to$ `0'), makes it active, and turns itself into a subscript -% instead (`0' $\to$ `${}_0$'). +% \begin{environment}{macro} +% We want to extend the old definition to allow comma-separated lists of +% macros, rather than one at a time. +% +% Keyval: % \begin{macrocode} -\cs_new_nopar:Npn \doc_assign_num:n #1 { - \cs_set_eq:cc { \string #1 } { char_other_\string #1 } - \char_set_catcode_active:N #1 - \cs_set_nopar:Npn #1 { \unskip \, $ {} \sb { \use:c { char_other_\string #1 } } $ } -} +\keys_define:nn { l3doc/macro } + { + aux .code:n = + { \bool_set_true:N \l_doc_macro_aux_bool } , + internal .code:n = + { \bool_set_true:N \l_doc_macro_internal_bool } , + var .code:n = + { \bool_set_true:N \l_doc_macro_var_bool } , + TF .code:n = + { \bool_set_true:N \l_doc_macro_TF_bool } , + pTF .code:n = + { \bool_set_true:N \l_doc_macro_pTF_bool } , + } % \end{macrocode} -% \end{macro} % -% \begin{environment}{macro} -% We want to extend the old definition to allow comma-separated lists of -% macros, rather than one at a time. keyval processing is very rudimentary; -% awaiting a more robust solution. % \begin{macrocode} \renewcommand \macro [1][] { @@ -1307,12 +1349,12 @@ Do not distribute a modified version of this file. { \int_gzero:N \g_doc_nested_macro_int } { \int_incr:N \g_doc_nested_macro_int } - \bool_set_false:N \l_doc_macro_aux_bool - \bool_set_false:N \l_doc_macro_internal_bool - \bool_set_false:N \l_doc_macro_TF_bool - \bool_set_false:N \l_doc_macro_pTF_bool - \bool_set_false:N \l_doc_macro_var_bool - \bool_set_false:N \l_doc_tested_bool + \bool_gset_false:N \l_doc_macro_aux_bool + \bool_gset_false:N \l_doc_macro_internal_bool + \bool_gset_false:N \l_doc_macro_TF_bool + \bool_gset_false:N \l_doc_macro_pTF_bool + \bool_gset_false:N \l_doc_macro_var_bool + \bool_gset_false:N \l_doc_tested_bool \cs_set_eq:NN \doc_macroname_prefix:n \use:n \cs_set_eq:NN \doc_macroname_suffix: \c_empty_tl @@ -1355,23 +1397,16 @@ Do not distribute a modified version of this file. { \clist_map_inline:Nn \l_doc_macro_input_clist { - \exp_args:Nf \doc_macro_single { \doc_predicate_from_base:w ##1 } + \exp_args:Nx \doc_macro_single:n { \doc_predicate_from_base:w ##1 \q_nil } } \bool_set_true:N \l_doc_macro_TF_bool - \clist_map_function:NN \l_doc_macro_input_clist \doc_macro_single + \clist_map_function:NN \l_doc_macro_input_clist \doc_macro_single:n \bool_set_false:N \l_doc_macro_TF_bool } - { \clist_map_function:NN \l_doc_macro_input_clist \doc_macro_single } + { \clist_map_function:NN \l_doc_macro_input_clist \doc_macro_single:n } } % \end{macrocode} % -% \begin{macrocode} -\cs_set_nopar:Npn \doc_macro_opt_aux: { \bool_set_true:N \l_doc_macro_aux_bool } -\cs_set_nopar:Npn \doc_macro_opt_internal: { \bool_set_true:N \l_doc_macro_internal_bool } -\cs_set_nopar:Npn \doc_macro_opt_TF: { \bool_set_true:N \l_doc_macro_TF_bool } -\cs_set_nopar:Npn \doc_macro_opt_pTF: { \bool_set_true:N \l_doc_macro_pTF_bool } -\cs_set_nopar:Npn \doc_macro_opt_var: { \bool_set_true:N \l_doc_macro_var_bool } -% \end{macrocode} % \end{environment} % % \begin{macrocode} @@ -1379,6 +1414,10 @@ Do not distribute a modified version of this file. { \cs_get_function_name:N #1 _p: \cs_get_function_signature:N #1 } +\cs_set:Npn \doc_predicate_from_base:w #1 : #2 \q_nil + { + #1 _p: #2 + } % \end{macrocode} % % \begin{environment}{doc_macro_single} @@ -1389,7 +1428,7 @@ Do not distribute a modified version of this file. % \item Macro/function/whatever name; input has already been sanitised. % \end{arguments} % \begin{macrocode} -\cs_set_nopar:Npn \doc_macro_single #1 { +\cs_set_nopar:Npn \doc_macro_single:n #1 { \int_incr:N \l_doc_macro_int \tl_set:Nx \saved@macroname { \token_to_str:N #1 } \topsep\MacroTopsep @@ -1562,34 +1601,38 @@ Do not distribute a modified version of this file. % % \begin{macro}{\endmacro} % \begin{macrocode} +\cs_set:Nn \doc_macro_wrap:n + { + #1 \bool_if:NT \l_doc_macro_TF_bool {TF} + } \cs_set:Nn \doc_texttt_comma:n {\,,~\texttt{#1}} \cs_set:Npn \endmacro { \int_compare:nT {\g_doc_nested_macro_int<1} { - \par\nobreak{\footnotesize(\emph{ + \par\nobreak\noindent{\footnotesize(\emph{ End~ definition~ for~ \prg_case_int:nnn { \clist_length:N \l_doc_macro_input_clist } { - {1} { \texttt{ \clist_use:N \l_doc_macro_input_clist }. } + {1} { \texttt{ \doc_macro_wrap:n { \clist_use:N \l_doc_macro_input_clist } }. } {2} { \tl_set:Nx \l_clist_first_tl { \clist_item:Nn \l_doc_macro_input_clist {0} } \tl_set:Nx \l_clist_last_tl { \clist_item:Nn \l_doc_macro_input_clist {1} } - \texttt{\l_clist_first_tl}\,~ and~ \texttt{\l_clist_last_tl}\,. + \texttt{\doc_macro_wrap:n\l_clist_first_tl}\,~ and~ \texttt{\doc_macro_wrap:n\l_clist_last_tl}\,. } {3} { \tl_set:Nx \l_clist_first_tl { \clist_item:Nn \l_doc_macro_input_clist {0} } \tl_set:Nx \l_clist_mid_tl { \clist_item:Nn \l_doc_macro_input_clist {1} } \tl_set:Nx \l_clist_last_tl { \clist_item:Nn \l_doc_macro_input_clist {2} } - \texttt{\l_clist_first_tl}\,,~ - \texttt{\l_clist_mid_tl}\,,~ - and~ \texttt{\l_clist_last_tl}\,. + \texttt{\doc_macro_wrap:n\l_clist_first_tl}\,,~ + \texttt{\doc_macro_wrap:n\l_clist_mid_tl}\,,~ + and~ \texttt{\doc_macro_wrap:n\l_clist_last_tl}\,. } } { \tl_set:Nx \l_clist_first_tl { \clist_item:Nn \l_doc_macro_input_clist {0} } - \texttt{\l_clist_first_tl}\,~and~others. + \texttt{\doc_macro_wrap:n\l_clist_first_tl}\,~and~others. } \bool_if:nT { !\l_doc_macro_aux_bool && @@ -2207,16 +2250,18 @@ page_precedence "rnaA" % \end{macrocode} % % \section{Testing} -%\ExplSyntaxOn -%\cs_set_eq:NN\g_saved_doc_functions_seq\g_doc_functions_seq -%\cs_set_eq:NN\g_saved_doc_macros_seq\g_doc_macros_seq -%\ExplSyntaxOff +% +% \begin{function}{foo} +% \begin{syntax} +% "\foo" <something_n> \Arg{something_1} +% \end{syntax} +% Does <something_1> with <something_n> +% \end{function} % % \begin{function}{.bool_set:N} % blah % \end{function} % -% \lipsum[2] % \ExplSyntaxOn \cs_set_eq:NN \c_alignment_token @ \ExplSyntaxOff % \begin{variabledoc} % { @@ -2227,17 +2272,17 @@ page_precedence "rnaA" % % \begin{function}[added=2011-09-06]{\example_foo:N,\example_foo:c} % \begin{syntax} -% "\example_foo:N" <arg1> -% "\example_foo:c" \Arg{arg1} +% "\example_foo:N" <arg_1> +% "\example_foo:c" \Arg{arg_1} % \end{syntax} -% <0123456789> <\0\1\2\3\4\5\6\7\8\9> \Arg{arg1} ":(" +% <0123456789> % \end{function} % -% \begin{function}[added=2011-09-06]{ \foo , \foo: , \foo:x , \barrz: } +% \begin{function}[added=2011-09-06]{ \foo , \fooo: , \foooo:n , \foooo:x , \fooooo:n , \fooooo:c , \fooooo:x } % \begin{syntax} -% "\example_foo:N" <arg1> +% "\example_foo:N" <arg_1> % \end{syntax} -% <0123456789> <\0\1\2\3\4\5\6\7\8\9> +% <0123456789> % \end{function} % % \begin{function}[TF]{\foo:N , \foo_if:c } @@ -2295,17 +2340,22 @@ page_precedence "rnaA" % \bigskip\bigskip % % \begin{macro}[aux]{ \foo_aux: } -% Testing. +% Testing `aux' option. % \end{macro} % -% \bigskip\bigskip -% % \begin{macro}[TF]{ \foo_if:c } -% Testing. +% Testing `TF' option. +% \end{macro} +% \begin{macro}[TF]{ \foo_if:c, \fooo_if:n } +% Testing `TF' option. +% \end{macro} +% +% \begin{macro}[pTF]{ \foo_if:d } +% Testing `pTF' option. % \end{macro} % -% \begin{macro}[internal]{ \foo_if:d } -% Testing. +% \begin{macro}[internal]{ \test_internal: } +% Testing `internal' option. % \end{macro} % % \bigskip\bigskip @@ -2364,10 +2414,6 @@ page_precedence "rnaA" % \end{macro} % % -%\ExplSyntaxOn -%\cs_set_eq:NN\g_doc_functions_seq\g_saved_doc_functions_seq -%\cs_set_eq:NN\g_doc_macros_seq\g_saved_doc_macros_seq -%\ExplSyntaxOff % % % \subsection{Macros} |