fixing the command index (was Re: [PATCH] Add @funindex for \fffff.)

[Mark Polesky]

Graham Percival wrote:
> I agree, but see these:
> http://lists.gnu.org/archive/html/lilypond-devel/2008-11/msg00285.html
> http://lists.gnu.org/archive/html/lilypond-user/2008-08/msg00063.html
>
> We had a clear discussion about this issue at near the end of GDP,
> and it was decided to use *both* foo and \foo.  I'm not eager to
> re-open the matter only one year after that decision, even if I
> think it was the wrong decision.  :|
>
> (also, as somebody who never ever uses the index, I'm tempted to
> disregard my opinion on the matter -- leaving the matter even more
> swayed towards having blah and \blah.)

Here are the two options.

*******************************

Option 1 -- indexing commands only as \foo:

PROS:
* concise: cuts the index size almost in half.
* meaningful: commands look like commands,
              properties look like properties.
* consistent: no risk of having two different entries which
              should be the same (compare current musicglyph and
              \musicglyph entries, for example).
* easier: developers only need to index one form -- less risk of
          screwing up the feature-adding process.

CONS:
* counterintuitive: users might look for \foo in the "f" section.
* error-prone: a developer can accidentally index the \foo command
               as foo (though I imagine this mistake wouldn't be
               too common).

*******************************

Option 2 -- indexing both \foo and foo (what we currently do):

PROS:
* robust: user will find something wherever they look.

CONS:
* bloated: index size almost twice as large as the alternative.
* misleading: foo could be a command, even though it doesn't look
              like one.
* inconsistent: risk of having two different entries which should
                be the same (compare current musicglyph and
                \musicglyph entries, for example). A user will
                miss some references if they look in the entry
                (/foo vs. foo) that has fewer.
* error-prone: a developer could index \foo but not foo -- but the
               opposite mistake is even worse: a user looking for
               \foo might think it doesn't exist when s/he doesn't
               see it between \fontsize and \fp.

***************************

Well, clearly I'm in favor of the first option, but one problem
really ought to be resolved:
* counterintuitive: users might look for \foo in the "f" section.

I see three possible solutions:

1) put a big note at the top that says something to the effect of:
   Note: commands are all listed together in the "\" section.

2) Get texinfo to ignore the backslashes when sorting the index,
   effectively mixing the commands in with the properties:

   ...
   \afterGrace
   after-title-space
   \aikenHeads
   \allowPageTurn
   \alternative
   \AncientRemoveEmptyStaffContext
   annotate-spacing
   \applyContext
   ...

   Graham has hinted in the past that this would be hard to do.

3) Make the "command index" strictly a *command* index.
   Add a separate "property index" strictly for properties. It
   could even be on the same page -- just the existence of a menu
   with the two different node names should be enough to help the
   user. But I think it would be fine being separated. Ultimately,
   I think this is my preference.

So what do you guys think?
- Mark