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.dtx248
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}.