Re: Resolving "cannot resolve rest collision: rest direction notset"warnings

[Arle Lommel]

David,

Sorry for the long response, but maybe it will be useful for project insiders to see how someone mostly on the outside experiences the documentation and the ways for finding things.

I think part of the problem is the sheer volume and being able to recognize what is directly relevant. For those who are immersed in the project there is a logic and clarity that those coming from outside may not always see. My need is sporadic. I may go six months and not touch Lilypond and then need it extensively for three weeks and then go another six months. That means I am consistently relearning things (although fewer things each time).

(Incidentally, I just found this page - http://lilypond.org/web/documentation - that is rather sorely out of date. I'm guessing it is an old, orphaned page?)

There is a table of contents,

OK, fair enough, but, using my case as an example, take a look at the TOC and ask yourself if you could find the appropriate point using it if you did not already know where it was. My guess is the answer would be no.

Searching for "rest" brings up zero hits in the TOC as it first appears. Now if I do click into 1.2 Rhythms, I get to 1.2.2. Writing Rests. I actually had looked through this a number of times while working on this piece, but never made the connection that I should look under the heading Positioning multi-measure rests to determine how to change the default position of plain rests. (Note that this section does not actually address how to change the default position of plain rests and even Phil, when chiding me for not using the index, himself had to extrapolate from the one section to the general solution.)

Now, as it happens, one can extrapolate the needed information from that section, if one makes the leap to say “maybe this bit applies to my similar, but not identical, situation” and if one knows how to make that extrapolation. But that is an inferential leap I did not happen to make.

There is no obvious path (at least to someone not immersed in the project) to get from "rests in my piece are showing up in the ‘wrong’ place and I want to change the default” that leads to the solution via the TOC.

there is an index,

The index might have helped. However, because of the layout of site and my screen size, it was hidden from view for me. I simply did not know it existed. If I may be so bold as to make a suggestion, perhaps the Index link could be put at the top of the TOC to encourage its use.

Leaving that aside, had I seen it and looked up rests, I would have found rest, specifying vertical position, which sounds promising indeed, but which does not address the question of setting defaults and indeed tells me what I already knew about constructs like b4\rest that I was using.

The other one I would have tried was rest, collisions of. Interestingly enough, that links to an anchor over the single sentence in the Known issues and warnings section that reads “Multi-measure rests do not take part in rest collisions.” I'd actually argue that that link doesn't even make much sense and that content higher up in the page is more relevant from a user perspective to the index heading than what it actually links to.

Again, the index might have helped me if I already knew what I needed to find. But for the outside user who doesn't know it, there isn't much helpful there.

Phil was able to find things because he already knew enough to use the index to find something different that happened to suggest the solution.

there is plain text search.

This, again, was hidden from me and I actually wondered why there was not a plain text search. I had been using plain Google to find things because I didn't spot that search field hidden well below the edge of my screen. Perhaps I should have scrolled down and seen it, but I did not. From a usability standpoint, the search field is wasted at the bottom of the page and should be made much more prominent. If anything I write in this mail has value, that should be it.

However, if I use it (now that I know about it) and search for "rest position," none of the hits are obviously relevant from the Google summaries except for the first one, but I'd already read that page and not made the connection that was needed.

The index contains "rest, specifying vertical position".

As mentioned above, that addresses the solution I already knew about, but does not actually address how to set the default, which is what I was looking for. (I just triple checked to be sure.)

There is also the analogous "positioning multi-measure rests".

And therein is the problem. It is analogous, not explicit, and stating that that is the solution presumes that one understands, while searching, that the analogy is there to be made. With more care and time, I might have made that leap. But I was searching the documentation for my particular issue, not a similar/analogous one.

So how could this have been made easier?

I don't really know, other than the simple fixes of making the index and search more obvious in the documentation’s TOC. Those two things would be a start, but ultimately wouldn't have helped me with this problem.

But at another level, I don't know there is much that can be done until you see where people have trouble and then augment the documentation. Now that I have, rather exhaustively, shown why it was not simple to find what I needed, one could add a section called “Setting the default position of rests” (or at least provide an explicit statement in the broader section), which would be found in the plain-text search and by digging in the TOC. But that is fundamentally a band-aid for a particular problem. (I'd still recommend adding it to the documentation. A band-aid does have its uses.)

Fundamentally it comes down to the problem that Lilypond does so much and is so powerful that documenting everything is a rather difficult proposition. You never know what has been missed and, until someone comes along with a specific need that isn't intuitive in what is written, the gap may never appear. There is fundamentally no way to know that you have covered everything.

That is probably far more than you wanted, but maybe it is useful. At the least it does give me the satisfaction of demonstrating (to myself and to others) that it was not laziness that kept me from finding the answer, but rather a set of real issues with how I interacted with the documentation and a lack of clarify in the documentation on this issue.

Best,

Arle