diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3doc.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3doc.dtx | 661 |
1 files changed, 444 insertions, 217 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx index d7d925dbfa5..551abe0a6a3 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx @@ -9,7 +9,7 @@ %% %% http://www.latex-project.org/lppl.txt %% -%% This file is part of the "expl3 bundle" (The Work in LPPL) +%% This file is part of the "l3kernel bundle" (The Work in LPPL) %% and all files in that bundle must be distributed together. %% %% The released version of this bundle is available from CTAN. @@ -65,7 +65,7 @@ Do not distribute a modified version of this file. %</driver> % %<*driver|class> -\RequirePackage{l3names} +\RequirePackage{expl3,xparse} %</driver|class> % % Need to protect the file metadata for any modules that load l3doc. @@ -78,7 +78,7 @@ Do not distribute a modified version of this file. % \end{macrocode} % %<*driver|class> -\GetIdInfo$Id: l3doc.dtx 2719 2011-09-04 13:40:25Z will $ +\GetIdInfo$Id: l3doc.dtx 2819 2011-09-12 17:26:47Z will $ {L3 Experimental documentation class} %</driver|class> % @@ -86,7 +86,7 @@ Do not distribute a modified version of this file. \ProvidesFile{\ExplFileName.dtx} [\ExplFileDate\space v\ExplFileVersion\space\ExplFileDescription] \documentclass{l3doc} -\usepackage{framed} +\usepackage{framed,lipsum} \begin{document} \DocInput{l3doc.dtx} \end{document} @@ -96,7 +96,6 @@ Do not distribute a modified version of this file. %<*class> \ProvidesExplClass {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} -\RequirePackage{expl3,xparse} \let \ExplFileName \filenameOld \let \ExplFileDate \filedateOld \let \ExplFileVersion \fileversionOld @@ -114,6 +113,7 @@ Do not distribute a modified version of this file. % % \begin{documentation} % +% % \section{Introduction} % % This is an ad-hoc class for documenting the \pkg{expl3} bundle, @@ -182,8 +182,7 @@ Do not distribute a modified version of this file. % % 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 +% (2)~no obvious link between the "\begin{function}" environment for % documenting things to the "\begin{macro}" function that's used % analogously in the implementation. % @@ -242,7 +241,7 @@ Do not distribute a modified version of this file. % \pkg{doc} uses the "\OnlyDocumentation"/"\AlsoImplementation" macros % to guide the use of "\StopEventually{}", which is intended to be placed % to partition the documentation and implementation within a single DTX file. -% +% % This isn't very flexible, since it assumes that we \emph{always} want % to print the documentation. For the \pkg{expl3} sources, I wanted to be % be able to input DTX files in two modes: only displaying the documentation, @@ -278,7 +277,7 @@ Do not distribute a modified version of this file. % \begin{framed} % \vspace{-\baselineskip} % \begin{verbatim} -% \begin{function}{ list_of , functions } +% \begin{function}{ \function_one: , \function_two: } % \begin{syntax} % "\foo_bar:" \Arg{meta} <test1> % \end{syntax} @@ -287,7 +286,7 @@ Do not distribute a modified version of this file. % \end{verbatim} % \vspace{-2\baselineskip} % \hrulefill -% \begin{function}{ list_of , functions } +% \begin{function}{ \function_one: , \function_two: } % \begin{syntax} % "\foo_bar:" \Arg{meta} <test1> % \end{syntax} @@ -320,7 +319,7 @@ Do not distribute a modified version of this file. % \end{framed} % % Note that the list of functions used to use "|" as a separator instead, -% and this syntax is still supported. +% 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. @@ -488,12 +487,43 @@ Do not distribute a modified version of this file. Javier~Bezos,~Will~Robertson,~Joseph~Wright,~Bruno~Le~Floch}} % \end{macrocode} % -% \subsection{Options and configuration} +% \subsection{Variables} % % \begin{macrocode} -\DeclareOption{a5paper}{\@latexerr{Option not supported}{}} +\coffin_new:N \l_doc_output_box +\coffin_new:N \l_doc_names_coffin +\coffin_new:N \l_doc_descr_coffin +\coffin_new:N \l_doc_syntax_coffin +\bool_new:N \l_doc_long_name_bool +\bool_new:N \g_doc_implementation_bool +\dim_new:N \l_doc_trial_width_dim +\int_new:N \l_doc_macro_int +\int_new:N \g_doc_nested_macro_int +\prop_new:N \g_doc_missing_tests_prop +\clist_new:N \g_docinput_clist +% \end{macrocode} +% +% \begin{macrocode} +\seq_new:N \g_doc_testfiles_seq +\seq_new:N \g_doc_functions_seq +\seq_new:N \g_doc_macros_seq +\seq_new:N \g_doc_not_tested_seq +% \end{macrocode} +% +% For function/macro environments: +% \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 +\bool_new:N \l_doc_meta_rEXP_bool +\bool_new:N \l_doc_macro_internal_bool +\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 % \end{macrocode} % +% For package options: % \begin{macrocode} \bool_new:N \g_doc_full_bool \bool_new:N \g_doc_lmodern_bool @@ -501,6 +531,34 @@ Do not distribute a modified version of this file. \bool_new:N \g_doc_checktest_bool % \end{macrocode} % +% \subsection{expl3 extras} +% +% \begin{macro} +% { +% \coffin_gset_eq:NN, \coffin_gset_eq:Nc, +% \coffin_gset_eq:cN, \coffin_gset_eq:cc +% } +% Setting two coffins equal is just a wrapper around other functions. +% \begin{macrocode} +\cs_set_protected_nopar:Npn \coffin_gset_eq:NN #1#2 + { + \coffin_if_exist:NT #1 + { + \box_gset_eq:NN #1 #2 + \coffin_gset_eq_structure:NN #1 #2 + } + } +\cs_generate_variant:Nn \coffin_gset_eq:NN { c , Nc , cc } +% \end{macrocode} +% \end{macro} +% +% \subsection{Options and configuration} +% +% \begin{macrocode} +\DeclareOption{a5paper}{\@latexerr{Option not supported}{}} +% \end{macrocode} +% +% % \begin{macrocode} \DeclareOption{full}{ \bool_set_true:N \g_doc_full_bool } \DeclareOption{onlydoc}{ \bool_set_false:N \g_doc_full_bool } @@ -548,7 +606,17 @@ Do not distribute a modified version of this file. % \begin{macrocode} \LoadClass{article} \RequirePackage{doc} -\RequirePackage{array,alphalph,booktabs,color,fixltx2e,enumitem,pifont,textcomp,trace,underscore,csquotes} +\RequirePackage{array,alphalph,booktabs,color,colortbl,fixltx2e,enumitem,pifont,textcomp,trace,underscore,csquotes,fancyvrb} +\raggedbottom +% \end{macrocode} +% +% +% I've never worked out why the verbatim environment adds extra space in dtx documents. +% Fix it with fancyvrb: +% \begin{macrocode} +\fvset{gobble=2} +\cs_set_eq:NN \verbatim \Verbatim +\cs_set_eq:NN \endverbatim \endVerbatim % \end{macrocode} % % \begin{macrocode} @@ -630,19 +698,19 @@ Do not distribute a modified version of this file. % \end{macrocode} % (These were introduced when "article" was the documentclass, but % I've left them here for now to remind me to do something about them -% later; we still have the problem of \emph{very long} command names.) +% later.) % % Customise lists: % \begin{macrocode} \cs_set_eq:NN \@@oldlist\list \cs_set_nopar:Npn \list#1#2{\@@oldlist{#1}{#2\listparindent\z@}} -\setlength \parindent { 0pt } +\setlength \parindent { 2em } \setlength \itemindent { 0pt } -\setlength \parskip { \medskipamount } +\setlength \parskip { 0pt plus 3pt minus 0pt } % \end{macrocode} % % -% Customise TOC (as we have so many sections). Different design and/or +% Customise TOC (as we have so many sections). Different design and/or % structure is called for ): % \begin{macrocode} \cs_set_nopar:Npn \l@section #1#2 { @@ -662,7 +730,6 @@ Do not distribute a modified version of this file. \cs_set_nopar:Npn\l@subsection{\@dottedtocline{2}{2.5em}{2.3em}} % #2 = 1.5em % \end{macrocode} % - % % \subsection{Text markup} % @@ -714,10 +781,9 @@ Do not distribute a modified version of this file. % \end{macrocode} % \end{macro} % -% \begin{macro}{\m,\file,\env,\pkg,\cls} +% \begin{macro}{\file,\env,\pkg,\cls} % This list may change\dots this is just my preference for markup. % \begin{macrocode} -\cs_set_eq:NN \m \meta \cs_set_eq:NN \file \nolinkurl \DeclareRobustCommand \env {\texttt} \DeclareRobustCommand \pkg {\textsf} @@ -738,11 +804,11 @@ Do not distribute a modified version of this file. % \end{environment} % % \begin{macro}{\tn} -% As \cs{cs}. Use this to mark up all \TeX\ and \LaTeXe\ commands; they +% As \cs{cs}. Use this to mark up all \TeX\ and \LaTeXe\ commands; they % then end up together in the index. TODO: hyperlinks in the index entries. % \begin{macrocode} \newcommand\tn[1]{ - \texttt{\bslash #1} + \texttt { \char`\\ #1 } \index{TeX~and~LaTeX2e~commands\actualchar \string\TeX{}~and~\string\LaTeXe{}~commands:\levelchar #1\actualchar{\string\ttfamily\string\bslash{}#1}}} @@ -756,9 +822,11 @@ Do not distribute a modified version of this file. % \begin{macrocode} \cs_new:Npn \doc_implementation: { \cs_set:Npn \variable {\macro[var]} + \cs_set_eq:NN \endvariable \endmacro } \cs_new:Npn \doc_docu: { \cs_set_eq:NN \variable \variabledoc + \cs_set_eq:NN \endvariable \endvariabledoc } \AtEndOfPackage{\doc_docu:} \newenvironment{documentation}{\doc_docu:}{} @@ -799,6 +867,35 @@ Do not distribute a modified version of this file. % \end{macrocode} % \end{environment} % +% \begin{macrocode} +\keys_define:nn { l3doc/function } + { + TF .code:n = + { + \bool_gset_true:N \l_doc_meta_TF_bool + } , + EXP .code:n = + { + \bool_gset_true:N \l_doc_meta_EXP_bool + \bool_gset_false:N \l_doc_meta_rEXP_bool + } , + rEXP .code:n = + { + \bool_gset_false:N \l_doc_meta_EXP_bool + \bool_gset_true:N \l_doc_meta_rEXP_bool + } , + pTF .code:n = + { + \bool_gset_true:N \l_doc_meta_pTF_bool + \bool_gset_true:N \l_doc_meta_TF_bool + \bool_gset_true:N \l_doc_meta_EXP_bool + } , + added .tl_set:N = \l_doc_date_added_tl , + updated .tl_set:N = \l_doc_date_updated_tl , + } +% \end{macrocode} +% +% % \begin{environment}{function} % \begin{environment}{variabledoc} % Environment for documenting function(s). @@ -807,107 +904,189 @@ Do not distribute a modified version of this file. % Ignore spaces and sanitize with catcodes before reading argument. % \begin{macrocode} \char_set_catcode_active:N \< -\DeclareDocumentCommand \function { O{} } { +\DeclareDocumentEnvironment {function} { O{} } { + \par\bigskip\noindent \phantomsection - + + \coffin_clear:N \l_doc_descr_coffin + \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 - \cs_set_nopar:Npn \KV_key_no_value_elt:n ##1 { \use:c {doc_meta_opt_##1:} } - \keyval_parse:NNn \KV_key_no_value_elt:n \use_none:nn {#1} + \keys_set:nn { l3doc/function } {#1} \char_set_catcode_active:N \< \cs_set_eq:NN < \doc_open_meta:n - + \group_begin: \MakePrivateLetters \char_set_catcode_other:N \| - \char_set_catcode_other:N \\ \char_set_catcode_space:N \~ \char_set_catcode_ignore:N \ % space \char_set_catcode_ignore:N \^^M \char_set_catcode_ignore:N \^^I + \function_aux:n -} + } + { + \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 + \l_doc_output_box {hc} {vc} + \l_doc_syntax_coffin {l} {T} + {0pt} {0pt} + \coffin_join:NnnNnnnn + \l_doc_output_box {l} {t} + \l_doc_names_coffin {r} {t} + {-\marginparsep} {0pt} + \coffin_join:NnnNnnnn + \l_doc_output_box {l} {b} + \l_doc_descr_coffin {l} {t} + {0.75\marginparwidth + \marginparsep} {-\medskipamount} + + \coffin_typeset:Nnnnn \l_doc_output_box {\l_doc_descr_coffin-l} {\l_doc_descr_coffin-t} {0pt} {0pt} + } + { + \coffin_join:NnnNnnnn + \l_doc_output_box {hc} {vc} + \l_doc_syntax_coffin {l} {t} + {0pt} {0pt} + \coffin_join:NnnNnnnn + \l_doc_output_box {l} {b} + \l_doc_descr_coffin {l} {t} + {0pt} {-\medskipamount} + \coffin_join:NnnNnnnn + \l_doc_output_box {l} {t} + \l_doc_names_coffin {r} {t} + {-\marginparsep} {0pt} + + \coffin_typeset:Nnnnn + \l_doc_output_box {\l_doc_syntax_coffin-l} {\l_doc_syntax_coffin-T} + {0pt} {0pt} + } + \par + \allowbreak + } \char_set_catcode_other:N \< \cs_set_eq:NN \variabledoc \function +\cs_set_eq:NN \endvariabledoc \endfunction % \end{macrocode} % -% \begin{macrocode} -\cs_set:Nn \doc_meta_opt_TF: { - \bool_gset_true:N \l_doc_meta_TF_bool -} -\cs_set:Nn \doc_meta_opt_EXP: { - \bool_gset_true:N \l_doc_meta_EXP_bool - \bool_gset_false:N \l_doc_meta_rEXP_bool -} -\cs_set:Nn \doc_meta_opt_rEXP: { - \bool_gset_false:N \l_doc_meta_EXP_bool - \bool_gset_true:N \l_doc_meta_rEXP_bool -} -\cs_set:Nn \doc_meta_opt_pTF: { - \bool_gset_true:N \l_doc_meta_pTF_bool - \bool_gset_true:N \l_doc_meta_TF_bool - \bool_gset_true:N \l_doc_meta_EXP_bool -} -% \end{macrocode} % % \begin{macro}{\function_aux:n} % \begin{arguments} -% \item Vertical bar--separated list of functions with optional metadata; +% \item Comma-separated list of functions; % 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_set_catcode_other:N \| -\cs_gset_nopar:Npn \function_aux:n #1 { - \cs_set_nopar:Npn \nextnewline{\cs_gset_nopar:Npn\nextnewline{\\}} - \tl_gset_eq:NN \g_doc_macro_tl \c_empty_tl - \bigskip\endgraf\noindent\ttfamily - \tabular[b]{ | l @{} c | } - \hline - \clist_map_inline:nn {#1} {\doc_showmacro:w ##1 | \q_stop} \\ - \hline - \endtabular +\cs_set_nopar:Npn \function_aux:n #1 { + \group_end: + + \tl_set:Nn \l_doc_function_input_tl {#1} + + \dim_zero:N \l_doc_trial_width_dim + \hcoffin_set:Nn \l_doc_names_coffin { \function_typeset:n {#1} } + \dim_set:Nn \l_doc_trial_width_dim { \box_wd:N \l_doc_names_coffin } + + \bool_set:Nn \l_doc_long_name_bool + { \dim_compare_p:nNn \l_doc_trial_width_dim > \marginparwidth } + + \vcoffin_set:Nnw \l_doc_descr_coffin {\textwidth} + \noindent\ignorespaces } -\group_end: +\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 + + \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 } \\ + } + \bottomrule + \end{tabular} + \normalfont\normalsize + } + +\prop_new:N \l_doc_functions_block_prop +\cs_generate_variant:Nn \prop_put:Nnn {Nxx} +\cs_new:Nn \doc_parse_functions:n + { + \exp_args:Nxx \tl_if_head_eq_charcode:nNTF { \token_to_str:N #1 } {\cs_to_str:N \\} + { + \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 } {:} + { + % again, no variants: + \prop_put:Nxx \l_doc_functions_block_prop { \cs_to_str:N #1 } { } + } + { + % finally, for regular old csnames: + \exp_args:NNf \prop_get:NnNTF + \l_doc_functions_block_prop + { \cs_get_function_name:N #1 } \l_doc_tmp_tl + { + \prop_put:Nxx \l_doc_functions_block_prop + { \cs_get_function_name:N #1 } + { \l_doc_tmp_tl , \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 } + } + } + } + % for keys and things that aren't actually csnames: + { + % 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 } { } + } + } + % \end{macrocode} % \end{macro} % \end{environment} % \end{environment} % -% \begin{macro}{\doc_showmacro:w} -% This function reads in a "|"-separated list, passing each item to -% the auxiliary function "\doc_showmacro_aux:w". -% \begin{macrocode} -\group_begin: -\char_set_catcode_other:N \| -\cs_gset_nopar:Npn \doc_showmacro:w #1 | { - \tl_if_blank:nTF {#1} { - \use_none:n - }{ - \doc_showmacro_aux:w #1 / \q_stop - \peek_meaning:NTF \q_stop { \use_none:n } { \doc_showmacro:w } - } -} -\group_end: -% \end{macrocode} -% \end{macro} % -% \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 -\bool_new:N \l_doc_meta_rEXP_bool -% \end{macrocode} -% -% \begin{macro}[aux]{\doc_showmacro_aux:w} +% \begin{macro}{\doc_showmacro:n} % This macro is passed one of: % \begin{quote} % "\abc:cnx / (EXP) / \q_stop" \\ @@ -919,115 +1098,117 @@ Do not distribute a modified version of this file. % \item Function/macro/variable name \item Metadata tags (if any) % \end{arguments} % \begin{macrocode} -\cs_new_nopar:Npn \doc_showmacro_aux:w #1 / #2 \q_stop { - - \tl_if_in:nnT {#2} { (TF) } { - \bool_gset_true:N \l_doc_meta_TF_bool - } - - \tl_if_in:nnT {#2} { (EXP) } { - \bool_gset_true:N \l_doc_meta_EXP_bool - } - \tl_if_in:nnT {#2} { (rEXP) } { - \bool_gset_true:N \l_doc_meta_rEXP_bool - } - - \tl_if_in:nnT {#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 +\cs_new:Nn \doc_show_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 } } } } +\cs_new_nopar:Nn \doc_showmacro:n { \bool_if:NT \l_doc_meta_pTF_bool { - \tl_set:Nx \l_doc_pTF_name_tl { \doc_predicate_from_base:w #1 \q_nil } - \doc_special_main_index:o { \l_doc_pTF_name_tl } + \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 } } \bool_if:NTF \l_doc_meta_TF_bool { - \doc_special_main_index:o { #1 TF } + \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 } } }{ - \doc_special_main_index:o { #1 } + \doc_special_main_index:o { \token_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_after:wN \doc_showmacro_aux_ii:w \l_doc_pTF_name_tl ::\q_stop + \exp_args:Nc \doc_showmacro_aux_ii:N \l_doc_pTF_name_tl \bool_gset_true:N \l_doc_meta_TF_bool - \doc_showmacro_aux_ii:w #1::\q_stop + \exp_args:Nc \doc_showmacro_aux_ii:N { \cs_to_str:N #1 } }{ - \exp_args:Nf \tl_if_head_eq_charcode:nNTF { \use_none:n #1 } {:} - { \doc_showmacro_aux_iii:n {#1} } - { \doc_showmacro_aux_ii:w #1::\q_stop } + \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 } } } % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\doc_showmacro_aux_ii:w} -% This macro is passed arguments in the following ways: -% \begin{quote} -% "\doc_showmacro_aux_ii:w "^^A -% \makebox[\widthof{\texttt{123456}}]{\meta{name}}^^A -% " ::\q_stop" \\ -% "\doc_showmacro_aux_ii:w \foo ::\q_stop" \\ -% "\doc_showmacro_aux_ii:w \foo: ::\q_stop" \\ -% "\doc_showmacro_aux_ii:w \foo:Z ::\q_stop" \\ -% \end{quote} -% Notice that for "\foo", "#2" and "#3" are empty,\\ -% for "\foo:", "#2" is empty, and "#3" is `":"'\\ -% for "\foo:Z", "#2" is `"Z"' and "#3" is `":"' . -% \begin{arguments} -% \item Function name \item Possible arg.\ spec. \item Possible colon -% \end{arguments} +% \begin{macro}[aux]{\doc_showmacro_aux_ii:N} % \begin{macrocode} -\cs_set_nopar:Npn \doc_showmacro_aux_ii:w #1:#2:#3 \q_stop { +\cs_set_nopar:Nn \doc_showmacro_aux_ii:N { \nextnewline - \str_if_eq:xxTF {#1} {\g_doc_macro_tl} { - \doc_typeset_aux:n - }{ - \tl_gset:Nn \g_doc_macro_tl {#1} - \use:n - } - { \g_doc_macro_tl } - #3 - #2 + \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 + \tl_if_empty:NF \l_doc_function_sig_tl { : \l_doc_function_sig_tl } \bool_if:NT \l_doc_meta_TF_bool { \doc_typeset_TF: } + & \bool_if:NT \l_doc_meta_EXP_bool { \hspace{\tabcolsep} - \hyperlink{expstar}{$\star$} + \hyperlink{expstar} {$\star$} } \bool_if:NT \l_doc_meta_rEXP_bool { \hspace{\tabcolsep} - \hyperlink{rexpstar}{\ding{73}}% hollow star + \hyperlink{rexpstar} {\ding{73}} % hollow star } - \tl_set:Nx \g_doc_macro_tl { \tl_to_str:N \g_doc_macro_tl } + + \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$} + } + \bool_if:NT \l_doc_meta_rEXP_bool { + \hspace{\tabcolsep} + \hyperlink{rexpstar} {\ding{73}} % hollow 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 { - \exp_args:Nf\label{doc/function/\g_doc_macro_tl#3#2} + \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:w} +% +% \begin{macro}[aux]{\doc_showmacro_aux_iii: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 { +\cs_set_nopar:Nn \doc_showmacro_aux_iii:N { \nextnewline - \tl_gset:Nx \g_doc_macro_tl {#1} - #1 & - \tl_set:Nx \g_doc_macro_tl { \tl_to_str:N \g_doc_macro_tl } + \tl_gset:Nx \g_doc_macro_tl { \token_to_str:N #1} + \token_to_str:N #1 & + \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 { - \exp_args:Nf\label{doc/function/\g_doc_macro_tl} + \exp_args:Nx \label { doc/function//\g_doc_macro_tl } } } % \end{macrocode} @@ -1036,16 +1217,33 @@ Do not distribute a modified version of this file. % \begin{environment}{syntax} % Syntax block placed next to the list of functions to illustrate their use. % \begin{macrocode} -\dim_new:N \g_doc_syntax_dim -\dim_set:Nn \g_doc_syntax_dim {0.7\textwidth} \newenvironment{syntax}{ - \minipage[b]{\g_doc_syntax_dim} - \small\ttfamily\raggedright - \obeyspaces\obeylines + \small\ttfamily + \bool_if:NTF \l_doc_long_name_bool + { + \hcoffin_set:Nw \l_doc_syntax_coffin + \arrayrulecolor{white} + \begin{tabular}{@{}l@{}} + \toprule + \begin{minipage} + { \textwidth+0.75\marginparwidth-\l_doc_trial_width_dim } + } + { + \hcoffin_set:Nw \l_doc_syntax_coffin + \arrayrulecolor{white} + \begin{tabular}{@{}l@{}} + \toprule + \begin{minipage}{ \textwidth } + } + \raggedright + \obeyspaces\obeylines }{ - \endminipage - \hfil\break - \global\@ignoretrue + \end{minipage} + \end{tabular} + \arrayrulecolor{black} + \hcoffin_set_end: + \coffin_gset_eq:NN \l_doc_syntax_coffin \l_doc_syntax_coffin + \ignorespacesafterend } % \end{macrocode} % \end{environment} @@ -1112,13 +1310,12 @@ Do not distribute a modified version of this file. \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:} } - \keyval_parse:NNn \KV_key_no_value_elt:n \use_none:nn {#1} - + + \keys_set:nn { l3doc/macro } {#1} + \cs_set_eq:NN \testfile \doc_print_testfile:n \group_begin: @@ -1129,6 +1326,10 @@ Do not distribute a modified version of this file. \char_set_catcode_ignore:N \^^I \doc_macro_aux:n } +\keys_define:nn { l3doc/macro } + { + unknown .code:n = { \use:c{doc_macro_opt_#1:} } + } % \end{macrocode} % After changing the catcodes, parse the arguments: % \begin{macrocode} @@ -1139,30 +1340,17 @@ Do not distribute a modified version of this file. { \clist_map_inline:nn {#1} { - \tl_if_blank:nF {##1} - { - \exp_args:Nf \doc_macro_single - { \doc_predicate_from_base:w ##1 \q_nil } - } + \exp_args:Nf \doc_macro_single { \doc_predicate_from_base:w ##1 } } \bool_set_true:N \l_doc_macro_TF_bool - \clist_map_inline:nn {#1} - { \tl_if_blank:nF {##1} { \doc_macro_single {##1} } } + \clist_map_function:nN {#1} \doc_macro_single \bool_set_false:N \l_doc_macro_TF_bool } - { - \clist_map_inline:nn {#1} - { \tl_if_blank:nF {##1} { \doc_macro_single {##1} } } - } + { \clist_map_function:nN {#1} \doc_macro_single } } % \end{macrocode} % % \begin{macrocode} -\bool_new:N \l_doc_macro_internal_bool -\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_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 } @@ -1172,7 +1360,10 @@ Do not distribute a modified version of this file. % \end{environment} % % \begin{macrocode} -\cs_set:Npn \doc_predicate_from_base:w #1:#2 \q_nil {#1_p:#2} +\cs_set:Nn \doc_predicate_from_base:N + { + \cs_get_function_name:N #1 _p: \cs_get_function_signature:N #1 + } % \end{macrocode} % % \begin{environment}{doc_macro_single} @@ -1183,7 +1374,6 @@ 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 } @@ -1211,7 +1401,7 @@ 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:Nnn \l_doc_macro_tl {\token_to_str:N _} {/} @@ -1241,7 +1431,7 @@ Do not distribute a modified version of this file. \SpecialMainIndex{#1}\nobreak \DoNotIndex{#1} } - + \global\advance \c@CodelineNo \m@ne \ignorespaces } @@ -1252,14 +1442,14 @@ Do not distribute a modified version of this file. \tl_clear:N \l_doc_macro_tl \cs_set_nopar:Npn \doc_print_macroname:n #1 { \strut - \int_compare:nTF { \tl_elt_count:n {#1} <= 28 } + \int_compare:nTF { \tl_length: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] + \hyperref [doc/function//\l_doc_macro_tl] } { \use:n } { @@ -1293,7 +1483,7 @@ Do not distribute a modified version of this file. } } \cs_set_nopar:Npn \doc_typeset_aux:n #1 { - {\color[gray]{0.5} #1} + {\color[gray]{0.7} #1} } % \end{macrocode} % \end{macro} @@ -1313,7 +1503,6 @@ Do not distribute a modified version of this file. } } } -\seq_new:N \g_doc_testfiles_seq % \end{macrocode} % \end{macro} % @@ -1340,7 +1529,6 @@ Do not distribute a modified version of this file. % \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 { @@ -1359,7 +1547,6 @@ Do not distribute a modified version of this file. % % \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} @@ -1399,7 +1586,7 @@ Do not distribute a modified version of this file. \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}. + \exp_args:Nx\pageref{doc/function//\l_doc_macro_tl}. } })\par} } @@ -1573,7 +1760,6 @@ Do not distribute a modified version of this file. % % \begin{macro}{\StopEventually,\Finale,\AlsoImplementation,\OnlyDescription} % \begin{macrocode} -\bool_new:N \g_doc_implementation_bool \cs_set_nopar:Npn \AlsoImplementation { \bool_set_true:N \g_doc_implementation_bool \cs_set:Npn \StopEventually ##1 { @@ -1601,7 +1787,6 @@ Do not distribute a modified version of this file. % \begin{macro}{\DocInput} % From \pkg{doc}. Now accepts comma-list input (who has commas in filenames?). % \begin{macrocode} -\clist_new:N \g_docinput_clist \cs_set:Npn \DocInput #1 { \clist_map_inline:nn {#1} { \clist_put_right:Nn \g_docinput_clist {##1} @@ -1744,12 +1929,6 @@ Do not distribute a modified version of this file. % Print all defined and documented macros/functions. % % \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} \iow_open:Nn \g_write_func_stream { \jobname.cmds } % \end{macrocode} % @@ -1820,7 +1999,7 @@ Do not distribute a modified version of this file. { \tl_put_right:Nn \l_tmpa_tl {^^J\space\space\space\space ##1 - ^^J\space\space\space\space\space\space ##2} + ^^J\space\space\space\space\space\space ##2} } } \seq_if_empty:NF \g_doc_not_tested_seq @@ -2013,49 +2192,90 @@ page_precedence "rnaA" % \end{macrocode} % % \section{Testing} -%\ExplSyntaxOn +%\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}{\example_foo:N|\example_foo:c} +% \begin{function}{.bool_set:N} +% blah +% \end{function} +% +% \lipsum[2] +% \ExplSyntaxOn \cs_set_eq:NN \c_alignment_token @ \ExplSyntaxOff +% \begin{variabledoc} +% { +% \c_alignment_token, +% } +% \end{variabledoc} +% \ExplSyntaxOn \cs_set_eq:NN \c_alignment_token & \ExplSyntaxOff +% +% \begin{function}[added=2011-09-06]{\example_foo:N,\example_foo:c} % \begin{syntax} % "\example_foo:N" <arg1> +% "\example_foo:c" \Arg{arg1} % \end{syntax} % <0123456789> <\0\1\2\3\4\5\6\7\8\9> \Arg{arg1} ":(" % \end{function} % -% \begin{function}{ \foo | \foo: | \foo:x | \barrz: } +% \begin{function}[added=2011-09-06]{ \foo , \foo: , \foo:x , \barrz: } % \begin{syntax} % "\example_foo:N" <arg1> % \end{syntax} % <0123456789> <\0\1\2\3\4\5\6\7\8\9> % \end{function} % -% \begin{function}{\foo:N / (TF) | \foo_if:c / (TF) (EXP)} +% \begin{function}[TF]{\foo:N , \foo_if:c } +% Test. +% \end{function} +% \begin{function}[TF,EXP]{\foo:N , \foo_if:c } % Test. % \end{function} % -% \begin{function}[EXP]{\fffoo:N} +% \begin{function}[added=2011-09-06,EXP]{\fffoo:N} +% Test. +% \end{function} +% \begin{function}[added=2011-09-06,updated=2011-09-07,EXP]{\fffoo:N} +% Test. +% \end{function} +% \begin{function}[updated=2011-09-06,EXP]{\fffoo:N} % Test. % \end{function} % \begin{function}[TF]{\ffffoo:N} % Test. % \end{function} % \begin{function}[pTF]{\ffoo:N} -% Test. +% \lipsum[6] +% \end{function} +% \begin{function}[pTF]{\ffoo:N,\ffoo:c,\ffoo:V} +% \lipsum[6] +% \end{function} +% \begin{function}[pTF]{\ffoo:N,\ffoo:c} +% \lipsum[6] +% \end{function} +% +% +% \begin{function}[TF]{\ffffoo_with_very_very_very_long_name:N} +% \lipsum[1] +% \end{function} +% +% \begin{function}[TF]{\ffffoo_with_very_very_very_long_name:N,\ffffoo_with_very_very_very_long_name:c,\ffffoo_with_very_very_very_long_name:V} +% \lipsum[1] % \end{function} % -% \begin{function}{ \bar / (EXP) | \bar: / (EXP) | \bar:x / (EXP) | } +% \begin{function}[TF]{\ffffoo_with_very_very_very_long_name:N,\ffffoo_with_very_very_very_long_name:c,\ffffoo_with_very_very_very_long_name:V} % \begin{syntax} -% "\example_foo:N" <arg1> +% this is how you use it % \end{syntax} -% <0123456789> <\0\1\2\3\4\5\6\7\8\9> +% \lipsum[1] % \end{function} % -% \begin{macro}{ \foo , \foo: , \foo:x } -% Testing. -% \end{macro} +% \begin{function}[TF]{\ffffoo_with_very_very_very_long_name:N,\ffffoo_with_very_very_very_long_name:V} +% \begin{syntax} +% this is how you use it +% \end{syntax} +% \lipsum[1] +% \end{function} % % \bigskip\bigskip % @@ -2081,18 +2301,25 @@ page_precedence "rnaA" % \end{macrocode} % \end{macro} % -% % \begin{function}{\::N} % this is (no longer) weird % \end{function} -% +% % \begin{macro}{\::N} % this is (no longer) weird % \end{macro} -% +% +% +% % \begin{function}[EXP]{\foo}\end{function} % \begin{function}[rEXP]{\foo}\end{function} -% +% +% here is some verbatim text: +% \begin{verbatim} +% a & B # c +% \end{verbatim} +% without overriding this with fancyvrb there would be extraneous whitespace. +% % \begin{macro}{\c_minus_one, % \c_zero, % \c_one, @@ -2121,8 +2348,8 @@ page_precedence "rnaA" % Another test. % \end{macro} % -% -%\ExplSyntaxOn +% +%\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 |