[latex3-commits] [git/LaTeX3-latex3-latex3] main: l3doc index: avoid duplicate pages and encap warnings (see #673) (c24acb98e)
Bruno Le Floch
blflatex at gmail.com
Mon May 3 01:52:38 CEST 2021
Repository : https://github.com/latex3/latex3
On branch : main
Link : https://github.com/latex3/latex3/commit/c24acb98eafa981d5e552c573b5053f94126d4f9
>---------------------------------------------------------------
commit c24acb98eafa981d5e552c573b5053f94126d4f9
Author: Bruno Le Floch <blflatex at gmail.com>
Date: Mon May 3 01:44:49 2021 +0200
l3doc index: avoid duplicate pages and encap warnings (see #673)
- makeindex doesn't actually support multi-letter page names so I
switched some internal hacks to use Roman numerals
- switched page references (for \cs and similar) to point to the
top-of-page hypertarget rather than more specific ones; to be
improved later: at least this avoids duplicate pages and the
multiple encap warning from makeindex
>---------------------------------------------------------------
c24acb98eafa981d5e552c573b5053f94126d4f9
l3kernel/CHANGELOG.md | 2 +
l3kernel/l3doc.dtx | 105 ++++++++++++++++++++++++++++++++++++++------------
2 files changed, 83 insertions(+), 24 deletions(-)
diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index 388fe7d2c..d97323169 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -26,6 +26,8 @@ this project uses date-based 'snapshot' version identifiers.
- Regex replacement now errors when using a submatch (`\1` etc) for which
the regex has too few groups
- Showing complex datatypes now validates their internal structure (issue #884)
+- Indexing in l3doc: all page references before codeline references,
+ improve target placement, solve pdfTeX and makeindex warnings
### Fixed
- Evalutate integer constants only once (issue #861)
diff --git a/l3kernel/l3doc.dtx b/l3kernel/l3doc.dtx
index 167c721bf..e856d71fc 100644
--- a/l3kernel/l3doc.dtx
+++ b/l3kernel/l3doc.dtx
@@ -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 at 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 at excludelist} has string catcodes
% in the first place.
% \begin{macrocode}
@@ -3767,21 +3767,53 @@ and all files in that bundle must be distributed together.
}
% \end{macrocode}
%
-% Here, |ACODELINE| is interpreted by |makeindex| as an uppercase latin
-% letter page. We cannot use |CODELINE| because the |C| makes it look
-% like a roman numeral and |makeindex| then complains about the~|O|.
-% Better word welcome.
+% 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 at 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 at wrindex #1
+\cs_gset_protected:Npn \@wrindex #1
+ {
+ \protected at write \@indexfile {}
+ { \string \indexentry {#1} { MMMMI - \thepage } }
+ \endgroup \@esphack
+ }
+\cs_gset_protected:Npn \codeline at wrindex #1
{
\immediate\write\@indexfile
{
\string\indexentry{#1}
- { ACODELINE - \filesep \int_use:N \c at CodelineNo }
+ { MMMMV - \filesep \int_use:N \c at CodelineNo }
}
}
\tl_gclear:N \filesep
+\cs_new_protected:Npn \@@_index_page_hc:nn #1#2
+ {
+ \protected at 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 at HD@hypercount}{#2} }
+ { MMMMV - \filesep \int_use:N \c at CodelineNo - MMMD - \the\c at 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 at CodelineNo| per code line and
+% change |hdclindex{\the\c at 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}
@@ -4249,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 at wrindex }
+ { \@@_index_codeline_hc:nn }
{
\str_case:nnF {#6}
{
- { main } { \codeline at wrindex }
- { usage } { \index }
+ { main } { \@@_index_codeline_hc:nn }
+ { usage } { \@@_index_page_hc:nn }
}
- { \@@_target: \index }
+ { \@@_target: \@@_index_page_hc:nn }
}
{
\tl_if_empty:nF { #3 #4 #5 }
@@ -4267,26 +4299,51 @@ and all files in that bundle must be distributed together.
\token_to_str:N \verbatim at font \c_space_tl
\l_@@_index_escaped_macro_tl
}
- \encapchar hdclindex{\the\c at HD@hypercount}{#6}
}
+ {#6}
}
% \end{macrocode}
%
-% \begin{macro}{\hdclindex, \@@_old_hdclindex:nnn}
-% Note that |#3| here could contain |ACODELINE-| more than once if
-% several successive code lines have been merged into a range somehow.
-% Note that the dash following |ACODELINE| is active in
-% |interface3.tex| and in |source3.tex| at least, so we cannot simply
-% search and remove |ACODELINE-|.
+% \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_generate_variant:Nn \@@_old_hdclindex:nnn { nnV }
-\cs_gset_protected:Npn \hdclindex #1#2#3
- {
- \tl_set:Nn \l_@@_tmpa_tl {#3}
- \tl_replace_all:Nnn \l_@@_tmpa_tl { ACODELINE } { \use_none:n }
- \@@_old_hdclindex:nnV {#1} {#2} \l_@@_tmpa_tl
+\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}
%
More information about the latex3-commits
mailing list.