Documentation for cross staff stems

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 9e7c59be99f4351cea7308f12eda454a532cde5f..83db4ea85980a7ba7bc1dc1b0d02b5ec5e8b3917 100644 (file)
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -60,6 +60,13 @@ which scares away people.
 * only show user-visible changes.
 
 @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.
+@lilypondfile[quote]
+{cross-staff-stems.ly}
+
 @item
 The syntax of words (character sequences recognized without enclosing
 quotes) and commands (now always a backslash @samp{\} followed by a

diff --git a/Documentation/notation/keyboards.itely b/Documentation/notation/keyboards.itely
index c693aa91ac9fd086206916993be3acedda786813..ee37e5560eafacd6c25886ac531b0e1195483561 100644 (file)
--- a/Documentation/notation/keyboards.itely
+++ b/Documentation/notation/keyboards.itely
@@ -417,40 +417,17 @@ Internals Reference:
 @cindex cross staff chords
 
 @funindex Stem
-@funindex cross-staff
-@funindex length
-@funindex flag-style
+@funindex \crossStaff
+@funindex \autoBeamOff
+@funindex Span_stem_engraver
 
-Chords that cross staves may be produced:
+Chords that cross staves may be produced using the
+@code{Span_stem_engraver}. 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.
 
-@lilypond[verbatim,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
-      } >>
-    }
-  }
->>
-@end lilypond
+@lilypondfile[verbatim,quote]
+{cross-staff-stems.ly}
 
 @snippets
 @lilypondfile[verbatim,quote,texidoc,doctitle]

diff --git a/Documentation/snippets/cross-staff-stems.ly b/Documentation/snippets/cross-staff-stems.ly
index dc9c3b8e838941955eca21801e81d90bf5a74646..2ef51185fc40f84a9f7f41d1380f5b8ea4519fe8 100644 (file)
--- a/Documentation/snippets/cross-staff-stems.ly
+++ b/Documentation/snippets/cross-staff-stems.ly
@@ -9,9 +9,12 @@
 
 \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"
 } % begin verbatim
 
@@ -27,12 +30,15 @@ the code takes care of the variable distance between noteheads and staves."
   \new PianoStaff <<
     \new Staff {
       <b d'>4 r d'16\> e'8. g8 r\!
+      e'8 f' g'4 e'2
     }
-   \new Staff {
-     \clef bass
+    \new Staff {
+      \clef bass
       \voiceOne
       \autoBeamOff
       \crossStaff { <e g>4 e, g16 a8. c8} d
+      \autoBeamOn
+      g8 f g4 c2
     }
   >>
 }

diff --git a/Documentation/snippets/new/cross-staff-stems.ly b/Documentation/snippets/new/cross-staff-stems.ly
index 2168e20222f3d349a715e542c1785f18cffb61e5..edf4fbf77b4db758733ff2658e6e7a52f18b9f6b 100644 (file)
--- a/Documentation/snippets/new/cross-staff-stems.ly
+++ b/Documentation/snippets/new/cross-staff-stems.ly
@@ -2,9 +2,12 @@
 
 \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"
 }
 
@@ -19,12 +22,15 @@ the code takes care of the variable distance between noteheads and staves."
   \new PianoStaff <<
     \new Staff {
       <b d'>4 r d'16\> e'8. g8 r\!
+      e'8 f' g'4 e'2
     }
-   \new Staff {
-     \clef bass
+    \new Staff {
+      \clef bass
       \voiceOne
       \autoBeamOff
       \crossStaff { <e g>4 e, g16 a8. c8} d
+      \autoBeamOn
+      g8 f g4 c2
     }
   >>
 }