From: Carl Sorensen Date: Sat, 9 Oct 2010 14:55:27 +0000 (-0600) Subject: Doc:: Notation -- Reorder autobeaming documentation X-Git-Tag: release/2.13.36-1~44 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=025fb26c1a84cd38ca78fa9a08b4379526696289;p=lilypond.git Doc:: Notation -- Reorder autobeaming documentation Update beam-endings-in-score-context.ly for new autobeam settings --- diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely index 021de18eb7..ed8dd90e38 100644 --- a/Documentation/notation/rhythms.itely +++ b/Documentation/notation/rhythms.itely @@ -1869,104 +1869,21 @@ Beams can collide with note heads and accidentals in other voices. @funindex \set @funindex set -The placement of automatic beams is determined by the context properties -@code{baseMoment}, @code{beatStructure}, @code{beamExceptions}, -and @code{autoBeaming}. - -The following rules, in order of priority, apply when determining -the appearance of beams: - -@itemize -@item -If a manual beam is specified with @code{[..]} set the beam -as specified, otherwise - -@item -if @code{\autoBeamOff} is in force do not beam, otherwise - -@item -if a beam-ending rule is defined in @code{beamExceptions} -for the beam-type, use it to determine the valid places where -beams may end, otherwise - -@item -if a beam-ending rule is defined in @code{beamExceptions} -for a longer beam-type, use it to determined the valid places -where beams may end, otherwise - -@item -use the values of @code{baseMoment} and @code{beatStructure} to -determine the ends of the beats in the measure, and -end beams at the end of beats. - -@end itemize - -The beam-type is the duration of the shortest note in the beamed group. - -@i{@strong{Modifying the grouping of beats}} - -By default @code{baseMoment} is set by the @code{\time} command, -normally to one over the denominator of the time signature. -Any exceptions to this default -can be found in @file{scm/@/time@/-signature@/-settings@/.scm}. -Changing the default value of @code{baseMoment} for a given -time signature is described in @ref{Time signature}. - -@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}. - -Special (i.e., other than at the end of the beat) autobeam settings -are stored in the -@code{beamExceptions} property. Default values of @code{beamExceptions} -are established by the @code{\time} command. Default values of -@code{beamExceptions} for a time signature -are determined in @file{scm/@/time@/-signature@/-settings@/.scm}. -Entries in @code{beamExceptions} are indexed by rule type and beam type. - -Rule type should be @code{#'end} for beam ending. - -The ending rules consist of a scheme alist -(or list of pairs) that -indicates the beam type and the grouping to be applied to -beams containing notes with a shortest duration of that -beam type. - -@example -#'((beam-type1 . grouping-1) - (beam-type2 . grouping-2) - (beam-type3 . grouping-3)) -@end example - -Beam type is a scheme pair indicating the duration -of the beam, e.g., @code{(1 . 16)}. - -Grouping is a scheme list indicating the grouping to be applied to -the beam. The grouping is in units of the beam type. - -For reference, the default beaming rules are found in -@file{scm/time-signature-settings.scm}. - -Alternate values for @code{beamExceptions} -can be defined using the @code{\set} command. - -@warning{ -A @code{beamExceptions} value must be -@emph{complete} exceptions list. That is, every exception that should -be applied must be included in the setting. -It is not possible to add, remove, or change only one of the exceptions. -While this may seem cumbersome, -it means that the current beaming settings need not be known -in order to specify a new beaming pattern.} +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 +the one over numerator of the time signature. By default, +each unit of length @code{baseMoment} is a single beat. @lilypond[quote,relative=2,verbatim] \time 5/16 -c8^"beats" c16 c8 | -\set beatStructure = #'(2 3) -c8^"(2+3)" c16 c8 -\set beatStructure = #'(3 2) -c8^"(3+2)" c16 c8 +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 Beam setting changes can be limited to specific contexts. If no @@ -2001,7 +1918,7 @@ staff: @lilypond[quote,verbatim,relative=2] \time 7/8 % rhythm 3-1-1-2 -% Context Voice specified -- does not work correctly +% Change applied to Voice by default -- does not work correctly % Because of autogenerated voices, all beating will % be at baseMoment (1 . 8) \set beatStructure = #'(3 1 1 2) @@ -2012,20 +1929,134 @@ staff: << {a8 a a a16 a a a a8 a} \\ {f4. f8 f f f} >> @end lilypond -Beam settings can be set back to default behavior. This -is accomplished by setting the time signature. +The value of @code{baseMoment} can be adjusted to change +the beaming behavior, if desired. When this is done, +the value of @code{beatStructure} must be set to be +compatible with the new value of @code{baseMoment}. @lilypond[quote,verbatim,relative=2] -\time 4/4 -\repeat unfold 8 {a8} -% eliminate beam exception that groups beats 1, 2 and 3, 4 -\set Timing.beamExceptions = #'() -\repeat unfold 8 {a8} +\time 5/8 +\set Timing.baseMoment = #(ly:make-moment 1 16) +\set Timing.beatStructure = #'(7 3) +\repeat unfold 10 {a16} +@end lilypond + +@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}. + +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 + ((1 . 32) . (2 2 2)) ;rule for 1/32 beams -- end each 1/16 + ))) %close all entries +c16 c c | +\repeat unfold 6 {c32} | +@end lilypond + +@code{beamExceptions} is an alist with a key of rule-type and +a value of beaming-rules. + +At this time the only available value of rule-type is +@code{#'end} for beam ending. + +Beaming-rules is a scheme alist (or list of pairs) that +indicates the beam type and the grouping to be applied to +beams containing notes with a shortest duration of that +beam type. + +@example +#'((beam-type1 . grouping-1) + (beam-type2 . grouping-2) + (beam-type3 . grouping-3)) +@end example + +Beam type is a scheme pair indicating the duration +of the beam, e.g., @code{(1 . 16)}. + +Grouping is a scheme list indicating the grouping to be applied to +the beam. The grouping is in units of the beam type. + +@warning{ +A @code{beamExceptions} value must be +@emph{complete} exceptions list. That is, every exception that should +be applied must be included in the setting. +It is not possible to add, remove, or change only one of the exceptions. +While this may seem cumbersome, +it means that the current beaming settings need not be known +in order to specify a new beaming pattern.} + +When the time signature is changed, default values of +@code{Timing.baseMoment}, @code{Timing.beatStructure}, +and @code{Timing.beamExceptions} are set. Setting the time signature +will reset the automatic beaming settings for the @code{Timing} +context to the default behavior. + +@lilypond[quote,verbatim,relative=2] +\time 6/8 +\repeat unfold 6 {a8} +% group (4 + 2) +\set Timing.beatStructure = #'(4 2) +\repeat unfold 6 {a8} % go back to default behavior -\time 4/4 -\repeat unfold 8 {a8} +\time 6/8 +\repeat unfold 6 {a8} @end lilypond +These 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}. + +@i{@strong{How automatic beaming works}} + +When automatic beaming is enabled, the placement of automatic beams +is determined by the context properties +@code{baseMoment}, @code{beatStructure}, and @code{beamExceptions}. + +The following rules, in order of priority, apply when determining +the appearance of beams: + +@itemize +@item +If a manual beam is specified with @code{[..]} set the beam +as specified, otherwise + +@item +if a beam-ending rule is defined in @code{beamExceptions} +for the beam-type, use it to determine the valid places where +beams may end, otherwise + +@item +if a beam-ending rule is defined in @code{beamExceptions} +for a longer beam-type, use it to determined the valid places +where beams may end, otherwise + +@item +use the values of @code{baseMoment} and @code{beatStructure} to +determine the ends of the beats in the measure, and +end beams at the end of beats. + +@end itemize + +In the rules above, the beam-type is the duration of the +shortest note in the beamed group. + +For reference, the default beaming rules are found in +@file{scm/time-signature-settings.scm}. @snippets diff --git a/Documentation/snippets/beam-endings-in-score-context.ly b/Documentation/snippets/beam-endings-in-score-context.ly index 1c340524c4..e35e1a2cef 100644 --- a/Documentation/snippets/beam-endings-in-score-context.ly +++ b/Documentation/snippets/beam-endings-in-score-context.ly @@ -2,10 +2,10 @@ % generated from Documentation/snippets/new % This file is in the public domain. %% Note: this file works from version 2.13.29 -\version "2.13.31" +\version "2.13.36" \header { -%% Translation of GIT committish: 0b55335aeca1de539bf1125b717e0c21bb6fa31b +%% Translation of GIT committish: 5160eccb26cee0bfd802d844233e4a8d795a1e94 texidoces = " Las reglas de final de barra especificadas en el contexto @code{Score} se aplican a todos los pentagramas, pero se pueden