Run scripts/auxiliar/update-with-convert-ly.sh

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

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index c0e88b3e277830c24041b0e29acb1ad239bb9465..973bbb9456417d309e18d5a239ea6608a8d6b25b 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.19.2"
+@c \version "2.19.21"

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


@@ -199,18 +199,16 @@ rests from 128th to maxima (8 x whole) may be printed.
 @funindex tuplet
 
 Tuplets are made from a music expression with the @code{\tuplet}
 @funindex tuplet
 
 Tuplets are made from a music expression with the @code{\tuplet}

-command, multiplying the speed of the music expression by a
-fraction:
+command, multiplying the speed of the music expression by a fraction:

 
 @example
 \tuplet @var{fraction} @{ @var{music} @}
 @end example
 
 @noindent
 
 @example
 \tuplet @var{fraction} @{ @var{music} @}
 @end example
 
 @noindent

-The fraction's numerator will be printed over or
-under the notes, optionally with a bracket.  The most common
-tuplets are triplets: 3@tie{}notes sound within the duration
-normally allowed for@tie{}2:
+The fraction's numerator will be printed over or under the notes,
+optionally with a bracket.  The most common tuplets are triplets
+(3@tie{}notes sound within the duration normally allowed for@tie{}2).

 
 @lilypond[quote,verbatim,relative=2]
 a2 \tuplet 3/2 { b4 4 4 }
 
 @lilypond[quote,verbatim,relative=2]
 a2 \tuplet 3/2 { b4 4 4 }


@@ -220,10 +218,9 @@ c4 c \tuplet 3/2 { b4 a g }
 @cindex tuplet grouping
 @noindent
 When entering long passages of tuplets, having to write a separate
 @cindex tuplet grouping
 @noindent
 When entering long passages of tuplets, having to write a separate

-@code{\tuplet} command for each group is inconvenient.  It is
-possible to specify the duration of one tuplet group directly
-before the music in order to have the tuplets grouped
-automatically:
+@code{\tuplet} command for each group is inconvenient.  It is possible
+to specify the duration of one tuplet group directly before the music
+in order to have the tuplets grouped automatically:

 
 @lilypond[quote,verbatim,relative=2]
 g2 r8 \tuplet 3/2 8 { cis16 d e e f g g f e }
 
 @lilypond[quote,verbatim,relative=2]
 g2 r8 \tuplet 3/2 8 { cis16 d e e f g g f e }


@@ -238,8 +235,14 @@ g2 r8 \tuplet 3/2 8 { cis16 d e e f g g f e }
 @funindex \tupletNeutral
 @funindex tupletNeutral
 
 @funindex \tupletNeutral
 @funindex tupletNeutral
 

-Tuplet brackets may be manually placed above or below the staff;
-see @ref{Direction and placement}.
+Tuplet brackets may be manually placed above or below the staff:
+
+@lilypond[quote,verbatim,relative=2]
+\tupletUp \tuplet 3/2 { c8 d e }
+\tupletNeutral \tuplet 3/2 { c8 d e }
+\tupletDown \tuplet 3/2 { f,8 g a }
+\tupletNeutral \tuplet 3/2 { f8 g a }
+@end lilypond

 
 Tuplets may be nested:
 
 
 Tuplets may be nested:
 


@@ -248,12 +251,11 @@ Tuplets may be nested:
 c4 \tuplet 5/4 { f8 e f \tuplet 3/2 { e[ f g] } } f4
 @end lilypond
 
 c4 \tuplet 5/4 { f8 e f \tuplet 3/2 { e[ f g] } } f4
 @end lilypond
 

-Modifying nested tuplets which begin at the same musical moment
-must be done with @code{\tweak}.
-
-To modify the duration of notes without printing a tuplet bracket,
-see @ref{Scaling durations}.
+Modifying nested tuplets which begin at the same musical moment must be
+done with @code{\tweak}.

 
 

+To modify the duration of notes without printing a tuplet bracket, see
+@ref{Scaling durations}.

 
 @predefined
 @code{\tupletUp},
 
 @predefined
 @code{\tupletUp},


@@ -271,7 +273,7 @@ see @ref{Scaling durations}.
 @funindex tupletSpannerDuration
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 @funindex tupletSpannerDuration
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

-{entering-several-tuplets-using-only-one--times-command.ly}
+{entering-several-tuplets-using-only-one--tuplet-command.ly}

 
 @cindex Tuplet number changes
 
 
 @cindex Tuplet number changes
 


@@ -299,6 +301,7 @@ Learning Manual:
 @rlearning{Tweaking methods}.
 
 Notation Reference:
 @rlearning{Tweaking methods}.
 
 Notation Reference:

+@ref{Direction and placement},

 @ref{Time administration},
 @ref{Scaling durations},
 @ref{The tweak command},
 @ref{Time administration},
 @ref{Scaling durations},
 @ref{The tweak command},


@@ -312,20 +315,6 @@ Internals Reference:
 @rinternals{TupletNumber},
 @rinternals{TimeScaledMusic}.
 
 @rinternals{TupletNumber},
 @rinternals{TimeScaledMusic}.
 

-@cindex grace notes within tuplet brackets
-
-@knownissues
-Grace notes may be placed within tuplet brackets, @emph{except}
-when a staff begins with a grace note followed by a tuplet.  In this
-particular case, the grace note must be placed before the @code{\tuplet}
-command to avoid errors.
-
-@cindex tempo marks within tuplet brackets
-
-When using a tuplet at the beginning of a piece with a @code{\tempo}
-mark, the music must be explicitly entered in a @code{\new Voice}
-block, as discussed in @rlearning{Voices contain music}.
-

 
 @node Scaling durations
 @unnumberedsubsubsec Scaling durations
 
 @node Scaling durations
 @unnumberedsubsubsec Scaling durations


@@ -446,8 +435,8 @@ dots cannot be used to denote the rhythm.  Ties should also be
 used when note values cross larger subdivisions of the measure:
 
 @lilypond[verbatim,quote]
 used when note values cross larger subdivisions of the measure:
 
 @lilypond[verbatim,quote]

-\relative c' {
-  r8 c~ 2 r4 |
+\relative {
+  r8 c'~ 2 r4 |

   r8^"not" c2~ 8 r4
 }
 @end lilypond
   r8^"not" c2~ 8 r4
 }
 @end lilypond


@@ -821,6 +810,8 @@ Internals Reference:
 @cindex whole rest for a full measure
 @cindex rest, whole for a full measure
 
 @cindex whole rest for a full measure
 @cindex rest, whole for a full measure
 

+@funindex compressMMRests
+@funindex \compressMMRests

 @funindex R
 
 Rests for one or more full measures are entered like notes with
 @funindex R
 
 Rests for one or more full measures are entered like notes with


@@ -828,11 +819,12 @@ the note name uppercase @code{R}:
 
 @lilypond[quote,verbatim,relative=2]
 % Rest measures contracted to single measure
 
 @lilypond[quote,verbatim,relative=2]
 % Rest measures contracted to single measure

-\compressFullBarRests
-R1*4
-R1*24
-R1*4
-b2^"Tutti" b4 a4
+\compressMMRests {
+  R1*4
+  R1*24
+  R1*4
+  b2^"Tutti" b4 a4
+}

 @end lilypond
 
 The duration of full-measure rests is identical to the duration
 @end lilypond
 
 The duration of full-measure rests is identical to the duration


@@ -841,15 +833,16 @@ always be an integral number of measure-lengths, so augmentation dots
 or fractions must often be used:
 
 @lilypond[quote,verbatim,relative=2]
 or fractions must often be used:
 
 @lilypond[quote,verbatim,relative=2]

-\compressFullBarRests
-\time 2/4
-R1 | R2 |
-\time 3/4
-R2. | R2.*2 |
-\time 13/8
-R1*13/8 | R1*13/8*12 |
-\time 10/8
-R4*5*4 |
+\compressMMRests {
+  \time 2/4
+  R1 | R2 |
+  \time 3/4
+  R2. | R2.*2 |
+  \time 13/8
+  R1*13/8 | R1*13/8*12 |
+  \time 10/8
+  R4*5*4 |
+}

 @end lilypond
 
 A full-measure rest is printed as either a whole or breve rest,
 @end lilypond
 
 A full-measure rest is printed as either a whole or breve rest,


@@ -867,11 +860,6 @@ R1*2 |
 @cindex multi-measure rest, expanding
 @cindex multi-measure rest, contracting
 
 @cindex multi-measure rest, expanding
 @cindex multi-measure rest, contracting
 

-@funindex \expandFullBarRests
-@funindex expandFullBarRests
-@funindex \compressFullBarRests
-@funindex compressFullBarRests
-

 By default a multi-measure rest is expanded in the printed score to
 show all the rest measures explicitly.  Alternatively, a multi-measure
 rest can be shown as a single measure containing a multi-measure rest
 By default a multi-measure rest is expanded in the printed score to
 show all the rest measures explicitly.  Alternatively, a multi-measure
 rest can be shown as a single measure containing a multi-measure rest


@@ -883,10 +871,10 @@ symbol, with the number of measures of rest printed above the measure:
 \time 2/4 R2 |
 \time 4/4
 % Rest measures contracted to single measure
 \time 2/4 R2 |
 \time 4/4
 % Rest measures contracted to single measure

-\compressFullBarRests
-r1 | R1*17 | R1*4 |
-% Rest measures expanded
-\expandFullBarRests
+\compressMMRests {
+  r1 | R1*17 | R1*4 |
+}
+% Rest measures expanded again

 \time 3/4
 R2.*2 |
 @end lilypond
 \time 3/4
 R2.*2 |
 @end lilypond


@@ -910,10 +898,11 @@ The predefined command @code{\fermataMarkup}
 is provided for adding fermatas.
 
 @lilypond[quote,verbatim,relative=2]
 is provided for adding fermatas.
 
 @lilypond[quote,verbatim,relative=2]

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

 @end lilypond
 
 @warning{Markups attached to a multi-measure rest are objects of type
 @end lilypond
 
 @warning{Markups attached to a multi-measure rest are objects of type


@@ -940,17 +929,14 @@ setting, resulting bar-check warnings may not be displayed.
 @funindex textLengthOff
 @funindex \fermataMarkup
 @funindex fermataMarkup
 @funindex textLengthOff
 @funindex \fermataMarkup
 @funindex fermataMarkup

-@funindex \compressFullBarRests
-@funindex compressFullBarRests
-@funindex \expandFullBarRests
-@funindex expandFullBarRests
+@funindex \compressMMRests
+@funindex compressMMRests

 
 @predefined
 @code{\textLengthOn},
 @code{\textLengthOff},
 @code{\fermataMarkup},
 
 @predefined
 @code{\textLengthOn},
 @code{\textLengthOff},
 @code{\fermataMarkup},

-@code{\compressFullBarRests},
-@code{\expandFullBarRests}.
+@code{\compressMMRests}.

 @endpredefined
 
 
 @endpredefined
 
 


@@ -1038,7 +1024,9 @@ The time signature is set as follows:
 \time 3/4 c2.
 @end lilypond
 
 \time 3/4 c2.
 @end lilypond
 

-@cindex time signature, visibility of
+Mid-measure time signature changes are covered in @ref{Upbeats}.
+
+@cindex time signature visibility

 
 Time signatures are printed at the beginning of a piece
 and whenever the time signature changes.  If a change takes place
 
 Time signatures are printed at the beginning of a piece
 and whenever the time signature changes.  If a change takes place


@@ -1332,15 +1320,16 @@ restores the default behavior of ignoring tempo marks
 for horizontal spacing.
 
 @lilypond[verbatim,quote,relative=0]
 for horizontal spacing.
 
 @lilypond[verbatim,quote,relative=0]

-\compressFullBarRests
-\markLengthOn
-\tempo "Molto vivace"
-R1*12
-\tempo "Meno mosso"
-R1*16
-\markLengthOff
-\tempo "Tranquillo"
-R1*20
+\compressMMRests {
+  \markLengthOn
+  \tempo "Molto vivace"
+  R1*12
+  \tempo "Meno mosso"
+  R1*16
+  \markLengthOff
+  \tempo "Tranquillo"
+  R1*20
+}

 @end lilypond
 
 @snippets
 @end lilypond
 
 @snippets


@@ -1367,7 +1356,7 @@ Music Glossary:
 
 Notation Reference:
 @ref{Formatting text},
 
 Notation Reference:
 @ref{Formatting text},

-@ref{MIDI output}.
+@ref{Creating MIDI output}.

 
 Snippets:
 @rlsr{Staff notation}.
 
 Snippets:
 @rlsr{Staff notation}.


@@ -1385,29 +1374,22 @@ Internals Reference:
 @cindex measure, partial
 @cindex measure, pickup
 @cindex pickup measure
 @cindex measure, partial
 @cindex measure, pickup
 @cindex pickup measure

+@cindex time signature, mid-measure

 
 @funindex measurePosition
 @funindex \partial
 @funindex partial
 
 Partial or pick-up measures, such as an @emph{anacrusis} or an
 
 @funindex measurePosition
 @funindex \partial
 @funindex partial
 
 Partial or pick-up measures, such as an @emph{anacrusis} or an

-@emph{upbeat}, are entered using the @code{\partial} command,
+@emph{upbeat}, are entered using the @code{\partial} command:

 
 @example
 \partial @var{duration}
 @end example
 
 
 @example
 \partial @var{duration}
 @end example
 

-@noindent
-where @code{@var{duration}} is the @emph{remaining} length of the
-partial measure @emph{before} the start of the next full measure.
-
-@lilypond[quote,verbatim,relative=1]
-\time 3/4
-\partial 8
-e8 | a4 c8 b c4 |
-@end lilypond
-
-The @var{duration} can be any value less than a full measure:
+When @code{\partial} is used at the beginning of a score,
+@code{@var{duration}} is the length of the music preceding the
+first bar.

 
 @lilypond[quote,verbatim,relative=1]
 \time 3/4
 
 @lilypond[quote,verbatim,relative=1]
 \time 3/4


@@ -1415,29 +1397,23 @@ The @var{duration} can be any value less than a full measure:
 r4 e8 | a4 c8 b c4 |
 @end lilypond
 
 r4 e8 | a4 c8 b c4 |
 @end lilypond
 

-@code{\partial @var{duration}} can also be written as:
-
-@example
-\set Timing.measurePosition -@var{duration}
-@end example
-
-So the first example above could be written:
+When @code{\partial} is used after the beginning of a score,
+@code{@var{duration}} is the @emph{remaining} length of the
+current measure.  It does not create a new numbered bar.

 
 @lilypond[quote,verbatim,relative=1]
 
 @lilypond[quote,verbatim,relative=1]

-\time 3/4
-\set Timing.measurePosition = #(ly:make-moment -1/8)
-e8 | a4 c8 b c4 |
+\set Score.barNumberVisibility = #all-bar-numbers-visible
+\override Score.BarNumber.break-visibility =
+          #end-of-line-invisible
+\time 9/8
+d'4.~ 4 d8 d( c) b | c4.~ 4. \bar "||"
+\time 12/8
+\partial 4.
+c8( d) e | f2.~ 4 f8 a,( c) f |

 @end lilypond
 
 @end lilypond
 

-The property @code{measurePosition} contains a rational number,
-which is usually positive and indicates how much of the measure
-has passed at this point.  @code{\partial @var{duration}} is
-defined such that no numbered bar gets created: when used at the
-beginning of a measure, @code{measurePosition} is set to a
-negative number, implying that the current bar will be
-@emph{preceded} by additional material.  When used after a measure
-has already started, however, it moves the requested distance
-before the @emph{end} of the bar.
+The @code{\partial} command is @emph{required} when the time
+signature changes in mid measure, but it may also be used alone.

 
 @lilypond[quote,verbatim,relative=1]
 \set Score.barNumberVisibility = #all-bar-numbers-visible
 
 @lilypond[quote,verbatim,relative=1]
 \set Score.barNumberVisibility = #all-bar-numbers-visible


@@ -1453,6 +1429,9 @@ r8 e8 | a4
 c8 b[ c b] |
 @end lilypond
 
 c8 b[ c b] |
 @end lilypond
 

+The @code{\partial} command sets the @code{Timing.measurePosition}
+property, which is a rational number that indicates how much of
+the measure has passed.

 
 @seealso
 Music Glossary:
 
 @seealso
 Music Glossary:


@@ -1606,8 +1585,8 @@ stretches of unmetered music to permit breaking:
 
 @cindex double time signatures
 @cindex signatures, polymetric
 
 @cindex double time signatures
 @cindex signatures, polymetric

-@cindex time signatures, polymetric
-@cindex time signatures, double
+@cindex time signature, polymetric
+@cindex time signature, double

 @cindex polymetric signatures
 @cindex meter, polymetric
 
 @cindex polymetric signatures
 @cindex meter, polymetric
 


@@ -1638,10 +1617,10 @@ may be necessary to insert beams manually, as the duration scaling will
 affect the autobeaming rules.
 
 @lilypond[quote,verbatim]
 affect the autobeaming rules.
 
 @lilypond[quote,verbatim]

-\relative c' <<
+\relative <<

   \new Staff {
     \time 3/4
   \new Staff {
     \time 3/4

-    c4 c c |
+    c'4 c c |

     c4 c c |
   }
   \new Staff {
     c4 c c |
   }
   \new Staff {


@@ -1684,10 +1663,10 @@ moving the @code{Timing_translator} and the
 
 % Now each staff has its own time signature.
 
 
 % Now each staff has its own time signature.
 

-\relative c' <<
+\relative <<

   \new Staff {
     \time 3/4
   \new Staff {
     \time 3/4

-    c4 c c |
+    c'4 c c |

     c4 c c |
   }
   \new Staff {
     c4 c c |
   }
   \new Staff {


@@ -2114,6 +2093,14 @@ 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.
 
 over the denominator of the time signature.  By default, each unit of
 length @code{baseMoment} is a single beat.
 

+Note that there are separate @code{beatStructure} and @code{baseMoment}
+values for each time signature.  Changes to these variables apply only
+to the time signature that is currently in force, hence those changes
+must be placed after the @code{\time} command which starts a new time
+signature section, not before it.  New values given to a particular
+time signature are retained and reinstated whenever that time signature
+is re-established.
+

 @lilypond[quote,relative=2,verbatim]
 \time 5/16
 c16^"default" c c c c |
 @lilypond[quote,relative=2,verbatim]
 \time 5/16
 c16^"default" c c c c |


@@ -2149,8 +2136,8 @@ enclosing context will apply.
   \set Staff.beatStructure = #'(2 3 2)
   <<
     \new Voice = one {
   \set Staff.beatStructure = #'(2 3 2)
   <<
     \new Voice = one {

-      \relative c'' {
-        a8 a a a a a a
+      \relative {
+        a'8 a a a a a a

       }
     }
     \new Voice = two {
       }
     }
     \new Voice = two {


@@ -2402,6 +2389,7 @@ in only one staff.
     \time 3/4
     \set Timing.baseMoment = #(ly:make-moment 1/8)
     \set Timing.beatStructure = #'(1 5)
     \time 3/4
     \set Timing.baseMoment = #(ly:make-moment 1/8)
     \set Timing.beatStructure = #'(1 5)

+    \set Timing.beamExceptions = #'()

     \repeat unfold 6 { a8 }
   }
   \new Staff {
     \repeat unfold 6 { a8 }
   }
   \new Staff {


@@ -3082,15 +3070,6 @@ next example, the second bar check will signal an error.
 \time 3/4 c2 e4 | g2 |
 @end example
 
 \time 3/4 c2 e4 | g2 |
 @end example
 

-Bar checks can also be used in lyrics:
-
-@example
-\lyricmode @{
-  \time 2/4
-  Twin -- kle | Twin -- kle |
-@}
-@end example
-

 An incorrect duration can result in a completely garbled score,
 especially if the score is polyphonic, so a good place to start
 correcting input is by scanning for failed bar checks and
 An incorrect duration can result in a completely garbled score,
 especially if the score is polyphonic, so a good place to start
 correcting input is by scanning for failed bar checks and


@@ -3100,6 +3079,22 @@ If successive bar checks are off by the same musical interval,
 only the first warning message is displayed.  This allows the
 warning to focus on the source of the timing error.
 
 only the first warning message is displayed.  This allows the
 warning to focus on the source of the timing error.
 

+Bar checks can also be inserted in lyrics:
+
+@example
+\lyricmode @{
+  \time 2/4
+  Twin -- kle | Twin -- kle |
+@}
+@end example
+
+Note that bar check marks in lyrics are evaluated at the musical
+moment when the syllable @emph{following} the check mark is processed.
+If the lyrics are associated with the notes of a voice which has a
+rest at the beginning of a bar, then no syllable can be located at the
+start of that bar and a warning will be issued if a bar check mark is
+placed in the lyrics at that position.
+

 
 @funindex |
 @funindex "|"
 
 @funindex |
 @funindex "|"


@@ -3512,32 +3507,11 @@ durations in the other staves.  For the above example
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-The use of grace notes within voice contexts confuses the way the voice
-is typeset. This can be overcome by inserting a rest or note between the
-voice command and the grace note.
-
-@lilypond[quote,verbatim]
-accMusic = {
-  \acciaccatura { f8 } e8 r8 \acciaccatura { f8 } e8 r4
-}
-
-\new Staff {
-  <<
-    \new Voice {
-      \relative c'' {
-        r8 r8 \voiceOne \accMusic \oneVoice r8 |
-        r8 \voiceOne r8 \accMusic \oneVoice r8 |
-      }
-    }
-    \new Voice {
-      \relative c' {
-        s8 s8 \voiceTwo \accMusic \oneVoice s8 |
-        s8 \voiceTwo r8 \accMusic \oneVoice s8 |
-      }
-    }
-  >>
-}
-@end lilypond
+Please make sure that you use the @code{\grace} command for the
+spacer part, even if the visual part uses @code{\acciaccatura} or
+@code{\appoggiatura} because otherwise an ugly slur fragment will
+be printed, connecting the invisible grace note with the following
+note.

 
 Grace sections should only be used within sequential music expressions.
 Nesting or juxtaposing grace sections is not supported, and might
 
 Grace sections should only be used within sequential music expressions.
 Nesting or juxtaposing grace sections is not supported, and might


@@ -3586,8 +3560,8 @@ functions take a defined piece of music as an argument and generate a
 multi-measure rest or @code{\skip} exactly as long as the piece.
 
 @lilypond[verbatim,quote]
 multi-measure rest or @code{\skip} exactly as long as the piece.
 
 @lilypond[verbatim,quote]

-MyCadenza = \relative c' {
-  c4 d8 e f g g4
+MyCadenza = \relative {
+  c'4 d8 e f g g4

   f2 g4 g
 }
 
   f2 g4 g
 }