# How to prevent doc from indexing foreign macros?

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?

-
A package usually defines many auxiliary macros which are not listed with \begin{macro} or \DescribeMacro. In some cases the list for \DoIndex would be longer than the list for \DoNotIndex. I usually copy a list for \DoNotIndex from another package and add the items necessary for the current one. –  egreg Feb 28 '12 at 17:27
@egreg: If one omits \begin{macro} for a new macro and uses the macro later, then he/she will end up with many "usage" entries in the index and no "definition" entry, which defeats the purpose of having the index. You could say that one can look at the first entry, but this is not semantically correct. –  Andrey Vihrov Feb 28 '12 at 17:57

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

-