summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/latex/expl3/l3doc.cls
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/tex/latex/expl3/l3doc.cls')
-rw-r--r--Master/texmf-dist/tex/latex/expl3/l3doc.cls307
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}