diff options
Diffstat (limited to 'Master/texmf-dist/tex/latex/expl3/l3doc.cls')
-rw-r--r-- | Master/texmf-dist/tex/latex/expl3/l3doc.cls | 307 |
1 files changed, 288 insertions, 19 deletions
diff --git a/Master/texmf-dist/tex/latex/expl3/l3doc.cls b/Master/texmf-dist/tex/latex/expl3/l3doc.cls index 09ece930f47..e79e3fbee21 100644 --- a/Master/texmf-dist/tex/latex/expl3/l3doc.cls +++ b/Master/texmf-dist/tex/latex/expl3/l3doc.cls @@ -53,11 +53,11 @@ \let \filedateOld \filedate \let \fileversionOld \fileversion \let \filedescriptionOld \filedescription -\GetIdInfo$Id: l3doc.dtx 2037 2010-09-20 21:22:45Z joseph $ +\GetIdInfo$Id: l3doc.dtx 2180 2011-03-06 10:38:35Z will $ {L3 Experimental documentation class} \ProvidesExplClass {\filename}{\filedate}{\fileversion}{\filedescription} -\RequirePackage{expl3} +\RequirePackage{expl3,xparse} \let \filename \filenameOld \let \filenameext \filenameextOld \let \filedate \filedateOld @@ -73,14 +73,17 @@ \bool_new:N \g_doc_full_bool \bool_new:N \g_doc_lmodern_bool \bool_new:N \g_doc_checkfunc_bool +\bool_new:N \g_doc_checktest_bool \DeclareOption{full}{ \bool_set_true:N \g_doc_full_bool } \DeclareOption{onlydoc}{ \bool_set_false:N \g_doc_full_bool } \DeclareOption{check}{ \bool_set_true:N \g_doc_checkfunc_bool } \DeclareOption{nocheck}{ \bool_set_false:N \g_doc_checkfunc_bool } +\DeclareOption{checktest}{ \bool_set_true:N \g_doc_checktest_bool } +\DeclareOption{nochecktest}{ \bool_set_false:N \g_doc_checktest_bool } \DeclareOption{cm-default}{ \bool_set_false:N \g_doc_lmodern_bool } \DeclareOption{lm-default}{ \bool_set_true:N \g_doc_lmodern_bool } \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} -\ExecuteOptions{full,a4paper,nocheck,lm-default} +\ExecuteOptions{full,a4paper,nocheck,nochecktest,lm-default} \InputIfFileExists{l3doc.cfg} { \typeout{*************************************^^J @@ -165,13 +168,20 @@ \index{TeX~and~LaTeX2e~commands\actualchar \string\TeX{}~and~\string\LaTeXe{}~commands:\levelchar #1\actualchar{\string\ttfamily\string\bslash{}#1}}} -\newenvironment{documentation}{}{} -\newenvironment{implementation}{}{} +\cs_new:Npn \doc_implementation: { + \cs_set:Npn \variable {\macro[var]} +} +\cs_new:Npn \doc_docu: { + \cs_set_eq:NN \variable \variabledoc +} +\AtEndOfPackage{\doc_docu:} +\newenvironment{documentation}{\doc_docu:}{} +\newenvironment{implementation}{\doc_implementation:}{} \newcommand\EnableDocumentation{% - \renewenvironment{documentation}{}{}% + \renewenvironment{documentation}{\doc_docu:}{}% } \newcommand\EnableImplementation{% - \renewenvironment{implementation}{}{}% + \renewenvironment{implementation}{\doc_implementation:}{}% } \newcommand\DisableDocumentation{% \cs_set_eq:NN \documentation \comment @@ -193,6 +203,7 @@ \group_begin: \char_make_active:N \< \cs_new_nopar:Npn \function { + \phantomsection \char_make_active:N \< \cs_set_eq:NN < \doc_open_meta:n \group_begin: @@ -206,7 +217,7 @@ \function_aux:n } \group_end: -\cs_set_eq:NN \variable \function +\cs_set_eq:NN \variabledoc \function \group_begin: \char_make_other:N \| \cs_gset_nopar:Npn \function_aux:n #1 { @@ -215,7 +226,7 @@ \bigskip\endgraf\noindent\ttfamily \tabular[b]{ | l @{} c | } \hline - \doc_showmacro:w #1 | \q_stop \\ + \clist_map_inline:nn {#1} {\doc_showmacro:w ##1 | \q_stop} \\ \hline \endtabular \group_end: @@ -233,6 +244,7 @@ } \group_end: \bool_new:N \l_doc_meta_TF_bool +\bool_new:N \l_doc_meta_pTF_bool \bool_new:N \l_doc_meta_EXP_bool \cs_new_nopar:Npn \doc_showmacro_aux:w #1 / #2 \q_stop { @@ -246,6 +258,19 @@ }{ \bool_gset_false:N \l_doc_meta_EXP_bool } + \tl_if_in:nnTF {#2} { (pTF) } { + \bool_gset_true:N \l_doc_meta_TF_bool + \bool_gset_true:N \l_doc_meta_pTF_bool + \bool_gset_true:N \l_doc_meta_EXP_bool + \tl_set:Nx \l_doc_pTF_name_tl { \doc_predicate_from_base:w #1 \q_nil } + }{ + \bool_gset_false:N \l_doc_meta_pTF_bool + } + + \bool_if:NT \l_doc_meta_pTF_bool { + \doc_special_main_index:o { \l_doc_pTF_name_tl } + \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:N \l_doc_pTF_name_tl } + } \bool_if:NTF \l_doc_meta_TF_bool { \doc_special_main_index:o { #1 TF } @@ -257,11 +282,17 @@ \seq_gput_right:Nx \g_doc_functions_seq { \tl_to_str:n { #1 } } } - \doc_showmacro_aux_ii:w #1::\q_stop + \bool_if:NTF \l_doc_meta_pTF_bool { + \bool_gset_false:N \l_doc_meta_TF_bool + \exp_after:wN \doc_showmacro_aux_ii:w \l_doc_pTF_name_tl ::\q_stop + \bool_gset_true:N \l_doc_meta_TF_bool + \doc_showmacro_aux_ii:w #1::\q_stop + }{ + \doc_showmacro_aux_ii:w #1::\q_stop + } } \cs_set_nopar:Npn \doc_showmacro_aux_ii:w #1:#2:#3 \q_stop { \nextnewline - \str_if_eq:xxTF {#1} {\g_doc_macro_tl} { \doc_typeset_aux:n }{ @@ -277,6 +308,12 @@ \hspace{\tabcolsep} $\star$ } + \tl_set:Nx \g_doc_macro_tl { \tl_to_str:N \g_doc_macro_tl } + \exp_args:NNf \tl_replace_all_in:Nnn \g_doc_macro_tl {\token_to_str:N _} {/} + \exp_args:NNf \tl_replace_all_in:Nnn \g_doc_macro_tl {\@backslashchar} {} + \bool_if:NT \g_doc_full_bool { + \exp_args:Nf\label{doc/function/\g_doc_macro_tl#3#2} + } } \dim_new:N \g_doc_syntax_dim \dim_set:Nn \g_doc_syntax_dim {0.7\textwidth} @@ -317,14 +354,25 @@ \cs_set_nopar:Npn #1 { \unskip \, $ {} \sb { \use:c { char_other_\string #1 } } $ } } \renewcommand \macro [1][] { + + \int_compare:nNnTF \currentgrouplevel=2 + { \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_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 + \cs_set_eq:NN \doc_macroname_prefix:n \use:n \cs_set_eq:NN \doc_macroname_suffix: \c_empty_tl \cs_set_nopar:Npn \KV_key_no_value_elt:n ##1 { \use:c {doc_macro_opt_##1:} } \KV_parse_space_removal_sanitize:n {#1} + \cs_set_eq:NN \testfile \doc_print_testfile:n + \group_begin: \MakePrivateLetters \char_make_letter:N \\ @@ -335,13 +383,34 @@ } \cs_new_nopar:Npn \doc_macro_aux:n #1 { \group_end: - \clist_map_inline:nn {#1} { \doc_macro_single {##1} } + \cs_set:Npn \l_doc_macro_input_clist {#1} + \bool_if:NTF \l_doc_macro_pTF_bool + { + \clist_map_inline:nn {#1} + { + \exp_args:Nf \doc_macro_single + { \doc_predicate_from_base:w ##1 \q_nil } + } + \bool_set_true:N \l_doc_macro_TF_bool + \clist_map_inline:nn {#1} { \doc_macro_single {##1} } + \bool_set_false:N \l_doc_macro_TF_bool + } + { + \clist_map_inline:nn {#1} { \doc_macro_single {##1} } + } } \bool_new:N \l_doc_macro_aux_bool \bool_new:N \l_doc_macro_TF_bool +\bool_new:N \l_doc_macro_pTF_bool +\bool_new:N \l_doc_macro_var_bool \cs_set_nopar:Npn \doc_macro_opt_aux: { \bool_set_true:N \l_doc_macro_aux_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_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 } +\cs_set:Npn \doc_predicate_from_base:w #1:#2 \q_nil {#1_p:#2} +\int_new:N \l_doc_macro_int \cs_set_nopar:Npn \doc_macro_single #1 { + \int_incr:N \l_doc_macro_int \tl_set:Nx \saved@macroname { \token_to_str:N #1 } \topsep\MacroTopsep \trivlist @@ -368,11 +437,17 @@ \cs_set_eq:NN \doc_macroname_suffix: \doc_typeset_TF: } - \cs_set_nopar:Npx \@tempa { + \bool_if:NF \l_doc_macro_aux_bool { + \tl_gset:Nx \l_doc_macro_tl { \tl_to_str:n {#1} } + \exp_args:NNf \tl_greplace_all_in:Nnn \l_doc_macro_tl {\token_to_str:N _} {/} + \exp_args:NNf \tl_greplace_all_in:Nnn \l_doc_macro_tl {\@backslashchar} {} + } + + \use:x { \exp_not:N \item [ \exp_not:N \doc_print_macroname:n { \tl_to_str:n {#1} }] - } \@tempa + } \global\advance \c@CodelineNo \@ne \bool_if:NF \l_doc_macro_aux_bool { @@ -395,17 +470,167 @@ \global\advance \c@CodelineNo \m@ne \ignorespaces } +\tl_clear:N \l_doc_macro_tl \cs_set_nopar:Npn \doc_print_macroname:n #1 { - \strut \MacroFont - \doc_macroname_prefix:n {#1} \doc_macroname_suffix: \ % space! + \strut + \int_compare:nTF { \tl_elt_count:n {#1} <= 28 } + { \MacroFont } { \MacroLongFont } + + % INEFFICIENT: (!) + \exp_args:NNx \seq_if_in:NnTF \g_doc_functions_seq + { #1 \bool_if:NT \l_doc_macro_TF_bool { \tl_to_str:n {TF} } } + { + \hyperref [doc/function/\l_doc_macro_tl] + } + { \use:n } + { + \doc_macroname_prefix:n {#1} \doc_macroname_suffix: \ % space! + } +} +\providecommand \MacroLongFont { + \fontfamily{lmtt}\fontseries{lc}\small } \cs_set_nopar:Npn \doc_typeset_TF: { - \color[gray]{0.5} - \underline { \color{black} \itshape TF \kern-0.1em } + \itshape TF% + \makebox[0pt][r]{% + \color[gray]{0.5} + \underline { \phantom{\itshape TF} \kern-0.1em } + } } \cs_set_nopar:Npn \doc_typeset_aux:n #1 { {\color[gray]{0.5} #1} } +\DeclareDocumentCommand \doc_print_testfile:n {m} { + \bool_set_true:N \l_doc_tested_bool + \tl_if_eq:nnF {#1} {*} { + \seq_if_in:NnF \g_doc_testfiles_seq {#1} + { + \par{\footnotesize(\textit{ + The~ test~ suite~ for~ this~ command,~ and~ others~ in~ this~ file,~ is~ \textsf{#1}}. + )\par} + \seq_gput_right:Nn \g_doc_testfiles_seq {#1} + } + } +} +\seq_new:N \g_doc_testfiles_seq +\DeclareDocumentCommand \TestFiles {m} { + \par + {\itshape + The~ following~ test~ files~ are~ used~ for~ this~ code:~ \textsf{#1}. + } + \par\ignorespaces +} +\DeclareDocumentCommand \UnitTested {} { + \testfile* +} +\cs_generate_variant:Nn \prop_gput:Nnn {NVx} +\prop_new:N \g_doc_missing_tests_prop +\DeclareDocumentCommand \TestMissing {m} { + \prop_if_in:NVTF \g_doc_missing_tests_prop \l_doc_macro_input_clist + { + \prop_get:NVN \g_doc_missing_tests_prop \l_doc_macro_input_clist \l_tmpa_tl + \prop_gput:NVx \g_doc_missing_tests_prop \l_doc_macro_input_clist + { + *~ \l_tmpa_tl + ^^J \exp_not:n {\space\space\space\space\space\space} + *~ #1 + } + } + { \prop_gput:NVn \g_doc_missing_tests_prop \l_doc_macro_input_clist {#1} } +} +\cs_set_nopar:Npn \clist_length:N #1 { + \tex_number:D \etex_numexpr:D + 0 + \clist_map_function:NN #1 \tl_elt_count_aux:n + \scan_stop: +} +\cs_set_nopar:Npn \clist_length:n #1 { + \tex_number:D \etex_numexpr:D + 0 + \clist_map_function:nN {#1} \tl_elt_count_aux:n + \scan_stop: +} +\cs_set_nopar:Npn \clist_item:Nn #1#2 { + \exp_args:No \clist_item:nn {#1} {#2} +} +\cs_generate_variant:Nn \clist_item:Nn { c } +\cs_set:Npn \clist_item:nn #1#2 { + \int_compare:nNnTF {#2} < { 0 } + { + \exp_args:Nf \clist_item_aux:nw + { \clist_length:n {#1} + #2 } + #1 , \q_recursion_tail \q_recursion_stop + } + { + \clist_item_aux:nw {#2} #1 + , \q_recursion_tail \q_recursion_stop + } +} +\cs_set:Npn \clist_item_aux:nw #1#2 , #3 { + \int_compare:nNnTF {#1} = { 0 } + { \use_i_delimit_by_q_recursion_stop:nw {#2} } + { + \quark_if_recursion_tail_stop:n {#3} + \clist_item_aux:nw { #1 - 1 } #3 + } +} +\int_new:N \g_doc_nested_macro_int +\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{ + 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 }. } + {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}\,. + } + {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}\,. + } + } + { + \tl_set:Nx \l_clist_first_tl { \clist_item:Nn \l_doc_macro_input_clist {0} } + \texttt{\l_clist_first_tl}\,~and~others. + } + \bool_if:nT { + !\l_doc_macro_aux_bool && + \int_compare_p:n {\g_doc_nested_macro_int<1} + } + { + \int_compare:nNnTF \l_doc_macro_int=1 {~This~} {~These~} + \bool_if:NTF \l_doc_macro_var_bool{variable}{function} + \int_compare:nNnTF \l_doc_macro_int=1 {~is~}{s~are~} + documented~on~page~ + \exp_args:Nx\pageref{doc/function/\l_doc_macro_tl}. + } + })\par} + } + \bool_if:nT + { \g_doc_checktest_bool && + !( \l_doc_macro_aux_bool || \l_doc_macro_var_bool ) && + !\l_doc_tested_bool + } + { + \seq_gput_right:Nx \g_doc_not_tested_seq + { + \l_doc_macro_input_clist + \bool_if:NT \l_doc_macro_pTF_bool {~(pTF)} + \bool_if:NT \l_doc_macro_TF_bool {~(TF)} + } + } +} \newcommand*{\DescribeOption}{ \leavevmode \@bsphack @@ -624,6 +849,7 @@ } \seq_new:N \g_doc_functions_seq \seq_new:N \g_doc_macros_seq +\seq_new:N \g_doc_not_tested_seq \iow_open:Nn \g_write_func_stream { \jobname.cmds } \cs_new_nopar:Npn \doc_show_functions_defined: { \bool_if:nT { \g_doc_implementation_bool && \g_doc_checkfunc_bool } { @@ -668,6 +894,49 @@ \tl_clear:N \l_tmpa_tl } } +\cs_new:Npn \doc_show_not_tested: { + \bool_if:NT \g_doc_checktest_bool + { + \bool_if:nT { !(\seq_if_empty_p:N \g_doc_not_tested_seq) || + !(\prop_if_empty_p:N \g_doc_missing_tests_prop) } + { + \tl_clear:N \l_tmpa_tl + \prop_if_empty:NF \g_doc_missing_tests_prop + { + \tl_put_right:Nn \l_tmpa_tl + { + ^^J^^JThe~ following~ macro(s)~ have~ incomplete~ tests:^^J + } + \prop_map_inline:Nn \g_doc_missing_tests_prop + { + \tl_put_right:Nn \l_tmpa_tl + {^^J\space\space\space\space ##1 + ^^J\space\space\space\space\space\space ##2} + } + } + \seq_if_empty:NF \g_doc_not_tested_seq + { + \tl_put_right:Nn \l_tmpa_tl + { + ^^J^^J + The~ following~ macro(s)~ do~ not~ have~ any~ tests:^^J + } + \seq_map_inline:Nn \g_doc_not_tested_seq + { + \clist_map_inline:nn {##1} + { + \tl_put_right:Nn \l_tmpa_tl {^^J\space\space\space\space ####1} + } + } + \int_set:Nn \l_tmpa_int {\etex_interactionmode:D} + \errorstopmode + \ClassError{l3doc}{\l_tmpa_tl}{} + \int_set:Nn \etex_interactionmode:D {\l_tmpa_int} + } + } + } +} +\AtEndDocument{ \doc_show_not_tested: } \g@addto@macro\theindex{\MakePrivateLetters} \cs_set:Npn \verbatimchar {&} \setcounter{IndexColumns}{2} |