Re: GDP: index entries for snippets
2008/2/11, Graham Percival [EMAIL PROTECTED]: Sorry, you missed the subtext. I wasn't asking for a poll of who considered the index useful, I was saying I'm not going to work on this. Any volunteers? I'm probably the one responsible for having hijacked your topic :) Sorry, Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: index entries for snippets
Sorry, you missed the subtext. I wasn't asking for a poll of who considered the index useful, I was saying I'm not going to work on this. Any volunteers? Cheers, - Graham PS If you want to work on both normal NR doc work *and* the indexes, I'm happy with that. It all comes down to your available time. :) On Mon, 11 Feb 2008 08:30:36 -0500 Palmer, Ralph [EMAIL PROTECTED] wrote: Back when I had time to actually do reasonably complex projects (i.e., transcribe music), I did use the index. In fact, I think I would have been lost without it a few cases. Ralph -- Message: 1 Date: Sat, 9 Feb 2008 12:25:08 +0100 From: Valentin Villenave [EMAIL PROTECTED] Subject: Re: GDP: index entries for snippets To: Graham Percival [EMAIL PROTECTED] Cc: lilypond-user Mailinglist lilypond-user@gnu.org Message-ID: [EMAIL PROTECTED] Content-Type: text/plain; charset=ISO-8859-1 2008/2/8, Graham Percival [EMAIL PROTECTED]: Of course, I famously never use the index, so I'm not the best person to judge whether certain index entries are helpful or not. Neither am I :-) Anyone else? Cheers, Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: index entries for snippets
Back when I had time to actually do reasonably complex projects (i.e., transcribe music), I did use the index. In fact, I think I would have been lost without it a few cases. Ralph -- Message: 1 Date: Sat, 9 Feb 2008 12:25:08 +0100 From: Valentin Villenave [EMAIL PROTECTED] Subject: Re: GDP: index entries for snippets To: Graham Percival [EMAIL PROTECTED] Cc: lilypond-user Mailinglist lilypond-user@gnu.org Message-ID: [EMAIL PROTECTED] Content-Type: text/plain; charset=ISO-8859-1 2008/2/8, Graham Percival [EMAIL PROTECTED]: Of course, I famously never use the index, so I'm not the best person to judge whether certain index entries are helpful or not. Neither am I :-) Anyone else? Cheers, Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: index entries for snippets
2008/2/8, Graham Percival [EMAIL PROTECTED]: Of course, I famously never use the index, so I'm not the best person to judge whether certain index entries are helpful or not. Neither am I :-) Anyone else? Cheers, Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
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
GDP: index entries for snippets
Latest GDP docs http://web.uvic.ca/~gperciva/ (although these are almost identical to the 2.11.39 docs at the moment) Do we want index entries for snippets? For example, in NR 1.1.3.2 Key signature there are two snippets: suppressing natural signs in key signatures, and non-standard key signatures. Do you want to have items like: @cindex key signatures, suppressing natural signs @cindex don't print natural signs in key signatures @cindex key signatures, non-standard @cindex key signatures, whole tone pointing to these? Adding index entries for all the snippets increases the amount of work that we need to do on each doc section, of course. I'm personally not convinced that these are necessary -- after all, if a user can't find key signature in the index, he won't be able to find key signature, suppressing natural signs. And if he _is_ looking a way to avoid printing natural signs in key signatures, I think he'd look at key signatures even if there wasn't a key signature, suppressing natural signs entry. More examples are in NR 1.2.1.2 Tuplets such as @funindex tupletNumberFormatFunction @funindex tupletSpannerDuration and @cindex tuplet bracket length @cindex triplet bracket length @cindex bracket length, tuplets Of course, I famously never use the index, so I'm not the best person to judge whether certain index entries are helpful or not. Discuss. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
RE: index entries for snippets
Graham Percival wrote on 08 February 2008 19:49 Do we want index entries for snippets? For example, in NR 1.1.3.2 Key signature there are two snippets: suppressing natural signs in key signatures, and non-standard key signatures. Do you want to have items like: @cindex key signatures, suppressing natural signs @cindex don't print natural signs in key signatures @cindex key signatures, non-standard @cindex key signatures, whole tone These are not helpful, especially the one beginning with don't, which is silly, but I would like both these snippets to be indexed with @cindex natural sign, suppressing At present the only entry for naturals takes you to a section on text markup commands. Not helpful if you're looking for a way to suppress extra naturals. More examples are in NR 1.2.1.2 Tuplets such as @funindex tupletNumberFormatFunction @funindex tupletSpannerDuration and @cindex tuplet bracket length @cindex triplet bracket length @cindex bracket length, tuplets An index is helpful only if it includes the term the user has in mind when he conducts a search. Sure, if that term isn't found, he'll try another, but the whole point of an index is to make it as quick and easy as possible to go from query to answer. So index entries should be constructed by thinking of what questions the user might have which could be answered by reading this section, and index the key terms in the questions, not the terms in the answer. So these are good (I wrote them, so I have to support them ;) Cheers, - Graham Trevor D ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: index entries for snippets
On Fri, 8 Feb 2008 21:08:08 - Trevor Daniels [EMAIL PROTECTED] wrote: @cindex natural sign, suppressing At present the only entry for naturals takes you to a section on text markup commands. Not helpful if you're looking for a way to suppress extra naturals. Well, obviously we want a @cindex natural sign at the top of Accidentals. (Ralph?) Assuming that we have that, do you still think we need a @cindex natural sign, suppressing for the snippets? I mean, if natural sign points to the top of the page anyway, dos natural sign, suppressing really add anything? Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
RE: index entries for snippets
Graham Percival wrote on 08 February 2008 21:26 On Fri, 8 Feb 2008 21:08:08 - Trevor Daniels [EMAIL PROTECTED] wrote: @cindex natural sign, suppressing At present the only entry for naturals takes you to a section on text markup commands. Not helpful if you're looking for a way to suppress extra naturals. Well, obviously we want a @cindex natural sign at the top of Accidentals. (Ralph?) Assuming that we have that, do you still think we need a @cindex natural sign, suppressing for the snippets? I mean, if natural sign points to the top of the page anyway, dos natural sign, suppressing really add anything? Maybe not. In this case the page is quite short, so reading through it is not too onerous. But without the suppressing entry the user looking for how to suppress naturals does not know whether or not it is there - he has to read through the page on the off-chance it may contain what he seeks. With the specific index entry he will -know- that what he is looking for -is- on that page. That's the difference and that's why it is helpful to include it. Cheers, - Graham ___ 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
