Rename macros to better indicate the output.

[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

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

@menu
* Writing repeats::             
* Other repeats::               
@end menu

@node Writing repeats
@subsection Writing repeats

This section discusses how to write repeats, including repeated
sections of music enclosed within repeat bars, alternate repeat
endings, tremolos, and beat or measure repeats.

@menu
* Repeat syntax::               
* Normal repeats::              
* Manual repeat commands::      
@end menu


@node Repeat syntax
@subsubsection Repeat syntax

@cindex repeats
@cindex repeat syntax
@cindex syntax, repeat

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

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

where @var{repeabody} is a music expression.

The following types of repetition are supported

@cindex repeat volta
@cindex volta

@table @code
@item volta
The repeated music is not written out but enclosed in 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.

@cindex repetitious music

@item unfold
The repeated music is fully written out, as many times as
specified by @var{repeatcount}.  This is useful when
entering repetitious music. 

@cindex tremolo
@cindex tremolo beams
@cindex beams, tremolo

@item tremolo
Make tremolo beams.

@cindex beat repeat
@cindex measure repeat
@cindex percent sign, for repeat

@item percent
Make beat or measure repeats.  These look like percent signs.
Percent repeats must be declared within a @code{Voice} context.

@end table

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
less alternatives than @var{repeatcount}, the first alternative
is assumed to be played more than once.


@node Normal repeats
@subsubsection Normal repeats

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

Normal repeats, with or without alternate repeats:

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\repeat volta 2 { c4 d e f }
\repeat volta 2 { g 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 d2 | e2 f2 | }
  \alternative { { g4 g g e } { a a a a | b2. } }
}
@end lilypond

@noindent
or

@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
\new Staff {
  \partial 4 
  \repeat volta 4 { e | c2 d2 | e2 f2 | }
  \alternative { { \partial 4*3 g4 g g } { a 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} {f\repeatTie f,} }
@end lilypond

By default, the volta brackets will be drawn over all of the
alternative music, but it is possible to shorten them by
setting @code{voltaSpannerDuration}.  In the next example, the
bracket only lasts one measure, which is a duration of 3/4.

@lilypond[verbatim,ragged-right,quote]
\relative c''{
  \time 3/4
  c c c
  \set Score.voltaSpannerDuration = #(ly:make-moment 3 4)
  \repeat volta 5 { d d d }
  \alternative { { e e e f f f }
  { g g g } }
}
@end lilypond

The @code{Volta_engraver} by default resides in the Score context,
and brackets for the repeat are thus normally only printed over
the topmost staff.  This can be adjusted by adding
@code{Volta_engraver} to the Staff context where you want the
brackets to appear; see @ref{Modifying context plug-ins} and
@c @lsr{repeats,volta@/-multi@/-staff@/.ly}.

@lilypond[verbatim,ragged-right,quote]
\score { <<
  \new Staff { \repeat volta 2 { c'1 } \alternative { c' } }
  \new Staff { \repeat volta 2 { c'1 } \alternative { c' } }
  \new Staff \with { \consists Volta_engraver } { c'2 g' e' a' }
  \new Staff { \repeat volta 2 { c'1 } \alternative { c' } }
 >> }
@end lilypond

@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

@example
@dots{} \bar "||:" \break 
\repeat volta 2 @{ @dots{} 
@end example

see @ref{Bar lines} for more information.

@seealso

Snippets: @lsrdir{Repeats,Repeats}

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

@c Examples:


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

@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{Text
markup}.  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 c4
  \set Score.repeatCommands = #'((volta #f))
c4 c4
@end lilypond

@c FIXME: improve visibility of bar lines link?

@seealso

Notation Reference: @ref{Bar lines}.

Snippets: @lsrdir{Repeats,Repeats}

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


@node Other repeats
@subsection Other repeats

@menu
* Tremolo repeats::             
* Measure repeats::             
@end menu

@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 d16 }
  \repeat tremolo 4 { c16 d16 }
  \repeat tremolo 2 { c16 d16 }
}
@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 can be used even 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

Notation Reference: @ref{Tremolo repeats}.

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

Snippets: @lsrdir{Repeats,Repeats}

Elsewhere: @internalsref{StemTremolo}.


@node Measure repeats
@subsubsection Measure repeats

@cindex percent repeats
@cindex measure repeats

A note pattern can be repeated with the @code{\repeat percent
@var{number}} syntax.  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 divide the
measure length are replaced by slashes.  Percent repeats must be
declared within a @code{Voice} context.

@lilypond[quote,verbatim,ragged-right]
\new Voice \relative c' {
  \repeat percent 4 { c4 }
  \repeat percent 2 { c2 es2 f4 fis4 g4 c4 }
}
@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}.