diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3doc.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3doc.dtx | 511 |
1 files changed, 345 insertions, 166 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx index 8eec496836e..137d75f056f 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -%% File: l3doc.dtx Copyright (C) 1990-2011 The LaTeX3 project +%% File: l3doc.dtx Copyright (C) 1990-2012 The LaTeX3 project %% %% It may be distributed and/or modified under the conditions of the %% LaTeX Project Public License (LPPL), either version 1.3c of this @@ -55,7 +55,7 @@ Do not distribute a modified version of this file. % stop docstrip adding \endinput \postamble \endpostamble -\generate{\file{l3doc.cls}{\from{l3doc.dtx}{class}}} +\generate{\file{l3doc.cls}{\from{l3doc.dtx}{class,cfg}}} \generate{\file{l3doc.ist}{\from{l3doc.dtx}{docist}}} \ifx\fmtname\nameofplainTeX \expandafter\endbatchfile @@ -64,10 +64,6 @@ Do not distribute a modified version of this file. \fi %</driver> % -%<*driver|class> -\RequirePackage{expl3,xparse,calc} -%</driver|class> -% % Need to protect the file metadata for any modules that load l3doc. % This is restored after "\ProvideExplClass" below. % \begin{macrocode} @@ -78,7 +74,11 @@ Do not distribute a modified version of this file. % \end{macrocode} % %<*driver|class> -\GetIdInfo$Id: l3doc.dtx 3491 2012-03-04 06:13:18Z bruno $ +\RequirePackage{expl3,xparse,calc} +%</driver|class> +% +%<*driver|class> +\GetIdInfo$Id: l3doc.dtx 3989 2012-07-16 01:15:43Z bruno $ {L3 Experimental documentation class} %</driver|class> % @@ -265,7 +265,7 @@ Do not distribute a modified version of this file. % when the DTX file is "\DocInput"; use "\DisableDocumentation"/"\DisableImplementation" % to omit the contents of those environments. % -% Note that \cmd\DocInput\ now takes comma-separated arguments, and \cmd\DocInputAgain\ +% Note that "\DocInput" now takes comma-separated arguments, and "\DocInputAgain" % can be used to re-input all DTX files previously input in this way. % % \subsection{Describing functions in the documentation} @@ -463,16 +463,6 @@ Do not distribute a modified version of this file. %<*class> % \end{macrocode} % -% The Guilty Parties. -% \begin{macrocode} -\cs_new_nopar:Npn\Team{% - The~\LaTeX3~Project\thanks{% - Frank~Mittelbach,~Denys~Duchier,~Chris~Rowley,~ - Rainer~Sch\"opf,~Johannes~Braams,~Michael~Downes,~ - David~Carlisle,~Alan~Jeffrey,~Morten~H\o{}gholm,~Thomas~Lotze,~ - Javier~Bezos,~Will~Robertson,~Joseph~Wright,~Bruno~Le~Floch}} -% \end{macrocode} -% % \subsection{Variables} % % \begin{macrocode} @@ -518,6 +508,19 @@ Do not distribute a modified version of this file. \bool_new:N \g_doc_checktest_bool % \end{macrocode} % +% Temporaries: +% \begin{macrocode} +\seq_new:N \g_doc_tmpa_seq +\tl_new:N \l_doc_tmpa_tl +\tl_new:N \l_doc_tmpb_tl +\int_new:N \l_doc_tmpa_int +% \end{macrocode} +% +% Other: +% \begin{macrocode} +\bool_new:N \l_doc_tested_bool +% \end{macrocode} +% % \subsection{expl3 extras} % % \begin{macro} @@ -526,18 +529,20 @@ Do not distribute a modified version of this file. % \coffin_gset_eq:cN, \coffin_gset_eq:cc % } % Setting two coffins equal is just a wrapper around other functions. +% Slightly naughty use of an internal coffin function here, but \ldots % \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 + \__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} % @@ -571,16 +576,18 @@ Do not distribute a modified version of this file. \ExecuteOptions{full,a4paper,nocheck,nochecktest,lm-default} % \end{macrocode} % -% Input a local configuration file, if it exists. +% Input a local configuration file, if it exists, with a message to the console that this has happened. Since we distribute a cfg file with the class, this should usually always be true. Therefore, check for \cs{ExplMakeTitle} (defined in `our' cfg file) and only output the informational message if it's not found. % % \begin{macrocode} -\InputIfFileExists{l3doc.cfg} +\msg_new:nnn {l3doc} {input-cfg} { - \typeout{*************************************^^J - *~Local~config~file~l3doc.cfg~used ^^J - *************************************} + Local~config~file~l3doc.cfg~loaded. + } +\file_if_exist:nT {l3doc.cfg} + { + \file_input:n {l3doc.cfg} + \msg_info:nn {l3doc} {input-cfg} } - { \@input{l3doc.ltx} } % \end{macrocode} % % \begin{macrocode} @@ -597,6 +604,7 @@ Do not distribute a modified version of this file. { array, alphalph, + amsmath, booktabs, color, colortbl, @@ -679,9 +687,9 @@ Do not distribute a modified version of this file. % \begin{macrocode} \setcounter{StandardModuleDepth}{1} \@addtoreset{CodelineNo}{part} -\cs_set_nopar:Npn \theCodelineNo { - \textcolor[gray]{0.5}{ \sffamily\tiny\arabic{CodelineNo} } -} +\tl_replace_once:Nnn \theCodelineNo + { \HDorg@theCodelineNo } + { \textcolor[gray]{0.5} { \sffamily\tiny\arabic{CodelineNo} } } % \end{macrocode} % % @@ -762,13 +770,29 @@ Do not distribute a modified version of this file. % \end{macrocode} % % \begin{macro}{\cmd,\cs} -% |\cmd{\foo}| Prints |\foo| verbatim. It may be used inside moving -% arguments. |\cs{foo}| also prints |\foo|, for those who prefer that -% syntax. -% \begin{macrocode} -\cs_set_nopar:Npn \cmd #1 { \cs{\expandafter\cmd@to@cs\string#1} } -\cs_set_nopar:Npn \cmd@to@cs #1#2 { \char\number`#2\relax } -\DeclareRobustCommand \cs [1] { \texttt { \char`\\ #1 } } +% |\cmd{\foo}| Prints |\foo| verbatim. It may be used inside moving +% arguments. |\cs{foo}| also prints |\foo|, for those who prefer that +% syntax. There is a bit of shuffling around to make sure that |_| +% has the catcode that \cs{doc_replace_at_at:N} expects, without +% rescanning the whole argument. For that we store in +% \cs{l_doc_tmpb_tl} a single underscore with the current catcode, +% then replace all such underscores by letter underscores in |#1| +% (stored in the |tmpa| token list). After calling +% \cs{doc_replace_at_at:N}, we replace the underscores back to their +% old meaning before using the token list. +% \begin{macrocode} +\cs_set_nopar:Npn \cmd #1 { \cs{\expandafter \doc_cmd_to_cs:w \string#1} } +\cs_set_nopar:Npn \doc_cmd_to_cs:w #1#2 { \char\number`#2\relax } +\DeclareRobustCommand \cs [1] + { + \tl_set_rescan:Nnn \l_doc_tmpb_tl { } { _ } + \tl_set:Nn \l_doc_tmpa_tl {#1} + \tl_replace_all:NVn \l_doc_tmpa_tl \l_doc_tmpb_tl { _ } + \doc_replace_at_at:N \l_doc_tmpa_tl + \tl_replace_all:NnV \l_doc_tmpa_tl { _ } \l_doc_tmpb_tl + \texttt { \char`\\ \tl_use:N \l_doc_tmpa_tl} + } +\cs_generate_variant:Nn \tl_replace_all:Nnn { NV , NnV } % \end{macrocode} % \end{macro} % @@ -823,7 +847,7 @@ Do not distribute a modified version of this file. % \begin{macro}{\DisableDocumentation,\DisableImplementation} % \begin{macrocode} \cs_new:Npn \doc_implementation: { - \cs_set:Npn \variable {\macro[var]} + \DeclareDocumentCommand {\variable} { O{} } { \doc_macro:n { var , ##1 } } \cs_set_eq:NN \endvariable \endmacro } \cs_new:Npn \doc_docu: { @@ -931,8 +955,9 @@ Do not distribute a modified version of this file. \char_set_catcode_ignore:N \ % space \char_set_catcode_ignore:N \^^M \char_set_catcode_ignore:N \^^I - - \function_aux:n + \exp_after:wN + \group_end: + \function_aux:n } { \vcoffin_set_end: @@ -989,8 +1014,6 @@ Do not distribute a modified version of this file. % \begin{macrocode} \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 @@ -1027,7 +1050,7 @@ Do not distribute a modified version of this file. % 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} "} , ... }" +% |> {my_function} => {| \Arg{Nargs_1} \Arg{sig_1} |,| \Arg{Nargs_2} \Arg{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} @@ -1048,22 +1071,22 @@ Do not distribute a modified version of this file. % 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 + { \__cs_get_function_name:N #1 } \l_doc_tmpb_tl { \prop_put:Nxx \l_doc_functions_block_prop - { \cs_get_function_name:N #1 } + { \__cs_get_function_name:N #1 } { - \l_doc_tmp_tl , - {\cs_get_arg_count_from_signature:N #1} - {\cs_get_function_signature:N #1} + \l_doc_tmpb_tl , + {\__cs_count_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_name:N #1 } { - {\cs_get_arg_count_from_signature:N #1} - {\cs_get_function_signature:N #1} + {\__cs_count_signature:N #1} + {\__cs_get_function_signature:N #1} } } } @@ -1072,7 +1095,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 } { {-1} {} } + \prop_put:Nxx \l_doc_functions_block_prop { \tl_to_str:n {#1} } { {-1} {} } } } @@ -1091,13 +1114,13 @@ Do not distribute a modified version of this file. \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 + \clist_gpop:NN \l_doc_variants_clist \l_doc_tmpb_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 } + \int_compare:nT { \exp_after:wN \use_i:nn \l_doc_tmpb_tl > -1 } {:} + \int_compare:nT { \exp_after:wN \use_i:nn \l_doc_tmpb_tl > 0 } + { \exp_after:wN \use_ii:nn \l_doc_tmpb_tl } } \\ } @@ -1105,18 +1128,22 @@ Do not distribute a modified version of this file. \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 + { \l_doc_function_name_prefix_tl \doc_predicate_from_base:N #1 } + \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 } \tl_set:Nx \l_doc_pTF_name_tl { \doc_predicate_from_base:N #1 } - \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 { \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} } - } + \tl_set:Nx \l_doc_tmpa_tl + { + \l_doc_function_name_prefix_tl + \cs_to_str:N #1 + \bool_if:NT \l_doc_meta_TF_bool { \tl_to_str:n {TF} } + } + \doc_special_main_index:o { \l_doc_tmpa_tl } + \seq_gput_right:No \g_doc_functions_seq { \l_doc_tmpa_tl } \bool_if:NTF \l_doc_meta_pTF_bool { @@ -1139,24 +1166,19 @@ Do not distribute a modified version of this file. % \begin{macro}[internal]{\doc_typeset_function_block:N} % \begin{macrocode} \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 \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 } \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 \g_doc_full_bool { \doc_label_function:N #1 } } \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 } - } + { \l_doc_function_name_prefix_tl \cs_to_str:N #1 } \cs_set:Nn \doc_typeset_expandability: { & @@ -1173,12 +1195,12 @@ Do not distribute a modified version of this file. { \\ \doc_typeset_aux:n \g_doc_macro_tl : - \int_compare:nTF { \clist_length:N \l_doc_variants_clist == 1 } + \int_compare:nTF { \clist_count: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_pop:NN \l_doc_variants_clist \l_doc_tmpb_tl + \exp_after:wN \use_ii:nn \l_doc_tmpb_tl \clist_map_inline:Nn \l_doc_variants_clist {\textrm| \use_ii:nn ##1} \textrm) } @@ -1193,15 +1215,12 @@ Do not distribute a modified version of this file. \hyperlink{rexpstar} {\ding{73}} % hollow star } } -\cs_set:Nn \doc_label_function: +\cs_set:Nn \doc_label_function:N { - \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 } - } + \tl_set:Nx \l_doc_tmpa_tl { \l_doc_function_name_prefix_tl \cs_to_str:N #1 } + \exp_args:NNf \tl_replace_all:Nnn \l_doc_tmpa_tl {\token_to_str:N _} {/} + \exp_args:NNf \tl_remove_all:Nn \l_doc_tmpa_tl {\@backslashchar} + \exp_args:Nx \label {doc/function//\l_doc_tmpa_tl} } % \end{macrocode} % \end{macro} @@ -1339,11 +1358,14 @@ Do not distribute a modified version of this file. { \bool_set_true:N \l_doc_macro_TF_bool } , pTF .code:n = { \bool_set_true:N \l_doc_macro_pTF_bool } , + tested .code:n = + { } , } % \end{macrocode} % % \begin{macrocode} -\renewcommand \macro [1][] { +\RenewDocumentCommand { \macro } { O{} } { \doc_macro:n {#1} } +\cs_new_protected:Npn \doc_macro:n #1 { \int_compare:nNnTF \currentgrouplevel=2 { \int_gzero:N \g_doc_nested_macro_int } @@ -1412,7 +1434,7 @@ Do not distribute a modified version of this file. % \begin{macrocode} \cs_set:Nn \doc_predicate_from_base:N { - \cs_get_function_name:N #1 _p: \cs_get_function_signature:N #1 + \__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 { @@ -1427,10 +1449,15 @@ Do not distribute a modified version of this file. % \begin{arguments} % \item Macro/function/whatever name; input has already been sanitised. % \end{arguments} +% \cs{l_doc_at_replaced_macro_tl} stores the macro name after +% replacement of |@@|. % \begin{macrocode} +\tl_new:N \l_doc_at_replaced_macro_tl \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 } + \tl_set:Nx \l_doc_at_replaced_macro_tl { \token_to_str:N #1 } + \doc_replace_at_at:N \l_doc_at_replaced_macro_tl + \tl_set_eq:NN \saved@macroname \l_doc_at_replaced_macro_tl \topsep\MacroTopsep \trivlist \cs_set_nopar:Npn \makelabel ##1 { \llap{##1} } @@ -1457,33 +1484,33 @@ Do not distribute a modified version of this file. } \bool_if:NF \l_doc_macro_aux_bool { - \tl_gset:Nx \l_doc_macro_tl { \tl_to_str:n {#1} } + \tl_gset:Nx \l_doc_macro_tl { \tl_to_str:N \l_doc_at_replaced_macro_tl } \exp_args:NNf \tl_greplace_all:Nnn \l_doc_macro_tl {\token_to_str:N _} {/} \exp_args:NNf \tl_greplace_all:Nnn \l_doc_macro_tl {\@backslashchar} {} } \use:x { \exp_not:N \item [ \exp_not:N \doc_print_macroname:n { - \tl_to_str:n {#1} + \tl_to_str:N \l_doc_at_replaced_macro_tl }] } \global\advance \c@CodelineNo \@ne \bool_if:NF \l_doc_macro_aux_bool { \bool_if:NTF \l_doc_macro_TF_bool { - \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:n { #1 TF } } - \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:n { #1 T } } - \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:n { #1 F } } + \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:N \l_doc_at_replaced_macro_tl \tl_to_str:n {TF} } + \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:N \l_doc_at_replaced_macro_tl \tl_to_str:n {T } } + \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:N \l_doc_at_replaced_macro_tl \tl_to_str:n { F} } }{ - \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:n {#1} } + \seq_gput_right:Nx \g_doc_macros_seq { \tl_to_str:N \l_doc_at_replaced_macro_tl } } } \bool_if:NTF \l_doc_macro_TF_bool { - \SpecialMainIndex{#1 TF}\nobreak - \DoNotIndex{#1 TF} + \exp_args:Nx \SpecialMainIndex{ \tl_to_str:N \l_doc_at_replaced_macro_tl TF}\nobreak + \exp_args:Nx \DoNotIndex{ \tl_to_str:N \l_doc_at_replaced_macro_tl TF} }{ - \SpecialMainIndex{#1}\nobreak - \DoNotIndex{#1} + \exp_args:Nx \SpecialMainIndex{ \tl_to_str:N \l_doc_at_replaced_macro_tl }\nobreak + \exp_args:Nx \DoNotIndex{ \tl_to_str:N \l_doc_at_replaced_macro_tl } } \global\advance \c@CodelineNo \m@ne @@ -1496,7 +1523,8 @@ 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_length:n {#1} <= 28 } + \HD@target + \int_compare:nTF { \tl_count:n {#1} <= 28 } { \MacroFont } { \MacroLongFont } % INEFFICIENT: (!) @@ -1581,15 +1609,16 @@ Do not distribute a modified version of this file. % \end{macro} % % \begin{macro}{\TestMissing} +% Note: There \cs{l_doc_macro_input_clist} may contain unconverted |@@|. % \begin{macrocode} \cs_generate_variant:Nn \prop_gput:Nnn {NVx} \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_get:NVN \g_doc_missing_tests_prop \l_doc_macro_input_clist \l_doc_tmpa_tl \prop_gput:NVx \g_doc_missing_tests_prop \l_doc_macro_input_clist { - *~ \l_tmpa_tl + *~ \l_doc_tmpa_tl ^^J \exp_not:n {\space\space\space\space\space\space} *~ #1 } @@ -1599,11 +1628,45 @@ Do not distribute a modified version of this file. % \end{macrocode} % \end{macro} % +% \begin{variable}{\g_doc_module_name_tl} +% \begin{macro}[int]{\doc_replace_at_at:N} +% \begin{macrocode} +\tl_new:N \g_doc_module_name_tl +\cs_new_protected:Npn \doc_replace_at_at:N #1 { + \tl_if_empty:NF \g_doc_module_name_tl + { + \tl_replace_all:Non #1 { \token_to_str:N @ } { @ } + \tl_replace_all:Non #1 { \token_to_str:N _ } { _ } + \tl_replace_all:Nox #1 { _@@ } { __ \g_doc_module_name_tl } + \tl_replace_all:Nox #1 { @@ } { __ \g_doc_module_name_tl } + } +} +\cs_generate_variant:Nn \tl_replace_all:Nnn { Non, Nox } +% \end{macrocode} +% \end{macro} +% \end{variable} +% % \begin{macro}{\endmacro} +% The \cs{doc_endmacro_wrap_each:N} puts each item of the sequence |#1| +% in \cs{texttt} font and with a trailing TF if needed. This should +% go inline in the definition of \cs{endmacro}, but somehow the |#| +% doesn't go through some \LaTeXe{} internals. % \begin{macrocode} -\cs_set:Nn \doc_macro_wrap:n +\cs_new_protected:Nn \doc_endmacro_build_seq:N + { + \seq_gclear:N #1 + \clist_map_inline:Nn \l_doc_macro_input_clist + { + \tl_set:Nn \l_doc_tmpa_tl {##1} + \doc_replace_at_at:N \l_doc_tmpa_tl + \seq_gput_right:No #1 { \l_doc_tmpa_tl } + } + } +\cs_set_protected:Nn \doc_endmacro_wrap_each:N { - #1 \bool_if:NT \l_doc_macro_TF_bool {TF} + \bool_if:NTF \l_doc_macro_TF_bool + { \seq_gset_map:NNn #1 #1 { \exp_not:N \texttt { ##1 TF } } } + { \seq_gset_map:NNn #1 #1 { \exp_not:N \texttt { ##1 } } } } \cs_set:Nn \doc_texttt_comma:n {\,,~\texttt{#1}} \cs_set:Npn \endmacro { @@ -1611,29 +1674,14 @@ Do not distribute a modified version of this file. { \par\nobreak\noindent{\footnotesize(\emph{ End~ definition~ for~ - \prg_case_int:nnn { \clist_length:N \l_doc_macro_input_clist } - { - {1} { \texttt{ \doc_macro_wrap:n { \clist_use:N \l_doc_macro_input_clist } }. } - {2} + \doc_endmacro_build_seq:N \g_doc_tmpa_seq + \doc_endmacro_wrap_each:N \g_doc_tmpa_seq + \int_compare:nTF { \seq_count:N \g_doc_tmpa_seq <= 3 } { - \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{\doc_macro_wrap:n\l_clist_first_tl}\,~ and~ \texttt{\doc_macro_wrap:n\l_clist_last_tl}\,. + \seq_use:Nnnn \g_doc_tmpa_seq + { \,~and~ } { \,,~ } { \,,~and~ } } - {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{\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{\doc_macro_wrap:n\l_clist_first_tl}\,~and~others. - } + { \seq_item:Nn \g_doc_tmpa_seq {1}\,~and~others. } \bool_if:nT { !\l_doc_macro_aux_bool && !\l_doc_macro_internal_bool && @@ -1656,7 +1704,7 @@ Do not distribute a modified version of this file. { \seq_gput_right:Nx \g_doc_not_tested_seq { - \l_doc_macro_input_clist + \seq_use:Nnnn \g_doc_tmpa_seq { , } { , } { , } \bool_if:NT \l_doc_macro_pTF_bool {~(pTF)} \bool_if:NT \l_doc_macro_TF_bool {~(TF)} } @@ -1665,6 +1713,70 @@ Do not distribute a modified version of this file. % \end{macrocode} % \end{macro} % +% \begin{environment}{macrocode} +% \begin{macro}[aux]{\doc_xmacro_code:n} +% Hook into the \texttt{macrocode} environment in a dirty way: +% \cs{xmacro@code} is responsible for grabbing (and tokenizing) the +% body of the environment. Redefine it to pass what it grabs to +% \cs{doc_xparse_code:n}. This new macro replaces all |@@| by the +% appropriate module name. One exceptional case is the +% |<@@=|\meta{module}|>| lines themselves, where |@@| should not be +% modified. Actually, we search for such lines, to set the module +% name automatically. We need to be careful: no |<@@=| should appear +% as such in the code below since \pkg{l3doc} is also typeset using +% this code. +% \begin{macrocode} +\group_begin: + \char_set_catcode_escape:N \/ + \char_set_catcode_other:N \^^A + \char_set_catcode_active:N \^^S + \char_set_catcode_active:N \^^B + \char_set_catcode_other:N \^^L + \char_set_catcode_other:N \^^R + \char_set_lccode:nn { `\^^A } { `\% } + \char_set_lccode:nn { `\^^S } { `\ } + \char_set_lccode:nn { `\^^B } { `\\ } + \char_set_lccode:nn { `\^^L } { `\{ } + \char_set_lccode:nn { `\^^R } { `\} } + \tl_to_lowercase:n + { + \group_end: + \cs_set_protected:Npn \xmacro@code + #1 ^^A ^^S^^S^^S^^S ^^Bend ^^Lmacrocode^^R + { \doc_xmacro_code:n {#1} /end{macrocode} } + } +\group_begin: + \char_set_catcode_active:N \< + \char_set_catcode_active:N \> + \cs_new_protected:Npn \doc_xmacro_code:n #1 + { + \tl_if_in:nnTF {#1} { < @ @ = } + { \doc_xmacro_code:w #1 \q_stop } + { + \tl_set:Nn \l_doc_tmpa_tl {#1} + \doc_replace_at_at:N \l_doc_tmpa_tl + \tl_use:N \l_doc_tmpa_tl + } + } + \cs_new_protected:Npn \doc_xmacro_code:w #1 < @ @ = #2 > #3 \q_stop + { + \tl_set:Nn \l_doc_tmpa_tl {#1} + \doc_replace_at_at:N \l_doc_tmpa_tl + + \tl_gset:Nn \g_doc_module_name_tl {#2} + \tl_put_right:Nn \l_doc_tmpa_tl { < @ @ = #2 > } + + \tl_set:Nn \l_doc_tmpb_tl {#3} + \doc_replace_at_at:N \l_doc_tmpb_tl + \tl_put_right:No \l_doc_tmpa_tl { \l_doc_tmpb_tl } + + \tl_use:N \l_doc_tmpa_tl + } +\group_end: +% \end{macrocode} +% \end{macro} +% \end{environment} +% % \begin{macro}{\DescribeOption} % For describing package options. Due to Joseph Wright. % Name/usage might change soon. @@ -1987,40 +2099,44 @@ Do not distribute a modified version of this file. % Print all defined and documented macros/functions. % % \begin{macrocode} -\iow_open:Nn \g_write_func_stream { \jobname.cmds } +\iow_new:N \g_doc_func_iow % \end{macrocode} % % \begin{macrocode} \cs_new_nopar:Npn \doc_show_functions_defined: { \bool_if:nT { \g_doc_implementation_bool && \g_doc_checkfunc_bool } { \typeout{ ======================================== ^^J } + \iow_open:Nn \g_doc_func_iow { \c_job_name_tl .cmds } - \tl_clear:N \l_tmpa_tl + \tl_clear:N \l_doc_tmpa_tl \seq_map_inline:Nn \g_doc_functions_seq { \seq_if_in:NnT \g_doc_macros_seq {##1} { - \tl_put_right:Nn \l_tmpa_tl { ##1 ^^J } - \iow_now:Nn \g_write_func_stream { ##1 } + \tl_put_right:Nn \l_doc_tmpa_tl { ##1 ^^J } + \iow_now:Nn \g_doc_func_iow { > ~ ##1 } } } - \iow_close:N \g_write_func_stream + \doc_functions_typeout:n { Functions~both~documented~and~defined:^^J (In~order~of~being~documented) } \seq_map_inline:Nn \g_doc_functions_seq { \seq_if_in:NnF \g_doc_macros_seq {##1} { - \tl_put_right:Nn \l_tmpa_tl { ##1 ^^J } + \tl_put_right:Nn \l_doc_tmpa_tl { ##1 ^^J } + \iow_now:Nn \g_doc_func_iow { ! ~ ##1} } } \doc_functions_typeout:n { Functions~documented~but~not~defined: } \seq_map_inline:Nn \g_doc_macros_seq { \seq_if_in:NnF \g_doc_functions_seq {##1} { - \tl_put_right:Nn \l_tmpa_tl { ##1 ^^J } + \tl_put_right:Nn \l_doc_tmpa_tl { ##1 ^^J } + \iow_now:Nn \g_doc_func_iow { ? ~ ##1} } } \doc_functions_typeout:n { Functions~defined~but~not~documented: } + \iow_close:N \g_doc_func_iow \typeout{ ======================================== } } } @@ -2029,12 +2145,12 @@ Do not distribute a modified version of this file. % % \begin{macrocode} \cs_set_nopar:Npn \doc_functions_typeout:n #1 { - \tl_if_empty:NF \l_tmpa_tl { + \tl_if_empty:NF \l_doc_tmpa_tl { \typeout{ -------------------------------------- ^^J #1 ^^J - -------------------------------------- ^^J \l_tmpa_tl + -------------------------------------- ^^J \l_doc_tmpa_tl } - \tl_clear:N \l_tmpa_tl + \tl_clear:N \l_doc_tmpa_tl } } % \end{macrocode} @@ -2046,23 +2162,23 @@ Do not distribute a modified version of this file. \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 + \tl_clear:N \l_doc_tmpa_tl \prop_if_empty:NF \g_doc_missing_tests_prop { - \tl_put_right:Nn \l_tmpa_tl + \tl_put_right:Nn \l_doc_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 + \tl_put_right:Nn \l_doc_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 + \tl_put_right:Nn \l_doc_tmpa_tl { ^^J^^J The~ following~ macro(s)~ do~ not~ have~ any~ tests:^^J @@ -2071,12 +2187,12 @@ Do not distribute a modified version of this file. { \clist_map_inline:nn {##1} { - \tl_put_right:Nn \l_tmpa_tl {^^J\space\space\space\space ####1} + \tl_put_right:Nn \l_doc_tmpa_tl {^^J\space\space\space\space ####1} } } \int_set:Nn \l_tmpa_int {\etex_interactionmode:D} \errorstopmode - \ClassError{l3doc}{\l_tmpa_tl}{} + \ClassError{l3doc}{\l_doc_tmpa_tl}{} \int_set:Nn \etex_interactionmode:D {\l_tmpa_int} } } @@ -2111,39 +2227,31 @@ Do not distribute a modified version of this file. % \end{macrocode} % % -% \begin{macro}{\doc_special_main_index:n,\doc_special_main_index:o,\hdpgindex} +% \begin{macro}{\doc_special_main_index:n,\doc_special_main_index:o, \doc_special_main_index:x} % Heiko's replacement to play nicely with |hypdoc|: % \begin{macrocode} \cs_set_nopar:Npn \doc_special_main_index:n #1 { + \HD@target \index{ \@gobble#1 \actualchar \string\verb\quotechar*\verbatimchar#1\verbatimchar \encapchar - hdpgindex{\thepage}{usage} - } -} -\cs_set_nopar:Npn \doc_special_main_index:o { \exp_args:No \doc_special_main_index:n } -% \end{macrocode} -% \begin{macrocode} -\cs_set_nopar:Npn \hdpgindex #1#2#3 { - \csname\ifx\\#2\\relax\else#2\fi\endcsname{ - \hyperlink{page.#1}{#3} + hdclindex{\the\c@HD@hypercount}{usage} } } +\cs_generate_variant:Nn \doc_special_main_index:n { o , x } % \end{macrocode} % \end{macro} % % \begin{macrocode} -\g@addto@macro \PrintIndex { \AtEndDocument{ \typeout{^^J - ========================================^^J - Generate~the~index~by~executing^^J - \c_space_tl \c_space_tl \c_space_tl \c_space_tl - makeindex~-s~l3doc.ist~-o~\jobname.ind~\jobname.idx^^J - ========================================^^J - }} -} +\msg_new:nnn {l3doc} {print-index-howto} + { + Generate~the~index~by~executing\\ + \iow_indent:n { makeindex~-s~l3doc.ist~-o~\c_job_name_tl .ind~\c_job_name_tl .idx } + } +\tl_gput_right:Nn \PrintIndex { \AtEndDocument{ \msg_info:nn {l3doc} {print-index-howto} } } % \end{macrocode} % % \subsection{Change history} @@ -2160,14 +2268,12 @@ Do not distribute a modified version of this file. % \end{macrocode} % % \begin{macrocode} -\g@addto@macro \PrintChanges { \AtEndDocument{ \typeout{^^J - ========================================^^J - Generate~the~change~list~by~executing^^J - \c_space_tl \c_space_tl \c_space_tl \c_space_tl - makeindex~-s~gglo.ist~~-o~\jobname.gls~\jobname.glo^^J - ========================================^^J - }} -} +\msg_new:nnn {l3doc} {print-changes-howto} + { + Generate~the~change~list~by~executing\\ + \iow_indent:n { makeindex~-s~gglo.ist~-o~\c_job_name_tl .gls~\c_job_name_tl .glo } + } +\tl_gput_right:Nn \PrintChanges { \AtEndDocument{ \msg_info:nn {l3doc} {print-changes-howto} } } % \end{macrocode} % %^^A The standard \changes command modified slightly to better cope with @@ -2190,7 +2296,7 @@ Do not distribute a modified version of this file. %^^A :\levelchar #3}}% %^^A \@tempa\endgroup\@esphack} % -% \subsection{cfg} +% \subsection{Default configuration} % % \begin{macrocode} \bool_if:NTF \g_doc_full_bool { @@ -2210,6 +2316,79 @@ Do not distribute a modified version of this file. %</class> % \end{macrocode} % +% \subsection{Internal macros for \LaTeX3 sources} +% +% These definitions are only used by the \LaTeX3 documentation; +% they are not necessary for third-party users of l3doc. +% In time this will be broken into a separate package that is specifically +% loaded in the various expl3 modules, etc. +% +% \begin{macrocode} +%<*cfg> +% \end{macrocode} +% +% The Guilty Parties. +% \begin{macrocode} +\cs_new_nopar:Npn\Team{% + The~\LaTeX3~Project\thanks{% + Frank~Mittelbach,~Denys~Duchier,~Chris~Rowley,~ + Rainer~Sch\"opf,~Johannes~Braams,~Michael~Downes,~ + David~Carlisle,~Alan~Jeffrey,~Morten~H\o{}gholm,~Thomas~Lotze,~ + Javier~Bezos,~Will~Robertson,~Joseph~Wright,~Bruno~Le~Floch}} +% \end{macrocode} +% +% \begin{macrocode} +\NewDocumentCommand{\ExplMakeTitle}{mm} + { + \title + { + The~\pkg{#1}~package \\ #2 + \thanks{This~file~describes~v\ExplFileVersion,~ + last~revised~\ExplFileDate.} + } + \author{The~\LaTeX3~Project\thanks{E-mail:~ + \href{mailto:latex-l@listserv.uni-heidelberg.de} + {latex-l@listserv.uni-heidelberg.de}}} + \date{Released~\ExplFileDate} + \maketitle + } +% \end{macrocode} +% +% \subsection{Text extras} +% +% \begin{macrocode} +\DeclareDocumentCommand\ie{}{\emph{i.e.}} +\DeclareDocumentCommand\eg{}{\emph{e.g.}} +\DeclareDocumentCommand\Ie{}{\emph{I.e.}} +\DeclareDocumentCommand\Eg{}{\emph{E.g.}} +% \end{macrocode} +% +% \subsection{Math extras} +% +% For \pkg{l3fp}. +% +% \begin{macrocode} +\AtBeginDocument + { + \clist_map_inline:nn + { + asin, acos, atan, acot, + asinh, acosh, atanh, acoth, round, floor, ceil + } + { \exp_args:Nc \DeclareMathOperator{#1}{#1} } + } +% \end{macrocode} +% +% \begin{macro}{\nan} +% \begin{macrocode} +\NewDocumentCommand { \nan } { } { \text { \texttt { nan } } } +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</cfg> +% \end{macrocode} +% % % \subsection{Makeindex configuration} % |