Use of \SpecialMacroIndex and related commands in tables

Question

Some time ago, the "doc" package evidently changed its default from not including hyperref to including hyperref, and I noticed a change in my output (other than the appearance of hyperlinks).

I was originally using \SpecialUsageIndex to add the descriptions of several macros to the index, because the descriptions of those macros were in a table environment and using DescribeMacro did not work with a floating environment. SpecialUsageIndex seems to to have been deprecated (?), so I switched to \SpecialMacroIndex, but I have the same problem either way.

The gist: Using \SpecialMacroIndex inside a table (probably any floating environment) inserts extra vertical space at the location of the command. This happens regardless of whether I leave space after the initial % or whether or not I include a % or \relax at the end of the line. If I turn off hyperref with the nohyperref class option to ltxdoc, however, I don't see this behavior.

Am I doing something wrong (e.g., I should not be using \SpecialMacroIndex for this purpose), and if so, what is the correct way to do this?

Here's a minimal working example:

% \iffalse
%
% To make the example, do this (saved as "reveal-bug.dtx"):
%
% pdflatex reveal-bug.dtx
% makeindex -s gind.ist -o reveal-bug.ind reveal-bug.idx
% pdflatex reveal-bug.dtx
% pdflatex reveal-bug.dtx
%
%<*driver>
\ProvidesFile{reveal-bug.dtx}
%</driver>
%
%<package>\NeedsTexFormat{LaTeX2e}
%
%<*driver>
%^^A\documentclass[nohyperref]{ltxdoc}
\documentclass{ltxdoc}
\PageIndex
\CodelineNumbered
\RecordChanges
\begin{document}
  \DocInput{reveal-bug.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{reveal-bug.dtx}
% \title{Test Document}
% \author{Me}
% \date{\filedate}
% \maketitle
%
% \begin{table}
%   \caption{Table with lots of macro descriptions in it.}
%   \SpecialMacroIndex{\abc}\relax
%   \SpecialMacroIndex{\def}\relax
%   \SpecialMacroIndex{\ghi}\relax
%   \SpecialMacroIndex{\jkl}\relax
%   (This is just here to make a table and define its boundaries.)
% \end{table}
% \SpecialMacroIndex{\mno}\relax
% \SpecialMacroIndex{\pqr}\relax
% \SpecialMacroIndex{\stu}\relax
% \SpecialMacroIndex{\vwx}\relax
%
% \StopEventually{\PrintChanges}{\PrintIndex}
%
% \iffalse
%</package>
% \fi
% \Finale
\endinput

Change the \documentclass line to the one that's commented out and compare the first page in both cases to reproduce this.

Some versioning info. from the log file: LaTeX2e <2022-06-01> patch level 5 L3 programming layer <2022-12-17> Document Class: ltxdoc 2022/06/22 v2.1h Document Class: article 2021/10/04 v1.4n Package: doc 2022/06/08 v3.0j

P.S. If anyone wants a less-than-minimal working example, the tables I am working with are tables 1 and 2 of the documentation for the thermodynamics package, as available on CTAN.

Answer 1

Well the problem is that hypdoc creates targets with \llap, and as you are in vertical mode, they pill up. Probably hypdoc should add an \leavevmode to switch to horizontal mode (this still could in some places lead to unwanted spaces, but not so much, in any case I would recommend to always use index commands in hmode):

% pdflatex reveal-bug.dtx
% makeindex -s gind.ist -o reveal-bug.ind reveal-bug.idx
% pdflatex reveal-bug.dtx
% pdflatex reveal-bug.dtx

\documentclass{ltxdoc}
\PageIndex
\CodelineNumbered
\RecordChanges
\begin{document}
\makeatletter
\def\HD@maketarget{%
  \stepcounter{HD@hypercount}%
  \def\HD@next{%
    \leavevmode% new
    \llap{\hypertarget{HD.\the\c@HD@hypercount}{}\,}%
  }%
  \ifHD@savedest
    \expandafter\ifx\csname HD.\the\c@HD@hypercount\endcsname\@empty
    \else
      \let\HD@next\relax
    \fi
  \fi
  \HD@next
}
\begin{table}
\caption{blub}
\SpecialMacroIndex{\def}\relax
\SpecialMacroIndex{\ghi}\relax
\SpecialMacroIndex{\jkl}\relax
some text
\end{table}
\PrintIndex
\end{document}