Merge branch 'master' of /home/lilydev/git/lily/

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

@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    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.
@end ignore

@c \version "2.11.38"

@node Repeats
@section Repeats

@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
{repeats-headword.ly}

Repetition is a central concept in music, and multiple notations
exist for repetitions. LilyPond supports the following kinds of repeats:


@table @code
@item volta
The repeated music is not written out but enclosed between repeat bar
lines.  If the repeat is at the beginning of a piece, a repeat bar
line is only printed at the end. Alternative endings (volte) are
printed left to right with brackets.  This is the standard 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
entering repetitious music. 

@item percent
These are beat or measure repeats.  They look like single slashes or
percent signs.

@item tremolo
This is used to write tremolo beams.

@end table


@menu
* Long repeats::                
* Short repeats::               
@end menu

@node Long repeats
@subsection Long repeats

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 can also be controlled manually.

@menu
* Normal repeats::              
* Manual repeat marks::         
* Written-out repeats::  
@end menu

@cindex volta
@cindex prima volta
@cindex seconda volta
@cindex volta, prima
@cindex volta, seconda
@funindex \repeat

@node Normal repeats
@subsubsection Normal repeats

The syntax for a normal repeat is

@example
\repeat volta @var{repeatcount} @var{musicexpr}
@end example

where @var{musicexpr} is a music expression.  Alternate endings can be
produced using @code{\alternative}.  If there are more repeats than
there are alternate endings, the earliest repeats are given the first
alternative.

Normal repeats without alternate endings:

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\repeat volta 2 { c4 d e f }
c2 d
\repeat volta 2 { d4 e f g }
@end lilypond

Normal repeats with alternate endings:

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\repeat volta 2 { g4 f e d }
  \alternative {
    { cis2 g' }
    { cis,2 b }
  }
\repeat volta 3 { c4 d e f }
  \alternative {
    { d2 e }
    { f2 g }
  }
c1
@end lilypond


Repeats with upbeats can be entered in two ways:

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\new Staff {
  \partial 4
  e |
  \repeat volta 4 { c2 d | e2 f | }
  \alternative {
    { g4 g g e }
    { a4 a a a | b2. }
  }
}
@end lilypond

@noindent
or

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\new Staff {
  \partial 4 
  \repeat volta 4 { e4 | c2 d | e2 f | }
  \alternative {
    { \partial 4*3 g4 g g }
    { a4 a a a | b2. }
  }
}
@end lilypond


@funindex \repeatTie

Ties may be added to a second ending:

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
c1
\repeat volta 2 {c4 d e f ~ }
\alternative {
  {f2 d}
  {f2\repeatTie f,}
}
@end lilypond

@snippets

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
{shortening-volta-brackets.ly}

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
{adding-volta-brackets-to-additional-staves.ly}


@c Is there a way to have a final bar ("|.") at the end of the
@c previous line? Doesn't seem to be.
@c It could be done by overriding
@c the BreakAlignment property. Want a separate example?
If you want to start a repeat at the beginning of a line and have a
double bar at the end of the previous line, use @code{\bar}. For more
information, see @ref{Bar lines}.

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
c4 c c c
\bar "||:" \break 
\repeat volta 2 { c4 d e f }   
@end lilypond


@seealso

Music Glossary: @rglos{repeat}, @rglos{volta}.

Notation Reference: @ref{Bar lines}, @ref{Modifying context plug-ins}.

Snippets: @rlsr{Repeats}.

Internals Reference: @rinternals{VoltaBracket},
@rinternals{RepeatedMusic}, @rinternals{VoltaRepeatedMusic},
@rinternals{UnfoldedRepeatedMusic}.

@knownissues

@cindex repeat, ambiguous

A nested repeat like

@example
\repeat @dots{}
\repeat @dots{}
\alternative
@end example

@noindent
is ambiguous, since it is 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.

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
@subsubsection Manual repeat marks

@funindex repeatCommands

In some cases, manual repeat marks can be created by simply
printing the relevant bar lines.  For more information, see
@ref{Bar lines}.

The property @code{repeatCommands} can be used to control the
layout of repeats.  Its value is a Scheme list of repeat commands.

@table @asis
@item @code{start-repeat}
Print a @code{|:} bar line:

@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
c1
\set Score.repeatCommands = #'( start-repeat )
d4 e f g
c1
@end lilypond

In order to print a @code{|:} bar line at the beginning of a piece,
the @code{BreakAlignment} property must be overridden:

@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
\once \override Score.BreakAlignment #'break-align-orders =
#(make-vector 3 '(
instrument-name
left-edge
ambitus
span-bar
breathing-sign
clef
key-signature
time-signature
staff-bar
custos
span-bar
))
\bar "|:"
c1
d1
d4 e f g
@end lilypond

@item @code{end-repeat}
Print a @code{:|} bar line:

@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
c1
d4 e f g
\set Score.repeatCommands = #'( end-repeat )
c1
@end lilypond

@item @code{(volta #f)}
Stop a running volta bracket.

@c FIXME: example?
@c TODO: Modify and insert <Test volta.ly>.

@item @code{(volta @var{number})}
Change the volta number.

FIXME: simple example?
@c Test volta text.ly works

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

@c @end lilypond

@end table

@c FIXME: Should this be a ``selected snippet''?
@c TODO: the example will be fixed.

By using Scheme, @var{text} can be included with the volta
bracket.  The text can be a number or numbers or markup text, see
@ref{Formatting text}.  The simplest way to use markup text is to
define the markup first, then include the the markup in a Scheme
list. When manually creating a volta bracket, the bracket must be
explicitly terminated or an error will be generated.

Manual control of the volte, including a @code{|:} bar line at the
beginning and explicit volta numbers:

@lilypond[verbatim,quote,relative=2]
@c FIXME: I can't believe this is right.  
@c TODO: I think it is. I plan
@c to delete this example, since it's
@c already been given at L238. rp
s1*1/10
\set Score.repeatCommands = #'( start-repeat )
c1*9/10
d4 e f g
\set Score.repeatCommands = #'( ( volta "1, 2, 5" ) )
f4 g a b
\set Score.repeatCommands = #'( ( volta #f ) ( volta "95" ) end-repeat )
g4 a g a
\set Score.repeatCommands = #'( ( volta #f ) )
c1
@end lilypond

Manual control of the volte, including markup text:

@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
c1
\set Score.repeatCommands = #'( start-repeat )
d1
d4 e f g
% FIXME: broken
%\set Score.repeatCommands = #(list (list 'volta voltaChorus ) )
f4 g a b
\set Score.repeatCommands = #'( ( volta #f ) ( volta "4" ) end-repeat )
g4 a g a
\set Score.repeatCommands = #'( ( volta #f ) )
c1
@end lilypond 

@seealso

Notation Reference:
@ref{Bar lines},
@ref{Formatting text}.

Snippets:
@rlsr{Repeats}.

Internals Reference:
@rinternals{VoltaBracket},
@rinternals{RepeatedMusic},
@rinternals{VoltaRepeatedMusic}.


@node Written-out repeats
@subsubsection Written-out repeats

@cindex written-out repeats
@cindex repetitious music
@cindex repeats, written-out

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

where @var{musicexpr} is a music expression.  Unfold repeats can be
made with or without alternate endings.  If there are more repeats
than there are alternate endings, the first alternative ending is
applied to the earliest endings.  Unfold repeats without alternate
endings:

@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
c1
\repeat unfold 2 { c4 d e f }
c1
@end lilypond

Unfold repeats with alternate endings:

@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
c1
\repeat unfold 2 { g4 f e d }
  \alternative {
    { cis2 g' }
    { cis,2 b }
  }
c1
\repeat unfold 3 { d4 c b2 }
  \alternative {
    { c4 d e f }
    { d4 c b a }
  }
c1
@end lilypond

@seealso

Snippets: @rlsr{Repeats}.

Internals Reference: @rinternals{RepeatedMusic},
@rinternals{UnfoldedRepeatedMusic}.

@node Short repeats
@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.

@menu
* Percent repeats::             
* Tremolo repeats::             
@end menu

@node Percent repeats
@subsubsection Percent repeats

@cindex percent repeats
@cindex measure repeats

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

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

where @var{musicexpr} is a music expression. 

@lilypond[quote,verbatim,ragged-right]
\relative c' {
  \repeat percent 4 { c4 }
  \repeat percent 2 { b'4 a g f }
  \repeat percent 2 { c2 es | f4 fis g c | }
}
@end lilypond

Measure repeats of more than two repeats get a counter if you switch
on the @code{countPercentRepeats} property:

@lilypond[relative=2,fragment,quote,verbatim,ragged-right]
\relative c' {
  \set countPercentRepeats = ##t
  \repeat percent 4 { c1 }
}
@end lilypond


Isolated percents can also be printed.  This is done by entering a
multi-measure rest with a different print function:

@lilypond[fragment,verbatim,quote]
\override MultiMeasureRest #'stencil
  = #ly:multi-measure-rest::percent
R1
@end lilypond


@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.


@seealso

Music Glossary: @rglos{percent repeat}, @rglos{simile}.

Snippets: @rlsr{Repeats}.

Internals Reference: @rinternals{RepeatSlash},
@rinternals{PercentRepeat}, @rinternals{DoublePercentRepeat},
@rinternals{DoublePercentRepeatCounter},
@rinternals{PercentRepeatCounter}, @rinternals{PercentRepeatedMusic}.

@node Tremolo repeats
@subsubsection Tremolo repeats

Tremolos can take two forms: alternation between two chords or two
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 slashes to a single note.

@cindex tremolo beams

To place tremolo marks between notes, use @code{\repeat} with
tremolo style:

@lilypond[quote,verbatim,ragged-right]
\relative c' {
  \repeat tremolo 8 { c16 d }
  \repeat tremolo 4 { c16 d }
  \repeat tremolo 2 { c16 d }
}
@end lilypond

The @code{\repeat tremolo} syntax expects exactly two notes within
the braces, and the number of repetitions must correspond to a
note value that can be expressed with plain or dotted notes.  Thus,
@code{\repeat tremolo 7} is valid and produces a double dotted
note, but @code{\repeat tremolo 9} is not.

The duration of the tremolo equals the duration of the
braced expression multiplied by the number of repeats:
@code{\repeat tremolo 8 @{ c16 d16 @}} gives a whole note tremolo,
notated as two whole notes joined by tremolo beams. 

There are two ways to put tremolo marks on a single note.  The
@code{\repeat tremolo} syntax is also used here, in which case
the note should not be surrounded by braces:

@lilypond[quote,verbatim,ragged-right]
\repeat tremolo 4 c'16
@end lilypond

@cindex tremolo marks
@funindex tremoloFlags

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

@lilypond[quote,ragged-right,verbatim,fragment]
c'2:8 c':32 | c': c': |
@end lilypond


@knownissues


Tremolos entered with @q{@code{:}[@var{number}]} do not carry over
into the MIDI output.


@seealso

Snippets: @rlsr{Repeats}.