From 2e3c5412eacdbfd976d2cd6c5cc90f272ddfc263 Mon Sep 17 00:00:00 2001
From: Phil Holmes <mail@philholmes.net>
Date: Mon, 6 Aug 2012 11:21:06 +0100
Subject: [PATCH] Documentation for cross staff stems

---
 Documentation/changes.tely                    |  7 ++++
 Documentation/notation/keyboards.itely        | 41 ++++---------------
 Documentation/snippets/cross-staff-stems.ly   | 16 +++++---
 .../snippets/new/cross-staff-stems.ly         | 16 +++++---
 4 files changed, 38 insertions(+), 42 deletions(-)

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 9e7c59be99..83db4ea859 100644
--- 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 c693aa91ac..ee37e5560e 100644
--- 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 dc9c3b8e83..2ef51185fc 100644
--- 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 2168e20222..edf4fbf77b 100644
--- 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
     }
   >>
 }
-- 
2.39.2