Ho,
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:
beams
···and line breaks 49 [or: "···line breaks, and"]
···automatic 29
···feathered 53
···kneed 49
···manual 47, 52
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! :)
Love,
Kess
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
