disable index creation in dtx file

Question

The following code is a minimal dtx code with ending .tex (only for the example).

I try to understand when an index created and when not, how this is influenced by the loading of hyperref and fail to see that the commands of doc.sty behave as documented.

% \iffalse
%<*driver>
\ProvidesFile{dtxcode.tex}
%</driver>
%
%<*driver>
\documentclass{ltxdoc}
% \usepackage{hyperref}

% \EnableCrossrefs  % (default) Every new macro name used within a macrocode or
                  % macrocode∗ environment will produce an index entry.
\DisableCrossrefs % turn off this feature
%
% If an index is created is determined by the use of the following
% declarations in the driver file preamble; if neither is used, no index is 
% produced.
% \PageIndex     % all index entries refer to their page number
% \CodelineIndex % index entries produced by \DescribeMacro and \DescribeEnv
               %  refer to page number but those produced by the macro
               %  environment refer to the code lines, 
               % which will be numbered automatically.
% \CodelineNumbered % no index is created, but the code lines are numbered


\RecordChanges
\listfiles

\begin{document}
  \DocInput{dtxcode.tex}
  \PrintIndex
\end{document}
%</driver>
% \fi
%%
% \DescribeMacro{\foobar} Prints out foobar \index{test}
% 
% \Finale
\endinput

In this code the index is created with both \DisableCrossrefs and DisableCrossrefs

However If I load additionally the package hyperref the index disappears completely no matter what commands I activate. The index file created is nevertheless still the same - it is just not loaded.

And if I use \CodelineNumbered when hyperref is loaded the index appears again though it should not according to the docs of doc.sty.

To me this appears like a bug in ltxdoc/doc.sty.

EDIT: Here a list of scenarios and their results. In all cases the idx file was deleted before execution and the pdf was created with pdflatex, makeindex.exe -s gind.ist %.idx, pdflatex

(a) no hyperref, \EnableCrossrefs and \PageIndex

%\usepackage{hyperref}
\EnableCrossrefs
\PageIndex

Index is created.

(b) no hyperref, \DisableCrossrefs and \PageIndex

%\usepackage{hyperref}
\DisableCrossrefs
\PageIndex

Index is created (but should not?)

(c) no hyperref, \DisableCrossrefs and \CodelineNumbered

%\usepackage{hyperref}
\DisableCrossrefs
\CodelineNumbered

Index is not created, empty idx file.

(d) no hyperref, \EnableCrossrefs and \CodelineNumbered

%\usepackage{hyperref}
\EnableCrossrefs
\CodelineNumbered

Index is not created. It seams that \EnableCrossrefs and \DisableCrossrefs do not control the index in contrast to the description of the documentation.

(e) with hyperref, \EnableCrossrefs and \PageIndex

\usepackage{hyperref}
\EnableCrossrefs
\PageIndex

idx file is created but only self defined \index entries are displayed. In this case test but not foobar, though both are in the idx file with

\indexentry{foobar=\verb!*+\foobar+|usage|hyperpage}{1}
\indexentry{test|hyperpage}{1}

(f) with hyperref, \EnableCrossrefs and \CodelineNumbered

\usepackage{hyperref}
\EnableCrossrefs
\CodelineNumbered

No idx file is created as without hyperref.

To summarize: With loading of hyperref the creation of the index files is not influenced, but the index entries of doc.sty arenot included during compilation in the pdf.

Answer 1

\EnableCrossrefs and \DisableCrossrefs

These macros control, whether command names inside macrocode or macrocode* environments are indexed. From the documentation of package doc:

2.7 Cross-referencing all macros used

\DisableCrossrefs, \EnableCrossrefs

As already mentioned, every new macro name used within a macrocode or macrocode* environment will produce an index entry. In this way one can easily find out where a specific macro is used. Since TeX is considerably slower when it has to produce such a bulk of index entries one can turn off this feature by using \DisableCrossrefs in the driver file. To turn it on again just use \EnableCrossrefs.

Index generation

As usual the index generation is triggered by \makeindex. Macros \CodelineIndex or \PageIndex also call \makeindex.

Discussion of the cases

I have extended dtxcode.tex to show the effect of \EnableCrossrefs:

%    \begin{macrocode}
\def\foobar{...}
%    \end{macrocode}

(a) no hyperref, \EnableCrossrefs and \PageIndex:

\indexentry{foobar=\verb!*+\foobar+|usage}{1}
\indexentry{test}{1}
\indexentry{def=\verb!*+\def+}{1}
\indexentry{foobar=\verb!*+\foobar+}{1}

⇒ Full page based index.

(e) with hyperref, \EnableCrossrefs and \PageIndex:

\indexentry{foobar=\verb!*+\foobar+|usage|hyperpage}{1}
\indexentry{test|hyperpage}{1}
\indexentry{def=\verb!*+\def+|hyperpage}{1}
\indexentry{foobar=\verb!*+\foobar+|hyperpage}{1}

⇒ Full page based index, but wrong index entry for \DescribeMacro/\usage, because hyperref does not support the index format of doc directly.

(b) no hyperref, \DisableCrossrefs and \PageIndex:

\indexentry{foobar=\verb!*+\foobar+|usage}{1}
\indexentry{test}{1}

⇒ Index entries for \DescribeMacro and \index only.

(c), (d), and (f) no/with hyperref, \DisableCrossrefs/\EnableCrossrefs and \CodelineNumbered:

⇒ No index at all, because one of \makeindex or \PageIndex or \CodelineIndex is missing.

Linked index entries

Package hypdoc can be used instead of hyperref: It loads package hyperref, disable hyperref's index support (hyperindex=false) and implements its own support for package doc's index commands. However, hyperpage is not added for plain \index commands, thus it needs to be added (\index{test|hyperpage}).

% \iffalse
%<*driver>
\ProvidesFile{dtxcode.tex}
%</driver>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{hypdoc}

\EnableCrossrefs

\PageIndex
%\CodelineIndex

\RecordChanges
\listfiles

\begin{document}
  \DocInput{dtxcode.tex}
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \DescribeMacro{\foobar} Prints out foobar \index{test|hyperpage}.
%
%    \begin{macrocode}
\def\foobar{...}
%    \end{macrocode}
%
% \Finale
\endinput

dtxcode.idx then contains:

\indexentry{foobar=\verb!*+\foobar+|hdclindex{2}{usage}}{1}
\indexentry{test|hyperpage}{1}
\indexentry{def=\verb!*+\def+|hdpindex{}}{1}
\indexentry{foobar=\verb!*+\foobar+|hdpindex{}}{1}

and all entries are linked.