X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Frepeats.itely;h=fb7cdf663b406f78dfa5b3674eb5849b94208e08;hb=26a079ca2393d053315ef8dbef626c897dc9645a;hp=7ffba85d30770dba82a7677ec260d5b18385b487;hpb=94408d4a2e538e8812561f29e09116ede58dd042;p=lilypond.git

diff --git a/Documentation/notation/repeats.itely b/Documentation/notation/repeats.itely
index 7ffba85d30..fb7cdf663b 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.12.0"
+@c \version "2.16.0"
 
 @node Repeats
 @section Repeats
@@ -29,7 +29,7 @@ notation for repeats with alternatives.
 
 @item unfold
 The repeated music is fully written out, as many times as
-specified by @var{repeatcount}.  This is useful when
+specified by @code{@var{repeatcount}}.  This is useful when
 entering repetitious music.
 
 @item percent
@@ -52,7 +52,7 @@ This is used to write tremolo beams.
 
 This section discusses how to input long (usually multi-measure)
 repeats.  The repeats can take two forms: repeats enclosed between
-repeat signs; or written out repeats, used to input repetitious music.
+repeat signs; or written-out repeats, used to input repetitious music.
 Repeat signs can also be controlled manually.
 
 @menu
@@ -84,7 +84,7 @@ The syntax for a normal repeat is
 @end example
 
 @noindent
-where @var{musicexpr} is a music expression.
+where @code{@var{musicexpr}} is a music expression.
 
 A single repeat without an alternate ending:
 
@@ -105,7 +105,7 @@ group of alternatives must be themselves, enclosed in a set of braces.
 @end example
 
 @noindent
-where @var{musicexpr} is a music expression.
+where @code{@var{musicexpr}} is a music expression.
 
 If there are more repeats than there are alternate endings, the earliest
 repeats are given the first alternative.
@@ -113,10 +113,10 @@ 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 }
+\repeat volta 2 { c4 d e f | }
 \alternative {
-  { c2 e }
-  { f2 g }
+  { c2 e | }
+  { f2 g | }
 }
 c1
 @end lilypond
@@ -124,10 +124,10 @@ c1
 A single repeat with more than one alternate ending:
 
 @lilypond[verbatim,quote,relative=2]
-\repeat volta 4 { c4 d e f }
+\repeat volta 4 { c4 d e f | }
 \alternative {
-  { c2 e }
-  { f2 g }
+  { c2 e | }
+  { f2 g | }
 }
 c1
 @end lilypond
@@ -135,15 +135,20 @@ c1
 Multiple repeats with more than one alternate ending:
 
 @lilypond[verbatim,quote,relative=2]
-\repeat volta 3 { c4 d e f }
+\repeat volta 3 { c4 d e f | }
 \alternative {
-  { c2 e }
-  { f2 g }
-  { a2 g }
+  { c2 e | }
+  { f2 g | }
+  { a2 g | }
 }
 c1
 @end lilypond
 
+@warning{If there are two or more alternatives, nothing should appear
+between the closing brace of one and the opening brace of the next
+in an @code{@bs{}alternative} block, otherwise you will not get the
+expected number of endings.}
+
 @warning{If you include @code{@bs{}relative} inside a
 @code{@bs{}repeat} without explicitly instantiating the
 @code{Voice} context, extra (unwanted) staves will appear.  See
@@ -157,7 +162,6 @@ c1
 @cindex pickup in a repeat
 @funindex \partial
 
-
 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
@@ -235,10 +239,28 @@ g1 |
 The @code{measureLength} property is described in @ref{Time
 administration}.
 
-@cindex repeats with ties
-@cindex alternative endings with ties
-@cindex ties in repeats
-@cindex ties in alternative endings
+@funindex \inStaffSegno
+
+The @code{\inStaffSegno} command can be used to place the segno
+symbol in cooperation with the @code{\repeat volta} command.
+Alternative bar line symbols can be set in a Score context by
+overriding the properties @code{segnoType},
+@code{startRepeatSegnoType}, @code{endRepeatSegnoType} or
+@code{doubleRepeatSegnoType} as required.
+
+@lilypond[verbatim,quote,relative=1]
+e1
+\repeat volta 2 {
+  \inStaffSegno
+  f2 g a b
+}
+c1_"D.S." \bar "|."
+@end lilypond
+
+@cindex repeats, with ties
+@cindex alternative endings, with ties
+@cindex ties, in repeats
+@cindex ties, alternative endings
 @funindex \repeatTie
 
 Ties may be added to a second ending:
@@ -253,16 +275,21 @@ c1
 @end lilypond
 
 @snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {shortening-volta-brackets.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {adding-volta-brackets-to-additional-staves.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {setting-the-double-repeat-default-for-volte.ly}
 
+@cindex repeats, bar numbers letters
+@cindex repeats, alternative bar numbers
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{alternative-bar-numbering.ly}
+
 @seealso
 Music Glossary:
 @rglos{repeat},
@@ -282,9 +309,7 @@ Internals Reference:
 @rinternals{VoltaRepeatedMusic},
 @rinternals{UnfoldedRepeatedMusic}.
 
-
 @knownissues
-
 @cindex repeat, ambiguous
 @cindex nested repeat
 @cindex repeat, nested
@@ -407,7 +432,8 @@ then include the markup in a Scheme list.
 voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
 \relative c'' {
   c1
-  \set Score.repeatCommands = #(list(list 'volta voltaAdLib) 'start-repeat)
+  \set Score.repeatCommands =
+    #(list(list 'volta voltaAdLib) 'start-repeat)
   c4 b d e
   \set Score.repeatCommands = #'((volta #f) (volta "4.") end-repeat)
   f1
@@ -418,10 +444,9 @@ voltaAdLib = \markup { 1. 2. 3... \text \italic { ad lib. } }
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {printing-a-repeat-sign-at-the-beginning-of-a-piece.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Bar lines},
@@ -440,32 +465,46 @@ Internals Reference:
 @unnumberedsubsubsec Written-out repeats
 
 @cindex written-out repeats
-@cindex repetitious music
 @cindex repeats, written-out
-@cindex repeat, unfold
-@cindex unfold music
+@cindex repeats, unfold
+@cindex repeats, alternative
 @cindex unfold repeat
-@cindex unfold repeat with alternate endings
-@cindex unfold music with alternate endings
-@cindex alternate ending in written-out repeats
+@cindex unfold repeat, alternate endings
+@cindex alternate repeats
+@cindex alternate endings, repeats
 @funindex unfold
 
-By using the @code{unfold} command, repeats can be used to simplify
-the writing out of repetitious music.  The syntax is
+By using the @code{unfold} command, repeats can be used to simplify the
+writing out of repetitious music.  The syntax is
 
 @example
 \repeat unfold @var{repeatcount} @var{musicexpr}
 @end example
 
 @noindent
-where @var{musicexpr} is a music expression and @var{repeatcount} is
-the number of times @var{musicexpr} is repeated.
+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
 @end lilypond
 
+In some cases, especially in a @code{\relative} context, the
+@code{\repeat unfold} function is not the same as writing out the
+music expression multiple times. E.g,
+
+@example
+\repeat unfold 2 @{ a'4 b c @}
+@end example
+
+is not equivalent to
+
+@example
+a'4 b c | a'4 b c
+@end example
+
 Unfold repeats can be made with alternate endings.
 
 @lilypond[verbatim,quote,relative=2]
@@ -491,9 +530,9 @@ make up the total number of repeats.
 c1
 @end lilypond
 
-If there are more alternate endings than repeats then the first
-alternatives are applied, LilyPond will ignore the remaining
-alternatives which will not be printed.
+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 }
@@ -519,14 +558,17 @@ without alternate endings).
 c1
 @end lilypond
 
+Chord constructs can be repeated by the chord repetition symbol
+@code{q}.  See @ref{Chord repetition}.
 
-@warning{If you include @code{@bs{}relative} inside a
-@code{@bs{}repeat} without explicitly instantiating the
-@code{Voice} context, extra (unwanted) staves will appear.  See
-@rprogram{An extra staff appears}.}
-
+@warning{If you include @code{@bs{}relative} inside a @code{@bs{}repeat}
+without explicitly instantiating the @code{Voice} context, extra
+(unwanted) staves will appear.  See @rprogram{An extra staff appears}.}
 
 @seealso
+Notation Reference:
+@ref{Chord repetition}.
+
 Snippets:
 @rlsr{Repeats}.
 
@@ -564,43 +606,55 @@ is replaced with a special sign.
 The syntax is
 
 @example
-@code{\repeat percent @var{number} @var{musicexpr}}
+\repeat percent @var{number} @var{musicexpr}
 @end example
 
 @noindent
-where @var{musicexpr} is a music expression.
+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 }
 @end lilypond
 
-Patterns of one or two measures are replaced by percent-like signs.
+Patterns of one or two measures are replaced by percent-like symbols.
 
 @lilypond[verbatim,quote,relative=2]
-\repeat percent 3 { c4 d e f }
-\repeat percent 4 { c2 d }
+\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' }
 @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 { \times 2/3 { r8 c d } e4 }
+@end lilypond
+
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {percent-repeat-counter.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {percent-repeat-count-visibility.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {isolated-percent-repeats.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{percent repeat},
@@ -611,23 +665,17 @@ Snippets:
 
 Internals Reference:
 @rinternals{RepeatSlash},
+@rinternals{RepeatSlashEvent},
+@rinternals{DoubleRepeatSlash},
 @rinternals{PercentRepeat},
+@rinternals{PercentRepeatCounter},
+@rinternals{PercentRepeatedMusic},
+@rinternals{Percent_repeat_engraver},
+@rinternals{DoublePercentEvent},
 @rinternals{DoublePercentRepeat},
 @rinternals{DoublePercentRepeatCounter},
-@rinternals{PercentRepeatCounter},
-@rinternals{PercentRepeatedMusic}.
-
-
-@knownissues
-
-Only three kinds of percent repeats are supported: a single slash
-representing a single beat (regardless of the duration of the repeated
-notes); a single slash with dots representing one full measure; and
-two slashes with dots crossing a bar line representing two full
-measures.  Neither multiple slashes representing single beat repeats
-consisting of sixteenth or shorter notes, nor two slashes with dots
-representing single beat repeats consisting of notes of varying
-durations, are supported.
+@rinternals{Double_percent_repeat_engraver},
+@rinternals{Slash_repeat_engraver}.
 
 
 @node Tremolo repeats
@@ -640,7 +688,7 @@ durations, are supported.
 @funindex tremolo
 
 Tremolos can take two forms: alternation between two chords or two
-notes, and rapid repetition of a single note or chord. Tremolos
+notes, and rapid repetition of a single note or chord.  Tremolos
 consisting of an alternation are indicated by adding beams between the
 notes or chords being alternated, while tremolos consisting of the
 rapid repetition of a single note are indicated by adding beams or
@@ -678,12 +726,11 @@ the note should not be surrounded by braces:
 @funindex tremoloFlags
 @funindex :
 
-The same output can be obtained by adding
-@q{@code{:}[@var{number}]} after the note.  The number indicates
-the duration of the subdivision, and it must be at least 8.  A
-@var{number} value of 8 gives one line across the note stem.  If
-the length is omitted, the last value (stored in
-@code{tremoloFlags}) is used:
+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:
 
 @lilypond[quote,verbatim,relative=2]
 c2:8 c:32
@@ -692,14 +739,12 @@ c: c:
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {cross-staff-tremolos.ly}
 
-
 @seealso
 Snippets:
 @rlsr{Repeats}.
 
 @cindex tremolo, cross-staff
 @cindex cross-staff tremolo
-