Doc: Clarify automatic beam setting (2701)

Documentation/notation/rhythms.itely

 @c -*- coding: utf-8; mode: texinfo; -*-
 @ignore
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     version that you are working on.  For details, see the Contributors'
     Guide, node Updating translation committishes..
 @end ignore
 
 @c \version "2.15.39"
@@ skipping 1966 matching lines @@
 @funindex autoBeaming
 @funindex baseMoment
 @funindex beamExceptions
 @funindex beatStructure
 @funindex measureLength
 @funindex \time
 @funindex time
 @funindex \set
 @funindex set
 
+When automatic beaming is enabled, the placement of automatic beams
+is determined by three context properties:
+@code{baseMoment}, @code{beatStructure}, and @code{beamExceptions}.
+If a @code{beamExceptions} rule is defined for the time signature in
+force, that rule is used to determine the beam placement.  If no
+@code{beamExceptions} rule is defined for the time signature in force,
+the beam placement is determined by the settings of @code{baseMoment}
+and @code{beatStructure}.
+
+By default, @code{beamExceptions} rules are defined for most common
+time signatures, so the @code{beamException} rules must be disabled
+if automatic beaming is to be based on @code{baseMoment} and
+@code{beatStructure}.  The @code{beamExceptions} rules are disabled
+by
+
+@example
+\set Timing.beamExceptions = #'()
+@end example
+
+
+@i{@strong{Beaming based on @code{baseMoment} and @code{beatStructure}}}

[Trevor Daniels, 2012/07/31 22:30:12]

I don't like this either, but it was already used elsewhere in this section.  We
already have unnumberedsubsubsec, so can't use that.

+
 In most instances, automatic beams will end at the end of a beat.
 The ending points for beats are determined by the context properties
 @code{baseMoment} and @code{beatStructure}.  @code{beatStructure}
 is a scheme list that defines the length of each beat in the measure
 in units of @code{baseMoment}.  By default, @code{baseMoment} is
 one over the denominator of the time signature.  By default,
 each unit of length @code{baseMoment} is a single beat.
 
 @lilypond[quote,relative=2,verbatim]
 \time 5/16
 c16^"default" c c c c |
 \set Timing.beatStructure = #'(2 3)
 c16^"(2+3)" c c c c |
 \set Timing.beatStructure = #'(3 2)
 c16^"(3+2)" c c c c |
 @end lilypond
 
+If a common time signature is being used, @code{beamExceptions}
+@emph{must} be disabled to enable @code{beatStructure} to work.
+The @code{\set Timing.beamExceptions = #'()} command can always
+be included if beaming is being determined by @code{beatStructure}.
+
+@lilypond[quote,relative=2,verbatim]
+\time 4/4
+a8^"default" a a a a a a a
+
+\set Timing.baseMoment = #(ly:make-moment 1 4)
+\set Timing.beatStructure = #'(1 1 1 1)
+a8^"no change" a a a a a a a
+
+\set Timing.beamExceptions = #'()
+\set Timing.baseMoment = #(ly:make-moment 1 4)
+\set Timing.beatStructure = #'(1 1 1 1)
+a8^"changed" a a a a a a a
+@end lilypond
+
 Beam setting changes can be limited to specific contexts.  If no
 setting is included in a lower-level context, the setting of the
 enclosing context will apply.
 
 @lilypond[quote, verbatim,relative=1]
 \new Staff {
   \time 7/8
   \set Staff.beatStructure = #'(2 3 2)
   <<
     \new Voice = one {
@@ skipping 44 matching lines @@
 
 @code{baseMoment} is a @i{moment}; a unit of musical duration.  A
 quantity of type @i{moment} is created by the scheme function
 @code{ly:make-moment}.  For more information about this function,
 see @ref{Time administration}.
 
 By default @code{baseMoment} is set to one over the denominator of
 the time signature. Any exceptions to this default can be found in
 @file{scm/time-signature-settings.scm}.
 
+@i{@strong{Beaming based on @code{beamExceptions}}}
+
 Special autobeaming rules (other than ending a beam on a beat)
 are defined in the @code{beamExceptions} property.
 
 @lilypond[quote,relative=2,verbatim]
 \time 3/16
 \set Timing.beatStructure = #'(2 1)
 \set Timing.beamExceptions =
   #'(                         ;start of alist
      (end .                   ;entry for end of beams
       (                       ;start of alist of end points
@@ skipping 1379 matching lines @@
 Notation Reference:
 @ref{Bar numbers},
 @ref{Unmetered music}.
 
 Snippets:
 @rlsr{Rhythms}.
 
 Internals Reference:
 @rinternals{Timing_translator},
 @rinternals{Score}.