Doc: ensure two spaces after end of sentence.

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

diff --git a/Documentation/notation/repeats.itely b/Documentation/notation/repeats.itely
index 302f1ca047ffea5552e7fb6f8bc89b4ccc011ad2..46726cd0521e7f63fba2f6594f7aad151b7d7028 100644 (file)
--- a/Documentation/notation/repeats.itely
+++ b/Documentation/notation/repeats.itely
@@ -3,7 +3,8 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the

-    version that you are working on.  See TRANSLATION for details.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..

 @end ignore
 
 @c \version "2.12.0"
 @end ignore
 
 @c \version "2.12.0"


@@ -83,13 +84,9 @@ The syntax for a normal repeat is
 @end example
 
 @noindent
 @end example
 
 @noindent

-where @var{musicexpr} is a music expression.  Alternate endings can be
-produced using @code{\alternative}.  In order to delimit the alternate
-endings, the group of alternatives must be enclosed in a set of
-braces.  If there are more repeats than there are alternate endings,
-the earliest repeats are given the first alternative.
+where @var{musicexpr} is a music expression.

 
 

-Normal repeats without alternate endings:
+A single repeat without an alternate ending:

 
 @lilypond[verbatim,quote,relative=2]
 \repeat volta 2 { c4 d e f }
 
 @lilypond[verbatim,quote,relative=2]
 \repeat volta 2 { c4 d e f }


@@ -97,20 +94,60 @@ c2 d
 \repeat volta 2 { d4 e f g }
 @end lilypond
 
 \repeat volta 2 { d4 e f g }
 @end lilypond
 

-Normal repeats with alternate endings:
+Alternative endings can be produced using @code{\alternative}.  Each
+group of alternatives must be themselves, enclosed in a set of braces.
+
+@example
+\repeat volta @var{repeatcount} @var{musicexpr}
+\alternative @{
+  @{ @var{musicexpr} @}
+@}
+@end example
+
+@noindent
+where @var{musicexpr} is a music expression.
+
+If there are more repeats than there are alternate endings, the earliest
+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 }
+}
+c1
+@end lilypond
+
+A single repeat with more than one alternate ending:

 
 @lilypond[verbatim,quote,relative=2]
 \repeat volta 4 { c4 d e f }
 \alternative {
 
 @lilypond[verbatim,quote,relative=2]
 \repeat volta 4 { c4 d e f }
 \alternative {

-  { d2 e }
+  { c2 e }
+  { f2 g }
+}
+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 }
   { f2 g }

+  { a2 g }

 }
 c1
 @end lilypond
 
 }
 c1
 @end lilypond
 

-@warning{Do not include @code{@bs{}relative} inside a
-@code{@bs{}repeat}.  It will cause unwanted staves to appear.
-See @rlearning{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}.}

 
 @cindex repeat with upbeat
 @cindex upbeat in a repeat
 
 @cindex repeat with upbeat
 @cindex upbeat in a repeat


@@ -120,30 +157,83 @@ See @rlearning{An extra staff appears}.}
 @cindex pickup in a repeat
 @funindex \partial
 
 @cindex pickup in a repeat
 @funindex \partial
 

-Repeats with upbeats can be entered in two ways:

 
 

-@lilypond[verbatim,quote,relative=2]
-\partial 4
-e |
-\repeat volta 4 { c2 d | e2 f | }
-\alternative {
-  { g4 g g e }
-  { a4 a a a | b2. }
+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:
+
+@lilypond[verbatim,quote,relative=1]
+% no \partial here
+c4 e g  % no bar check here
+% no \partial here
+\repeat volta 4 {
+  e4 |
+  c2 e |
+  % no \partial here
+  g4 g g  % no bar check here

 }
 }

+% no \partial here
+g4 |
+a2 a |
+g1 |

 @end lilypond
 
 @end lilypond
 

-@noindent
-or
+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:
+
+@lilypond[verbatim,quote,relative=1]
+\partial 4  % required
+\repeat volta 4 {
+  e4 |
+  c2 e |
+  % no \partial here
+  g4 g g  % no bar check here
+}
+% no \partial here
+g4 |
+a2 a |
+g1 |
+@end lilypond

 
 

-@lilypond[verbatim,quote,relative=2]
+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
 \partial 4

-\repeat volta 4 { e4 | c2 d | e2 f | }
+\repeat volta 2 { e4 | c2 e | }

 \alternative {
 \alternative {

-  { \partial 4*3 g4 g g }
-  { a4 a a a | b2. }
+  {
+    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 |
+  }

 }
 }

+g1 |

 @end lilypond
 
 @end lilypond
 

+The @code{measureLength} property is described in @ref{Time
+administration}.

 
 @cindex repeats with ties
 @cindex alternative endings with ties
 
 @cindex repeats with ties
 @cindex alternative endings with ties


@@ -155,7 +245,7 @@ Ties may be added to a second ending:
 
 @lilypond[verbatim,quote,relative=2]
 c1
 
 @lilypond[verbatim,quote,relative=2]
 c1

-\repeat volta 2 { c4 d e f ~ }
+\repeat volta 2 { c4 d e f~ }

 \alternative {
   { f2 d }
   { f2\repeatTie f, }
 \alternative {
   { f2 d }
   { f2\repeatTie f, }


@@ -170,6 +260,8 @@ c1
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {adding-volta-brackets-to-additional-staves.ly}
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {adding-volta-brackets-to-additional-staves.ly}
 

+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{setting-the-double-repeat-default-for-volte.ly}

 
 @seealso
 Music Glossary:
 
 @seealso
 Music Glossary:


@@ -178,7 +270,8 @@ Music Glossary:
 
 Notation Reference:
 @ref{Bar lines},
 
 Notation Reference:
 @ref{Bar lines},

-@ref{Modifying context plug-ins}.
+@ref{Modifying context plug-ins},
+@ref{Time administration}.

 
 Snippets:
 @rlsr{Repeats}.
 
 Snippets:
 @rlsr{Repeats}.


@@ -202,6 +295,16 @@ Internals Reference:
 @cindex repeat and slur
 @cindex slur and repeat
 
 @cindex repeat and slur
 @cindex slur and repeat
 

+Slurs that span from a @code{\repeat} block into an
+@code{\alternative} block will only work for the first alternate
+ending.  Also, slurs cannot wrap around from the end of one
+alternative back to the beginning of the repeat.
+
+If a repeat that begins with an incomplete measure has an
+@code{\alternative} block that contains modifications to the
+@code{measureLength} property, using @code{\unfoldRepeats} will
+result in wrongly-placed bar lines and bar check warnings.
+

 A nested repeat like
 
 @example
 A nested repeat like
 
 @example


@@ -211,17 +314,11 @@ A nested repeat like
 @end example
 
 @noindent
 @end example
 
 @noindent

-is ambiguous, since it is is not clear to which @code{\repeat} the
+is ambiguous, since it is not clear to which @code{\repeat} the

 @code{\alternative} belongs.  This ambiguity is resolved by always
 having the @code{\alternative} belong to the inner @code{\repeat}.
 For clarity, it is advisable to use braces in such situations.
 
 @code{\alternative} belongs.  This ambiguity is resolved by always
 having the @code{\alternative} belong to the inner @code{\repeat}.
 For clarity, it is advisable to use braces in such situations.
 

-Timing information is not remembered at the start of an alternative,
-so after a repeat timing information must be reset by hand; for
-example, by setting @code{Score.measurePosition} or entering
-@code{\partial}.  Similarly, slurs are also not repeated.
-
-

 
 @node Manual repeat marks
 @unnumberedsubsubsec Manual repeat marks
 
 @node Manual repeat marks
 @unnumberedsubsubsec Manual repeat marks


@@ -241,7 +338,7 @@ example, by setting @code{Score.measurePosition} or entering
 
 @warning{These methods are only used for displaying unusual repeat
 constructs, and may produce unexpected behavior.  In most cases,
 
 @warning{These methods are only used for displaying unusual repeat
 constructs, and may produce unexpected behavior.  In most cases,

-repeats should be created using the standard @code{\\repeat} command
+repeats should be created using the standard @code{@bs{}repeat} command

 or by printing the relevant bar lines.  For more information, see
 @ref{Bar lines}.}
 
 or by printing the relevant bar lines.  For more information, see
 @ref{Bar lines}.}
 


@@ -365,26 +462,70 @@ where @var{musicexpr} is a music expression and @var{repeatcount} is
 the number of times @var{musicexpr} is repeated.
 
 @lilypond[verbatim,quote,relative=2]
 the number of times @var{musicexpr} is repeated.
 
 @lilypond[verbatim,quote,relative=2]

+\repeat unfold 2 { c4 d e f }

 c1
 c1

+@end lilypond
+
+Unfold repeats can be made with alternate endings.
+
+@lilypond[verbatim,quote,relative=2]

 \repeat unfold 2 { c4 d e f }
 \repeat unfold 2 { c4 d e f }

+\alternative {
+  { c2 g' }
+  { c,2 b }
+}
+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
 @end lilypond
 
 c1
 @end lilypond
 

-Unfold repeats can be made with alternate endings.  If there are
-more repeats than there are alternate endings, the first
-alternative ending is applied to the earliest endings.
+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.

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

+\repeat unfold 2 { c4 d e f }
+\alternative {
+  { c2 g' }
+  { c,2 b }
+  { e2 d }
+}

 c1
 c1

-\repeat unfold 2 { g4 f e d }
+@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 {
   \alternative {

-    { cis2 g' }
-    { cis,2 b }
+    { c2 g' }
+    { c,2 b }

   }
   }

+}

 c1
 @end lilypond
 
 
 c1
 @end lilypond
 
 

+@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
 Snippets:
 @rlsr{Repeats}.
 @seealso
 Snippets:
 @rlsr{Repeats}.


@@ -398,8 +539,8 @@ Internals Reference:
 @subsection Short repeats
 
 This section discusses how to input short repeats.  Short repeats can
 @subsection Short repeats
 
 This section discusses how to input short repeats.  Short repeats can

-take two basic forms: repeats of a single note to two measures,
-represented by slashes or percent signs; and tremolos.
+take two forms: slashes or percent signs to represent repeats of a
+single note, a single measure or two measures, and tremolos otherwise.

 
 @menu
 * Percent repeats::
 
 @menu
 * Percent repeats::


@@ -417,10 +558,10 @@ represented by slashes or percent signs; and tremolos.
 @funindex \repeat percent
 @funindex percent
 
 @funindex \repeat percent
 @funindex percent
 

-Repeated short patterns of notes are supported.  The music is printed
-once, and the pattern is replaced with a special sign.  Patterns that
-are shorter than one measure are replaced by slashes, and patterns of
-one or two measures are replaced by percent-like signs.  The syntax is
+Repeated short patterns are printed once, and the repeated pattern
+is replaced with a special sign.
+
+The syntax is

 
 @example
 @code{\repeat percent @var{number} @var{musicexpr}}
 
 @example
 @code{\repeat percent @var{number} @var{musicexpr}}


@@ -429,10 +570,23 @@ one or two measures are replaced by percent-like signs.  The syntax is
 @noindent
 where @var{musicexpr} is a music expression.
 
 @noindent
 where @var{musicexpr} is a music expression.
 

+Patterns that are shorter than one measure are replaced by slashes.
+

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

+\repeat percent 4 { c8 d }

 \repeat percent 4 { c4 }
 \repeat percent 4 { c4 }

-\repeat percent 2 { b4 a g f }
-\repeat percent 2 { c2 es | f4 fis g c | }
+\repeat percent 2 { c2 }
+@end lilypond
+
+Patterns of one or two measures are replaced by percent-like signs.
+
+@lilypond[verbatim,quote,relative=2]
+\repeat percent 3 { c4 d e f }
+\repeat percent 4 { c2 d }
+@end lilypond
+
+@lilypond[verbatim,quote,relative=2]
+\repeat percent 3 { c4 d e f | c2 g' }

 @end lilypond
 
 @snippets
 @end lilypond
 
 @snippets


@@ -486,7 +640,7 @@ durations, are supported.
 @funindex tremolo
 
 Tremolos can take two forms: alternation between two chords or two
 @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
 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


@@ -549,7 +703,3 @@ Snippets:
 @cindex tremolo, cross-staff
 @cindex cross-staff tremolo
 
 @cindex tremolo, cross-staff
 @cindex cross-staff tremolo
 

-@knownissues
-
-Cross-staff tremolos do not work well.
-