Re: Subject: GDP: index entries for snippets
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] ···automatic29 ···feathered53 ···kneed49 ···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
Re: Subject: GDP: index entries for snippets
On Sat, 9 Feb 2008 12:55:06 +0100 Kess Vargavind [EMAIL PROTECTED] wrote: First, I love indeces (indexes?) and use them everywhere. Would you be willing to maintain the indeces/indexes? Some of the doc writers (including myself) either aren't good, or aren't interested, in trying to think of potential terms. I'd rather have those people work on the actual documentation text. The idea is this: once we've finished a section of the docs (for example, NR 1.1 Pitches), you take the file and add whatever index entries wherever you want. I won't complain about having too many or too few or if they're in the wrong place or whatever... but in exchange, if anybody complains about the index (too much info, links in the wrong places, whatever), I send those complaints to you. :) Just as a reminder, a few weeks ago I offered a challenge: tell me exactly what index text to add, and I can do so in less than 30 seconds. As a result of that challenge, 1 person offered 1 index entry. Nobody else did anything. 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. Easily added. Just send me whatever text you suggest. Ideally something that makes sense for all output formats, but if necessary we could insert HTML-only text. I added examples of this intro text to the GDP site. 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. This is easily done -- actually, it was a technical challenge to get them combined in the first place. But when the question first arose two years ago, the general concensus was that the general index should include commands as well. I'm quite open to changing this, but I'd want a fair amount of discussion first. 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: ___ Sort under the letters A to Z and one or two others. For instance that !, /+, ~ c. are sorted under one heading, e. g. Symbols. ___ Always use main head words (although they in some cases may be contrived and hypothetical, they really help the The aboe points hold true in general, but specifically so for the pdf All those things would be nice, but we cannot do this for technical reasons. If you're interested in more information, please see the texinfo manual (ie google for it) and look at their info about indices. Sorry. 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.) Sorry, I don't understand -- you look for the term you want, then click on the link. I know this sounds like a completely stupid and useless answer, but I really don't understand the question how does it work. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: Subject: GDP: index entries for snippets
Not knowing the question to ask is often a problem for me to. You are not alone with this experience. Perhaps he is asking how docbook format works. I'm just guessing about his query myself. 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.) Sorry, I don't understand -- you look for the term you want, then click on the link. I know this sounds like a completely stupid and useless answer, but I really don't understand the question how does it work. However, I'll add this; It is truly frustrating to have a question and not know how to ask it. I know that you all cannot help with this, its a personal struggle (chuckle) we all have had at one time or other. It just happens with Lilypond more often. That isn't a comment on the quality of the workmanship on the project as much as it is a comment on the complexity of the objectives of the project. Written music itself is a major challenge, Western European Music is another order more complex than most. Lilypond not only renders WEM, but adds music of other cultures to the mix. Its sort of like trying to be all things to all people. That Lilypond has gotten as far as it has is something of a miracle in itself! -- David Fedoruk B.Mus. UBC,1986 Certificate in Internet Systems Administration, UBC, 2003 http://recordjackethistorian.wordpress.com Music is enough for one's life time, but one life time is not enough for music Sergei Rachmaninov ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Subject: GDP: index entries for snippets
As a former librarian, I know that creating indexes is a total pain and unfortunately should be as extensive and repetitious as possible. Over-estimating the users ability/intelligence is a grave error. Yours- Jay Jay Hamilton ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
