Merge branch 'lilypond/translation' of ssh://thsoft@git.sv.gnu.org/srv/git/lilypond...

[lilypond.git] / Documentation / notation / 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.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.14.0"

@node Staff notation
@section Staff notation

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

This section explains how to influence the appearance of staves,
how to print scores with more than one staff, and how to add tempo
indications and cue notes to 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.

@menu
* Instantiating new staves::
* Grouping staves::
* Nested staff groups::
* Separating systems::
@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 staff, drum
@cindex staff, percussion
@cindex drum staff
@cindex percussion staff
@cindex Gregorian transcription staff
@cindex rhythmic staff
@cindex tabstaff
@cindex tablature

@funindex \drummode
@funindex drummode
@funindex DrumStaff
@funindex RhythmicStaff
@funindex TabStaff
@funindex MensuralStaff
@funindex VaticanaStaff
@funindex GregorianTranscriptionStaff

@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

The @code{DrumStaff} context creates a five-line staff set up for
a typical drum set.  Each instrument is shown with a different
symbol.  The instruments are entered in drum mode following a
@code{\drummode} command, with each instrument specified by name.
For details, see @ref{Percussion staves}.

@lilypond[verbatim,quote]
\new DrumStaff {
  \drummode { cymc hh ss tomh }
}
@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}.

The @code{GregorianTranscriptionStaff} context 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 e d }
@end lilypond

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 staff, grand
@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}


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

@knownissues
@code{PianoStaff} does not, by default, accept @code{ChordNames}.


@node Nested staff groups
@unnumberedsubsubsec 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

Staff-group contexts can be nested to arbitrary depths.  In this
case, each child context creates a new bracket adjacent to the
bracket of its parent group.

@lilypond[verbatim,quote,relative=2]
\new StaffGroup <<
  \new Staff { c2 c | c2 c }
  \new StaffGroup <<
    \new Staff { g2 g | g2 g }
    \new StaffGroup \with {
      systemStartDelimiter = #'SystemStartSquare
    }
    <<
      \new Staff { e2 e | e2 e }
      \new Staff { c2 c | c2 c }
    >>
  >>
>>
@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{StaffGroup},
@rinternals{ChoirStaff},
@rinternals{SystemStartBar},
@rinternals{SystemStartBrace},
@rinternals{SystemStartBracket},
@rinternals{SystemStartSquare}.

@node Separating systems
@unnumberedsubsubsec Separating systems

@cindex system separator mark

If the number of systems per page changes from page to page it is
customary to separate the systems by placing a system separator mark
between them.  By default the system separator is blank, but can be
turned on with a @code{\paper} option.

@c \book is required here to display the system separator
@c ragged-right is required as there are two systems
@lilypond[verbatim,quote,ragged-right]
\book {
  \score {
    \new StaffGroup <<
      \new Staff {
        \relative c'' {
          c4 c c c
          \break
          c4 c c c
        }
      }
      \new Staff {
        \relative c'' {
          c4 c c c
          \break
          c4 c c c
        }
      }
    >>
  }
  \paper {
    system-separator-markup = \slashSeparator
    % following commands are needed only to format this documentation
    paper-width = 100\mm
    paper-height = 100\mm
    tagline = ##f
  }
}
@end lilypond

@seealso
Notation Reference:
@ref{Page layout}.

Snippets:
@rlsr{Staff notation}.


@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 staff symbol, drawing
@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

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.  In the example the two numbers are factors multiplying
the staff line thickness and the staff line spacing.  The two
contributions are added to give the ledger 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

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

@cindex stopping a staff
@cindex starting a staff
@cindex staff, starting
@cindex staff, stopping

@funindex \startStaff
@funindex startStaff
@funindex \stopStaff
@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

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


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


@node Ossia staves
@unnumberedsubsubsec Ossia staves

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

@funindex \startStaff
@funindex startStaff
@funindex \stopStaff
@funindex stopStaff

@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 not what is usually desired.  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"
    \override Clef #'transparent = ##t
    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{\Staff \RemoveEmptyStaves} 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.  For more information about
@code{\Staff \RemoveEmptyStaves}, see @ref{Hiding staves}.

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

\layout {
  \context {
    \Staff \RemoveEmptyStaves
    \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

@funindex \RemoveEmptyStaves
@funindex Staff_symbol_engraver
@funindex \stopStaff
@funindex stopStaff


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


Empty staves can be hidden by setting the
@code{\Staff \RemoveEmptyStaves} 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{A staff is considered empty when it contains only
multi-measure rests, rests, skips, spacer rests, or a combination of these
elements.}

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

\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{\Staff \RemoveEmptyStaves} 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 \RemoveEmptyStaves

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


@predefined
@code{\Staff \RemoveEmptyStaves},
@code{\VaticanaStaff \RemoveEmptyStaves},
@code{\RhythmicStaff \RemoveEmptyStaves}.
@endpredefined


@snippets

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


@seealso
Music Glossary:
@rglos{Frenched staff}.

Learning Manual:
@rlearning{Visibility and color of objects}.

Notation Reference:
@ref{Changing context default settings},
@ref{Staff symbol},
@ref{Ossia staves},
@ref{Hidden notes},
@ref{Invisible rests},
@ref{Visibility of objects}.

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

For the Known issues and warnings associated with
@code{\Staff \RemoveEmptyStaves} see
@ref{Changing context default settings}.

@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
* Instrument names::
* Quoting other voices::
* Formatting cue notes::
@end menu

@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}, @code{PianoStaff}, @code{StaffGroup}, @code{GrandStaff}
and @code{ChoirStaff} 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,indent=1.5\cm,relative=2]
<<
  \new Staff {
    \set Staff.instrumentName = #"Flute"
    f2 g4 f
  }
  \new Staff {
    \set Staff.instrumentName = \markup \center-column {
      Clarinet
      \line { "in B" \smaller \flat }
    }
    c4 b c2
  }
>>
@end lilypond

@funindex indent
@funindex 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{\paper variables for shifts and indents}.

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

\relative c'' <<
  \new Staff {
    \set Staff.instrumentName = #"Alto Flute in G"
    \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

@cindex instrument names, adding to other contexts

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

@cindex instrument names, changing
@cindex changing instrument names

Instrument names may be changed in the middle of a piece.
However, remember that @code{instrumentName} will not be
displayed in the middle of the piece, as it only appears
on the first staff:

@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

@funindex \addInstrumentDefinition
@funindex addInstrumentDefinition
@funindex \instrumentSwitch
@funindex instrumentSwitch

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 association list 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{\paper variables for shifts and indents},
@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 quote, voices
@cindex voices, quoting
@cindex fragments, quoting
@cindex cue notes

@funindex \addQuote
@funindex addQuote
@funindex \quoteDuring
@funindex quoteDuring
@funindex \transposition
@funindex transposition

It is very common for one voice to use the same notes as those from
another voice.  For example, first and second violins playing the same
phrase during a particular passage of the music.  This is done by
letting one voice @emph{quote} the other, without having to re-enter the
music all over again for the second voice.

The @code{\addQuote} command, used in the top level scope, defines a
stream of music from which fragments can be quoted.

The @code{\quoteDuring} command is used to indicate the point where the
quotation begins.  It is followed by two arguments: the name of the
quoted voice, as defined with @code{\addQuote}, and a music expression
for the duration of the quote.

@lilypond[verbatim,quote]
fluteNotes = \relative c'' {
  a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
}

oboeNotes = \relative c'' {
  c4 cis c b \quoteDuring #"flute" { s1 }
}

\addQuote "flute" { \fluteNotes }

\score {
  <<
    \new Staff \with { instrumentName = "Flute" } \fluteNotes
    \new Staff \with { instrumentName = "Oboe" } \oboeNotes
  >>
}
@end lilypond

If the music expression used in @code{\quoteDuring} contains notes
instead of spacer or multimeasure rests then the quote will appear as
polyphony and may produce unexpected results.

@lilypond[verbatim,quote]
fluteNotes = \relative c'' {
  a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
}

oboeNotes = \relative c'' {
  c4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
}

\addQuote "flute" { \fluteNotes }

\score {
  <<
    \new Staff \with { instrumentName = "Flute" } \fluteNotes
    \new Staff \with { instrumentName = "Oboe" } \oboeNotes
  >>
}
@end lilypond

The @code{\quoteDuring} command uses the @code{\transposition} settings
of both quoted and quoting parts to produce notes for the quoting part
that have the same sounding pitch as those in the quoted part.

@lilypond[verbatim,quote]
clarinetNotes = \relative c'' {
  \transposition bes
  \key d \major
  b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
}

oboeNotes = \relative c'' {
  c4 cis c b \quoteDuring #"clarinet" { s1 }
}

\addQuote "clarinet" { \clarinetNotes }


\score {
  <<
    \new Staff \with { instrumentName = "Clarinet" } \clarinetNotes
    \new Staff \with { instrumentName = "Oboe" } \oboeNotes
  >>
}
@end lilypond

@cindex note-event
@cindex articulation-event
@cindex dynamic-event
@cindex rest-event
@cindex slur-event
@cindex crescendo-event

@funindex quotedEventTypes
@funindex quotedCueEventTypes

By default quoted music will include all articulations, dynamics,
markups, etc., in the quoted expression.  It is possible to choose which
of these objects from the quoted music are displayed by using the
@code{quotedEventTypes} context property.

@lilypond[verbatim,quote]
fluteNotes = \relative c'' {
  a2 g2 |
  b4\<^"quoted" r8 ais a4\f( c->)
 }

oboeNotes = \relative c'' {
  c2. b4 |
  \quoteDuring #"flute" { s1 }
}

\addQuote "flute" { \fluteNotes }

\score {
  <<
    \set Score.quotedEventTypes = #'(note-event articulation-event
                                     crescendo-event rest-event
                                     slur-event dynamic-event)
    \new Staff \with { instrumentName = "Flute" } \fluteNotes
    \new Staff \with { instrumentName = "Oboe" } \oboeNotes
  >>
 }
@end lilypond

Quotes can also be tagged, see @ref{Using tags}.

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

Snippets:
@rlsr{Staff notation}.

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

Installed Files:
@file{scm/define-event-classes.scm}.


@knownissues

Only the contents of the first @code{Voice} occurring in an
@code{\addQuote} command will be considered for quotation, so
@code{@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 cue notes
@cindex fragments
@cindex cue notes, formatting
@cindex formatting, cue notes
@cindex voices, quoting


@funindex \cueDuring
@funindex cueDuring
@funindex \cueClef
@funindex cueClef
@funindex \cueDuringWithClef
@funindex cueDuringWithClef
@funindex \quoteDuring
@funindex quoteDuring

@cindex notes, smaller
@cindex smaller notes
@cindex CueVoice

The simplest way to format cue notes is to explicitly create a
@code{CueVoice} context within the part.

@lilypond[verbatim,relative=1]
R1
<<
  { e2\rest r4. e8 }
  \new CueVoice {
    \stemUp d'8^"flute" c d e fis2
  }
>>
d,4 r a r
@end lilypond

The @code{\cueClef} command can also be used with an explict
@code{CueVoice} context if a change of clef is required and will print
an appropriately sized clef for the cue notes.  The @code{\cueClefUnset}
command can then be used to switch back to the original clef, again with
an appropriately sized clef.

@lilypond[verbatim,noragged-right,relative=1]
\clef "bass"
R1
<<
  { e2\rest r4. \cueClefUnset e,8 }
  \new CueVoice {
    \cueClef "treble" \stemUp d''8^"flute" c d e fis2
  }
>>
d,,4 r a r
@end lilypond

The @code{\cueClef} and @code{\cueClefUnset} command can also be used
without a @code{CueVoice} if required.

@lilypond[verbatim,noragged-right,relative=1]
\clef "bass"
R1
\cueClef "treble"
d'8^"flute" c d e fis2
\cueClefUnset
d,,4 r a r
@end lilypond

For more complex cue note placement, e.g including transposition, or
inserting cue notes from multiple music sources the @code{\cueDuring} or
@code{\cueDuringWithClef} commands can be used.  These are more
specialized form of @code{\quoteDuring}, see @ref{Quoting other voices}
in the previous section.

The syntax is:

@example
\cueDuring #@var{quotename} #@var{direction} #@var{music}
@end example

and

@example
\cueDuringWithClef #@var{quotename} #@var{direction} #@var{clef} #@var{music}
@end example

The music from the corresponding measures of the @code{@var{quote name}}
is added as @code{CueVoice} context and occurs simultaneously with the
@code{@var{music}}, which creates a polyphonic situation.  The
@code{@var{direction}} takes the argument @code{UP} or @code{DOWN}, and
corresponds to first and second voices respectively determining how
the cue notes are printed in relation to the other voice.

@lilypond[verbatim,quote]
fluteNotes = \relative c'' {
  r2. c4 | d8 c d e fis2 | g2 d |
}

oboeNotes = \relative c'' {
  R1
  s1*0^\markup { \tiny "flute" }
  \cueDuring #"flute" #UP { R1 }
  g2 c,
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \oboeNotes
}
@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.

It is possible to adjust which aspects of the music are quoted with
@code{\cueDuring} by setting the @code{quotedCueEventTypes}
property.  Its default value is @code{#'(note-event rest-event
tie-event beam-event tuplet-span-event)}, which means that only
notes, rests, ties, beams and tuplets are quoted, but not
articulations, dynamic marks, markup etc.

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

\new Voice \relative c'' {
  \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
                                      beam-event tuplet-span-event
                                      dynamic-event slur-event)
  \cueDuring #"oboe" #UP { R1 }
  g2 c,
}
@end lilypond

Markup can be used to show the name of the quoted instrument.  Also,
if the cue notes require a change in clef, this can be done manually but
the original clef should also be restored manually at the end of the cue
notes.

@lilypond[verbatim,quote]
fluteNotes = \relative c'' {
  r2. c4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
  \clef bass
  R1
  \clef treble
  s1*0^\markup { \tiny "flute" }
  \cueDuring #"flute" #UP { R1 }
  \clef bass
  g4. b8 d2
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \bassoonNotes
}
@end lilypond

Alternatively, the @code{\cueDuringWithClef} function can be used
instead.  This command takes an extra argument to specify the change of
clef that needs to be printed for the cue notes but will automatically
print the original clef once the cue notes have finished.

@lilypond[verbatim,quote]
fluteNotes = \relative c'' {
  r2. c4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
  \clef bass
  R1
  s1*0^\markup { \tiny "flute" }
  \cueDuringWithClef #"flute" #UP #"treble" { R1 }
  g4. b8 d2
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \bassoonNotes
}
@end lilypond

@funindex \transposedCueDuring
@funindex transposedCueDuring

Like @code{\quoteDuring}, @code{\cueDuring} takes instrument
transpositions into account.  Cue notes are produced at the
pitches that would be written for the instrument receiving the cue
to produce the sounding pitches of the source instrument.

To transpose cue notes differently, use
@code{\transposedCueDuring}.  This command takes an extra argument
to specify (in absolute mode) the printed pitch that you want to
represent the sound of a concert middle C.  This is useful for
taking cues from an instrument in a completely different register.

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

bassClarinetNotes = \relative c' {
  \key d \major
  \transposition bes,
  d4 r a r
  \transposedCueDuring #"piccolo" #UP d { R1 }
  d4 r a r
}

\addQuote "piccolo" { \piccoloNotes }

<<
  \new Staff \piccoloNotes
  \new Staff \bassClarinetNotes
>>
@end lilypond

@cindex removing cue notes
@cindex cue notes, removing

@funindex \killCues
@funindex killCues
@funindex \addInstrumentDefinition
@funindex addInstrumentDefinition

The @code{\killCues} command removes cue notes from a music
expression, so the same music expression can be used to produce
the instrument part with cues and the score.  The @code{\killCues}
command removes only the notes and events that were quoted by
@code{\cueDuring}.  Other markup associated with cues, such as clef
changes and a label identifying the source instrument, can be
tagged for selective inclusion in the score; see @ref{Using tags}.

@lilypond[verbatim,quote]
fluteNotes = \relative c'' {
  r2. c4 d8 c d e fis2 g2 d2
}

bassoonNotes = \relative c {
  \clef bass
  R1
  \tag #'part {
    \clef treble
    s1*0^\markup { \tiny "flute" }
  }
  \cueDuring #"flute" #UP { R1 }
  \tag #'part \clef bass
  g4. b8 d2
}

\addQuote "flute" { \fluteNotes }

\new Staff {
  \bassoonNotes
}

\new StaffGroup <<
  \new Staff {
    \fluteNotes
  }
  \new Staff {
    \removeWithTag #'part { \killCues { \bassoonNotes } }
  }
>>
@end lilypond

Alternatively, Clef changes and instrument labels can be
collected into an instrument definition for repeated use, using
@code{\addInstrumentDefinition} described in @ref{Instrument names}.


@seealso
Notation Reference:
@ref{Quoting other voices},
@ref{Instrument transpositions},
@ref{Instrument names},
@ref{Clef},
@ref{Musical cues},
@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.  When using
@code{\cueDuringWithClef} or @code{\transposedCueDuring} the extra
argument required for each case must come after the quote and the
direction.