Can I use ltxdoc, makeidx, doc and bookmarks? If so, how?

Question

Is it possible to use ltxdoc.cls with makeidx and bookmark?

MNWE:

\documentclass{ltxdoc}
\usepackage{makeidx}
\usepackage{bookmark}
\makeindex
\begin{document}
\DescribeMacro{\mymacro}\marg{argument}\par
\printindex
\end{document}

Following the advice in comments, I then tried

makeindex -s gind.ist prawf

Here's makeindex's transcript:

This is makeindex, version 2.17 [TeX Live 2023] (kpathsea + Thai 
support).
Scanning style file /usr/local/texlive/2023/texmf-dist/makeindex/latex/gind.ist.............done (13 attributes redefined, 3 ignored).
Scanning input file prawf.idx...done (0 entries accepted, 1 rejected).
Nothing written in prawf.ind.
Transcript written in prawf.ilg.

The log:

This is makeindex, version 2.17 [TeX Live 2023] (kpathsea + Thai support).
Scanning style file /usr/local/texlive/2023/texmf-dist/makeindex/latex/gind.ist..........
** Input style error (file = /usr/local/texlive/2023/texmf-dist/makeindex/latex/gind.ist, line = 75):
   -- Unknown specifier lethead_prefix.
** Input style error (file = /usr/local/texlive/2023/texmf-dist/makeindex/latex/gind.ist, line = 76):
   -- Unknown specifier lethead_suffix.
** Input style error (file = /usr/local/texlive/2023/texmf-dist/makeindex/latex/gind.ist, line = 77):
   -- Unknown specifier lethead_flag.
...done (13 attributes redefined, 3 ignored).
Scanning input file prawf.idx...
!! Input index error (file = prawf.idx, line = 1):
   -- Extra `|' at position 46 of first argument.
done (0 entries accepted, 1 rejected).
Nothing written in prawf.ind.
Transcript written in prawf.ilg.

The raw index file is

\indexentry{mymacro=\verb!*+\mymacro+|hdclindex{2}{usage}|hyperpage}{1}

you do not need doc as that is loaded, use a makeindec style using different special characters such as the gind.ist file distributed with doc. — David Carlisle, Aug 21 '23 at 05:56
BTW: TeX Live provides mkindex that processes the .idx and .glo files of a document using (makeindex and) gind.ist resp. gglo.ist. — cabohah, Aug 21 '23 at 07:20
@DavidCarlisle TEXMFHOME=/d makeindex -s gind.ist prawf? I have to set the file up to use something different, too, I guess. (I don't make indexes often.) Thanks re. the doc. I discovered I'm not explicitly loading it in the actual document, but added it for the MNWE. I know doc provides indexing macros, but I don't know if I should be using those or not. (I don't have a dtx.) — cfr, Aug 21 '23 at 15:05
ltxdoc is essentially article class plus doc package, so doc is loaded before you specify it, — David Carlisle, Aug 21 '23 at 15:28
@DavidCarlisle Could you suggest what I need to do beside -s gind.ist? — cfr, Sep 04 '23 at 18:49
@cfr Scanning input file ee131.idx...done (0 entries accepted, 1 rejected). Nothing written in ee131.ind. hmm not good:-) i may have no time this evening but I'll try to look later — David Carlisle, Sep 04 '23 at 19:46
@DavidCarlisle Thank you. I really appreciate that. I was sure I was doing something stupid, so I'm only half unhappy you don't immediately point out what. And thanks for finding the r! — cfr, Sep 04 '23 at 23:27
@DavidCarlisle I also tried with doc2 because indexing worked OK in June for prooftrees and I've not updated TL. With just doc2 I still get the error, but if I add a bit of prooftrees.tex preamble, it works. (I can't apply this to my new document as it is committed to version 3 of doc.) Specifically \renewcommand*\Describe@Macro[1]{\endgroup \marginpar{% \raggedleft\PrintDescribeMacro{#1}\par }% \expandafter\prooftrees@index{\macrolabelname}{\protect\verb \protect #1}\@esphack\ignorespaces} \newcommand*\macrolabelname{macro} \def\prooftrees@index#1#2{\index{#1s!#2}} — cfr, Sep 05 '23 at 00:34
@DavidCarlisle Wondering if you had a chance to look at this or if there's some alternative approach I could try? — cfr, Sep 08 '23 at 13:16
sorry I was on one of these will try to look before I get on another — David Carlisle, Sep 08 '23 at 19:22
@DavidCarlisle If I'd known your muse was demanding your attention, I wouldn't have asked ;). It's only that if I don't get this package on CTAN soon, I'll probably lose the courage. Or I'll find another bug :(. — cfr, Sep 08 '23 at 22:37

score 4 · Accepted Answer · edited Sep 09 '23 at 15:10

You get a warning in the log:

Package hypdoc Warning: hyperref has been loaded before. Check the options!

hypdoc loads at the end of the preamble hyperref with the option hyperindex=false to avoid that it interferes but as you already load hyperref through the bookmark package this no longer works.

Sadly it is not trivial to disentangle 30 years of history and to avoid this loading order problem: currently the hyperindex can't be reset after the package.

The easiest currently for you is to load hypdoc earlier, before hyperref:

\documentclass{ltxdoc}
\usepackage{makeidx}
\usepackage{hypdoc}
\usepackage{bookmark}
\makeindex
\begin{document}
\DescribeMacro{\mymacro}\marg{argument}\par
\printindex
\end{document}

Additionally, as already mentioned in the comments, you must call makeindex with a special style e.g. -s gind then you get this

Thank you so much! I was trying to do completely the wrong thing. I thought I needed hyperindex, so I tried to make sure it had that. Then I realised it was enabled anyway, so I thought the problem must be something else. — cfr, Sep 09 '23 at 15:13

Can I use ltxdoc, makeidx, doc and bookmarks? If so, how?

1 Answers1