As a librarian-in-training I have to agree with Jay (it generally hurts more omitting an entry than including it, especially in a open project like this that/which doesn't really have page limits to think about). I've been thinking on speaking up about the indeces for quite some while now but have never really bothered taking my time to formulate what could be done to make them more usable (at least to me).
First, I love indeces (indexes?) and use them everywhere. Though trying to use the ones in the current manual I'm most often giving up, them not working the way I assume. Below, some thoughts about the behaviour I assume, why it does/doesn't work at the moment and what I suggest.
- - - - -
Explanations about the indeces. I always look for a paragraph or two just before the index itself, that (which?!) explains the conventions. Especially needed in the html version, if I may say so. (See below.) Not so important, but might help the user finding what they want.
Different indeces. This is good and important. At the moment there's two, though spontaneously I think them to be good choices (a general one versus one for the commands) they would really further the indeces' purpose if they truly split up. I mean this, the command index' coverage is great (but as always, can be tweaked further) but needs some loving in the formatting and sorting department, while the general index really needs a work-through.
The command index. A few suggestions: • Sort alphabetically (after usage rather than literally), that is, do not sort under a leading interpunction symbol. Example order: \addlyrics, arranger, \autoBeamOff • Sort under the letters A to Z and one or two others. For instance that !, /+, ~ & c. are sorted under one heading, e. g. "Symbols".
The general index. A few suggestions. • Remove the commands! They already are in the command index and as it is now clutters the general one. True, in some usage cases it is great to have them combined like that, but in others it is oppositely so. And already having them available in a separate index, the commands are never long away, so I say, purge them from the general index immediately. ;)
• Always use main head words (although they in some cases may be contrived and hypothetical, they really help the index looker quickly find their need, remember that the head words musn't always point to a specific page or somewhere at all) and further narrowed entries come "beneath" (indented that is). Example ("···" symbolising an indent), note the unreferencee notion of the headword:
The aboe points hold true in general, but specifically so for the pdf version. One thing I personally love in the pdf is how the page numbers themselves constitutes the links and the entries are ordinary, "un-clickable" text. The html version though, some work is needed to.
The html version's indeces. See above for general pointers, there really is just one main thing that/which (aargh! you've made me realise I have no idea how to use that/which now...) give my skin rashes. Namely, how does it work? (You don't have to answer here as I already have figured most of it out, but it really would help if someone explains it in the docs themselves.)
This index really, really needs an explanatory paragraph! A few pointers. • For each entry, there are two links, what's the difference? • What's text after each head word?
To me, a more logical structure would be something like:
• The headwords themselves link to the relevant place • No section names (that is, only the head words remain) • Sorting as mentioned further above • Whether subentries are grouped beneath a group headword or not as I suggested for the pdf isn't as important or obvious here, as I believe/assume the usage of indeces work a bit differently in a more inherently electronic text
Or, a structure more similar to the one right now: • Example entry: "Clef: Clef" and "Clef: Accidentals" (which otherwise could be
differentiated with explanatory/narrowed subentries, with number appendages or the like) • The index looker should with a quick glance understand the
structure and function of the index • For instance, the head word
remains as is now but without link (really helps differentiating what is what, and what needs to be clicked) • The section names remain with their links but if a
certain headword point to several sections (as "Clef" do), then merge
them onto the same line)
- - - - -
No offence meant, if taken. I always have had a hard time forming my understanding into words, especially so into a foregin language. And. Many thanks for all's good work and for reading my personal purging urgings through! :)