summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3doc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3doc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3doc.dtx483
1 files changed, 404 insertions, 79 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3doc.dtx b/Master/texmf-dist/source/latex/expl3/l3doc.dtx
index ae52fcdcc3d..b374d8c5942 100644
--- a/Master/texmf-dist/source/latex/expl3/l3doc.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3doc.dtx
@@ -77,7 +77,7 @@ Do not distribute a modified version of this file.
% \end{macrocode}
%
%<*driver|class>
-\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}
%</driver|class>
%
@@ -94,7 +94,7 @@ Do not distribute a modified version of this file.
%<*class>
\ProvidesExplClass
{\filename}{\filedate}{\fileversion}{\filedescription}
-\RequirePackage{expl3}
+\RequirePackage{expl3,xparse}
\let \filename \filenameOld
\let \filenameext \filenameextOld
\let \filedate \filedateOld
@@ -179,11 +179,10 @@ Do not distribute a modified version of this file.
%
% \section{Problems \& Todo}
%
-% Problems at the moment: (1)~not flexible in the types of things that can be documented; (2)~very nonstandard markup (using `"|"' as a delimiter and the odd `"/ (...)"' tags; (3)~no obvious link between the "\begin{function}" environment for documenting things to the "\begin{macro}" function that's used analogously in the implementation.
+% Problems at the moment: (1)~not flexible in the types of things that can be documented; (2)~very nonstandard markup (e.g., the odd `"/ (...)"' tags; (3)~no obvious link between the "\begin{function}" environment for documenting things to the "\begin{macro}" function that's used analogously in the implementation.
%
-% The environments "function" and "macro" should probably
-% be renamed to something like \env{funcdoc} and \env{funcimpl},
-% respectively.
+% The "macro" should probably be renamed to "function" when it is used within
+% an implementation section. But they should have the same syntax before that happens!
%
% Furthermore, we need another `layer' of documentation commands to
% account for `user-macro' as opposed to `code-functions'; the \pkg{expl3}
@@ -271,7 +270,7 @@ Do not distribute a modified version of this file.
% Two heavily-used environments are defined to describe the syntax
% of \textsf{expl3} functions and variables.
% \begin{verbatim}
-% \begin{function}{ list_of | functions }
+% \begin{function}{ list_of , functions }
% \begin{syntax}
% "\foo_bar:" \Arg{meta} <test1>
% \end{syntax}
@@ -279,22 +278,22 @@ Do not distribute a modified version of this file.
% \end{function}
% \end{verbatim}
%
-% \begin{function}{ list_of | functions }
+% \begin{function}{ list_of , functions }
% \begin{syntax}
% "\foo_bar:" \Arg{meta} <test1>
% \end{syntax}
% <description>
% \end{function}
%
-% Note that the list of functions use "|" as a separator.
+% Functions may be suffixed by an optional flag or two to indicate whether it is
+% expandable or defined in conditional forms. Use "/" to separate the function name
+% from the flag(s) and then add any of "(EXP)", "(TF)", or "(pTF)" for this.
+% Note that "(pTF)" implies "(EXP)" since predicates must always be expandable.
%
-% \bigskip
-% \textbf{MAJOR PROPOSED CHANGE}\qquad
-% I think we should probably discourage this sort of free-form markup in
-% \LaTeX3 and change this to a plain ol' comma-separated list instead.
+% Note that the list of functions used to use "|" as a separator instead, and this syntax is still supported.
%
-% Alternatively, we could provide programmatic means of looping through
-% lists with arbitary separators and promote this kind of thing.
+% \DescribeEnv{function}
+% If you are documenting a variable instead of a function, use the "variable" environment instead; it behaves identically to the "function" environment above.
%
% \subsection{Describing functions in the implementation}
%
@@ -311,6 +310,33 @@ Do not distribute a modified version of this file.
% % \end{macrocode}
% % \end{macro}
% \end{verbatim}
+% If you are documenting an auxiliary macro, it's generally not necessary
+% to highlight it as much and you also don't need to check it for, say,
+% having a test function and having a documentation chunk earlier in a "function"
+% environment. In this case, write "\begin[aux]{macro}" and it will be
+% marked as such; its margin call-out will be printed in grey.
+%
+% For documenting \pkg{expl3}-type conditionals, you may also pass this
+% environment a "TF" option (and omit it from the function name) to denote that
+% the function is provided with "T", "F", and "TF" suffixes.
+% A similar "pTF" option will print both "TF" and "_p" predicate forms.
+%
+% \DescribeMacro{\testfile}
+% Within a "macro" environment, it is a good idea to mark whether a unit test has
+% been created for the commands it defines. This is indicated by writing \cs{testfile}\marg{filename}
+% anywhere within "\begin{macro}" \dots "\end{macro}".
+% The first time a test file is referred to its filename will be printed in the documentation;
+% subsequent referals will be noted by \textsf{l3doc} but not printed.
+%
+% If the class option "checktest" is enabled, then it is an \emph{error} to have a
+% "macro" environment without a \cs{testfile} file. This is intended for large packages such
+% as \pkg{expl3} that should have absolutely comprehensive tests suites and whose authors
+% may not always be as sharp at adding new tests with new code as they should be.
+%
+% \DescribeEnv{variable}
+% When documenting variable definitions, use the "variable" environment instead.
+% It will, here, behave identically to the "macro" environment, except that if the class
+% option "checktest" is enabled, variables will not be required to have a test file.
%
% \DescribeEnv{arguments}
% Within a \env{macro} environment, you may use the \env{arguments} environment
@@ -424,6 +450,7 @@ Do not distribute a modified version of this file.
\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
% \end{macrocode}
%
% \begin{macrocode}
@@ -437,13 +464,18 @@ Do not distribute a modified version of this file.
% \end{macrocode}
%
% \begin{macrocode}
+\DeclareOption{checktest}{ \bool_set_true:N \g_doc_checktest_bool }
+\DeclareOption{nochecktest}{ \bool_set_false:N \g_doc_checktest_bool }
+% \end{macrocode}
+%
+% \begin{macrocode}
\DeclareOption{cm-default}{ \bool_set_false:N \g_doc_lmodern_bool }
\DeclareOption{lm-default}{ \bool_set_true:N \g_doc_lmodern_bool }
% \end{macrocode}
%
% \begin{macrocode}
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
-\ExecuteOptions{full,a4paper,nocheck,lm-default}
+\ExecuteOptions{full,a4paper,nocheck,nochecktest,lm-default}
% \end{macrocode}
%
% Input a local configuration file, if it exists.
@@ -631,13 +663,20 @@ Do not distribute a modified version of this file.
% \begin{macro}{\EnableDocumentation,\EnableImplementation}
% \begin{macro}{\DisableDocumentation,\DisableImplementation}
% \begin{macrocode}
-\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
@@ -670,7 +709,7 @@ Do not distribute a modified version of this file.
% \end{environment}
%
% \begin{environment}{function}
-% \begin{environment}{variable}
+% \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{...}|.
@@ -679,6 +718,7 @@ Do not distribute a modified version of this file.
\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:
@@ -692,10 +732,7 @@ Do not distribute a modified version of this file.
\function_aux:n
}
\group_end:
-% \end{macrocode}
-% And the "variable" function is exactly the same for now:
-% \begin{macrocode}
-\cs_set_eq:NN \variable \function
+\cs_set_eq:NN \variabledoc \function
% \end{macrocode}
%
% \begin{macro}{\function_aux:n}
@@ -704,6 +741,7 @@ Do not distribute a modified version of this file.
% input has already been sanitised by catcode changes before reading
% the argument.
% \end{arguments}
+% Because vertical bars are odd delimiters to choose, we also now iterate over commas!
% \begin{macrocode}
\group_begin:
\char_make_other:N \|
@@ -713,7 +751,7 @@ Do not distribute a modified version of this file.
\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:
@@ -744,6 +782,7 @@ Do not distribute a modified version of this file.
%
% \begin{macrocode}
\bool_new:N \l_doc_meta_TF_bool
+\bool_new:N \l_doc_meta_pTF_bool
\bool_new:N \l_doc_meta_EXP_bool
% \end{macrocode}
%
@@ -771,6 +810,19 @@ Do not distribute a modified version of this file.
}{
\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 }
@@ -782,7 +834,14 @@ Do not distribute a modified version of this file.
\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
+ }
}
% \end{macrocode}
% \end{macro}
@@ -806,7 +865,6 @@ Do not distribute a modified version of this file.
% \begin{macrocode}
\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
}{
@@ -822,6 +880,12 @@ Do not distribute a modified version of this file.
\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}
+ }
}
% \end{macrocode}
% \end{macro}
@@ -895,13 +959,24 @@ Do not distribute a modified version of this file.
% awaiting a more robust solution.
% \begin{macrocode}
\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
@@ -916,18 +991,40 @@ Do not distribute a modified version of this file.
% \begin{macrocode}
\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} }
+ }
}
% \end{macrocode}
%
% \begin{macrocode}
\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 }
% \end{macrocode}
% \end{environment}
%
+% \begin{macrocode}
+\cs_set:Npn \doc_predicate_from_base:w #1:#2 \q_nil {#1_p:#2}
+% \end{macrocode}
+%
% \begin{environment}{doc_macro_single}
% Let's start to mess around with "doc"'s "macro" environment. See \file{doc.dtx}
% for a full explanation of the original environment. It's
@@ -936,7 +1033,9 @@ Do not distribute a modified version of this file.
% \item Macro/function/whatever name; input has already been sanitised.
% \end{arguments}
% \begin{macrocode}
+\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
@@ -962,12 +1061,18 @@ Do not distribute a modified version of this file.
\bool_if:NT \l_doc_macro_TF_bool {
\cs_set_eq:NN \doc_macroname_suffix: \doc_typeset_TF:
}
+
+ \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} {}
+ }
- \cs_set_nopar:Npx \@tempa {
+ \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 {
@@ -986,7 +1091,7 @@ Do not distribute a modified version of this file.
\SpecialMainIndex{#1}\nobreak
\DoNotIndex{#1}
}
-
+
\global\advance \c@CodelineNo \m@ne
\ignorespaces
}
@@ -994,21 +1099,45 @@ Do not distribute a modified version of this file.
%
% \begin{macro}{\doc_print_macroname:n}
% \begin{macrocode}
+\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!
+ }
}
% \end{macrocode}
% \end{macro}
% \end{environment}
%
+% \begin{macro}{\MacroLongFont}
+% \begin{macrocode}
+\providecommand \MacroLongFont {
+ \fontfamily{lmtt}\fontseries{lc}\small
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\doc_typeset_TF:,\doc_typeset_aux:n}
% Used by \cs{doc_macro_single} and \cs{doc_showmacro_aux_ii:w} to typeset
% conditionals and auxiliary functions.
% \begin{macrocode}
\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}
@@ -1016,6 +1145,167 @@ Do not distribute a modified version of this file.
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\doc_print_testfile:n}
+% Used to show that a macro has a test, somewhere.
+% \begin{macrocode}
+\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
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TestFiles}
+% \begin{macrocode}
+\DeclareDocumentCommand \TestFiles {m} {
+ \par
+ {\itshape
+ The~ following~ test~ files~ are~ used~ for~ this~ code:~ \textsf{#1}.
+ }
+ \par\ignorespaces
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\UnitTested}
+% \begin{macrocode}
+\DeclareDocumentCommand \UnitTested {} {
+ \testfile*
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\TestMissing}
+% \begin{macrocode}
+\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} }
+}
+% \end{macrocode}
+% \end{macro}
+%
+% Delete these when they're finally available:
+% \begin{macrocode}
+\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
+ }
+}
+% \end{macrocode}
+%
+% \begin{macro}{\endmacro}
+% \begin{macrocode}
+\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)}
+ }
+ }
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\DescribeOption}
% For describing package options. Due to Joseph Wright.
% Name/usage might change soon.
@@ -1342,6 +1632,7 @@ Do not distribute a modified version of this file.
% \begin{macrocode}
\seq_new:N \g_doc_functions_seq
\seq_new:N \g_doc_macros_seq
+\seq_new:N \g_doc_not_tested_seq
% \end{macrocode}
%
% \begin{macrocode}
@@ -1397,6 +1688,52 @@ Do not distribute a modified version of this file.
}
% \end{macrocode}
%
+% \begin{macrocode}
+\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: }
+% \end{macrocode}
+%
% \subsection{Indexing}
%
% Fix index (for now):
@@ -1610,53 +1947,41 @@ page_precedence "rnaA"
%
% \bigskip\bigskip
%
-% \begin{macro}{\c_minus_one}
-% \begin{macro}{\c_zero}
-% \begin{macro}{\c_one}
-% \begin{macro}{\c_two}
-% \begin{macro}{\c_three}
-% \begin{macro}{\c_four}
-% \begin{macro}{\c_five}
-% \begin{macro}{\c_six}
-% \begin{macro}{\c_seven}
-% \begin{macro}{\c_eight}
-% \begin{macro}{\c_nine}
-% \begin{macro}{\c_ten}
-% \begin{macro}{\c_eleven}
-% \begin{macro}{\c_sixteen}
-% \begin{macro}{\c_thirty_two}
-% \begin{macro}{\c_hundred_one}
-% \begin{macro}{\c_twohundred_fifty_five}
-% \begin{macro}{\c_twohundred_fifty_six}
-% \begin{macro}{\c_thousand}
-% \begin{macro}{\c_ten_thousand}
-% \begin{macro}{\c_ten_thousand_one}
+% \begin{macro}{\aaaa_bbbb_cccc_dddd_eeee_ffff_gggg_hhhh}
+% Long macro names need to be printed in a shorter font.
+% \begin{macrocode}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\c_minus_one,
+% \c_zero,
+% \c_one,
+% \c_two,
+% \c_three,
+% \c_four,
+% \c_five,
+% \c_six,
+% \c_seven,
+% \c_eight,
+% \c_nine,
+% \c_ten,
+% \c_eleven,
+% \c_sixteen,
+% \c_thirty_two,
+% \c_hundred_one,
+% \c_twohundred_fifty_five,
+% \c_twohundred_fifty_six,
+% \c_thousand,
+% \c_ten_thousand,
+% \c_ten_thousand_one}
% \begin{arguments}
% \item name
% \item parameters
% \end{arguments}
% Another test.
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+%
%
%\ExplSyntaxOn
%\cs_set_eq:NN\g_doc_functions_seq\g_saved_doc_functions_seq