Doc -- Clarify instructions on autobeam settings (issue4160048)

[Carl . D . Sorensen]

Reviewers: ,

Message:
Mats identified some unexpected behavior with autobeam settings and time
signature setting.

http://thread.gmane.org/gmane.comp.gnu.lilypond.bugs/23117

This patch demonstrates the problem, describes the reason, and documents
two ways of avoiding the problem.

Please review this patch.  I'm afraid I might have been a little too
much LM style in it, although I didn't talk through the code.

Thanks,

Carl


Description:
Doc -- Clarify instructions on autobeam settings
Multiple \time calls can revert custom autobeam settings.  Clarify
in the documentation.

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

Affected files:
  M Documentation/notation/rhythms.itely


Index: Documentation/notation/rhythms.itely
diff --git a/Documentation/notation/rhythms.itely  
b/Documentation/notation/rhythms.itely
index  
f0d518d99d1720d3de4b9ef9c82c12e95aaadae8..218f931a450ca72c62346f2b1fa0b90b52d0f03b  
100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -2085,12 +2085,92 @@ context to the default behavior.
 \repeat unfold 6 { a8 }
 @end lilypond

-These default automatic beaming settings for a time signature
+By default, the @code{Timing} translator is aliased to the
address@hidden context.  This means that a setting the time signature
+in one staff will affect the beaming of the other staves as well.
+Thus, in the following example, the beaming will be at the standard
+beaming for 3/4 time, because the time signature setting in the
+second staff resets the beaming.
+
address@hidden,verbatim,relative=2]
+<<
+  \new Staff {
+    \time 3/4
+    \set Timing.baseMoment = #(ly:make-moment 1 8)
+    \set Timing.beatStructure = #'(1 5)
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+>>
address@hidden lilypond
+
+In contrast, in this example, the beaming will follow the specified
+beaming rules, because the custom beaming in the second staff
+overrides the default beaming.
+
address@hidden,verbatim,relative=2]
+<<
+  \new Staff {
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \time 3/4
+    \set Timing.baseMoment = #(ly:make-moment 1 8)
+    \set Timing.beatStructure = #'(1 5)
+    \repeat unfold 6 { a8 }
+  }
+>>
address@hidden lilypond
+
+To avoid this problem, the time signature can be set in only one
+staff.
+
address@hidden,verbatim,relative=2]
+<<
+  \new Staff {
+    \time 3/4
+    \set Timing.baseMoment = #(ly:make-moment 1 8)
+    \set Timing.beatStructure = #'(1 5)
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \repeat unfold 6 { a8 }
+  }
+>>
address@hidden lilypond
+
+The default beam settings for the time signature can also be
+changed, so that when the time signature is set the desired
+behavior will be set.  Changes in automatic beaming settings
+for a time signature are described in @ref{Time signature}.
+
address@hidden,verbatim,relative=2]
+<<
+  \new Staff {
+    \overrideTimeSignatureSettings
+      #'(3 . 4)         % timeSignatureFraction
+      #'(1 . 8)         % baseMomentFraction
+      #'(1 5)           % beatStructure
+      #'()             % beamExceptions
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+>>
address@hidden lilypond
+
+
+The default automatic beaming settings for a time signature
 are determined in @file{scm/time-signature-settings.scm}.
-The automatic beaming settings for a time signature can be changed
-as described in @ref{Time signature}.

-Most automatic beaming settings for a time signature contain an
+Many automatic beaming settings for a time signature contain an
 entry for @code{beamExceptions}.  For example, 4/4 time tries to
 beam the measure in two if there are only eighth notes.  The
 @code{beamExceptions} rule can override the @code{beatStructure} setting