How to prevent `doc` from indexing foreign macros?

Question

The doc package, used for documenting LaTeX packages, has the ability to produce an index of all macros used in the package. Index entries can of of three types: where the macro is described, where it is defined and where it is used. However, if \DisableCrossrefs has not been specified, doc will index every macro in the code, including obviously useless entries like \newcommand, \relax, \ifx and so on. There is a command \DoNotIndex, which can be used to specify which macros should not be indexed. However, keeping the list intact is a tedious task that is prone to errors: each time you write a line of code, you need to think/check whether it introduces new unwanted index entries.

One "solution" is to say \DisableCrossrefs and forget about code indexing. I would want something different, namely, have only macros defined by my package listed in the index, which, IMO, makes more sense than blindly indexing everything but a set of explicit exceptions. More specifically, only names specified in the macro and environment environments should be tracked for where they are used, and other names should be omitted (for completeness, one can introduce a \DoIndex command, that is the opposite of \DoNotIndex, for exceptions that should be indexed anyway).

In the following example code, the desired output is that \newcommand and \GenericInfo are not in the index, but, at the same time, \mymacro is still in the index and shows all three references: where it is described, defined and used:

% \iffalse
\documentclass{ltxdoc}
\EnableCrossrefs         
\CodelineIndex
\begin{document}
  \DocInput{test.dtx}
\end{document}
% \fi
%
% \DescribeMacro{\mymacro}
% Some meaningful description.
% 
% \StopEventually{\PrintIndex}
%
% \begin{macro}{\mymacro}
% Here we define the macro.
%    \begin{macrocode}
\newcommand{\mymacro}{hello}
%    \end{macrocode}
% \end{macro}
%
% And here we use it.
%    \begin{macrocode}
\PackageInfo{test}{\mymacro}
%    \end{macrocode}
% 
% \Finale

(Process it with two LaTeX runs with

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

between them.)

How can one achieve this result? Is there a package that already does this?

Answer 1

This version just indexes things that have a |main index entry. It could be adapted to filter on other things. It lists the things that need indexing in the .aux file so may take an extra run before makeindex so things stabilize, this is needed so that a later main entry enables indexing of earlier occurrences.

% \iffalse
\documentclass{ltxdoc}
\makeatletter
\def\SpecialMainIndex#1{%
\@bsphack
\immediate\write\@auxout{%
\global\noexpand\expandafter\let\noexpand\csname MAIN:\noexpand\string\string#1\endcsname\noexpand\@empty}%
\SpecialIndex@{#1}{\encapchar main}\@esphack}
\def\SpecialIndex#1{%
\@bsphack
   \expandafter\ifx\csname MAIN:\string#1\endcsname\@empty
   \special@index{\expandafter\@gobble
                                      \string#1\actualchar
      \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}%
   \fi
    \@esphack}

\EnableCrossrefs      
\EnableCrossrefs         
\CodelineIndex
\begin{document}
  \DocInput{test.dtx}
\end{document}
% \fi
%
% \DescribeMacro{\mymacro}
% Some meaningful description.
% 
% \StopEventually{\PrintIndex}
%
% \begin{macro}{\mymacro}
% Here we define the macro.
%    \begin{macrocode}
\newcommand{\mymacro}{hello}
%    \end{macrocode}
% \end{macro}
%
% And here we use it.
%    \begin{macrocode}
\PackageInfo{test}{\mymacro}
%    \end{macrocode}
% 
% \Finale