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

[Peekay Ex]

forwarding because I forgot to cc dev.

Sorry David, that wasn't mean to be aimed at you specifically.

James


---------- Forwarded message ----------
From: Peekay Ex <address@hidden>
Date: Sun, Sep 11, 2011 at 2:45 PM
Subject: Re: Another frog job: pepper the documentation with indexing commands
To: David Kastrup <address@hidden>


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.

No I don't think that is true anymore. At least not since I have been involved.

> 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.

It also requires some consistency.

Beaming is a good case.

How many different permutations does one need in the index for e.g

beams, beam, beaming, autobeams, autobeaming, autobeams or just
'beams, auto'? and that doesn't include all the verbs that go with it

setting, how to set, controlling, editing, configuring blah blah.

There is already a tracker or two on the index not least trying to
decide if I should look up \function or just 'function' where the
leading slash is not properly alphabetised.

Peppering' the documentation with cindex and funindex is not that
useful to anyone unless we have some consistency. In fact indexing
'for the sake' of indexing makes an index almost useless.

Have you actually looked at the index lately to see how unweildy it is becoming?

My frustration is my lack of texinfo skills to even begin to tackle
this, adding more for the sake of it solves nothing and makes the
(hopefully) eventual tidy up more painful.

One man's 'interesting thing' is another's 'irrelevance' or 'edge-case example'.

In fact I'd say in some cases it is easier to not bother with the
index but simply use the 'find' features of your favourite PDF or
Webbrowser.



--
--
James



-- 
--
James