X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Frepeats.itely;h=3a3fcb44c31c7770d96a5a38a63ace70aa9629f4;hb=c4a960d0461ee5ecd87cd46692ec11682b8969b0;hp=f3c4c5ac6c14d530bf6be0273c183be445388743;hpb=9828eb47c05a7d6446726ef96647e342e7122dc4;p=lilypond.git

diff --git a/Documentation/notation/repeats.itely b/Documentation/notation/repeats.itely
index f3c4c5ac6c..3a3fcb44c3 100644
--- a/Documentation/notation/repeats.itely
+++ b/Documentation/notation/repeats.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.11"
+@c \version "2.19.21"
 
 @node Repeats
 @section Repeats
@@ -88,10 +88,24 @@ where @code{@var{musicexpr}} is a music expression.
 
 A single repeat without an alternate ending:
 
-@lilypond[verbatim,quote,relative=2]
-\repeat volta 2 { c4 d e f }
-c2 d
-\repeat volta 2 { d4 e f g }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 2 { c''4 d e f }
+  c2 d
+  \repeat volta 2 { d4 e f g }
+}
+@end lilypond
+
+An @q{opening} repeat mark is not, by default, printed in the first full
+measure.  However it is possible to add one by using @code{\bar ".|:"}
+before the first note.
+
+@lilypond[verbatim,fragment,quote]
+\relative {
+  \repeat volta 2 { \bar ".|:" c''4 d e f }
+  c2 d
+  \repeat volta 2 { d4 e f g }
+}
 @end lilypond
 
 Alternative endings can be produced using @code{\alternative}.  Each
@@ -112,36 +126,42 @@ repeats are given the first alternative.
 
 A single repeat with one alternate ending:
 
-@lilypond[verbatim,quote,relative=2]
-\repeat volta 2 { c4 d e f | }
-\alternative {
-  { c2 e | }
-  { f2 g | }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 2 { c''4 d e f | }
+  \alternative {
+    { c2 e | }
+    { f2 g | }
+  }
+  c1
 }
-c1
 @end lilypond
 
 Multiple repeats with one alternate ending:
 
-@lilypond[verbatim,quote,relative=2]
-\repeat volta 4 { c4 d e f | }
-\alternative {
-  { c2 e | }
-  { f2 g | }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 4 { c''4 d e f | }
+  \alternative {
+    { c2 e | }
+    { f2 g | }
+  }
+  c1
 }
-c1
 @end lilypond
 
 Multiple repeats with more than one alternate ending:
 
-@lilypond[verbatim,quote,relative=2]
-\repeat volta 3 { c4 d e f | }
-\alternative {
-  { c2 e | }
-  { f2 g | }
-  { a2 g | }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat volta 3 { c''4 d e f | }
+  \alternative {
+    { c2 e | }
+    { f2 g | }
+    { a2 g | }
+  }
+  c1
 }
-c1
 @end lilypond
 
 @warning{If there are two or more alternatives, nothing should appear
@@ -161,84 +181,43 @@ expected number of endings.}
 @cindex repeat with pickup
 @cindex pickup in a repeat
 @funindex \partial
+@cindex bar checks with repeats
+@cindex repeats with bar checks
 
-If a repeat starts in the middle of a measure and has no alternate
-endings, normally the end of the repeat will also fall in the
-middle of a measure, so that the two ends add up to one complete
-measure.  In such cases, the repeat signs do not constitute true
-bar lines.  Do not use @code{\partial} commands or bar checks
-where these repeat signs are printed:
+If a repeat that has no alternate endings starts in the middle of a
+measure, it will usually end at a corresponding place in the middle of a
+later measure (so that the two ends add up to one complete measure).  In
+this case the repeat signs are not @q{true} bar lines so neither bar
+checks nor @code{\partial} commands should be placed there:
 
 @lilypond[verbatim,quote,relative=1]
-% no \partial here
-c4 e g  % no bar check here
-% no \partial here
+c'4 e g
 \repeat volta 4 {
   e4 |
   c2 e |
-  % no \partial here
-  g4 g g  % no bar check here
+  g4 g g
 }
-% no \partial here
-g4 |
-a2 a |
-g1 |
+  g4 |
+  a2 a |
+  g1 |
 @end lilypond
 
-Similarly, if a repeat begins with the initial partial measure of
-a score and has no alternate endings, the same conditions apply as
-in the above example, except that in this case the @code{\partial}
-command is required at the beginning of the score:
+If a repeat that has no alternate endings starts with a partial measure,
+then the same principles apply, except that a @code{\partial} command is
+required at the start of the measure:
 
 @lilypond[verbatim,quote,relative=1]
-\partial 4  % required
+\partial 4
 \repeat volta 4 {
-  e4 |
+  e'4 |
   c2 e |
-  % no \partial here
-  g4 g g  % no bar check here
-}
-% no \partial here
-g4 |
-a2 a |
-g1 |
-@end lilypond
-
-When alternate endings are added to a repeat that begins with an
-incomplete measure, it becomes necessary to set the
-@code{Timing.measureLength} context property manually, in the
-following specific places:
-
-@itemize
-@item
-at the start of any incomplete measures in the @code{\alternative}
-block, which normally occur at the end of each alternative, except
-(in most cases) the last.
-
-@item
-at the start of each alternative, except the first.
-@end itemize
-
-@lilypond[verbatim,quote,relative=1]
-\partial 4
-\repeat volta 2 { e4 | c2 e | }
-\alternative {
-  {
-    f2 d |
-    \set Timing.measureLength = #(ly:make-moment 3/4)
-    g4 g g  % optional bar check is allowed here
-  }
-  {
-    \set Timing.measureLength = #(ly:make-moment 4/4)
-    a2 a |
-  }
+  g4 g g
 }
-g1 |
+  g4 |
+  a2 a |
+  g1 |
 @end lilypond
 
-The @code{measureLength} property is described in @ref{Time
-administration}.
-
 @cindex repeats, with ties
 @cindex alternative endings, with ties
 @cindex ties, in repeats
@@ -247,12 +226,14 @@ administration}.
 
 Ties may be added to a second ending:
 
-@lilypond[verbatim,quote,relative=2]
-c1
-\repeat volta 2 { c4 d e f~ }
-\alternative {
-  { f2 d }
-  { f2\repeatTie f, }
+@lilypond[verbatim,quote]
+\relative {
+  c''1
+  \repeat volta 2 { c4 d e f~ }
+  \alternative {
+    { f2 d }
+    { f2\repeatTie f, }
+  }
 }
 @end lilypond
 
@@ -269,48 +250,56 @@ corresponding @qq{D.S.} mark must be added manually.
 
 Away from a repeat:
 
-@lilypond[verbatim,quote,relative=1]
-e1
-\inStaffSegno
-f2 g a b
-c1_"D.S." \bar "|."
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \inStaffSegno
+  f2 g a b
+  c1_"D.S." \bar "|."
+}
 @end lilypond
 
 At the start of a repeat:
 
-@lilypond[verbatim,quote,relative=1]
-e1
-\repeat volta 2 {
-  \inStaffSegno  % start repeat
-  f2 g a b
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \repeat volta 2 {
+    \inStaffSegno  % start repeat
+    f2 g a b
+  }
+  c1_"D.S." \bar "|."
 }
-c1_"D.S." \bar "|."
 @end lilypond
 
 At the end of a repeat:
 
-@lilypond[verbatim,quote,relative=1]
-e1
-\repeat volta 2 {
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \repeat volta 2 {
+    f2 g a b
+    \inStaffSegno  % end repeat
+  }
   f2 g a b
-  \inStaffSegno  % end repeat
+  c1_"D.S." \bar "|."
 }
-f2 g a b
-c1_"D.S." \bar "|."
 @end lilypond
 
 Between two repeats:
 
-@lilypond[verbatim,quote,relative=1]
-e1
-\repeat volta 2 {
-  f2 g a b
-}
-\inStaffSegno  % double repeat
-\repeat volta 2 {
-  f2 g a b
+@lilypond[verbatim,quote]
+\relative {
+  e'1
+  \repeat volta 2 {
+    f2 g a b
+  }
+  \inStaffSegno  % double repeat
+  \repeat volta 2 {
+    f2 g a b
+  }
+  c1_"D.S." \bar "|."
 }
-c1_"D.S." \bar "|."
 @end lilypond
 
 Alternative bar line symbols can be obtained by setting (in the Score
@@ -320,17 +309,19 @@ required bar line type.  The alternative bar line types must be
 selected from the pre-defined types or types previously defined
 with the @code{\defineBarLine} command (see @ref{Bar lines}).
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
 \defineBarLine ":|.S[" #'(":|." "S[" "")
 \defineBarLine "]" #'("]" "" "")
-e1
-\repeat volta 2 {
-  f2 g a b
-  \once \set Score.endRepeatSegnoType = ":|.S["
-  \inStaffSegno
+\relative {
+  e'1
+  \repeat volta 2 {
+    f2 g a b
+    \once \set Score.endRepeatSegnoType = ":|.S["
+    \inStaffSegno
+  }
+  f2 g \bar "]" a b
+  c1_"D.S." \bar "|."
 }
-f2 g \bar "]" a b
-c1_"D.S." \bar "|."
 @end lilypond
 
 @snippets
@@ -360,6 +351,9 @@ Notation Reference:
 @ref{Modifying ties and slurs},
 @ref{Time administration}.
 
+Installed Files:
+@file{ly/engraver-init.ly}.
+
 Snippets:
 @rlsr{Repeats}.
 
@@ -452,11 +446,13 @@ layout of repeats.  Its value is a Scheme list of repeat commands.
 @item start-repeat
 Print a @code{.|:} bar line.
 
-@lilypond[verbatim,quote,relative=2]
-c1
-\set Score.repeatCommands = #'(start-repeat)
-d4 e f g
-c1
+@lilypond[verbatim,quote]
+\relative {
+  c''1
+  \set Score.repeatCommands = #'(start-repeat)
+  d4 e f g
+  c1
+}
 @end lilypond
 
 As per standard engraving practice, repeat signs are not printed
@@ -465,37 +461,43 @@ at the beginning of a piece.
 @item end-repeat
 Print a @code{:|.} bar line:
 
-@lilypond[verbatim,quote,relative=2]
-c1
-d4 e f g
-\set Score.repeatCommands = #'(end-repeat)
-c1
+@lilypond[verbatim,quote]
+\relative {
+  c''1
+  d4 e f g
+  \set Score.repeatCommands = #'(end-repeat)
+  c1
+}
 @end lilypond
 
 @item (volta @var{number}) @dots{} (volta #f)
 Create a new volta with the specified number.  The volta bracket must
 be explicitly terminated, or it will not be printed.
 
-@lilypond[verbatim,quote,relative=2]
-f4 g a b
-\set Score.repeatCommands = #'((volta "2"))
-g4 a g a
-\set Score.repeatCommands = #'((volta #f))
-c1
+@lilypond[verbatim,quote]
+\relative {
+  f''4 g a b
+  \set Score.repeatCommands = #'((volta "2"))
+  g4 a g a
+  \set Score.repeatCommands = #'((volta #f))
+  c1
+}
 @end lilypond
 
 @end table
 
 Multiple repeat commands may occur at the same point:
 
-@lilypond[verbatim,quote,relative=2]
-f4 g a b
-\set Score.repeatCommands = #'((volta "2, 5") end-repeat)
-g4 a g a
-c1
-\set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
-b1
-\set Score.repeatCommands = #'((volta #f))
+@lilypond[verbatim,quote]
+\relative {
+  f''4 g a b
+  \set Score.repeatCommands = #'((volta "2, 5") end-repeat)
+  g4 a g a
+  c1
+  \set Score.repeatCommands = #'((volta #f) (volta "95") end-repeat)
+  b1
+  \set Score.repeatCommands = #'((volta #f))
+}
 @end lilypond
 
 @cindex volta bracket with text
@@ -508,8 +510,8 @@ then include the markup in a Scheme list.
 
 @lilypond[verbatim,quote]
 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
-\relative c'' {
-  c1
+\relative {
+  c''1
   \set Score.repeatCommands =
     #(list(list 'volta voltaAdLib) 'start-repeat)
   c4 b d e
@@ -519,12 +521,6 @@ voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
 }
 @end lilypond
 
-
-@snippets
-
-@lilypondfile[verbatim,quote,texidoc,doctitle]
-{printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
-
 @seealso
 Notation Reference:
 @ref{Bar lines},
@@ -564,9 +560,11 @@ where @code{@var{musicexpr}} is a music expression and
 @code{@var{repeatcount}} is the number of times
 @code{@var{musicexpr}} is repeated.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat unfold 2 { c4 d e f }
-c1
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 { c''4 d e f }
+  c1
+}
 @end lilypond
 
 In some cases, especially in a @code{\relative} context, the
@@ -585,55 +583,63 @@ a'4 b c | a'4 b c
 
 Unfold repeats can be made with alternate endings.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat unfold 2 { c4 d e f }
-\alternative {
-  { c2 g' }
-  { c,2 b }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 { c''4 d e f }
+  \alternative {
+    { c2 g' }
+    { c,2 b }
+  }
+  c1
 }
-c1
 @end lilypond
 
 If there are more repeats than there are alternate endings, the first
 alternative is applied multiple times until the remaining alternatives
 make up the total number of repeats.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat unfold 4 { c4 d e f }
-\alternative {
-  { c2 g' }
-  { c,2 b }
-  { e2 d }
- }
-c1
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 4 { c''4 d e f }
+  \alternative {
+    { c2 g' }
+    { c,2 b }
+    { e2 d }
+   }
+  c1
+}
 @end lilypond
 
 If there are more alternate endings than repeats then only the first
 alternatives are applied.  The remaining alternatives will be ignored
 and not printed.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat unfold 2 { c4 d e f }
-\alternative {
-  { c2 g' }
-  { c,2 b }
-  { e2 d }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 { c''4 d e f }
+  \alternative {
+    { c2 g' }
+    { c,2 b }
+    { e2 d }
+  }
+  c1
 }
-c1
 @end lilypond
 
 It is also possible to nest multiple @code{unfold} functions (with or
 without alternate endings).
 
-@lilypond[verbatim,quote,relative=2]
-\repeat unfold 2 {
-  \repeat unfold 2 { c4 d e f }
-  \alternative {
-    { c2 g' }
-    { c,2 b }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat unfold 2 {
+    \repeat unfold 2 { c''4 d e f }
+    \alternative {
+      { c2 g' }
+      { c,2 b }
+    }
   }
+  c1
 }
-c1
 @end lilypond
 
 Chord constructs can be repeated by the chord repetition symbol
@@ -692,34 +698,42 @@ where @code{@var{musicexpr}} is a music expression.
 
 Patterns that are shorter than one measure are replaced by slashes.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat percent 4 { c128 d e f }
-\repeat percent 4 { c64 d e f }
-\repeat percent 5 { c32 d e f }
-\repeat percent 4 { c16 d e f }
-\repeat percent 4 { c8 d }
-\repeat percent 4 { c4 }
-\repeat percent 2 { c2 }
+@lilypond[verbatim,quote]
+\relative c'' {
+  \repeat percent 4 { c128 d e f }
+  \repeat percent 4 { c64 d e f }
+  \repeat percent 5 { c32 d e f }
+  \repeat percent 4 { c16 d e f }
+  \repeat percent 4 { c8 d }
+  \repeat percent 4 { c4 }
+  \repeat percent 2 { c2 }
+}
 @end lilypond
 
 Patterns of one or two measures are replaced by percent-like symbols.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat percent 2 { c4 d e f }
-\repeat percent 2 { c2 d }
-\repeat percent 2 { c1 }
+@lilypond[verbatim,quote]
+\relative c'' {
+  \repeat percent 2 { c4 d e f }
+  \repeat percent 2 { c2 d }
+  \repeat percent 2 { c1 }
+}
 @end lilypond
 
-@lilypond[verbatim,quote,relative=2]
-\repeat percent 3 { c4 d e f | c2 g' }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat percent 3 { c''4 d e f | c2 g' }
+}
 @end lilypond
 
 Patterns that are shorter than one measure but contain mixed durations
 use a double-percent symbol.
 
-@lilypond[verbatim,quote,relative=2]
-\repeat percent 4 { c8. <d f>16 }
-\repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
+@lilypond[verbatim,quote]
+\relative {
+  \repeat percent 4 { c''8. <d f>16 }
+  \repeat percent 2 { \tuplet 3/2 { r8 c d } e4 }
+}
 @end lilypond
 
 @snippets
@@ -755,6 +769,26 @@ Internals Reference:
 @rinternals{Double_percent_repeat_engraver},
 @rinternals{Slash_repeat_engraver}.
 
+@knownissues
+Percent repeats will not contain anything else apart from the percent
+sign itself; in particular, timing changes will not be repeated.
+
+@lilypond[quote,verbatim,relative=2]
+\repeat percent 3 { \time 5/4 c2. 2 \time 4/4 2 2 }
+@end lilypond
+
+@noindent
+Any meter changes or @code{\partial} commands need to occur in parallel
+passages @emph{outside} of any percent repeat, e.g in a separate
+timing track.
+
+@lilypond[quote,verbatim,relative=2]
+<<
+  \repeat percent 3 { c2. 2 2 2 }
+  \repeat unfold 3 { \time 5/4 s4*5 \time 4/4 s1 }
+>>
+@end lilypond
+
 
 @node Tremolo repeats
 @unnumberedsubsubsec Tremolo repeats
@@ -775,10 +809,12 @@ slashes to a single note.
 To place tremolo marks between notes, use @code{\repeat} with
 tremolo style:
 
-@lilypond[quote,verbatim,relative=2]
-\repeat tremolo 8 { c16 d }
-\repeat tremolo 6 { c16 d }
-\repeat tremolo 2 { c16 d }
+@lilypond[quote,verbatim]
+\relative c'' {
+  \repeat tremolo 8 { c16 d }
+  \repeat tremolo 6 { c16 d }
+  \repeat tremolo 2 { c16 d }
+}
 @end lilypond
 
 The @code{\repeat tremolo} syntax expects exactly two notes within
@@ -801,18 +837,19 @@ the note should not be surrounded by braces:
 @end lilypond
 
 @cindex tremolo marks
-@funindex tremoloFlags
 @funindex :
 
 The same output can be obtained by adding @code{:@var{N}} after
 the note, where @code{@var{N}} indicates the duration of the
 subdivision (it must be at least 8).  If @code{@var{N}} is 8, one
 beam is added to the note's stem.  If @code{@var{N}} is omitted,
-the last value (stored in @code{tremoloFlags}) is used:
+the last value is used:
 
-@lilypond[quote,verbatim,relative=2]
-c2:8 c:32
-c: c:
+@lilypond[quote,verbatim]
+\relative {
+  c''2:8 c:32
+  c: c:
+}
 @end lilypond
 
 @snippets