doc: noindex Suppresses All \index Entries Within macro Environment

[rhelder]

This bug relates to the doc package, v3.0q (2024/10/23).

Actual behavior

When the macro environment is passed the option noindex, all macros in all macrocode environments contained in the macro environment are not indexed -- not just the macro passed to the macro environment as an argument.

Expected behavior

The macro environment should only refuse to index instances of the macro passed to it as an argument, not instances of other macros.

I can't be entirely sure that this is the intended behavior, because the doc documentation (while generally excellent -- thank you!) is somewhat equivocal. First, the documentation says that the noindex option suppresses indexing 'for that particular instance' (p. 6). Consider the following example (not my MWE -- just for illustration purposes):

% \begin{macro}[noindex]{\bar}
%    Here begins the documentation of \cs{bar}.
%    \begin{macrocode}
\def\bar{\def\ARealMacro{a real definition}}
\bar
\undef\bar
%    \end{macrocode}
% \end{macro}

You might think that the documentation means that just the first instance of \bar won't be indexed, but the second and third instances will. This would make some sense, since one of the primary functions of the macro environment is to indicate, in the index, at what line the macro was defined -- so you might think it is that entry which would be suppressed by passing noindex.

Later, when discussing the implementation of environments like macro, the documentation says otherwise; it says that 'further \index entries' are to be suppressed as well (p. 64). Judging by the code (line 964, in the documentation), 'further \index entries' means 'further \index entries of the macro passed to the macro environment as an argument':

\if#1\expandafter\DoNotIndex \expandafter {\saved@macroname}\fi

This also makes some sense; perhaps we don't want to clutter up our index with references to our macro right after we've defined it. (Maybe better to leave that choice to the user though, since they can easily enough call \DoNotIndex themselves within the scope of the macro environment. It is less straightforward, if the user doesn't want further index entries to be ignored, to undo the \DoNotIndex call that the macro environment has already made). In any event, from this part of the documentation, it looks like that what we should expect when we pass noindex to the macro environment is that all instances of the macro won't be indexed -- the noindex option will suppress the first \index entry, and the rest are suppressed by default.

So although the documentation isn't fully clear, it does seem like the intended behavior is not for every \index entry in every macrocode environment to be ignored. (Moreover, as I suggested, the behavior indicated by the user-level documentation seems preferable to the behavior indicated by the documentation of the code).

Use cases affected by the bug

This bug diminishes the macro environment's usefulness in cases where you do not want to index a particular line, but you do want to utilize the macro environment's ability to print macro names in the margins. (E.g., perhaps you are documenting two related macros, that are defined in succession -- you want to print both macro names at once, but slip in an index entry to the second macro later, so that you can get the line number of the definition in the index exactly right). There are, of course, other ways to print marginal text, but there are reasons to prefer being consistent -- so if I am printing some macro names in the margins using the macro environment, I would want all of my macro names to be typeset in the same way.

MWE

Here is a minimal example (min.tex). The example consists of one macro environment enclosing two macrocode environments (to show that the bug extends to more than just the first macrocode environment):

% \iffalse
\RequirePackage{latexbug}
\documentclass{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\begin{document}
\DocInput{min.dtx}
\PrintIndex
\end{document}
% \fi
%
% \begin{macro}[noindex]{\foo}
%    This is uninteresting documentation
%    about the uninteresting macro \cs{foo},
%    which stubbornly rebuts `bar'
%    in response to any argument.
%    \begin{macrocode}
\NewDocumentCommand{\foo}{m}{%
  \large
  \textsc{bar}%
}
%    \end{macrocode}
%    Even \cs{foo}, however,
%    is capable of (uninteresting) change.
     \begin{macrocode}
\RenewDocumentCommand{\foo}{m}{%
  \small
  \textit{bar}%
}
%    \end{macrocode}
% \end{macro}

You will see that, with the noindex option passed to the macro environment, no index entries are produced at all.

As is standard, I used the following makeindex invocation:

makeindex -s gind.ist -o min.ind min.idx

And, as required, I have attached my log file.

Thank you very much for your work -- I hope this bug report can be helpful.

min.log