Re: info --index not finding all indexed entries

[Eli Zaretskii]

> Date: Fri, 30 Jul 2010 19:57:30 +0200
> From: Ralf Wildenhues <address@hidden>
> Cc: Karl Berry <address@hidden>, address@hidden
> 
> > Which means the Automake manual needs to be fixed.  Having more than
> > one index entry in different places is not a good idea, and this
> > thread is just another instance of the proof.
> 
> I wasn't aware that this is considered a bad idea in general, and I'm
> not quite convinced yet: checked now, the Automake manual contains more
> than hundred duplicate entries, the Autoconf roughly 60, the Texinfo
> manual at least three dozen.  Are those all bugs?

Not bugs, just not the best style.  It makes it harder to use the
indices efficiently.

> Neither the 'Index Entries' nor the 'Indexing Commands' node of the
> Texinfo manual mention that duplicates should be avoided.

Karl, how about adding that?

> > One of the entries should be qualified, like
> > 
> >   @findex AM_INIT_AUTOMAKE, how to ...
> 
> While this which is definitely nicer to have, sometimes you may simply
> have more than one relevant place in a manual.

I don't think so.  I frequently use TAB after typing a few first
characters of a term I'm looking for.  With identical index entries,
what that shows me is a list such as

    Possible completions are:
    AM_INIT_AUTOMAKE    AM_INIT_AUTOMAKE<1>
    AM_INIT_AUTOMAKE<2>         AM_INIT_AUTOMAKE<3>

This leaves me with no clue regarding which one to choose.  In
contrast, if I see something like

    Possible completions are:
    AM_INIT_AUTOMAKE                   AM_INIT_AUTOMAKE, and foo
    AM_INIT_AUTOMAKE, how to use       AM_INIT_AUTOMAKE, when bar is in effect

I'll have a good idea which is the one I'm after.

Index entries are there to make it a snap to find a specific subject
in a manual -- they let you use a manual as a reference, even if it
wasn't written like one.  That is why good index entries should always
be specific, and if there are more than one about the same topic, each
one should be qualified with the specific aspects of the topic
described where the index entry points.