diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3doc.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3doc.dtx | 248 |
1 files changed, 200 insertions, 48 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx index 47f57dfb669..9e079c7f430 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3doc.dtx @@ -27,7 +27,7 @@ \ifx\fmtname\nameofplainTeX\else \expandafter\begingroup \fi -\input l3docstrip.tex +\input docstrip % \askforoverwritefalse \preamble @@ -79,7 +79,7 @@ and all files in that bundle must be distributed together. % % \title{The \cls{l3doc} class} % \author{\Team} -% \date{Released 2021-02-18} +% \date{Released 2021-05-07} % \maketitle % \tableofcontents % @@ -1573,7 +1573,7 @@ and all files in that bundle must be distributed together. % This function tests whether a macro name stored in % \tn{macro@namepart} was excluded from indexing by \tn{DoNotIndex}. % Rather than trying to fix catcodes that come into here, turn -% everything to string catcodes. This is somewhat inefficient as we +% everything to string catcodes. This is slightly inefficient as we % could have ensured that \tn{index@excludelist} has string catcodes % in the first place. % \begin{macrocode} @@ -1981,7 +1981,7 @@ and all files in that bundle must be distributed together. \tl_replace_all:Nno \l_@@_cmd_tl { _ } \l_@@_tmpb_tl } % \end{macrocode} -% \paragraph{Typesetting} +% Typesetting. % Note the replacement for the underscore is to permit linebreaks. % The \texttt{underscore} package adds the linebreak, % and the regex results in applying the breakable underscore only to the \emph{last} @@ -1989,6 +1989,7 @@ and all files in that bundle must be distributed together. % \begin{macrocode} \mode_if_math:T { \mbox } { + \bool_if:NT \l_@@_allow_indexing_bool { \@@_target: } \verbatim@font \@@_if_almost_str:VT \l_@@_cmd_tl { @@ -1996,8 +1997,8 @@ and all files in that bundle must be distributed together. \bool_if:NT \g_@@_cs_break_bool { \regex_replace_all:nnN - {([^\\])_([^\_])} - {\1\c{BreakableUnderscore}\2} + { ([^\\\_]\_*) \_ ([^\_]) } + { \1 \c{BreakableUnderscore} \2 } \l_@@_cmd_tl } } @@ -2006,16 +2007,17 @@ and all files in that bundle must be distributed together. \@ } % \end{macrocode} -% \paragraph{Indexing} +% Indexing. % \begin{macrocode} - \bool_if:NF \l_@@_cmd_noindex_bool - { + \bool_if:NT \l_@@_allow_indexing_bool + { + \bool_if:NF \l_@@_cmd_noindex_bool + { \quark_if_no_value:NF \l_@@_cmd_index_tl { \__kernel_tl_set:Nx \l_@@_cmd_tl { \c_backslash_str \exp_not:o { \l_@@_cmd_index_tl } } } - \exp_args:No \@@_key_get:n { \l_@@_cmd_tl } \quark_if_no_value:NF \l_@@_cmd_module_tl { @@ -2028,7 +2030,8 @@ and all files in that bundle must be distributed together. { \l_@@_index_module_tl } { usage } \l_@@_index_internal_bool - } + } + } } \cs_generate_variant:Nn \@@_cmd:nn { no } % \end{macrocode} @@ -2241,7 +2244,7 @@ and all files in that bundle must be distributed together. % \begin{macro}{\@@_names_typeset:} % \begin{macro}{\@@_names_typeset_auxi:n} % This code is in particular used when typesetting function names in a -% \env{function} environment. The mapping to \cs{l_@@_names_block_tl} +% \env{function} environment. The mapping over \cs{l_@@_names_block_tl} % cannot use \cs{tl_map_inline:Nn} because the code following |\\| % would not be expandable, thus breaking \tn{bottomrule}. % @@ -2688,8 +2691,7 @@ and all files in that bundle must be distributed together. \cs_new_protected:Npn \@@_typeset_functions: { \small\ttfamily - \HD@savedestfalse - \HD@target + \@@_target: \Hy@MakeCurrentHref { HD. \int_use:N \c@HD@hypercount } \begin{tabular} [t] { @{} l @{} >{\hspace{\tabcolsep}} r @{} } \toprule @@ -2982,8 +2984,7 @@ and all files in that bundle must be distributed together. \hbox:n { \strut - \int_compare:nNnT \l_@@_macro_int = 0 - { \HD@target } + \int_compare:nNnT \l_@@_macro_int = 0 { \@@_target: } } \vskip \int_eval:n { \l_@@_macro_int - 1 } \baselineskip } @@ -3146,7 +3147,9 @@ and all files in that bundle must be distributed together. % the first items of nested \tn{trivlist}, but these were not closed % properly with \tn{endtrivlist}. Also, it interacted in surprising % ways with \pkg{hyperref} targets. Now, we collect typeset macro -% names by hand in the box \cs{l_@@_macro_box}. Note the space |\ |. +% names by hand in the box \cs{l_@@_macro_box}. The fixed-size space +% |\MacroFont\ | could be replaced by an customizable horizontal +% space; it is important for it to be the same for all macros. % |#1| is the macro name, |#2| whether to add |TF|. % \begin{macrocode} \cs_new_protected:Npn \@@_macro_typeset_one:nN #1#2 @@ -3154,9 +3157,8 @@ and all files in that bundle must be distributed together. \vbox_set:Nn \l_@@_macro_box { \vbox_unpack_drop:N \l_@@_macro_box - \hbox { \llap { \__codedoc_print_macroname:nN {#1} #2 - \MacroFont % <----- without it the \ is in lmr10 if a link is made - \ + \hbox { \llap { \@@_print_macroname:nN {#1} #2 + \MacroFont \ } } } \int_incr:N \l_@@_macro_int @@ -3440,21 +3442,16 @@ and all files in that bundle must be distributed together. { \@bsphack \begingroup - \HD@target - \let\HDorg@encapchar\encapchar - \edef\encapchar usage - { - \HDorg@encapchar hdclindex{\the\c@HD@hypercount}{usage} - } + \@@_target: \index { #1\actualchar{\protect\ttfamily#1}~(option) - \encapchar usage + \encapchar hdclindex{\the\c@HD@hypercount}{usage} } \index { options:\levelchar#1\actualchar{\protect\ttfamily#1} - \encapchar usage + \encapchar hdclindex{\the\c@HD@hypercount}{usage} } \endgroup \@esphack @@ -3770,17 +3767,53 @@ and all files in that bundle must be distributed together. } % \end{macrocode} % +% Here, |MMMMI| (for page references) and |MMMMV| (for codeline +% references) are interpreted by |makeindex| as an uppercase Roman +% number pages, and should be large enough to avoid collisions with +% other uses of uppercase Roman number pages. Two subtle differences +% between \cs{@wrindex} and \cs{codeline@wrindex} are that the first +% must be a delayed write because the page number is not known yet, and +% it must close a group and finish some space-hack. +% +% We also provide versions for our use that refer % \begin{macrocode} -\cs_gset:Npn \codeline@wrindex #1 +\cs_gset_protected:Npn \@wrindex #1 + { + \protected@write \@indexfile {} + { \string \indexentry {#1} { MMMMI - \thepage } } + \endgroup \@esphack + } +\cs_gset_protected:Npn \codeline@wrindex #1 { \immediate\write\@indexfile { \string\indexentry{#1} - { \filesep \int_use:N \c@CodelineNo } + { MMMMV - \filesep \int_use:N \c@CodelineNo } } } \tl_gclear:N \filesep +\cs_new_protected:Npn \@@_index_page_hc:nn #1#2 + { + \protected@write \@indexfile {} + { + \string \indexentry { #1 \encapchar hdpindex{#2} } + { MMMMI - \thepage } + } + } +\cs_new_protected:Npn \@@_index_codeline_hc:nn #1#2 + { + \immediate\write\@indexfile + { + \string \indexentry { #1 \encapchar hdclindex{\the\c@HD@hypercount}{#2} } + { MMMMV - \filesep \int_use:N \c@CodelineNo - MMMD - \the\c@HD@hypercount - M } + } + } % \end{macrocode} +% We already have a single |HD.xx| target per code line. It would be +% better to have a target |CL.\the\c@CodelineNo| per code line and +% change |hdclindex{\the\c@HD@hypercount}| to a mechanism closer to +% |hdpindex|, but we need to understand better the different types of +% indexings, and there are subtleties with indexing |\{| and |\}|. % \end{macro} % % \begin{macro}{\docincludeaux} @@ -4038,6 +4071,53 @@ and all files in that bundle must be distributed together. % % \subsection{Indexing} % +% \subsubsection{Necessary patching} +% +% The following is useful to set up \pkg{hyperref} targets, for instance +% for the purpose of indexing. Contrarily to \pkg{hypdoc} we do not try +% to save pdf destinations, as this leads to too many \pdfTeX{} warnings +% on early runs. +% \begin{macrocode} +\cs_new_protected:Npn \@@_target: + { + \mode_leave_vertical: + \group_begin: + \HD@savedestfalse \HD@target + \group_end: + } +% \end{macrocode} +% Force targets on every code line. +% \begin{macrocode} +\cs_set_nopar:Npx \theCodelineNo + { + \group_begin: + \exp_not:N \HD@savedestfalse + \exp_not:o \theCodelineNo + \group_end: + } +% \end{macrocode} +% +% Inside the table of contents (and other similar lists introduced by +% \cs{@starttoc}), we suppress indexing. This is because \cs{cmd}, +% \cs{cs}, or \cs{tn} appearing in titles only gets typeset in the +% second run, and getting their indexing right would require even more +% runs than we already need. Besides, it is not useful to index uses of +% some command in the table of contents. +% \begin{macrocode} +\bool_new:N \l_@@_allow_indexing_bool +\bool_set_true:N \l_@@_allow_indexing_bool +\use:x + { + \exp_not:n { \cs_set_nopar:Npn \@starttoc #1 } + { + \group_begin: + \bool_set_false:N \l_@@_allow_indexing_bool + \exp_not:o { \@starttoc {#1} } + \group_end: + } + } +% \end{macrocode} +% % \subsubsection{Userspace commands} % % Fix index (for now): @@ -4201,14 +4281,14 @@ and all files in that bundle must be distributed together. \@@_quote_special_char:N \l_@@_index_escaped_key_tl \@@_special_index_set:Nn \l_@@_index_escaped_macro_tl {#2} \str_if_eq:onTF { \@currenvir } { macrocode } - { \codeline@wrindex } + { \@@_index_codeline_hc:nn } { \str_case:nnF {#6} { - { main } { \codeline@wrindex } - { usage } { \index } + { main } { \@@_index_codeline_hc:nn } + { usage } { \@@_index_page_hc:nn } } - { \HD@target \index } + { \@@_target: \@@_index_page_hc:nn } } { \tl_if_empty:nF { #3 #4 #5 } @@ -4219,12 +4299,54 @@ and all files in that bundle must be distributed together. \token_to_str:N \verbatim@font \c_space_tl \l_@@_index_escaped_macro_tl } - \encapchar - hdclindex{\the\c@HD@hypercount}{#6} } + {#6} } % \end{macrocode} % +% \begin{macro}{\hdpindex, \@@_old_hdpindex:nn, \hdclindex, \@@_old_hdclindex:nnn, \@@_hdindex:nn, \c_@@_active_minus_tl, \@@_hdindex_aux:nn, \@@_hdindex_aux:w} +% Note that |#3| here could contain |MMMMI-| or |MMMMV-| more than once +% if several successive code lines have been merged into a range +% somehow. Note incidentally that the dash is active in some of our +% sources, like |interface3.tex| or |source2e.tex|. +% \begin{macrocode} +\group_begin: +\char_set_active_eq:NN - \scan_stop: +\tl_const:Nx \c_@@_active_minus_tl { \char_generate:nn { `- } { 13 } } +\group_end: +\cs_new_eq:NN \@@_old_hdpindex:nn \hdpindex +\cs_new_eq:NN \@@_old_hdclindex:nnn \hdclindex +\cs_gset_protected:Npn \hdpindex #1 + { \@@_hdindex:nn { \@@_old_hdpindex:nn {#1} } } +\cs_gset_protected:Npn \hdclindex #1#2 + { \@@_hdindex:nn { \@@_old_hdclindex:nnn {#1} {#2} } } +\cs_new_protected:Npn \@@_hdindex:nn #1#2 + { + \tl_set:Nn \l_@@_tmpa_tl {#2} + \tl_replace_all:Nxn \l_@@_tmpa_tl + { \exp_not:V \c_@@_active_minus_tl \exp_not:V \c_@@_active_minus_tl } + { -- } + \seq_set_split:NnV \l_@@_tmpa_seq { -- } \l_@@_tmpa_tl + \seq_set_map:NNn \l_@@_tmpa_seq \l_@@_tmpa_seq + { \@@_hdindex_aux:nn {#1} {##1} } + \seq_use:Nn \l_@@_tmpa_seq { -- } + } +\cs_new_protected:Npn \@@_hdindex_aux:nn #1#2 + { + \tl_set:Nn \l_@@_tmpa_tl {#2} + \tl_replace_all:Nnn \l_@@_tmpa_tl { MMMM } { \use_none:nn } + \tl_if_in:NnT \l_@@_tmpa_tl { MMMD } + { + \tl_replace_all:Nxn \l_@@_tmpa_tl + { \exp_not:V \c_@@_active_minus_tl MMMD } { - MMMD } + \tl_replace_all:Nnn \l_@@_tmpa_tl { - MMMD } { \@@_hdindex_aux:w } + } + \use:x { \exp_not:n {#1} { \exp_not:V \l_@@_tmpa_tl } } + } +\cs_new_protected:Npn \@@_hdindex_aux:w #1 M { } +% \end{macrocode} +% \end{macro} +% % \begin{macrocode} \cs_new_protected:Npn \@@_special_index_set:Nn #1#2 { @@ -4373,11 +4495,18 @@ and all files in that bundle must be distributed together. % otherwise use the part before any underscore as the module name. % For variables, distinguish quarks and scan marks (starting with |q| % and~|s|), then drop the first letter (local/global/constant marker) -% and underscores. If there is no underscore left we had something -% like \cs{c_zero} which we assume is an integer constant. If there -% is one underscore we assume it is a variable like \cs{c_empty_tl} -% whose module name is the last part. Otherwise the module name is -% the part before any underscore. +% and underscores to improve the index sorting. +% Then get the module as the first (underscore-delimited) \enquote{word}. +% In the past, we distinguished according to how many such words there +% were, to detect commands like \cs[no-index]{c_zero}, which should be +% sorted as |int| variables, and \cs[no-index]{l_tmpa_dim}, which should +% be sorted in the |dim| and not the |tmpa| module. +% Now the first case has been deprecated for some time, while |tmpa| and +% similar are special-cased through an explicit list given below. +% The way it works is that if the module is in a list of special names +% that are not valid modules, then we try the last word, and if that +% also fails (for instance in the deprecated \cs[no-index]{c_one_hundred}) +% we empty the module completely. % \begin{macrocode} \cs_new_protected:Npn \@@_key_var: { @@ -4387,7 +4516,7 @@ and all files in that bundle must be distributed together. \str_case:fn { \str_head:N \l_@@_index_key_tl } { { q } { \tl_set:Nn \l_@@_index_module_tl { quark } } - { s } { \tl_set:Nn \l_@@_index_module_tl { quark } } + { s } { \tl_set:Nn \l_@@_index_module_tl { scan } } } \@@_key_pop: \@@_key_pop: @@ -4396,15 +4525,14 @@ and all files in that bundle must be distributed together. { \seq_set_split:NoV \l_@@_tmpa_seq { \token_to_str:N _ } \l_@@_index_key_tl - \__kernel_tl_set:Nx \l_@@_index_module_tl + \seq_get_left:NN \l_@@_tmpa_seq \l_@@_index_module_tl + \clist_if_in:NoT \g_@@_non_modules_clist \l_@@_index_module_tl { - \int_case:nnF { \seq_count:N \l_@@_tmpa_seq } + \seq_get_right:NN \l_@@_tmpa_seq \l_@@_index_module_tl + \clist_if_in:NoT \g_@@_non_modules_clist \l_@@_index_module_tl { - { 0 } { } - { 1 } { int } - { 2 } { \seq_item:Nn \l_@@_tmpa_seq { 2 } } + \tl_clear:N \l_@@_index_module_tl } - { \seq_item:Nn \l_@@_tmpa_seq { 1 } } } } } @@ -4416,6 +4544,30 @@ and all files in that bundle must be distributed together. % \end{macrocode} % \end{macro} % +% \begin{variable}{\g_@@_non_modules_clist} +% List of names that appear as the first word in an \pkg{expl3} +% command, but that are not true modules, so that they should be +% sorted differently in an index. +% \begin{macrocode} +\clist_new:N \g_@@_non_modules_clist +\clist_gset:Nx \g_@@_non_modules_clist + { + \tl_to_str:n + { + + alignment, ampersand, atsign, backslash, catcode, circumflex, + code, colon, document, dollar, e, empty, false, hash, inf, + initex, job, left, log, math, mark, max, minus, nan, nil, no, + novalue, other, parameter, percent, pi, recursion, right, space, + stop, term, tilde, tmpa, tmpb, true, underscore, zero, one, two, + three, four, five, six, seven, eight, nine, ten, eleven, twelve, + thirteen, fourteen, fifteen, sixteen, thirty, hundred + + } + } +% \end{macrocode} +% \end{variable} +% % \subsection{Change history} % % Set the change history to use \tn{part}. |