Re: Another frog job: pepper the documentation with indexing commands

[David Kastrup]

Peekay Ex <address@hidden> writes:

> Hello,
>
> On Sun, Sep 11, 2011 at 6:49 AM, David Kastrup <address@hidden> wrote:
>>
>> The documentation is not really indexed all that well: new additions
>> often are made without indexing entries.  Going through the source and
>> index and trying to make sure that interesting things can be found under
>> obvious names in the index is a bunch of work requiring mostly editorial
>> skills.
>
> Here is a good (i.e. bad) example of inconsistent and, in my opinion,
> 'noisy' index entries. This comes from repeats.itely
>
> --snip--
>
> @node Written-out repeats
> @unnumberedsubsubsec Written-out repeats
>
> @cindex written-out repeats
> @cindex repetitious music
> @cindex repeats, written-out
> @cindex repeat, unfold
> @cindex unfold music
> @cindex unfold repeat
> @cindex unfold repeat with alternate endings
> @cindex unfold music with alternate endings
> @cindex alternate ending in written-out repeats
> @funindex unfold
>
> --snip--
>
> Yes it's nice to have all the possible ways to say the same thing
> indexed for the 1 user that might choose to look for 'repetitious
> music' (!!) but please, isn't this just silly?

The info readers have TAB completion.  You start typing a few letters,
then press TAB.  Indexing the same section with key phrases starting all
the same is nothing but a nuisance.  The same holds for the printed
index.  Similarly for "repetitious music".  "alternate ending", in
contrast, is a useful additional index entry.  There is no harm that it
is longer than necessary: if you do tab completion or read the printed
version, it gives you an additional clue whether you'll find what you
are interested in.

-- 
David Kastrup