summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-02-28 00:40:51 +0000
committerKarl Berry <karl@freefriends.org>2012-02-28 00:40:51 +0000
commit29c459636115f7de4ae9a8681927b52a1e896805 (patch)
tree5200a1da0c7a7bae64d8c07c48df4a5daf30323e /Master/texmf-dist/source/latex/l3kernel/l3doc.dtx
parente20ea4bdd670e0418363a2a38a54b422a4d83231 (diff)
l3kernel 3471 (26feb12)
git-svn-id: svn://tug.org/texlive/trunk@25525 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3doc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3doc.dtx468
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}