[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.38"

@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 to create and group
staves into groups, which can be marked in 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
@subsubsection 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

The lines of a staff (pl. staves) are produced by the @code{staff symbol} 
layout object.  Staves are created with the @code{\new} or
@code{\context} commands.  For an explanation on these commands,
see @ref{Creating contexts}.

There are different predefined staff contexts available in LilyPond:

@itemize
@item
The default is @code{Staff}:
@lilypond[verbatim,ragged-right,quote]
\relative c'' {
  \new Staff { c d e f }
}
@end lilypond

@item
@code{DrumStaff} creates a five line staff set up for a typical drum set.
It uses different names for each instrument.  The instrument names have to
be set using the @code{drummode}.  See @ref{Percussion staves}.
@lilypond[verbatim,ragged-right,quote]
\new DrumStaff { 
  \drummode { cymc hh ss tomh }
}
@end lilypond

@item
@code{GregorianTranscriptionStaff} sets up a staff to notate modern
Gregorian chant.  It does not show bar lines.
@lilypond[verbatim,ragged-right,quote]
\relative c'' {
  \new GregorianTranscriptionStaff { c d e f }
}
@end lilypond

@item
@code{RhythmicStaff} can be used to show the rhythm of some music.  The
notes are printed on one line regardless of their pitch, but the duration
is preserved.  See @ref{Showing melody rhythms}.
@lilypond[verbatim,ragged-right,quote]
\relative c'' {
  \new RhythmicStaff { c d e f }
}
@end lilypond

@item
@code{TabStaff} creates by default a tablature with six strings in 
standard guitar tuning.  See @ref{Tablatures basic}.
@lilypond[verbatim,ragged-right,quote]
\relative c'' {
  \new TabStaff { c d e f }
}
@end lilypond

@end itemize

@noindent
Besides these staves 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}.

Once a staff is instantiated it can be started or stopped at every point
in the score.  This is done with the commands @code{\startStaff} and 
@code{\stopStaff}.  How to use it is explained in @ref{Staff symbol}.


@seealso

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

Notation Reference: @ref{Percussion staves}, 
@ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
@ref{Mensural contexts}.

Snippets: @lsrdir{Staff,Staff-notation}.

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



@node Grouping staves
@subsubsection Grouping staves

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

LilyPond provides different types of contexts to group single staves 
together.  These contexts influence in the first place the appearance
of the system start delimiter, but they have also influence on the
behavior of the bar lines.

Each staff group context sets the property
@code{systemStartDelimiter} to one of the values
@code{SystemStartBar}, @code{SystemStartBrace},
and @code{SystemStartBracket}.  A fourth delimiter,
@code{systemStartSquare}, is also available, but must be
instantiated manually.  The usage of this last delimiter is shown further
down in the snippet section.


@itemize
@item
If no context is specified, the default properties for the score
will be used: the group is started with a vertical line, and the
bar lines are not connected.  The name of the beginning bar line 
grob is @code{SystemStartBar}.  

@lilypond[verbatim,ragged-right,quote]
\relative c'' <<
  \new Staff { c1 c }
  \new Staff { c c }
>>
@end lilypond

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

@lilypond[verbatim,ragged-right,quote]
\new StaffGroup {
  \relative c'' <<
    \new Staff { c1 c }
    \new Staff { c c }
  >>
}
@end lilypond

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

@lilypond[verbatim,ragged-right,quote]
\new ChoirStaff {
  \relative c'' <<
    \new Staff { c1 c }
    \new Staff { c c }
  >>
}
@end lilypond

@item
In a @code{GrandStaff}, the group is started with a brace
at the left, and bar lines are connected between the staves. 

@lilypond[verbatim,ragged-right,quote]
\new GrandStaff {
  \relative c'' <<
    \new Staff { c1 c }
    \new Staff { c c }
  >>
}
@end lilypond

@item
The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is
optimized for setting piano music. In particular it supports the printing
of an instrument name directly, see @ref{Instrument names}.

@lilypond[verbatim,ragged-right,quote]
\new PianoStaff {
  \relative c'' <<
    \new Staff { c1 c }
    \new Staff { c c }
  >>
}
@end lilypond

@end itemize

According to classic engraver rules an orchestral score consists of
staves connected only with a single line at the beginning of the system. 
In LilyPond this is produced grouping the @code{Staff} contexts with
@code{<< ... >>}.

Each instrument family is grouped inside of a @code{StaffGroup} with a 
starting bracket.  A group of same instruments or an instrument using
more than one staff is grouped with braces in a @code{GrandStaff}.

As the context names tell, @code{PianoStaff} is used for notating
piano music and @code{ChoirStaff} for all kind of vocal ensemble music.


@snippets

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

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
{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,ragged-right,texidoc]
{mensurstriche-layout-bar-lines-between-the-staves.ly}


@seealso

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

Snippets: @lsrdir{Staff,Staff-notation}

Internals Reference: @internalsref{ChoirStaff},
@internalsref{GrandStaff}, @internalsref{StaffGroup},
@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
@internalsref{SystemStartBracket}, and @internalsref{systemStartSquare}.


@node Deeper nested staff groups
@subsubsection Deeper nested staff groups

There are also two inner staff contexts named @code{InnerStaffGroup}
and @code{InnerChoirStaffGroup} besides the grouping contexts mentioned
in @ref{Grouping staves}.  They behave in the same way as their simple
counterparts, except that they are contained in another staff grouping
context, thus producing one more bracket on top of the existing one. 
Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
grouping contexts.  They can both be inside any other staff context, 
including inner staff groups, though.

Here is an example of an orchestral score using groupings and nesting
of these groupings.  Note that the instrument names are omitted from the
source code, see @ref{Instrument names} how to set them.

@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


@example
\score @{ <<
  \new StaffGroup %woodwinds
  <<
  \new Staff @{ c'1 d' @} %flute
  \new InnerStaffGroup <<
    \new Staff @{ c' d' @} %sax 
    \new Staff @{ c' d' @} %oboe
    \new Staff @{ c' d' @} %English horn
    >>
  \new Staff @{ \clef bass c d @} %bassoon
  >>
  \new StaffGroup %the brass group
  <<
    \new Staff @{ c' d' @} %trumpet
    \new Staff @{ \clef bass c d @} %trombone
    \new GrandStaff %the horns need a GrandStaff (same instrument)
    <<
      \new Staff @{ c' d' @}
      \new Staff @{ \clef bass c d @}
    >>
  >>
  \new ChoirStaff %for setting vocal music
  <<
   \new Staff @{ c' d' @}
    \new InnerChoirStaff <<
     \new Staff @{ c' d' @}
     \new Staff @{ c' d' @}
    >>
   \new Staff @{ c' d' @}
  >>
  \new PianoStaff %for the piano
  <<
    \new Staff @{ c' d' @}
    \new Staff @{\clef bass c d @}
  >>
>> @}
@end example

@c no verbatim so instrument names are only in the music
@lilypond[ragged-right,quote]
\score { <<
  \new StaffGroup %woodwinds
  <<
  \new Staff {\set Staff.instrumentName = "fl" c'1 d' } %flute
  \new InnerStaffGroup <<
    \new Staff { \set Staff.instrumentName = "sax" c' d' } %sax 1
    \new Staff { \set Staff.instrumentName = "ob" c' d' } %sax 2
    \new Staff { \set Staff.instrumentName = "ca" c' d' }
    >>
  \new Staff {\set Staff.instrumentName = "bs" \clef bass c d } %bassoon
  >>
  \new StaffGroup %the brass group
  <<
    \new Staff {\set Staff.instrumentName = "tr" c' d' } %trumpet
    \new Staff {\set Staff.instrumentName = "tb" \clef bass c d } %trombone
    \new GrandStaff %the horns need a GrandStaff (same instrument)
    <<
      \new Staff {\set Staff.instrumentName = "cor1" c' d' }
      \new Staff {\set Staff.instrumentName = "cor2" \clef bass c d }
    >>
  >>
  \new ChoirStaff %for setting vocal music
  <<
   \new Staff {\set Staff.instrumentName = "S" c' d' }
    \new InnerChoirStaff <<
     \new Staff {\set Staff.instrumentName = "A1" c' d' }
     \new Staff {\set Staff.instrumentName = "A2" c' d' }
    >>
   \new Staff {\set Staff.instrumentName = "T" c' d' }
  >>
  \new PianoStaff %for the piano
  <<
    \new Staff { c' d' }
    \new Staff {\clef bass c d }
  >>
>> }
@end lilypond


@snippets

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


@seealso

Internals Reference: @internalsref{SystemStartBar}, 
@internalsref{SystemStartBrace}, @internalsref{SystemStartBracket},
@internalsref{systemStartDelimiterHierarchy}.



@node Modifying single staves
@subsection Modifying single staves

This section explains how to change specific attributes of one 
staff like the staff lines, starting and stopping of staves, sizing
of staves, and setting ossia sections.

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

@node Staff symbol
@subsubsection 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 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

The layout object which draws the lines of a staff is called
@code{staff symbol}.  The staff symbol may be tuned in number,
thickness and distance of lines, using properties.  It may also
be started and stopped at every point in the score.

@itemize
@item
Changing the number of staff lines is done by overriding 
@code{line-count}.  You may need to adjust the clef position
and the position of the middle C to fit to the new staff.  For
an explanation, see the snippet section in @ref{Displaying pitches}.

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

@item
The placement and amount of the staff lines can also set totally 
manually by defining their positions explicitly.  The middle
of the staff has the value of 0, each half staff space up and down
adds an integer.  The default values are 4 2 0 -2 -4.  Bar lines
are drawn according to the calculated width of the system, but
they are always centered.  As the
example shows, the positions of the notes are not influenced
by the position of the staff lines.

@lilypond[verbatim,ragged-right,quote]
\new Staff \with {
  \override StaffSymbol #' line-positions = #' ( 7 3 0 -4 -6 -7 )
  }{
  a e' f' b' d''
}
@end lilypond

@item
The staff line thickness can be set by overriding the @code{thickness}
property.  Note that it gets applied also to ledger lines and stems, 
since they depend on the staff line thickness.  The argument of 
@code{thickness} is a factor of @code{line-thickness} which defaults
to the normal staff line thickness.

@lilypond[verbatim,ragged-right,quote]
\new Staff \with {
  \override StaffSymbol #'thickness = #3
  }{
  d d d d
}
@end lilypond

@item
The thickness of the ledger lines can also be set independent of the
settings for staff lines.  The setting is calculated from a pair of
values which will be added for the final thickness.  The first value 
is the staff line thickness multiplied by a factor, the second is
the staff space multiplied by a factor.  In the example the ledger
lines get their thickness from one staff line thickness plus 1/5 
staff space, so they are heavier than a normal staff line.

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

@item
The distance of the stafflines can be changed with the 
@code{staff-space} property. Its argument is the amount
of staff spaces that should be inserted between the lines.
The default value is 1. Setting the distance has
influence on the staff lines as well as on ledger lines.

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

@item
The length of the staff line can also be adjusted
manually.  The unit is one staff space.  Spacing 
of the objects inside the staff does not get influenced 
by this setting.

@lilypond[verbatim,ragged-right,quote]
\new Staff \with {
  \override StaffSymbol #' width = #23
  }{
  a e' f' b' d''
}
@end lilypond

@end itemize

These properties can only be set before instantiating the staff symbol.
But it is possible to start and stop staves in the middle of a score,
so each new setting will be applied to the newly instantiated staff.

@lilypond[verbatim,relative=2,fragment]
b4 b
%Set here the overrides for the staff 
\override Staff.StaffSymbol #'line-count = 2
\stopStaff \startStaff
b b
%Revert to the default
\revert Staff.StaffSymbol #'line-count
\stopStaff \startStaff
b b
@end lilypond
 
@predefined

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

@snippets

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

@seealso

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

Internals Reference: @internalsref{StaffSymbol}.

@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
@subsubsection Ossia staves

@cindex staves, Frenched
@cindex ossia
@cindex Frenched staves

Tweaking the staff object allows to resize the staff:

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

@noindent
This involves shrinking the staff spaces, the staff lines and
the font size. See @ref{Setting the staff size}.

In combination with Frenched staves, this may be used to typeset
@emph{ossia} sections.  An example is shown here

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

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

    s2

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

>>
@end lilypond

@cindex staff lines, setting number of
@cindex staff lines, setting thickness of
@cindex thickness of staff lines, setting
@cindex number of staff lines, setting

@snippets

@c  lilypondfile{Making-some-staff-lines-thicker-than-the-others.ly}
@c snippet 277

@seealso

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

Snippets: @lsrdir{Staff,Staff-notation}

Internals Reference: @internalsref{StaffSymbol},
@internalsref{DrumStaff}.


@node Hiding staves
@subsubsection Hiding staves

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

In orchestral scores, staff lines that only have rests are usually
removed; this saves some space.  This style is called @q{French
Score}.  For @code{Lyrics}, @code{ChordNames} and
@code{FiguredBass}, 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, a specialized @code{Staff} context is
available, which does the same: staves containing nothing (or only
multi-measure rests) are removed.  The context definition is
stored in @code{\RemoveEmptyStaffContext} variable.  Observe how
the second staff in this example disappears in the second line

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

{
  \relative c' <<
    \new Staff { e4 f g a \break c1 }
    \new Staff { c4 d e f \break R1 }
  >>
}
@end lilypond

The first system shows all staves in full.  If empty staves should
be removed from the first system too, set @code{remove-first} to
true in @code{VerticalAxisGroup}.

@example
\override Score.VerticalAxisGroup #'remove-first = ##t
@end example

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

@cindex ossia

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{Staff
symbol}. 

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


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

@seealso

Notation Reference: @ref{Staff symbol}.

Snippets: @lsrdir{Staff,Staff-notation}

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

@node Writing parts
@subsection Writing parts

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

@node Metronome marks
@subsubsection 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[quote,ragged-right,verbatim,fragment]
\tempo 8.=120 c''1
@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[quote,ragged-right,verbatim,relative,fragment]
c4^\markup {
  (
  \smaller \general-align #Y #DOWN \note #"16." #1
  =
  \smaller \general-align #Y #DOWN \note #"8" #1
  ) }
@end lilypond

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

Snippets: @lsrdir{Staff,Staff-notation}.

Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
output}.


@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
@subsubsection 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[quote,verbatim,ragged-right,relative=1,fragment]
\set Staff.instrumentName = "Ploink "
\set Staff.shortInstrumentName = "Plk "
c1
\break
c''
@end lilypond

You can also use markup texts to construct more complicated
instrument names, for example

@lilypond[quote,fragment,verbatim,ragged-right]
\set Staff.instrumentName = \markup {
  \column { "Clarinetti"
            \line { "in B" \smaller \flat } } }
c''1
@end lilypond

@cindex instrument names, centering

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

@lilypond[quote,verbatim,ragged-right]
{ <<
\new Staff {
  \set Staff.instrumentName = \markup \center-align {
    Clarinetti
    \line { "in B" \smaller \flat }
  }
  c''1
}
\new Staff {
  \set Staff.instrumentName = "Vibraphone"
  c''1
}
>>
}
@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[quote,fragment,verbatim,ragged-right]
\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: @lsrdir{Staff,Staff-notation}

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


@node Quoting other voices
@subsubsection 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[quote,ragged-right,verbatim]
\addQuote clarinet \relative c' {
  \transposition bes
  f4 fis g gis
}

{
  e'8 f'8 \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.

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

@seealso

Notation Reference: @ref{Instrument transpositions}.

Snippets: @lsrdir{Staff,Staff-notation}

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


@node Formatting cue notes
@subsubsection 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,ragged-right]
smaller = {
  \set fontSize = #-2
  \override Stem #'length-fraction = #0.8
  \override Beam #'thickness = #0.384
  \override Beam #'length-fraction = #0.8
}

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

\new Staff \relative  <<

  % 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,ragged-right,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 |
}

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

@seealso

Snippets: @lsrdir{Staff,Staff-notation}.

Internals Reference: @internalsref{Voice}.