Add regression test for issue 317

[lilypond.git] / Documentation / notation / rhythms.itely

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index 5d1770fa41107eeb3b7b97f2df0ca736acdd2c27..f0d518d99d1720d3de4b9ef9c82c12e95aaadae8 100644 (file)
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.13.36"
+@c \version "2.13.44"

 
 @node Rhythms
 @section Rhythms
 
 @node Rhythms
 @section Rhythms


@@ -430,7 +430,7 @@ the chord.
 
 @lilypond[quote,verbatim,relative=1]
 <c e g> ~ <c e g>
 
 @lilypond[quote,verbatim,relative=1]
 <c e g> ~ <c e g>

-<c ~ e g ~ b> <c e g b>
+<c~ e g~ b> <c e g b>

 @end lilypond
 
 @cindex repeating ties
 @end lilypond
 
 @cindex repeating ties


@@ -570,7 +570,7 @@ Internals Reference:
 Switching staves when a tie is active will not produce a slanted
 tie.
 
 Switching staves when a tie is active will not produce a slanted
 tie.
 

-Changing clefs or octavations during a tie is not really
+Changing clefs or ottavations during a tie is not really

 well-defined.  In these cases, a slur may be preferable.
 
 
 well-defined.  In these cases, a slur may be preferable.
 
 


@@ -611,7 +611,7 @@ commands:
 
 @c \time 16/1 is used to avoid spurious bar lines
 @c and long tracts of empty measures
 
 @c \time 16/1 is used to avoid spurious bar lines
 @c and long tracts of empty measures

-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,relative=2]

 \new Staff {
   % These two lines are just to prettify this example
   \time 16/1
 \new Staff {
   % These two lines are just to prettify this example
   \time 16/1


@@ -739,14 +739,14 @@ A spacer rest implicitly causes @code{Staff} and @code{Voice}
 contexts to be created if none exist, just like notes and rests
 do:
 
 contexts to be created if none exist, just like notes and rests
 do:
 

-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,relative=2]

 s1 s s
 @end lilypond
 
 @code{\skip} simply skips musical time; it creates no output of
 any kind.
 
 s1 s s
 @end lilypond
 
 @code{\skip} simply skips musical time; it creates no output of
 any kind.
 

-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,relative=2]

 % This is valid input, but does nothing
 \skip 1 \skip1 \skip 1
 @end lilypond
 % This is valid input, but does nothing
 \skip 1 \skip1 \skip 1
 @end lilypond


@@ -796,7 +796,7 @@ notation used for notes.  The duration in a multi-measure rest must
 always be an integral number of measure-lengths, so augmentation dots
 or fractions must often be used:
 
 always be an integral number of measure-lengths, so augmentation dots
 or fractions must often be used:
 

-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,relative=2]

 \compressFullBarRests
 \time 2/4
 R1 | R2 |
 \compressFullBarRests
 \time 2/4
 R1 | R2 |


@@ -811,7 +811,7 @@ R4*5*4 |
 A full-measure rest is printed as either a whole or breve rest,
 centered in the measure, depending on the time signature.
 
 A full-measure rest is printed as either a whole or breve rest,
 centered in the measure, depending on the time signature.
 

-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,relative=2]

 \time 4/4
 R1 |
 \time 6/4
 \time 4/4
 R1 |
 \time 6/4


@@ -833,7 +833,7 @@ show all the rest measures explicitly.  Alternatively, a multi-measure
 rest can be shown as a single measure containing a multi-measure rest
 symbol, with the number of measures of rest printed above the measure:
 
 rest can be shown as a single measure containing a multi-measure rest
 symbol, with the number of measures of rest printed above the measure:
 

-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,relative=2]

 % Default behavior
 \time 3/4 r2. | R2.*2 |
 \time 2/4 R2 |
 % Default behavior
 \time 3/4 r2. | R2.*2 |
 \time 2/4 R2 |


@@ -865,7 +865,7 @@ Markups can be added to multi-measure rests.
 The predefined command @code{\fermataMarkup}
 is provided for adding fermatas.
 
 The predefined command @code{\fermataMarkup}
 is provided for adding fermatas.
 

-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,relative=2]

 \compressFullBarRests
 \time 3/4
 R2.*10^\markup { \italic "ad lib." }
 \compressFullBarRests
 \time 3/4
 R2.*10^\markup { \italic "ad lib." }


@@ -877,7 +877,7 @@ R2.^\fermataMarkup
 be directed to the correct object, or they will be ignored.  See the
 following example:}
 
 be directed to the correct object, or they will be ignored.  See the
 following example:}
 

-@lilypond[quote,verbatim,fragment]
+@lilypond[quote,verbatim,relative=2]

 % This fails, as the wrong object name is specified
 \override TextScript #'padding = #5
 R1^"wrong"
 % This fails, as the wrong object name is specified
 \override TextScript #'padding = #5
 R1^"wrong"


@@ -1056,25 +1056,23 @@ be changed, or new default values can be added:
 
 @lilypond[quote,verbatim]
 \score {
 
 @lilypond[quote,verbatim]
 \score {

-  \relative c' {
-    \overrideTimeSignatureSettings
-      #'Score    % context
-      #'(4 . 4)  % timeSignatureFraction
-      #'(1 . 4)  % baseMomentFraction
-      #'(3 1)    % beatStructure
-      #'()       % beamExceptions
-    \time 4/4
-    \repeat unfold 8 { c8 } |
+  \new Staff {
+    \relative c' {
+      \overrideTimeSignatureSettings
+        #'(4 . 4)  % timeSignatureFraction
+        #'(1 . 4)  % baseMomentFraction
+        #'(3 1)    % beatStructure
+        #'()       % beamExceptions
+      \time 4/4
+      \repeat unfold 8 { c8 } |
+    }

   }
 }
 @end lilypond
 
   }
 }
 @end lilypond
 

-@code{\overrideTimeSignatureSettings} takes five arguments:
+@code{\overrideTimeSignatureSettings} takes four arguments:

 
 @enumerate
 
 @enumerate

-@item
-@code{@var{context}}, a Scheme symbol that describes the context
-to which the default setting will apply.

 
 @item
 @code{@var{timeSignatureFraction}}, a Scheme pair describing the
 
 @item
 @code{@var{timeSignatureFraction}}, a Scheme pair describing the


@@ -1094,6 +1092,38 @@ for the time signature that go beyond ending at every beat, as
 described in @ref{Setting automatic beam behavior}.
 @end enumerate
 
 described in @ref{Setting automatic beam behavior}.
 @end enumerate
 

+The context containing @code{\overrideTimeSignatureSettings} must
+be instantiated before the @code{\overrideTimeSignatureSettings}
+call is executed.  That means it must either be explicitly
+instantiated or there must be music in the context before the
+@code{\overrideTimeSignatureSettings} call:
+
+@lilypond[quote,verbatim]
+\score {
+  \relative c' {
+    % This call will fail because the context isn't yet instantiated
+    \overrideTimeSignatureSettings
+      #'(4 . 4)  % timeSignatureFraction
+      #'(1 . 4)  % baseMomentFraction
+      #'(3 1)    % beatStructure
+      #'()       % beamExceptions
+    \time 4/4
+    c8^\markup {"Beamed (2 2)"}
+    \repeat unfold 7 { c8 } |
+    % This call will succeed
+    \overrideTimeSignatureSettings
+      #'(4 . 4)  % timeSignatureFraction
+      #'(1 . 4)  % baseMomentFraction
+      #'(3 1)    % beatStructure
+      #'()       % beamExceptions
+    \time 4/4
+    c8^\markup {"Beamed (3 1)"}
+    \repeat unfold 7 { c8 } |
+  }
+}
+@end lilypond
+
+

 @cindex time signature properties, restoring default values
 @cindex restoring default properties for time signatures
 @funindex \revertTimeSignatureSettings
 @cindex time signature properties, restoring default values
 @cindex restoring default properties for time signatures
 @funindex \revertTimeSignatureSettings


@@ -1106,20 +1136,61 @@ to the original values:
   \relative c' {
     \repeat unfold 8 { c8 } |
     \overrideTimeSignatureSettings
   \relative c' {
     \repeat unfold 8 { c8 } |
     \overrideTimeSignatureSettings

-      #'Score                         % context
-      #'(4 . 4)                       % timeSignatureFraction
-      #'(1 . 4)                       % baseMomentFraction
-      #'(3 1)                         % beatStructure
-      #'((end . (((1 . 8) . (3 1))))) % beamExceptions
+      #'(4 . 4)  % timeSignatureFraction
+      #'(1 . 4)  % baseMomentFraction
+      #'(3 1)    % beatStructure
+      #'()       % beamExceptions

     \time 4/4
     \repeat unfold 8 { c8 } |
     \time 4/4
     \repeat unfold 8 { c8 } |

-    \revertTimeSignatureSettings #'Score #'(4 . 4)
+    \revertTimeSignatureSettings #'(4 . 4)

     \time 4/4
     \repeat unfold 8 { c8 } |
   }
 }
 @end lilypond
 
     \time 4/4
     \repeat unfold 8 { c8 } |
   }
 }
 @end lilypond
 

+Different values of default time signature properties can be established
+for different staves by moving the @code{Timing_translator} and the
+@code{Default_bar_line_engraver} from the @code{Score} context to the
+@code{Staff} context.
+
+@lilypond[quote, verbatim]
+\score {
+  \new StaffGroup <<
+     \new Staff {
+        \overrideTimeSignatureSettings
+          #'(4 . 4)  % timeSignatureFraction
+          #'(1 . 4)  % baseMomentFraction
+          #'(3 1)    % beatStructure
+          #'()       % beamExceptions
+        \time 4/4
+        \repeat unfold 8 {c''8}
+     }
+     \new Staff {
+        \overrideTimeSignatureSettings
+          #'(4 . 4)  % timeSignatureFraction
+          #'(1 . 4)  % baseMomentFraction
+          #'(1 3)    % beatStructure
+          #'()       % beamExceptions
+        \time 4/4
+        \repeat unfold 8 {c''8}
+     }
+  >>
+  \layout {
+    \context {
+      \Score
+      \remove "Timing_translator"
+      \remove "Default_bar_line_engraver"
+    }
+    \context {
+      \Staff
+      \consists "Timing_translator"
+      \consists "Default_bar_line_engraver"
+    }
+  }
+}
+@end lilypond
+

 @predefined
 @code{\numericTimeSignature},
 @code{\defaultTimeSignature}.
 @predefined
 @code{\numericTimeSignature},
 @code{\defaultTimeSignature}.


@@ -1175,6 +1246,14 @@ c2 d
 e4. d8 c2
 @end lilypond
 
 e4. d8 c2
 @end lilypond
 

+Metronome marks may also be printed as a range of two numbers:
+
+@lilypond[verbatim,quote,relative=1]
+\tempo 4 = 40 ~ 46
+c4. e8 a4 g
+b,2 d4 r
+@end lilypond
+

 Tempo indications with text can be used instead:
 
 @lilypond[verbatim,quote,relative=2]
 Tempo indications with text can be used instead:
 
 @lilypond[verbatim,quote,relative=2]


@@ -1823,7 +1902,7 @@ Notation Reference:
 @ref{Setting automatic beam behavior}.
 
 Installed Files:
 @ref{Setting automatic beam behavior}.
 
 Installed Files:

-@file{scm/@/auto@/-beam@/.scm}.
+@file{scm/auto-beam.scm}.

 
 Snippets:
 @rlsr{Rhythms}.
 
 Snippets:
 @rlsr{Rhythms}.


@@ -1942,7 +2021,7 @@ 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
 
 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}.
+@file{scm/time-signature-settings.scm}.

 
 Special autobeaming rules (other than ending a beam on a beat)
 are defined in the @code{beamExceptions} property.
 
 Special autobeaming rules (other than ending a beam on a beat)
 are defined in the @code{beamExceptions} property.


@@ -2007,10 +2086,40 @@ context to the default behavior.
 @end lilypond
 
 These default automatic beaming settings for a time signature
 @end lilypond
 
 These default automatic beaming settings for a time signature

-are determined in @file{scm/@/time@/-signature@/-settings@/.scm}.
+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}.
 
 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
 @i{@strong{How automatic beaming works}}
 
 When automatic beaming is enabled, the placement of automatic beams


@@ -2071,7 +2180,7 @@ For reference, the default beaming rules are found in
 
 
 @seealso
 
 
 @seealso

-Installed files:
+Installed Files:

 @file{scm/beam-settings.scm}.
 
 Snippets:
 @file{scm/beam-settings.scm}.
 
 Snippets:


@@ -2212,9 +2321,9 @@ feathered beam must be indicated manually using @code{[} and
 direction to the @code{Beam} property @code{grow-direction}.
 
 If the placement of the notes and the sound in the MIDI output is to
 direction to the @code{Beam} property @code{grow-direction}.
 
 If the placement of the notes and the sound in the MIDI output is to

-reflect the ritardando or accelerando indicated by the feathered beam
-the notes must be grouped as a music expression delimited by braces
-and preceded by a @code{featherDurations} command which specifies
+reflect the @emph{ritardando} or @emph{accelerando} indicated by the
+feathered beam the notes must be grouped as a music expression delimited
+by braces and preceded by a @code{featherDurations} command which specifies

 the ratio between the durations of the first and last notes in the
 group.
 
 the ratio between the durations of the first and last notes in the
 group.
 


@@ -2779,7 +2888,7 @@ c1 \mark \default
 c1
 @end lilypond
 
 c1
 @end lilypond
 

-The file @file{scm/@/translation@/-functions@/.scm} contains the
+The file @file{scm/translation-functions.scm} contains the

 definitions of @code{format-mark-numbers} (the default format),
 @code{format-mark-box-numbers}, @code{format-mark-letters} and
 @code{format-mark-box-letters}.  These can be used as inspiration
 definitions of @code{format-mark-numbers} (the default format),
 @code{format-mark-box-numbers}, @code{format-mark-letters} and
 @code{format-mark-box-letters}.  These can be used as inspiration


@@ -2841,7 +2950,7 @@ Notation Reference:
 @ref{Aligning objects}.
 
 Installed Files:
 @ref{Aligning objects}.
 
 Installed Files:

-@file{scm/@/translation@/-functions@/.scm} contains
+@file{scm/translation-functions.scm} contains

 the definitions of @code{format-mark-numbers} and
 @code{format-mark-letters}.  They can be used as inspiration for
 other formatting functions.
 the definitions of @code{format-mark-numbers} and
 @code{format-mark-letters}.  They can be used as inspiration for
 other formatting functions.


@@ -3010,7 +3119,7 @@ Notation Reference:
 @ref{Manual beams}.
 
 Installed Files:
 @ref{Manual beams}.
 
 Installed Files:

-@file{ly/@/grace@/-init@/.ly}.
+@file{ly/grace-init.ly}.

 
 Snippets:
 @rlsr{Rhythms}.
 
 Snippets:
 @rlsr{Rhythms}.