[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
fixing the command index (was Re: [PATCH] Add @funindex for \fffff.)
From: |
Mark Polesky |
Subject: |
fixing the command index (was Re: [PATCH] Add @funindex for \fffff.) |
Date: |
Fri, 14 Aug 2009 19:26:06 -0700 (PDT) |
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