From ff89624de9566c48f27ec827ad440bd00db46eda Mon Sep 17 00:00:00 2001
From: Carl Sorensen <c_sorensen@byu.edu>
Date: Sat, 4 Dec 2010 19:03:13 -0700
Subject: [PATCH] Doc -- add information on beamExceptions to Notation Manual

---
 Documentation/notation/rhythms.itely | 30 ++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index 6a9c08a8ac..c8b791790f 100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -2011,6 +2011,36 @@ 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
+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
+if @code{beamExceptions} is not reset.
+
+@lilypond[quote,verbatim,relative=2]
+\time 4/4
+\set Timing.baseMoment = #(ly:make-moment 1 8)
+\set Timing.beatStructure = #'(3 3 2)
+% This won't beam (3 3 2) because of beamExceptions
+\repeat unfold 8 {c8} |
+% This will beam (3 3 2) because we clear beamExceptions
+\set Timing.beamExceptions = #'()
+\repeat unfold 8 {c8}
+@end lilypond
+
+In a similar fashion, eighth notes in 3/4 time are beamed as a full
+measure by default.  To beam eighth notes in 3/4 time on the beat,
+reset @code{beamExceptions}.
+
+@lilypond[quote,verbatim,relative=2]
+\time 3/4
+% by default we beam in (3) due to beamExceptions
+\repeat unfold 6 {a8} |
+% This will beam (1 1 1) due to beatLength
+\set Timing.beamExceptions = #'()
+\repeat unfold 6 {a8}
+@end lilypond
+
 @i{@strong{How automatic beaming works}}
 
 When automatic beaming is enabled, the placement of automatic beams
-- 
2.39.2