Documentation for cross staff stems (issue 6432063)

[PhilEHolmes]

Reviewers: Graham Percival, Trevor Daniels,

Message:
Please review my attempt at some documentation.

Description:
Updated the documentation to take account of the new cross staff stem
feature.

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

Affected files:
  M Documentation/changes.tely
  M Documentation/notation/keyboards.itely
  M Documentation/snippets/new/cross-staff-stems.ly


Index: Documentation/changes.tely
diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index  
6545c1dd69c8de8ce1ce80753cfb22b054a1449b..cb0bc056bd654178e5ceafe857b5a42b1368a0c2  
100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -61,6 +61,13 @@ which scares away people.

 @end ignore
 @item
+Support for cross-staff stems on chords, using @code{crossStaff}
+and the @code{Span_stem_engraver}.  This calculates the length of
+cross-staff stems automatically.
address@hidden
+{cross-staff-stems.ly}
+
address@hidden
 Support for Kievan square notation:
 @lilypond[quote,relative=1,verbatim]
 \new KievanVoice {
Index: Documentation/notation/keyboards.itely
diff --git a/Documentation/notation/keyboards.itely  
b/Documentation/notation/keyboards.itely
index  
c693aa91ac9fd086206916993be3acedda786813..ca83fa5e41aa4fe688284414712678acdce49dd6  
100644
--- a/Documentation/notation/keyboards.itely
+++ b/Documentation/notation/keyboards.itely
@@ -417,44 +417,18 @@ Internals Reference:
 @cindex cross staff chords

 @funindex Stem
address@hidden cross-staff
address@hidden length
address@hidden flag-style
address@hidden \crossStaff
address@hidden \autoBeamOff
address@hidden Span_stem_engraver

-Chords that cross staves may be produced:
-
address@hidden,quote]
-\new PianoStaff <<
-  \new Staff {
-    \relative c' {
-      f8 e4 d8 d f e4
-    }
-  }
-  \new Staff {
-    \relative c' {
-      << {
-        \clef bass
-        % stems may overlap the other staff
-        \override Stem #'cross-staff = ##t
-        % extend the stems to reach the other staff
-        \override Stem #'length = #12
-        % do not print extra flags
-        \override Flag #'style = #'no-flag
-        % prevent beaming as needed
-        a8 g4 f8 f bes\noBeam g4
-      }
-      \\
-      {
-        f,2 bes4 c
-      } >>
-    }
-  }
->>
address@hidden lilypond
+Chords that cross staves may be produced using the
address@hidden Care must be taken to ensure that
+automatic beams do not beam the notes on one staff when it’s not
+required on the other.

 @snippets
address@hidden,quote,texidoc,doctitle]
-{indicating-cross-staff-chords-with-arpeggio-bracket.ly}
address@hidden,quote]
+{cross-staff-stems.ly}

 @seealso
 Snippets:
Index: Documentation/snippets/new/cross-staff-stems.ly
diff --git a/Documentation/snippets/new/cross-staff-stems.ly  
b/Documentation/snippets/new/cross-staff-stems.ly
index  
2168e20222f3d349a715e542c1785f18cffb61e5..d7ad5800d44915a2911fd7f3d69bb52b72693102  
100644
--- a/Documentation/snippets/new/cross-staff-stems.ly
+++ b/Documentation/snippets/new/cross-staff-stems.ly
@@ -2,9 +2,10 @@

 \header {
   lsrtags = "staff-notation, tweaks-and-overrides, contexts-and-engravers"
-  texidoc = "This file demonstrates a scheme engraver that
-connects stems across staves.  The stem length need not be specified, as
-the code takes care of the variable distance between noteheads and staves."
+  texidoc = "This snippet shows the use of the @code{Span_stem_engraver}
+  and @code{\crossStaff} to connect stems across staves automatically.
+  The stem length need not be specified, as the variable distance
+  between noteheads and staves is calculated automatically."
   doctitle = "Cross staff stems"
 }