Merge branch 'master' into lilypond/translation

[lilypond.git] / Documentation / user / staff.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.51"

@node Staff notation
@section Staff notation

@lilypondfile[quote]{staff-headword.ly}

This section explains how to influence the staff appearance, print
scores with more than one staff, and how to apply specific
performance marks to single staves.

@menu
* Displaying staves::
* Modifying single staves::
* Writing parts::
@end menu


@node Displaying staves
@subsection Displaying staves

This section shows the different possibilities of creating and
grouping staves, which are marked at the beginning of each line
with either a bracket or a brace.

@menu
* Instantiating new staves::
* Grouping staves::
* Deeper nested staff groups::
@end menu

@node Instantiating new staves
@unnumberedsubsubsec Instantiating new staves

@cindex new staff
@cindex staff initiation
@cindex staff instantiation
@cindex staff, new
@cindex staff, single
@cindex drum staff
@cindex percussion staff
@cindex Gregorian transcription staff
@cindex rhythmic staff
@cindex tabstaff
@cindex tablature

@notation{Staves} (singular: @notation{staff}) are created with
the @code{\new} or @code{\context} commands.  For details, see
@ref{Creating contexts}.

The basic staff context is @code{Staff}:

@lilypond[verbatim,quote,relative=2]
\new Staff { c4 d e f }
@end lilypond

@code{DrumStaff} creates a five-line staff set up for a
typical drum set.  It uses different names for each instrument.
The instrument names are set using the @code{\drummode} command.
For details, see @ref{Percussion staves}.

@lilypond[verbatim,quote]
\new DrumStaff {
  \drummode { cymc hh ss tomh }
}
@end lilypond

@c FIXME: remove when mentioned in NR 2.8
@code{GregorianTranscriptionStaff} creates a staff to notate
modern Gregorian chant.  It does not show bar lines.

@lilypond[verbatim,quote,relative=2]
\new GregorianTranscriptionStaff { c4 d e f }
@end lilypond

@code{RhythmicStaff} creates a single-line staff that only
displays the rhythmic values of the input.  Real durations are
preserved. For details, see @ref{Showing melody rhythms}.

@lilypond[verbatim,quote,relative=2]
\new RhythmicStaff { c4 d e f }
@end lilypond

@code{TabStaff} creates a tablature with six strings in standard
guitar tuning.  For details, see @ref{Default tablatures}.

@lilypond[verbatim,quote,relative=2]
\new TabStaff { c4 d e f }
@end lilypond

There are two staff contexts specific for the notation of ancient
music: @code{MensuralStaff} and @code{VaticanaStaff}.  They are
described in @ref{Pre-defined contexts}.

Staves can be started or stopped at any point in the score.  The
commands @code{\startStaff} and @code{\stopStaff} are used for
this purpose.  For details, see @ref{Staff symbol}.


@seealso

Music Glossary:
@rglos{staff},
@rglos{staves}.

Notation Reference:
@ref{Creating contexts},
@ref{Percussion staves},
@ref{Default tablatures},
@ref{Gregorian chant contexts},
@ref{Mensural contexts},
@ref{Staff symbol},
@ref{Pre-defined contexts},
@ref{Showing melody rhythms}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{Staff},
@rinternals{DrumStaff},
@rinternals{GregorianTranscriptionStaff},
@rinternals{RhythmicStaff},
@rinternals{TabStaff},
@rinternals{MensuralStaff},
@rinternals{VaticanaStaff},
@rinternals{StaffSymbol}.


@node Grouping staves
@unnumberedsubsubsec Grouping staves

@cindex start of system
@cindex staff, multiple
@cindex staves, multiple
@cindex system start delimiters
@cindex bracket, vertical
@cindex brace, vertical
@cindex choir staff
@cindex grand staff
@cindex piano staff
@cindex staff group
@cindex staff, choir
@cindex staff, piano
@cindex system

Various contexts exist to group single staves together in order to
form multi-stave systems.  Each grouping context sets the style of
the system start delimiter and the behavior of bar lines.

If no context is specified, the default properties will be used:
the group is started with a vertical line, and the bar lines are
not connected.

@lilypond[verbatim,quote,relative=2]
<<
  \new Staff { c1 c }
  \new Staff { c1 c }
>>
@end lilypond

In the @code{StaffGroup} context, the group is started with a
bracket and bar lines are drawn through all the staves.

@lilypond[verbatim,quote,relative=2]
\new StaffGroup <<
  \new Staff { c1 c }
  \new Staff { c1 c }
>>
@end lilypond

In a @code{ChoirStaff}, the group starts with a bracket, but bar
lines are not connected.

@lilypond[verbatim,quote,relative=2]
\new ChoirStaff <<
  \new Staff { c1 c }
  \new Staff { c1 c }
>>
@end lilypond

In a @code{GrandStaff}, the group begins with a brace, and bar
lines are connected between the staves.

@lilypond[verbatim,quote,relative=2]
\new GrandStaff <<
  \new Staff { c1 c }
  \new Staff { c1 c }
>>
@end lilypond

The @code{PianoStaff} is almost identical to a @code{GrandStaff},
except that it supports printing the instrument name directly.
For details, see @ref{Instrument names}.

@lilypond[verbatim,quote,relative=2]
\new PianoStaff <<
  \set PianoStaff.instrumentName = "Piano"
  \new Staff { c1 c }
  \new Staff { c1 c }
>>
@end lilypond

Each staff group context sets the property
@code{systemStartDelimiter} to one of the following values:
@code{SystemStartBar}, @code{SystemStartBrace}, or
@code{SystemStartBracket}.  A fourth delimiter,
@code{SystemStartSquare}, is also available, but it must be
explicitly specified.


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{use-square-bracket-at-the-start-of-a-staff-group.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{display-bracket-with-only-one-staff-in-a-system.ly}

@cindex mensurstriche layout
@cindex renaissance music
@cindex transcription of mensural music
@cindex mensural music, transcription of

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{mensurstriche-layout-bar-lines-between-the-staves.ly}
@c FIXME: move to NR 2.8.x when sectioning is ready


@seealso

Music Glossary:
@rglos{brace},
@rglos{bracket},
@rglos{grand staff}.

Notation Reference:
@ref{Instrument names}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{Staff},
@rinternals{ChoirStaff},
@rinternals{GrandStaff},
@rinternals{PianoStaff},
@rinternals{StaffGroup},
@rinternals{SystemStartBar},
@rinternals{SystemStartBrace},
@rinternals{SystemStartBracket},
@rinternals{SystemStartSquare}.


@node Deeper nested staff groups
@unnumberedsubsubsec Deeper nested staff groups

@cindex staff, nested
@cindex staves, nested
@cindex nesting of staves
@cindex system start delimiters, nested
@cindex nested staff brackets
@cindex brackets, nesting of
@cindex braces, nesting of
@cindex inner staff group
@cindex inner choir staff group

Two additional staff-group contexts are available that can be
nested within a @code{StaffGroup} or @code{ChoirStaff} context:
@code{InnerStaffGroup} and @code{InnerChoirStaff}.  These contexts
create an additional bracket next to the original bracket of their
parent staff group.

An @code{InnerStaffGroup} is treated similarly to a
@code{StaffGroup}; bar lines are connected between each stave
within the context:

@lilypond[verbatim,quote,relative=2]
\new StaffGroup <<
  \new Staff { c2 c }
  \new InnerStaffGroup <<
    \new Staff { g2 g }
    \new Staff { e2 e }
  >>
>>
@end lilypond

Bar lines are @emph{not} connected between staves of an
@code{InnerChoirStaff}, just like a @code{ChoirStaff}:

@lilypond[verbatim,quote,relative=2]
\new ChoirStaff <<
  \new Staff { c2 c }
  \new InnerChoirStaff <<
    \new Staff { g2 g }
    \new Staff { e2 e }
  >>
  \new Staff { c1 }
>>
@end lilypond


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{nesting-staves.ly}


@seealso

Snippets:
@rlsr{Staff notation}.

Notation Reference:
@ref{Grouping staves},
@ref{Instrument names}.

Internals Reference:
@rinternals{InnerStaffGroup},
@rinternals{StaffGroup},
@rinternals{InnerChoirStaff},
@rinternals{ChoirStaff},
@rinternals{SystemStartBar},
@rinternals{SystemStartBrace},
@rinternals{SystemStartBracket}.


@node Modifying single staves
@subsection Modifying single staves

This section explains how to change specific attributes of one
staff: for example, modifying the number of staff lines or the
staff size.  Methods to start and stop staves and set ossia
sections are also described.

@menu
* Staff symbol::
* Ossia staves::
* Hiding staves::
@end menu


@node Staff symbol
@unnumberedsubsubsec Staff symbol

@cindex adjusting staff symbol
@cindex drawing staff symbol
@cindex staff symbol, setting of
@cindex stop staff lines
@cindex start staff lines
@cindex staff lines, amount of
@cindex staff lines, number of
@cindex staff line, thickness of
@cindex amount of staff lines
@cindex thickness of staff lines
@cindex ledger lines, setting
@cindex setting of ledger lines
@cindex spacing of ledger lines
@cindex number of staff lines

The grob @code{StaffSymbol} is responsible for drawing the lines
of a staff.  Its properties can be altered in order to change the
appearance of a staff, but they must be changed before the staff
is created.  A staff may be started or stopped at any point in the
score.

The number of staff lines may be changed.  The clef position and
the position of middle C may need to be modified to fit the new
staff.  For an explanation, refer to the snippet section in
@ref{Clef}.

@lilypond[verbatim,quote,relative=2]
\new Staff {
  \override Staff.StaffSymbol #'line-count = #3
  d4 d d d
}
@end lilypond

The vertical position of staff lines and the number of staff lines
can be defined at the same time.  As the example shows, the
positions of the notes are not influenced by the position of the
staff lines.  Details for modifying this property are found in
@rinternals{staff-symbol-interface}.

@warning{The @code{'line-positions} property overrides the
@code{'line-count} property.  The number of staff lines is
implicitly defined by the number of elements in the list of values
for @code{'line-positions}}

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
}
{ a4 e' f b | d1 }
@end lilypond

The staff line thickness can be modified.  The thickness of ledger
lines and stems are also affected, since they depend on staff line
thickness.

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'thickness = #3
}
{ e4 d c b }
@end lilypond

The thickness of ledger lines can be set independently of staff
line thickness.  A description of this property is also found in
@rinternals{staff-symbol-interface}.

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
}
{ e4 d c b }
@end lilypond

The distance between staff lines can be changed.  The setting has
influence on ledger lines as well.

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'staff-space = #1.5
}
{ a4 b c d }
@end lilypond

The width of a staff can be adjusted.  The unit is one staff
space.  The spacing of objects inside the staff is not influenced
by this setting.

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'width = #23
}
{ a4 e' f b | d1 }
@end lilypond

Modifications to staff properties in the middle of a score can be
placed between @code{\stopStaff} and @code{\startStaff}:

@lilypond[verbatim,quote,relative=2]
c2 c
\stopStaff
\override Staff.StaffSymbol #'line-count = #2
\startStaff
b2 b
\stopStaff
\revert Staff.StaffSymbol #'line-count
\startStaff
a2 a
@end lilypond


@predefined

@funindex \startStaff
@code{\startStaff},
@funindex \stopStaff
@code{\stopStaff}.


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{making-some-staff-lines-thicker-than-the-others.ly}


@seealso

Music Glossary:
@rglos{line},
@rglos{ledger line},
@rglos{staff}.

Notation Reference:
@ref{Displaying pitches}.

Internals Reference:
@rinternals{StaffSymbol},
@rinternals{staff-symbol-interface}.


@knownissues

When setting staff lines manually, bar lines are always drawn
centered on the position 0, so the maximum distance of the bar
lines in either direction must be equal.


@node Ossia staves
@unnumberedsubsubsec Ossia staves

@cindex staff, Frenched
@cindex ossia
@cindex Frenched staves
@cindex staff, resizing of
@cindex resizing of staves

Tweaking the staff object allows to resize the staff:

@lilypond[verbatim,quote]
\new Staff \with {
  fontSize = #-3
  \override StaffSymbol #'staff-space = #(magstep -3)
  \override StaffSymbol #'thickness = #(magstep -3)
}
\relative c {
  \clef bass
  c8 c c c  c c c c
}
@end lilypond

This involves shrinking the staff spaces, the staff lines and the
font size by the factor 3.  You find a more precise explanation in
@ref{Setting the staff size}.

The @emph{ossia} section in the next example are just put parallel
to the main staff with @code{<<} and @code{>>} brackets.  The
@emph{ossia} staff is stopped and started explicitely and white
space is inserted with the @code{\skip} command.

@lilypond[verbatim,quote]
<<
  \new Staff \with
  {
    %No time signature in the ossia staff
    \remove "Time_signature_engraver"
    fontSize = #-3
    \override StaffSymbol #'staff-space = #(magstep -3)
    \override StaffSymbol #'thickness = #(magstep -3)
    firstClef = ##f
  }
  \relative c'' {
    \stopStaff
    \skip 2

    \startStaff
    \clef treble
    bes8[^"ossia" g bes g]
    \stopStaff

    s2

    \startStaff
    f8 d g4
  }
  \new Staff \relative c'' {
    \time 2/4
    c4 c g' g a a g2
  }
>>
@end lilypond


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{vertically-aligning-ossias-and-lyrics.ly}


@seealso

Music Glossary:
@rglos{ossia},
@rglos{staff},
@rglos{Frenched staff}.

Learning Manual:
@rlearning{Nesting music expressions},
@rlearning{Size of objects},
@rlearning{Length and thickness of objects}.

Notation Reference:
@ref{Setting the staff size}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{StaffSymbol}.


@node Hiding staves
@unnumberedsubsubsec Hiding staves

@cindex Frenched scores
@cindex staff, hiding
@cindex staff, empty
@cindex hiding of staves
@cindex empty staves
@cindex Frenched staves

In orchestral scores, staff lines that only have rests are usually
removed; this saves some space.  This style is called @q{French
Score}.  For the @code{Lyrics}, @code{ChordNames}, and
@code{FiguredBass} contexts, this is switched on by default.  When
the lines of these contexts turn out empty after the line-breaking
process, they are removed.

For normal staves this behaviour is called with the
@code{\RemoveEmptyStaffContext} command.  It is set in the
@code{\layout} block.  As a result staves containing nothing or
whole mesure rests are removed after a line break.

@lilypond[verbatim,quote]
\layout {
  \context {
    \RemoveEmptyStaffContext
  }
}
\relative c'' {
  <<
    \new Staff { e4 f g a \break c1 }
    \new Staff { c4 d e f \break R1 }
  >>
}
@end lilypond

To remove other types of contexts, use
@code{\AncientRemoveEmptyStaffContext} or
@code{\RemoveEmptyRhythmicStaffContext}.

@cindex ossia

@c FIXME Really? I need to see about this.  -pm

Another application of the @code{\RemoveEmptyStaffContext} is to
make ossia sections, i.e., alternative melodies on a separate
piece of staff, with help of a Frenched staff.  See
@ref{Ossia staves}.

@c FIXME Is this in the right section?
@c maybe move to Staff symbol -pm

You can make the staff lines invisible by removing the
@code{Staff_symbol_engraver} from the @code{Staff} context.

@lilypond[verbatim,quote]
\score {
  \new Staff \relative c'' { c8 c c16 c c c }
  \layout{
    \context {
      \Staff
      \remove Staff_symbol_engraver
    }
  }
}
@end lilypond


@snippets

The first empty staff can also be removed from the score with a
setting in the @code{VerticalAxisGroup} property.  This can be
done globally inside the @code{\layout} block, or locally inside
the specific staff that should be removed. In the latter case, you
have to specify the context (@code{Staff} applies only to the
current staff) in front of the property.

The lower staff of the second staff group is not removed, because
the setting applies only to the specific staff inside of which it
is written.

@lilypond[verbatim,quote]
\layout {
  \context {
    \RemoveEmptyStaffContext
    %To use the setting globally, uncomment the following line:
    %\override VerticalAxisGroup #'remove-first = ##t
  }
}
\new StaffGroup
  \relative c'' <<
    \new Staff {
      e4 f g a \break c1 }
    \new Staff {
      %To use the setting globally, comment this line, uncomment the line above
      \override Staff.VerticalAxisGroup #'remove-first = ##t
      R1 \break R1 }
  >>
\new StaffGroup
  <<
    \new Staff { e4 f g a \break c1 }
    \new Staff { R \break R1 }
  >>
@end lilypond

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{removing-the-first-empty-line.ly}


@predefined

@funindex \RemoveEmptyStaffContext
@code{\RemoveEmptyStaffContext},
@funindex \AncientRemoveEmptyStaffContext
@code{\AncientRemoveEmptyStaffContext},
@funindex \RemoveEmptyRhythmicStaffContext
@code{\RemoveEmptyRhythmicStaffContext}.


@seealso

Notation Reference:
@ref{Staff symbol},
@ref{Ossia staves}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{ChordNames},
@rinternals{FiguredBass},
@rinternals{Lyrics},
@rinternals{Staff},
@rinternals{VerticalAxisGroup}.


@node Writing parts
@subsection Writing parts

@menu
* Metronome marks::
* Instrument names::
* Quoting other voices::
* Formatting cue notes::
@end menu


@node Metronome marks
@unnumberedsubsubsec Metronome marks

@cindex tempo
@cindex beats per minute
@cindex metronome marking

Metronome settings can be entered as follows

@example
\tempo @var{duration} = @var{per-minute}
@end example

In the MIDI output, they are interpreted as a tempo change.  In
the layout output, a metronome marking is printed

@funindex \tempo

@lilypond[verbatim,quote,relative=2]
\tempo 8. = 120
c1
@end lilypond


@snippets

To change the tempo in the MIDI output without printing anything,
make the metronome marking invisible @example \once \override
Score.MetronomeMark #'transparent = ##t @end example

To print other metronome markings, use these markup commands
@lilypond[verbatim,quote,relative=1]
c4^\markup {
  (
  \smaller \general-align #Y #DOWN \note #"16." #1
  =
  \smaller \general-align #Y #DOWN \note #"8" #1
  ) }
@end lilypond

For more details, see @ref{Formatting text}.


@seealso

Music Glossary:
@rglos{metronome},
@rglos{metronomic indication},
@rglos{tempo indication},
@rglos{metronome mark}.

Notation Reference:
@ref{Formatting text},
@ref{MIDI output}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{MetronomeMark}.


@knownissues

Collisions are not checked.  If you have notes above the top line
of the staff (or notes with articulations, slurs, text, etc), then
the metronome marking may be printed on top of musical symbols.
If this occurs, increase the padding of the metronome mark to
place it further away from the staff.

@example
\override Score.MetronomeMark #'padding = #2.5
@end example

@c perhaps also an example of how to move it horizontally?


@node Instrument names
@unnumberedsubsubsec Instrument names

@cindex instrument names
@cindex instrument names, short

In an orchestral score, instrument names are printed at the left
side of the staves.

This can be achieved by setting @code{Staff}.@code{instrumentName}
and @code{Staff}.@code{shortInstrumentName}, or
@code{PianoStaff}.@code{instrumentName} and
@code{PianoStaff}.@code{shortInstrumentName}.  This will print
text before the start of the staff.  For the first staff,
@code{instrumentName} is used.  If set, @code{shortInstrumentName}
is used for the following staves.

@lilypond[verbatim,quote,relative=1]
\set Staff.instrumentName = "Ploink "
\set Staff.shortInstrumentName = "Plk "
c1
\break
c''1
@end lilypond

Markup mode can be used to create more complicated instrument
names:

@lilypond[verbatim,quote,relative=2]
\set Staff.instrumentName = \markup {
  \column { "Clarinetti"
            \line { "in B" \smaller \flat } } }
c1
@end lilypond

@cindex instrument names, centering

As instrument names are centered by default, multi line names are
better entered using @code{\center-align}:

@lilypond[verbatim,quote,relative=2]
<<
  \new Staff {
    \set Staff.instrumentName = \markup \center-align {
      Clarinetti
      \line { "in B" \smaller \flat }
    }
    c1
  }
  \new Staff {
    \set Staff.instrumentName = "Vibraphone"
    c1
  }
>>
@end lilypond

For longer instrument names, it may be useful to increase the
@code{indent} setting in the @code{\layout} block.

Short instrument names, printed before the systems following the
first one, are also centered by default, in a space which width is
given by the @code{short-indent} variable of the @code{\layout}
block.

To add instrument names to other contexts (such as
@code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
engraver must be added to that context.

@example
\layout@{
  \context @{\GrandStaff \consists "Instrument_name_engraver"@}
@}
@end example

@noindent
More information about adding and removing engravers can be found
in @ref{Modifying context plug-ins}.

@cindex instrument names, changing

Instrument names may be changed in the middle of a piece:

@lilypond[verbatim,quote,relative=1]
\set Staff.instrumentName = "First"
\set Staff.shortInstrumentName = "one"
c1 c c c \break
c1 c c c \break
\set Staff.instrumentName = "Second"
\set Staff.shortInstrumentName = "two"
c1 c c c \break
c1 c c c \break
@end lilypond


@seealso

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

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{InstrumentName},
@rinternals{PianoStaff},
@rinternals{Staff}.


@node Quoting other voices
@unnumberedsubsubsec Quoting other voices

@cindex cues
@cindex quoting other voices
@cindex fragments
@cindex cue notes

With quotations, fragments of other parts can be inserted into a
part directly.  Before a part can be quoted, it must be marked
especially as quotable.  This is done with the @code{\addQuote}
command.

@example
\addQuote @var{name} @var{music}
@end example

@noindent
Here, @var{name} is an identifying string.  The @var{music} is any
kind of music.  Here is an example of @code{\addQuote}

@example
\addQuote clarinet \relative c' @{
  f4 fis g gis
@}
@end example

This command must be entered at toplevel, i.e., outside any music
blocks.  Typically, one would use an already defined music event
as the @var{music}:

@example
clarinet = \relative c' @{
  f4 fis g gis
@}
\addQuote clarinet @{ \clarinet @}
@end example

After calling @code{\addQuote}, the quotation may then be done
with @code{\quoteDuring} or @code{\cueDuring},

@example
\quoteDuring #@var{name} @var{music}
@end example

During a part, a piece of music can be quoted with the
@code{\quoteDuring} command.

@example
\quoteDuring #"clarinet" @{ s2. @}
@end example

This would cite three quarter notes (the duration of @code{s2.})
of the previously added @code{clarinet} voice.

More precisely, it takes the current time-step of the part being
printed, and extracts the notes at the corresponding point of the
@code{\addQuote}d voice.  Therefore, the argument to
@code{\addQuote} should be the entire part of the voice to be
quoted, including any rests at the beginning.

It is possible to use another music expression instead of
@code{s}, thus creating a polyphonic section, but this may not
always give the desired result.

Quotations take into account the transposition of both source and
target instruments, if they are specified using the
@code{\transposition} command.

@lilypond[verbatim,quote,relative=1]
\addQuote clarinet
{
  \transposition bes
  f4 fis g gis
}

{
  e8 f8 \quoteDuring #"clarinet" { s2 }
}
@end lilypond

The type of events that are present in the quoted music can be
trimmed with the @code{quotedEventTypes} property.  The default
value is @code{(note-event rest-event)}, which means that only
notes and rests of the quoted voice end up in the
@code{\quoteDuring}.  Setting

@example
\set Staff.quotedEventTypes =
       #'(note-event articulation-event dynamic-event)
@end example

@noindent
will quote notes (but no rests), together with scripts and
dynamics.


@seealso

Notation Reference:
@ref{Instrument transpositions}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{QuoteMusic},
@rinternals{Voice}.


@knownissues

Only the contents of the first @code{Voice} occurring in an
@code{\addQuote} command will be considered for quotation, so
@var{music} can not contain @code{\new} and @code{\context Voice}
statements that would switch to a different Voice.

Quoting grace notes is broken and can even cause LilyPond to
crash.

Quoting nested triplets may result in poor notation.

In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
written entirely in lower-case letters: @code{\addquote}.


@node Formatting cue notes
@unnumberedsubsubsec Formatting cue notes

@cindex cues
@cindex cue notes
@cindex cue notes, formatting
@cindex fragments
@cindex quoting other voices
@cindex cues, formatting

The previous section deals with inserting notes from another
voice.  There is a more advanced music function called
@code{\cueDuring}, which makes formatting cue notes easier.

The syntax is

@example
  \cueDuring #@var{name} #@var{updown} @var{music}
@end example

This will insert notes from the part @var{name} into a
@code{Voice} called @code{cue}.  This happens simultaneously with
@var{music}, which usually is a rest.  When the cue notes start,
the staff in effect becomes polyphonic for a moment.  The argument
@var{updown} determines whether the cue notes should be notated as
a first or second voice.

@lilypond[verbatim]
smaller = {
  \set fontSize = #-2
  \override Stem #'length-fraction = #0.8
  \override Beam #'thickness = #0.384
  \override Beam #'length-fraction = #0.8
}

\addQuote clarinet
\relative c' {
  R1*20
  r2 r8 c' f f
}

\new Staff \relative c' <<

  % setup a context for cue notes.
  \new Voice = "cue" { \smaller \skip 1*21 }

  \set Score.skipBars = ##t

  \new Voice {
    R1*20
    \cueDuring #"clarinet" #UP {
      R1
    }
    g4 g2.
  }
>>
@end lilypond

Here are a couple of hints for successful cue notes:

@itemize
@item
Cue notes have smaller font sizes.

@item
The cued part is marked with the instrument playing the cue.

@item
When the original part takes over again, this should be marked
with the name of the original instrument.

@item
Any other changes introduced by the cued part should also be
undone.  For example, if the cued instrument plays in a different
clef, the original clef should be stated once again.

@end itemize

The macro @code{\transposedCueDuring} is useful to add cues to
instruments which use a completely different octave range (for
example, having a cue of a piccolo flute within a contra bassoon
part).

@lilypond[verbatim,quote]
picc = \relative c''' {
  \clef "treble^8"
  R1 |
  c8 c c e g2 |
  a4 g g2 |
}
\addQuote "picc" { \picc }

cbsn = \relative c, {
  \clef "bass_8"
  c4 r g r
  \transposedCueDuring #"picc" #UP c,, { R1 } |
  c4 r g r |
}

<<
  \new Staff = "picc" \picc
  \new Staff = "cbsn" \cbsn
>>
@end lilypond


@seealso

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{Voice}.