Doc: NR cross-staff

Doc: NR cross-staff
Some collisions are allowed by design,
as controlled by the 'cross-staff' property.

[Carl, 2010-12-20 05:57:37]

Here's Keith's patch for cross-staff documentation.

LGTM.

[Carl, 2010-12-23 02:19:05]

This has been up for nearly three days now.  Any comments?

[Valentin Villenave, 2010-12-23 07:57:58]

LGTM. I was a bit shocked when I saw the collisions in the example, but I think
I understand Keith's point.

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:173: time of the switch.  If necessary,
add spacer rests to
Doc guidelines mention that we should avoid addressing the reader. I'd rephrase
that as "if necessary, spacer rests may be added to keep staves @qq{alive}, as
explained in @ref{Keeping contexts alive}."

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:188: s2\mf\< s4. s8\!
Do we really want to show collisions in our examples? :-)

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:205: Automatic collision resolution is
suspended for beams, slurs
Oh I see: it's not a bug, it's a feature :)

All-righty then.

[pkx166h, 2010-12-23 13:14:22]

Just one comment.

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:206: and other spanners that connect
notes on different staves,
In which case should this addition be an @warning?

[Keith, 2010-12-23 21:17:02]

On 2010/12/23 07:57:58, Valentin Villenave wrote:
> Oh I see: it's not a bug, it's a feature :)

There is some of that.  I hope the text does not sound dismissive. I was trying
to sound humble: crossing staves is difficult; LilyPond might need your help.

There are several un-necessary collisions shown in the tracker that I would call
bugs, and hope LP can someday handle with a bit more sophistication.

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:173: time of the switch.  If necessary,
add spacer rests to
On 2010/12/23 07:57:58, Valentin Villenave wrote:
> Doc guidelines [...] avoid addressing the reader. 
CG4.4.5 says "do not explicitly refer to the reader/user ... there is no-one
else", and I thought that meant drop the extra words in "[-The-user-should-] add
spacer rests". We are *always* addressing the reader/user, no?

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:204: Notice that the stems overlap the
intervening line of dynamics.
Doc guidelines do say avoid fluff. "[-Notice-that-] The stems overlap..."

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:206: and other spanners that connect
notes on different staves,
On 2010/12/23 13:14:22, pkx166h wrote:
> In which case should this addition be an @warning?
I think not here.  Most @warnings are things the user needs to know on first use
of a feature, but would likely miss in simple text instruction.  Here, we want
to help users who are already crossing staves, and who have come back to the
manual for help with collisions.  The image with an overlapping beam helps the
reader find this text better than a "Note:" box.

[Trevor Daniels, 2010-12-24 08:54:38]

The content looks fine, but it should be rearranged a little to match the
existing style of the documentation.

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:173: time of the switch.  If necessary,
add spacer rests to
No, it means write in the third person, not the second.  (The LM is written in a
more chatty style; here the style should be impersonal.)

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:195: @end lilypond
This example and the point it makes is a useful addition, but I would prefer to
see the original example retained to show in the starkest fashion how staves
should be changed manually, with this one added later to show the possibility of
collisions.  Note also that the established policy is to explain the point being
made first with the illustrative example following.

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:205: Automatic collision resolution is
suspended for beams, slurs
Better joined to previous sentence: "The stems overlap the intervening line of
dynamics because automatic collision.."

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:209: Resolve the resulting collisions
manually, when necessary,
Third person

[Keith, 2010-12-25 04:37:52]

On Fri, 24 Dec 2010 00:54:38 -0800, <tdanielsmusic@googlemail.com> wrote:
> [...]I would prefer to see the original example retained to show in the
starkest
> fashion how staves should be changed manually, with this one added later
> to show the possibility of collisions.

That's a better way to do it.  The attached patch reverts the original example,
and is a simple addition of one @lilypond and one paragraph.

Carl started this issue for me, and I think it best to stay on his issue number
for continuity. Carl will probably upload the patch to his issue for me, but we
can't expect that to happen too soon.

No need to wait for the upload, though, because this simple patch is
human-readable.

The new example involves the types of collisions that I see most often.  Tell me
if the resolutions of the ugly collisions, the pitched rests and commented use
of staff-padding, needs any extra description in the text.

-Keith

[Keith, 2010-12-25 04:43:13]

See the corresponding thread on lilypond-devel for new patch.

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
File Documentation/notation/keyboards.itely (right):

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:195: @end lilypond
On 2010/12/24 08:54:39, Trevor Daniels wrote:
> I would prefer to see the original example retained ...

New patch reverts everything above, and adds a separate example.

http://codereview.appspot.com/3782042/diff/1/Documentation/notation/keyboards...
Documentation/notation/keyboards.itely:209: Resolve the resulting collisions
manually, when necessary,
On 2010/12/24 08:54:39, Trevor Daniels wrote:
> Third person

Done.

[c_sorensen, 2010-12-25 05:03:14]

On 12/24/10 9:37 PM, "Keith OHara" <k-ohara5a5a@oco.net> wrote:

> On Fri, 24 Dec 2010 00:54:38 -0800, <tdanielsmusic@googlemail.com> wrote:
>> [...]I would prefer to see the original example retained to show in the
>> starkest
>> fashion how staves should be changed manually, with this one added later
>> to show the possibility of collisions.
> 
> That's a better way to do it.  The attached patch reverts the original
> example, and is a simple addition of one @lilypond and one paragraph.
> 
> Carl started this issue for me, and I think it best to stay on his issue
> number for continuity. Carl will probably upload the patch to his issue for
> me, but we can't expect that to happen too soon.
> 
> No need to wait for the upload, though, because this simple patch is
> human-readable.
> 
> The new example involves the types of collisions that I see most often.  Tell
> me if the resolutions of the ugly collisions, the pitched rests and commented
> use of staff-padding, needs any extra description in the text.

Actually, we don't track Reitveld issue numbers.  The only issue numbers we
track are LilyPond issue numbers.

And it's best to have the patch from your git, because it has all your
information as the author.

You've put it on the email, so Trevor can push it.

Thanks,

Carl


> 
> -Keith 

[c_sorensen, 2010-12-25 05:26:49]

On 12/24/10 9:37 PM, "Keith OHara" <k-ohara5a5a@oco.net> wrote:

> On Fri, 24 Dec 2010 00:54:38 -0800, <tdanielsmusic@googlemail.com> wrote:
>> [...]I would prefer to see the original example retained to show in the
>> starkest
>> fashion how staves should be changed manually, with this one added later
>> to show the possibility of collisions.
> 
> That's a better way to do it.  The attached patch reverts the original
> example, and is a simple addition of one @lilypond and one paragraph.
> 
> Carl started this issue for me, and I think it best to stay on his issue
> number for continuity. Carl will probably upload the patch to his issue for
> me, but we can't expect that to happen too soon.

Oh -- I misunderstood.  I'll go ahead and post on Reitveld.

Carl
 

[Carl, 2010-12-25 05:32:54]

OK -- changes posted.

Keith, 

The patch wouldn't apply to the previous commit (I think it included your
previous patch) so I applied it to the parent of your previous commit.  Then it
applied.  Please check to make sure it's what you wanted.

Thanks,

Carl

[Keith, 2010-12-25 05:50:31]

On 2010/12/25 05:32:54, Carl wrote:
> Keith, 
> The patch wouldn't apply to the previous commit ...
I pondered a while on how to update before generating the patch; seeing how you
did this clear things up for me.  Thanks.

The changes posted here are as intended.

[Trevor Daniels, 2010-12-25 09:07:56]

LGTM

I like this example of collisions better than the earlier one.

If there are no averse comments over Christmas I'll push this next week.

Thanks Keith.

[t.daniels_treda.co.uk, 2010-12-29 11:36:34]

tdanielsmusic@googlemail.com wrote Saturday, December 25, 2010 9:07 
AM

> If there are no averse comments over Christmas I'll push this next 
> week.

Now pushed.  Thanks again Keith.

http://codereview.appspot.com/3782042/

Trevor