summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3doc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3doc.dtx661
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