Update from Ralph.

[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 percent signs.
Percent repeats must be declared within a @code{Voice} context.

@item tremolo
This is used to write tremolo beams.

@end table

@ignore
LilyPond has one syntactic construct for specifying different
types of repeats.  The syntax is

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

where @var{musicexpr} is a music expression.


Alternative endings are entered with 
@funindex \alternative
@example
\alternative @{
  @var{alternative1}
  @var{alternative2}
  @var{alternative3}
  @dots{}
@}
@end example

@noindent
after a @code{\repeat volta} or @code{unfold} block, where each
@var{alternative} is a music expression.  If you give fewer
alternatives than @var{repeatcount}, the first alternative is assumed
to be played more than once.
@end ignore


@menu
* Writing long repeats::        
* Short repeats::               
@end menu

@node Writing long repeats
@subsection Writing long repeats

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

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 }
  }
c1
@end lilypond


Repeats with upbeats:

@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]
{shortening-volta-brackets.ly}

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
{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.
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: @lsrdir{Repeats,Repeats}.

Internals Reference: @internalsref{VoltaBracket},
@internalsref{RepeatedMusic}, @internalsref{VoltaRepeatedMusic},
@internalsref{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 or ties are also not repeated.



@node Manual repeat marks
@subsubsection Manual repeat marks

@funindex repeatCommands

@c FIXME: Markup does not work in the "text" field
@c And how does one change the font?
@c On the whole, this section needs better documentation (why the
@c double parentheses around the volta expressions?)

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.

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

@item @code{(volta @var{text})}
Print a volta bracket saying @var{text}.  The text can be specified as
a text string or as a markup text; see @ref{Formatting text}.  Do not
forget to change the font, as the default number font does not contain
alphabetic characters.


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

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

@c FIXME: improve visibility of bar lines link?

@seealso

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

Snippets: @lsrdir{Repeats,Repeats}.

Internals Reference: @internalsref{VoltaBracket},
@internalsref{RepeatedMusic}, @internalsref{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.

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
@end lilypond

@seealso

Snippets: @lsrdir{Repeats,Repeats}.

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

@node Short repeats
@subsection Short repeats

@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 also supported.  The music is
printed once, and the pattern is replaced with a special sign.
Patterns of one and two measures are replaced by percent-like signs,
patterns that are shorter than one measure are replaced by slashes.
Percent repeats must be declared within a @code{Voice} context.  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]
\new Voice \relative c' {
  \repeat percent 4 { c4 }
  \repeat percent 2 { b4 a g f }
  \repeat percent 2 { c2 es | f4 fis g c | }
}
@end lilypond

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

@lilypond[relative=2,fragment,quote,verbatim,ragged-right]
\new Voice {
  \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


@seealso

Snippets: @lsrdir{Repeats,Repeats}.

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

@node Tremolo repeats
@subsubsection Tremolo repeats

@cindex tremolo beams

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

@lilypond[quote,verbatim,ragged-right]
\new Voice \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

Music Glossary: @rglos{tremolo}.

Notation Reference: @ref{Tremolo repeats}.

Internals Reference: @internalsref{Beam}, @internalsref{StemTremolo}.

Snippets: @lsrdir{Repeats,Repeats}.