Doc: NR cross-staff (issue3782042)

[Carl . D . Sorensen]

Reviewers: ,

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

LGTM.


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

Please review this at http://codereview.appspot.com/3782042/

Affected files:
  M Documentation/notation/keyboards.itely


Index: Documentation/notation/keyboards.itely
diff --git a/Documentation/notation/keyboards.itely  
b/Documentation/notation/keyboards.itely
index  
7735ef89e8a5dac8380b5ede198c779ac935604f..4652079fc7ad7d6ae8794d5077d5da0198c0228b  
100644
--- a/Documentation/notation/keyboards.itely
+++ b/Documentation/notation/keyboards.itely
@@ -170,10 +170,8 @@ the current voice from its current staff to the staff  
called
 @code{"up"} and @code{"down"}, or @code{"RH"} and @code{"LH"}.

 The staff to which the voice is being switched must exist at the
-time of the switch.  If necessary, staves should be @qq{kept alive},
-see @ref{Keeping contexts alive}.
-
-Cross-staff notes are beamed automatically:
+time of the switch.  If necessary, add spacer rests to
+keep staves @qq{alive}, see @ref{Keeping contexts alive}.

 @lilypond[verbatim,quote]
 \new PianoStaff <<
@@ -182,25 +180,34 @@ Cross-staff notes are beamed automatically:
     \change Staff = "down"
     g8 fis g
     \change Staff = "up"
-    <g'' c''>8
+    <g'' c''>8\(
     \change Staff = "down"
-    e8 dis e
-    \change Staff = "up"
+    e8 dis e\)
+  }
+  \new Dynamics {
+    s2\mf\< s4. s8\!
   }
   \new Staff = "down" {
     \clef bass
-    % keep staff alive
-    s1
+    s1 % keep this staff alive
   }
 >>
 @end lilypond

+Cross-staff beams are created automatically.
 If the beaming needs to be tweaked, make any changes to the stem
 directions first.  The beam positions are then measured from the
 center of the staff that is closest to the beam.  For a simple
 example of beam tweaking, see @rlearning{Fixing overlapping
 notation}.

+Notice that the stems overlap the intervening line of dynamics.
+Automatic collision resolution is suspended for beams, slurs
+and other spanners that connect notes on different staves,
+as well as for any stems or articulations that are
+attached to such cross-staff objects.
+Resolve the resulting collisions manually, when necessary,
+using the methods in @rlearning{Fixing overlapping notation}.

 @seealso
 Learning Manual: