Merge commit 'origin/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.57"

@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 describes the different methods 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}.

New single staff contexts may be defined.  For details, see
@ref{Defining new contexts}.


@seealso

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

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

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

New staff group contexts may be defined.  For details, see
@ref{Defining new contexts}.


@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},
@ref{Defining new contexts}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{Staff},
@rinternals{StaffGroup},
@rinternals{ChoirStaff},
@rinternals{GrandStaff},
@rinternals{PianoStaff},
@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 a 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 | c2 c }
  \new InnerStaffGroup <<
    \new Staff { g2 g | g2 g }
    \new Staff { e2 e | 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 | c2 c }
  \new InnerChoirStaff <<
    \new Staff { g2 g | g2 g }
    \new Staff { e2 e | e2 e }
  >>
  \new Staff { c1 | c1 }
>>
@end lilypond

New nested staff group contexts can be defined.  For details, see
@ref{Defining new contexts}.


@snippets

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


@seealso

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

Snippets:
@rlsr{Staff notation}.

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


@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 lines of a staff belong to the @code{StaffSymbol} grob.
@code{StaffSymbol} properties can be modified to change the
appearance of a staff, but they must be modified before the staff
is created.

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 \with {
  \override 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 following example shows,
note positions are not influenced by the staff line positions.

@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

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

Ledger line thickness can be set independently of staff line
thickness.

@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.  This setting
affects the spacing of 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 modified.  The unit is one staff
space.  The spacing of objects inside the staff is not affected by
this setting.

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

Further details about the properties of @code{StaffSymbol} can be
found here: @rinternals{staff-symbol-interface}.

@funindex \startStaff
@funindex \stopStaff

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

@cindex stopping a staff

@noindent
In general, @code{\startStaff} and @code{\stopStaff} can be used
to stop or start a staff in the middle of a score.

@lilypond[verbatim,quote,relative=2]
c4 b a2
\stopStaff
b4 c d2
\startStaff
e4 d c2
@end lilypond


@predefined

@code{\startStaff},
@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{Clef}.

Snippets:
@rlsr{Staff notation}.

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


@knownissues

When setting vertical staff line positions manually, bar lines are
always centered on position 0, so the maximum distance between the
outermost 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

@notation{Ossia} staves can be set by creating a new simultaneous
staff in the appropriate location:

@lilypond[verbatim,quote]
\new Staff \relative c'' {
  c4 b d c
  <<
    { c4 b d c }
    \new Staff { e4 d f e }
  >>
  c4 b c2
}
@end lilypond

@noindent
However, the above example is usually not the desired result.  To
create ossia staves that are above the original staff, have no
time signature or clef, and have a smaller font size, tweaks must
be used.  The Learning Manual describes a specific technique to
achieve this goal, beginning with
@rlearning{Nesting music expressions}.

The following example uses the @code{alignAboveContext} property
to align the ossia staff.  This method is most appropriate when
only a few ossia staves are needed.

@lilypond[verbatim,quote]
\new Staff = main \relative c'' {
  c4 b d c
  <<
    { c4 b d c }

    \new Staff \with {
      \remove "Time_signature_engraver"
      alignAboveContext = #"main"
      fontSize = #-3
      \override StaffSymbol #'staff-space = #(magstep -3)
      \override StaffSymbol #'thickness = #(magstep -3)
      firstClef = ##f
    }
    { e4 d f e }
  >>
  c4 b c2
}
@end lilypond

If many isolated ossia staves are needed, creating an empty
@code{Staff} context with a specific @emph{context id} may be more
appropriate; the ossia staves may then be created by
@emph{calling} this context and using @code{\startStaff} and
@code{\stopStaff} at the desired locations.  The benefits of this
method are more apparent if the piece is longer than the following
example.

@lilypond[verbatim,quote,ragged-right]
<<
  \new Staff = ossia \with {
    \remove "Time_signature_engraver"
    \remove "Clef_engraver"
    fontSize = #-3
    \override StaffSymbol #'staff-space = #(magstep -3)
    \override StaffSymbol #'thickness = #(magstep -3)
  }
  { \stopStaff s1*6 }

  \new Staff \relative c' {
    c4 b c2
    <<
      { e4 f e2 }
      \context Staff = ossia {
        \startStaff e4 g8 f e2 \stopStaff
      }
    >>
    g4 a g2 \break
    c4 b c2
    <<
      { g4 a g2 }
      \context Staff = ossia {
        \startStaff g4 e8 f g2 \stopStaff
      }
    >>
    e4 d c2
  }
>>
@end lilypond

Using the @code{\RemoveEmptyStaffContext} command to create ossia
staves may be used as an alternative.  This method is most
convenient when ossia staves occur immediately following a line
break.  In this case, spacer rests do not need to be used at all;
only @code{\startStaff} and @code{\stopStaff} are necessary.  For
more information about @code{\RemoveEmptyStaffContext}, see
@ref{Hiding staves}.

@lilypond[verbatim,quote,ragged-right]
<<
  \new Staff = ossia \with {
    \remove "Time_signature_engraver"
    \remove "Clef_engraver"
    fontSize = #-3
    \override StaffSymbol #'staff-space = #(magstep -3)
    \override StaffSymbol #'thickness = #(magstep -3)
  }
  \new Staff \relative c' {
    c4 b c2
    e4 f e2
    g4 a g2 \break
    <<
      { c4 b c2 }
      \context Staff = ossia {
        c4 e8 d c2 \stopStaff
      }
    >>
    g4 a g2
    e4 d c2
  }
>>

\layout {
  \context {
    \RemoveEmptyStaffContext
    \override VerticalAxisGroup #'remove-first = ##t
  }
}
@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{Hiding staves}.

Snippets:
@rlsr{Staff notation}.

Internals Reference:
@rinternals{StaffSymbol}.


@node Hiding staves
@unnumberedsubsubsec Hiding staves

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

Staff lines can be hidden by removing the
@code{Staff_symbol_engraver} from the @code{Staff} context.  As an
alternative, @code{\stopStaff} may be used.

@lilypond[verbatim,quote]
\new Staff \with {
  \remove "Staff_symbol_engraver"
}
\relative c''' { a8 f e16 d c b a2 }
@end lilypond

@funindex \RemoveEmptyStaffContext

Empty staves can be hidden by setting the
@code{\RemoveEmptyStaffContext} command in the @code{\layout}
block.  In orchestral scores, this style is known as @q{Frenched
Score}.  By default, this command hides and removes all empty
staves in a score except for those in the first system.

@warning{An empty staff may only include multi-measure rests,
skips, spacer rests, or a combination of these elements.}

@lilypond[verbatim,quote,ragged-right]
\layout {
  \context {
    \RemoveEmptyStaffContext
  }
}

\relative c' <<
  \new Staff {
    e4 f g a \break
    b1 \break
    a4 b c2
  }
  \new Staff {
    c,4 d e f \break
    R1 \break
    f4 g c,2
  }
>>
@end lilypond

@cindex ossia

@noindent
@code{\RemoveEmptyStaffContext} can also be used to create ossia
sections for a staff.  For details, see @ref{Ossia staves}.

@cindex hiding ancient staves
@cindex hiding rhythmic staves
@funindex \AncientRemoveEmptyStaffContext
@funindex \RemoveEmptyRhythmicStaffContext

The @code{\AncientRemoveEmptyStaffContext} command may be used to
hide empty staves in ancient music contexts.  Similarly,
@code{\RemoveEmptyRhythmicStaffContext} may be used to hide empty
@code{RhythmicStaff} contexts.


@predefined

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


@snippets

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


@seealso

Music Glossary:
@rglos{Frenched staff}.

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

Snippets:
@rlsr{Staff notation}.

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


@knownissues

Removing @code{Staff_symbol_engraver} also hides bar lines.  If
bar line visibility is forced, formatting errors may occur.  In
this case, use the following overrides instead of removing the
engraver:

@example
\override StaffSymbol #'stencil = ##f
\override NoteHead #'no-ledgers = ##t
@end example


@node Writing parts
@subsection Writing parts

This section explains how to insert tempo indications and
instrument names into a score.  Methods to quote other voices and
format cue notes are also described.

@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
@cindex metronome marking with text
@funindex \tempo

A basic metronome mark is simple to write:

@lilypond[verbatim,quote,relative=1]
\tempo 4 = 120
c2 d
e4. d8 c2
@end lilypond

Tempo indications with text can be used instead:

@lilypond[verbatim,quote,relative=2]
\tempo "Allegretto"
c4 e d c
b4. a16 b c4 r4
@end lilypond

Combining a metronome mark and text will automatically place the
metronome mark within parentheses:

@lilypond[verbatim,quote,relative=2]
\tempo "Allegro" 4 = 160
g4 c d e
d4 b g2
@end lilypond

In general, the text can be any markup object:

@lilypond[verbatim,quote,relative=2]
\tempo \markup { \italic Faster } 4 = 132
a8-. r8 b-. r gis-. r a-. r
@end lilypond

A parenthesized metronome mark with no textual indication may be
written by including an empty string in the input:

@lilypond[verbatim,quote,relative=2]
\tempo "" 8 = 96
d4 g e c
@end lilypond


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{printing-metronome-and-rehearsal-marks-below-the-staff.ly}

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

@c TODO add snippet to LSR -pm
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

@c TODO add snippet to LSR -pm
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}.


@node Instrument names
@unnumberedsubsubsec Instrument names

@cindex instrument names
@cindex instrument names, short

Instrument names can be printed on the left side of staves in the
@code{Staff} and @code{PianoStaff} contexts.  The value of
@code{instrumentName} is used for the first staff, and the value
of @code{shortInstrumentName} is used for all succeeding staves.

@lilypond[verbatim,quote,ragged-right,relative=1]
\set Staff.instrumentName = "Violin "
\set Staff.shortInstrumentName = "Vln "
c4.. g'16 c4.. g'16
\break
c1
@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 } } }
c4 c,16 d e f g2
@end lilypond

@cindex instrument names, centering

When two or more staff contexts are grouped together, the
instrument names and short instrument names are centered by
default.  To center multi-line instrument names,
@code{\center-column} must be used:

@lilypond[verbatim,quote,relative=2]
<<
  \new Staff {
    \set Staff.instrumentName = "Flute"
    f2 g4 f
  }
  \new Staff {
    \set Staff.instrumentName = \markup \center-column {
      Clarinetti
      \line { "in B" \smaller \flat }
    }
    c4 b c2
  }
>>
@end lilypond

@cindex indent
@cindex short-indent

However, if the instrument names are longer, the instrument names
in a staff group may not be centered unless the @code{indent} and
@code{short-indent} settings are increased.  For details about
these settings, see @ref{Page formatting}.

@lilypond[verbatim,quote,ragged-right]
\layout {
  indent = 2.5\cm
  short-indent = 1.5\cm
}

\relative c'' <<
  \new Staff {
    \set Staff.instrumentName = "Flute"
    \set Staff.shortInstrumentName = "Fl."
    f2 g4 f \break
    g4 f g2
  }
  \new Staff {
    \set Staff.instrumentName = "Clarinet"
    \set Staff.shortInstrumentName = "Clar."
    c,4 b c2 \break
    c2 b4 c
  }
>>
@end lilypond

To add instrument names to other contexts (such as
@code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}),
@code{Instrument_name_engraver} must be added to that context.
For details, see @ref{Modifying context plug-ins}.

@cindex instrument names, changing

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

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

@cindex instrument switch
@cindex switching instruments

If an instrument @emph{switch} is needed,
@code{\addInstrumentDefinition} may be used in combination with
@code{\instrumentSwitch} to create a detailed list of the
necessary changes for the switch.  The
@code{\addInstrumentDefinition} command has two arguments: an
identifying string, and an alist of context properties and values
to be used for the instrument.  It must be placed in the toplevel
scope.  @code{\instrumentSwitch} is used in the music expression
to declare the instrument switch:

@lilypond[verbatim,quote,ragged-right]
\addInstrumentDefinition #"contrabassoon"
  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
     (shortInstrumentName . "Cbsn.")
     (clefGlyph . "clefs.F")
     (middleCPosition . 6)
     (clefPosition . 2)
     (instrumentCueName . ,(make-bold-markup "cbsn."))
     (midiInstrument . "bassoon"))

\new Staff \with {
  instrumentName = "Bassoon"
}
\relative c' {
  \clef tenor
  \compressFullBarRests
  c2 g'
  R1*16
  \instrumentSwitch "contrabassoon"
  c,,2 g \break
  c,1 ~ | c1
}
@end lilypond


@seealso

Notation Reference:
@ref{Page formatting},
@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

Fragments of other parts can be inserted directly into a music
expression; this is called @emph{quotation}.  Before a part can be
quoted, the @code{\addQuote} command must be used to initialize
the quoted fragment.  This command must be used in the toplevel
scope.  The first argument is an identifying string, and the
second is a music expression:

@example
flute = \relative c'' @{
  a4 gis g gis
@}
\addQuote "flute" @{ \flute @}
@end example

The @code{\quoteDuring} command is used to indicate when the
quotation should take place.  The corresponding measures from the
quotation are inserted into the music expression.  The syntax is
similar to @code{\addQuote}:

@lilypond[verbatim,quote]
flute = \relative c'' {
  a4 gis g gis
}
\addQuote "flute" { \flute }

\relative c' {
  c4 cis \quoteDuring #"flute" { s2 }
}
@end lilypond

If the music expression used for @code{\quoteDuring} contains
anything but a spacer rest or multi-measure rest, a polyphonic
situation is created, which is often not desirable:

@lilypond[verbatim,quote]
flute = \relative c'' {
  a4 gis g gis
}
\addQuote "flute" { \flute }

\relative c' {
  c4 cis \quoteDuring #"flute" { c4 b }
}
@end lilypond

Quotations recognize instrument transposition settings for both
the source and target instruments if the @code{\transposition}
command is used.  For details about @code{\transposition}, see
@ref{Instrument transpositions}.

@lilypond[verbatim,quote]
clarinet = \relative c'' {
  \transposition bes
  a4 gis g gis
}
\addQuote "clarinet" { \clarinet }

\relative c' {
  c4 cis \quoteDuring #"clarinet" { s2 }
}
@end lilypond

It is possible to tag quotations with unique names in order to
process them in different ways.  For details about this procedure,
see @ref{Using tags}.

@c add to snippets, possibly.  It might already be there.  -pm
@c
@c The type of events that are present in the quoted music can be
@c trimmed with the @code{quotedEventTypes} property.  The default
@c value is @code{(note-event rest-event)}, which means that only
@c notes and rests of the quoted voice end up in the
@c @code{\quoteDuring}.  Setting
@c
@c @example
@c \set Staff.quotedEventTypes =
@c        #'(note-event articulation-event dynamic-event)
@c @end example
@c
@c @noindent
@c will quote notes (but no rests), together with scripts and
@c dynamics.


@snippets

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{quoting-another-voice-with-transposition.ly}

@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
{quoting-another-voice.ly}


@seealso

Notation Reference:
@ref{Instrument transpositions},
@ref{Using tags}.

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} cannot 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 explains how to create quotations.  The
@code{\cueDuring} command is a more specialized form of
@code{\quoteDuring}, being particularly useful for inserting cue
notes into a part.  The syntax is as follows:

@example
  \cueDuring #@var{partname} #@var{voice} @var{music}
@end example

This command copies the corresponding measures from @var{partname}
into a @code{CueVoice} context.  The @code{CueVoice} is created
implicitly, and occurs simultaneously with @var{music}, which
creates a polyphonic situation.  The @var{voice} argument
determines whether the cue notes should be notated as a first or
second voice; @code{UP} corresponds to the first voice, and
@code{DOWN} corresponds to the second.

@lilypond[verbatim,quote]
oboe = \relative c'' {
  r2 r8 d16 f e g f a
  g8 g16 g g2.
}
\addQuote "oboe" { \oboe }

\new Voice \relative c'' {
  \cueDuring #"oboe" #UP { R1 }
  g2 c,
}
@end lilypond

@noindent
In the above example, the @code{Voice} context had to be
explicitly declared, or else the entire music expression would
belong to the @code{CueVoice} context.

The name of the cued instrument can be printed by setting the
@code{instrumentCueName} property in the @code{CueVoice} context.

@lilypond[verbatim,quote]
oboe = \relative c''' {
  g4 r8 e16 f e4 d
}
\addQuote oboe { \oboe }

\new Staff \relative c'' <<
  \new CueVoice \with {
    instrumentCueName = "ob."
  }
  \new Voice {
    \cueDuring #"oboe" #UP { R1 }
    g4. b8 d2
  }
>>
@end lilypond

In addition to printing the name of the cued instrument, when cue
notes end, the name of the original instrument should be printed,
and any other changes introduced by the cued part should be
undone.  This can be accomplished by using
@code{\addInstrumentDefinition} and @code{\instrumentSwitch}.  For
an example and explanation, see @ref{Instrument names}.

The @code{\killCues} command removes cue notes from a music
expression.  This can be useful if cue notes need to be removed
from a part but may be restored at a later time.

@lilypond[verbatim,quote]
flute = \relative c''' {
  r2 cis2 r2 dis2
}
\addQuote flute { \flute }

\new Voice \relative c'' {
  \killCues {
    \cueDuring #"flute" #UP { R1 }
    g4. b8 d2
  }
}
@end lilypond

The @code{\transposedCueDuring} command is useful for adding
instrumental cues from a completely different register.  The
syntax is similar to @code{\cueDuring}, but it requires one extra
argument to specify the transposition of the cued instrument.  For
more information about transposition, see
@ref{Instrument transpositions}.

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

cbassoon = \relative c, {
  \clef "bass_8"
  c4 r g r
  \transposedCueDuring #"piccolo" #UP c,, { R1 }
  c4 r g r
}

<<
  \new Staff = "piccolo" \piccolo
  \new Staff = "cbassoon" \cbassoon
>>
@end lilypond

It is possible to tag cued parts with unique names in order to
process them in different ways.  For details about this procedure,
see @ref{Using tags}.


@seealso

Notation Reference:
@ref{Instrument transpositions},
@ref{Instrument names},
@ref{Using tags}.

Snippets:
@rlsr{Staff notation}.

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


@knownissues

Collisions can occur with rests, when using @code{\cueDuring},
between @code{Voice} and @code{CueVoice} contexts.