[tex-eplain] Hyperlinks in index, take two

[Dan Luecking]

At 02:41 PM 8/7/2005, geolsoft at mail.ru wrote:
>On Fri, Aug 05, 2005 at 10:24:11AM +0300, geolsoft at mail.ru wrote:
> > I will write to
> > Heiko, ask about indexing and inform him of the $Id$ problem.
>
>I've received the reply.  I quote the answers below.
>
>Regarding index hyperlinks in hyperref:
>
>
>Regarding his document `alphalph.pdf':
>
> > Look at the .zip file in the directory, it contains the sources.
> > I have just redefined some macros of the LaTeX doc system.
>
>So it actually _was_ a non-standard trick.  I downloaded the
>sources and glanced through them, but they did not make much
>sense to me, I am not a LaTeX guru (or even a LaTeX user).
>I hope I can sort it out later, but I believe that since the
>method used in `alphalph.pdf' did not become `standard' in
>hyperref, it was not generic enough, so we wouldn't be able
>to use it in Eplain neither.  Well, so far it is just a wild
>guess.

The ltxdoc class normally produces an index entry for each
\begin{macro}{...} environment, for each \DescribeMacro{...} command,
and for each use of a  macro in a macrocode environment. In the file
holtxdoc.sty, Heiko redefines some of the internals of the ltxdoc class
so that the first two write \indexentry commands of the form
   \indexentry{aa at alph=\verb!*+\aa at alph+|main[10]}{6}
   \indexentry{aa at alph=\verb!*+\aa at alph+|usage[11]}{6}
The only difference between this and the normal output of the ltxdoc
indexing commands is the optional argument of the encapsulating commands
(\main and \usage). This argument is a unique integer generated by a
counter which is stepped with each indexing command. He also redefines
ltxdoc internals so a destination anchor is created at the word being
indexed. The name of the anchor is made unique by using the counter in
its name. Finally, the encapsulation commands \main and \usage are
redefined to take an optional argument and create a link to the corresponding
destination.

I don't think Heiko's method is any different than the ideas already
discussed here. The fact that he achieves it by rewriting some of ltxdoc
makes it difficult to follow, but that would not be an issue in eplain
where you are writing the index commands from scratch.

Note: the \main and \usage commands are expected to be used at most once
each per indexed word. In the .dtx system, output like
   \item \verb+\macroname+, \main{2}, \usage{2}, 2
is common. It indicates that the main description of the term, the
description of its usage and an appearence in code all occur on page 2.
(Optionally, the line number of code can occur instead of the page
number for the third case.) So it is not a problem but a feature, that
makeindex will see two index commands on the same page as different.


Dan


Daniel H. Luecking
Department of Mathematical Sciences
University of Arkansas
"Be kind. Every person you meet is fighting a hard battle." - Anon.