[latex3-commits] [git/LaTeX3-latex3-latex3] master: Some indexing fixes to the l3doc doc (see #450) (#602) (1ff98b23f)
Joseph Wright
joseph.wright at morningstar2.co.uk
Wed Jul 24 17:52:14 CEST 2019
Repository : https://github.com/latex3/latex3
On branch : master
Link : https://github.com/latex3/latex3/commit/1ff98b23f059eaacee491156abf432467ce301cd
>---------------------------------------------------------------
commit 1ff98b23f059eaacee491156abf432467ce301cd
Author: Phelype Oleinik <phe.h.o1 at gmail.com>
Date: Wed Jul 24 12:52:14 2019 -0300
Some indexing fixes to the l3doc doc (see #450) (#602)
* Some indexing fixes to the l3doc doc (see #450)
Some indexing fixes after Stone-Zeng's comments in #450. Namely:
1) Replace <@@=...> by <@@@@=...> in comments (bug introduced with #596);
2) Fixed `\@for\@tempa:=` (: is a letter here): replaced by `\clist_map_inline:Nn`;
3) Removed indexing of pseudo commands (`\meta{name}:\meta{signature}`);
4) `\>` would become `\!\efill` and `|` and `=` would fail to index.
* Added do-not-index option to macro environment
Added a `do-not-index` option to the `macro` environment to keep some control sequences from being indexed when innapropriate.
>---------------------------------------------------------------
1ff98b23f059eaacee491156abf432467ce301cd
l3kernel/l3doc.dtx | 69 ++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 57 insertions(+), 12 deletions(-)
diff --git a/l3kernel/l3doc.dtx b/l3kernel/l3doc.dtx
index bfac8aa61..1a0f256d4 100644
--- a/l3kernel/l3doc.dtx
+++ b/l3kernel/l3doc.dtx
@@ -266,7 +266,7 @@ and all files in that bundle must be distributed together.
%
% Additionally, commands can be used in the argument of \cs{cs}. For
% instance, |\cs{\meta{name}:\meta{signature}}| produces
-% \cs{\meta{name}:\meta{signature}}.
+% \cs[no-index]{\meta{name}:\meta{signature}}.
%
% The \meta{options} are a key--value list which can contain the
% following keys:
@@ -782,19 +782,23 @@ and all files in that bundle must be distributed together.
% \begin{variable}
% {
% \l_@@_index_macro_tl, \l_@@_index_key_tl,
-% \l_@@_index_module_tl, \l_@@_index_internal_bool
+% \l_@@_index_module_tl, \l_@@_index_internal_bool,
+% \l_@@_macro_do_not_index_tl
% }
% When analyzing a control sequence found within a \env{macrocode}
% environment, \cs{l_@@_index_macro_tl} holds the control sequence
% (partially a string), \cs{l_@@_index_key_tl} holds the future
% sort key in the index, and \cs{l_@@_index_module_tl} is the
-% subindex in which the control sequence should be listed. Finally,
+% subindex in which the control sequence should be listed.
% \cs{l_@@_index_internal_bool} indicates when the control sequence is
% internal and should be indexed in a slightly different subindex.
+% Finally, \cs{l_@@_macro_do_not_index_tl} indicates control sequences
+% which should not be indexed in a specifiv \env{macro} envronment.
% \begin{macrocode}
\tl_new:N \l_@@_index_macro_tl
\tl_new:N \l_@@_index_key_tl
\tl_new:N \l_@@_index_module_tl
+\tl_new:N \l_@@_macro_do_not_index_tl
\bool_new:N \l_@@_index_internal_bool
% \end{macrocode}
% \end{variable}
@@ -970,6 +974,7 @@ and all files in that bundle must be distributed together.
\cs_generate_variant:Nn \tl_remove_all:Nn { Nx }
\cs_generate_variant:Nn \tl_replace_all:Nnn { Nx , Nnx, No , Nno }
\cs_generate_variant:Nn \tl_replace_once:Nnn { Noo }
+\cs_generate_variant:Nn \tl_set_rescan:Nnn { NnV }
\cs_generate_variant:Nn \tl_to_str:n { f , o }
\cs_generate_variant:Nn \prop_get:NnNTF { Nx }
\cs_generate_variant:Nn \prop_put:Nnn { Nx }
@@ -1945,7 +1950,7 @@ and all files in that bundle must be distributed together.
}
% \end{macrocode}
%
-% \begin{macro}{\@@_cmd:nn, \@@_cmd:no}
+% \begin{macro}[do-not-index={\\,\_,\1,\c,\2}]{\@@_cmd:nn, \@@_cmd:no}
% Apply the key--value \meta{options}~|#1| after setting some
% default values. Then (unless |replace=false|) replace |@@| in~|#2|,
% which is a bit tricky: the |_| must be given the catcode expected by
@@ -2424,7 +2429,8 @@ and all files in that bundle must be distributed together.
}
% \end{macrocode}
%
-% \begin{macro}{\@@_date_set:Nn,\@@_date_set_past:Nn}
+% \begin{macro}[do-not-index={\A,\Z,\d,\1,\2,\3}]
+% {\@@_date_set:Nn,\@@_date_set_past:Nn}
% Normalize the date into the format \texttt{YYYY-MM-DD}; more
% precisely month and day are allowed to be single digits. The
% \cs{@@_date_set_past:Nn} function only allows dates in the past (or
@@ -2917,6 +2923,9 @@ and all files in that bundle must be distributed together.
verb .bool_set:N = \l_@@_names_verb_bool ,
module .tl_set:N = \l_@@_override_module_tl ,
documented-as .tl_set:N = \l_@@_macro_documented_tl ,
+ do-not-index .value_required:n = true ,
+ do-not-index .tl_set:N = \l_@@_macro_do_not_index_tl ,
+ % do-not-index .default:n = \q_no_value ,
}
% \end{macrocode}
%
@@ -2936,6 +2945,7 @@ and all files in that bundle must be distributed together.
\keys_set:nn { l3doc/macro } {#1}
\@@_names_get_seq:nN {#2} \l_@@_names_seq
\@@_names_parse:
+ \@@_macro_exclude_index:
\@@_macro_save_names:
\@@_names_typeset:
\@@_macro_dump:
@@ -3011,6 +3021,37 @@ and all files in that bundle must be distributed together.
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\@@_macro_exclude_index:}
+% Some control sequences in a \env{macrocode} environment shouldn't
+% be indexed, for different reasons. This macro parses the argument
+% of the |do-not-index| option and locally removes the given macros
+% from the index.
+%
+% The optional argument to \env{macro} is not scanned with verbatim
+% catcodes, so we use \cs{tl_set_rescan:NnV} to rescan the commands
+% with the same catcodes as \cs{DoNotIndex}. The scanned token list
+% contains spaces after control sequences, which are not there when
+% \cs{DoNotIndex} is used. Since \cs{seq_set_from_clist:Nn} removes
+% spaces around the items, we can abuse that and \cs{seq_use:Nn} to
+% normalise each item. After that \cs{DoNotIndex} can do its thing.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_macro_exclude_index:
+ {
+ \tl_if_empty:NF \l_@@_macro_do_not_index_tl
+ {
+ \tl_set_rescan:NnV \l_@@_macro_do_not_index_tl
+ { \MakePrivateLetters \catcode`\\12 }
+ \l_@@_macro_do_not_index_tl
+ \exp_args:NNV \seq_set_from_clist:Nn
+ \l_@@_tmpa_seq \l_@@_macro_do_not_index_tl
+ \tl_set:Nx \l_@@_macro_do_not_index_tl
+ { \seq_use:Nn \l_@@_tmpa_seq { , } }
+ \exp_args:NV \DoNotIndex \l_@@_macro_do_not_index_tl
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\@@_macro_dump:}
% This calls |\makelabel{}|
% \begin{macrocode}
@@ -3494,7 +3535,7 @@ and all files in that bundle must be distributed together.
% \end{macrocode}
% \end{macro}
%
-% \begin{environment}{\NOTE}
+% \begin{environment}{NOTE}
% \begin{NOTE}{wspr}
% this is what I #$%& think about this!
% \end{NOTE}
@@ -3686,10 +3727,12 @@ and all files in that bundle must be distributed together.
\@tempswatrue
\if at partsw
\@tempswafalse
- \cs_set:Npx \@tempb{#1}
- \@for\@tempa:=\@partlist\do
+ \cs_set:Npx \@tempb {#1}
+ \clist_map_inline:Nn \@partlist
{
- \ifx\@tempa\@tempb\@tempswatrue\fi
+ \if_meaning:w \@tempa \@tempb
+ \@tempswatrue
+ \fi:
}
\fi
\if at tempswa
@@ -3825,7 +3868,7 @@ and all files in that bundle must be distributed together.
}
\cs_new_protected:Npn \@@_xmacro_code:w #1 < @ @ = #2 >
{
- % Add code before <@@=...>
+ % Add code before <@@@@=...>
\tl_set:Nn \l_@@_tmpb_tl {#1}
\@@_detect_internals:N \l_@@_tmpb_tl
\@@_replace_at_at:N \l_@@_tmpb_tl
@@ -3833,7 +3876,7 @@ and all files in that bundle must be distributed together.
% Check for \q_recursion_tail
\quark_if_recursion_tail_stop_do:nn {#2}
{ \tl_use:N \l_@@_tmpa_tl }
- % Change module name and add <@@=#2> to typeset output
+ % Change module name and add <@@@@=#2> to typeset output
\tl_gset:Nn \g_@@_module_name_tl {#2}
\tl_put_right:Nn \l_@@_tmpa_tl { < \text { \verbatim at font @ @ = #2 } > }
% Loop
@@ -4221,7 +4264,7 @@ and all files in that bundle must be distributed together.
% \begin{macrocode}
\cs_new_protected:Npn \@@_quote_special_char:N #1
{
- \tl_map_inline:nn { \quotechar \actualchar \encapchar \levelchar }
+ \tl_map_inline:nn { \quotechar \actualchar \encapchar \levelchar \bslash }
{
\tl_replace_all:Nxn #1
{ \tl_to_str:N ##1 } { \quotechar \tl_to_str:N ##1 }
@@ -4521,6 +4564,7 @@ and all files in that bundle must be distributed together.
% Frank: at the moment we do not distribute or generate this file.
% \file{gind.ist} is used instead.
%
+% \begin{macro}[do-not-index={\\,\n}]{}
% \begin{macrocode}
actual '='
quote '!'
@@ -4548,6 +4592,7 @@ headings_flag 1
% Remove R so I is treated in sequence I J K not I II III
page_precedence "rnaA"
% \end{macrocode}
+% \end{macro}
%
% \begin{macrocode}
%</docist>
More information about the latex3-commits
mailing list