Add dynamic script fffff; update docs.

[lilypond.git] / Documentation / user / staff.itely

diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely
index 3c4be6a41d7f45b8a37c48d1ef47bfb1860e1f9e..c9a8254d901e65014e10227bc65f03de8852f7f4 100644 (file)
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -6,16 +6,16 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.51"
+@c \version "2.12.0"

 
 @node Staff notation
 @section Staff notation
 
 @lilypondfile[quote]{staff-headword.ly}
 
 
 @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.
+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::
 
 @menu
 * Displaying staves::


@@ -27,16 +27,16 @@ performance marks to single staves.
 @node Displaying staves
 @subsection Displaying staves
 
 @node Displaying staves
 @subsection Displaying staves
 

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

 
 @menu
 * Instantiating new staves::
 * Grouping staves::
 
 @menu
 * Instantiating new staves::
 * Grouping staves::

-* Deeper nested staff groups::
+* Nested staff groups::

 @end menu
 
 @end menu
 

+

 @node Instantiating new staves
 @unnumberedsubsubsec Instantiating new staves
 
 @node Instantiating new staves
 @unnumberedsubsubsec Instantiating new staves
 


@@ -45,6 +45,8 @@ with either a bracket or a brace.
 @cindex staff instantiation
 @cindex staff, new
 @cindex staff, single
 @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 drum staff
 @cindex percussion staff
 @cindex Gregorian transcription staff


@@ -52,6 +54,15 @@ with either a bracket or a brace.
 @cindex tabstaff
 @cindex tablature
 
 @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}.
 @notation{Staves} (singular: @notation{staff}) are created with
 the @code{\new} or @code{\context} commands.  For details, see
 @ref{Creating contexts}.


@@ -62,9 +73,10 @@ The basic staff context is @code{Staff}:
 \new Staff { c4 d e f }
 @end lilypond
 
 \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.
+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]
 For details, see @ref{Percussion staves}.
 
 @lilypond[verbatim,quote]


@@ -73,14 +85,6 @@ For details, see @ref{Percussion staves}.
 }
 @end lilypond
 
 }
 @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}.
 @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}.


@@ -100,13 +104,18 @@ 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}.
 
 music: @code{MensuralStaff} and @code{VaticanaStaff}.  They are
 described in @ref{Pre-defined contexts}.
 

-Staves can be started or stopped at any point in the score.  The
-commands @code{\startStaff} and @code{\stopStaff} are used for
-this purpose.  For details, see @ref{Staff symbol}.
+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

 
 

+@seealso

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


@@ -114,12 +123,13 @@ Music Glossary:
 Notation Reference:
 @ref{Creating contexts},
 @ref{Percussion staves},
 Notation Reference:
 @ref{Creating contexts},
 @ref{Percussion staves},

+@ref{Showing melody rhythms},

 @ref{Default tablatures},
 @ref{Default tablatures},

+@ref{Pre-defined contexts},
+@ref{Staff symbol},

 @ref{Gregorian chant contexts},
 @ref{Mensural contexts},
 @ref{Gregorian chant contexts},
 @ref{Mensural contexts},

-@ref{Staff symbol},
-@ref{Pre-defined contexts},
-@ref{Showing melody rhythms}.
+@ref{Defining new contexts}.

 
 Snippets:
 @rlsr{Staff notation}.
 
 Snippets:
 @rlsr{Staff notation}.


@@ -150,6 +160,7 @@ Internals Reference:
 @cindex staff group
 @cindex staff, choir
 @cindex staff, piano
 @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
 @cindex system
 
 Various contexts exist to group single staves together in order to


@@ -197,13 +208,13 @@ lines are connected between the staves.
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-The @code{PianoStaff} is almost identical to a @code{GrandStaff},
-except that it supports printing the instrument name directly.
-For details, see @ref{Instrument names}.
+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 <<
 
 @lilypond[verbatim,quote,relative=2]
 \new PianoStaff <<

-  \set PianoStaff.instrumentName = "Piano"
+  \set PianoStaff.instrumentName = #"Piano"

   \new Staff { c1 c }
   \new Staff { c1 c }
 >>
   \new Staff { c1 c }
   \new Staff { c1 c }
 >>


@@ -216,6 +227,9 @@ Each staff group context sets the property
 @code{SystemStartSquare}, is also available, but it must be
 explicitly specified.
 
 @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
 
 
 @snippets
 


@@ -232,36 +246,35 @@ explicitly specified.
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {mensurstriche-layout-bar-lines-between-the-staves.ly}
 
 @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
 
 
 @seealso

-

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

-@ref{Instrument names}.
+@ref{Instrument names},
+@ref{Defining new contexts}.

 
 Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:
 @rinternals{Staff},
 
 Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:
 @rinternals{Staff},

+@rinternals{StaffGroup},

 @rinternals{ChoirStaff},
 @rinternals{GrandStaff},
 @rinternals{PianoStaff},
 @rinternals{ChoirStaff},
 @rinternals{GrandStaff},
 @rinternals{PianoStaff},

-@rinternals{StaffGroup},

 @rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
 
 @rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
 

-@node Deeper nested staff groups
-@unnumberedsubsubsec Deeper nested staff groups
+@node Nested staff groups
+@unnumberedsubsubsec Nested staff groups

 
 @cindex staff, nested
 @cindex staves, nested
 
 @cindex staff, nested
 @cindex staves, nested


@@ -270,42 +283,29 @@ Internals Reference:
 @cindex nested staff brackets
 @cindex brackets, nesting of
 @cindex braces, nesting of
 @cindex nested staff brackets
 @cindex brackets, nesting of
 @cindex braces, nesting of

-@cindex inner staff group
-@cindex inner choir staff group

 
 

-Two additional staff-group contexts are available that can be
-nested within a @code{StaffGroup} or @code{ChoirStaff} context:
-@code{InnerStaffGroup} and @code{InnerChoirStaff}.  These contexts
-create an additional bracket next to the original bracket of their
-parent staff group.
-
-An @code{InnerStaffGroup} is treated similarly to a
-@code{StaffGroup}; bar lines are connected between each stave
-within the context:
+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 <<
 
 @lilypond[verbatim,quote,relative=2]
 \new StaffGroup <<

-  \new Staff { c2 c }
-  \new InnerStaffGroup <<
-    \new Staff { g2 g }
-    \new Staff { e2 e }
+  \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
 
   >>
 >>
 @end lilypond
 

-Bar lines are @emph{not} connected between staves of an
-@code{InnerChoirStaff}, just like a @code{ChoirStaff}:
-
-@lilypond[verbatim,quote,relative=2]
-\new ChoirStaff <<
-  \new Staff { c2 c }
-  \new InnerChoirStaff <<
-    \new Staff { g2 g }
-    \new Staff { e2 e }
-  >>
-  \new Staff { c1 }
->>
-@end lilypond
+New nested staff group contexts can be defined.  For details, see
+@ref{Defining new contexts}.

 
 
 @snippets
 
 
 @snippets


@@ -315,22 +315,21 @@ Bar lines are @emph{not} connected between staves of an
 
 
 @seealso
 
 
 @seealso

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

 
 Snippets:
 @rlsr{Staff notation}.
 
 
 Snippets:
 @rlsr{Staff notation}.
 

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

 Internals Reference:
 Internals Reference:

-@rinternals{InnerStaffGroup},

 @rinternals{StaffGroup},
 @rinternals{StaffGroup},

-@rinternals{InnerChoirStaff},

 @rinternals{ChoirStaff},
 @rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},
 @rinternals{ChoirStaff},
 @rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},

-@rinternals{SystemStartBracket}.
+@rinternals{SystemStartBracket},
+@rinternals{SystemStartSquare}.

 
 
 @node Modifying single staves
 
 
 @node Modifying single staves


@@ -354,6 +353,7 @@ sections are also described.
 @cindex adjusting staff symbol
 @cindex drawing staff symbol
 @cindex staff symbol, setting of
 @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 stop staff lines
 @cindex start staff lines
 @cindex staff lines, amount of


@@ -366,11 +366,10 @@ sections are also described.
 @cindex spacing of ledger lines
 @cindex number of staff lines
 
 @cindex spacing of ledger lines
 @cindex number of staff lines
 

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


@@ -378,31 +377,13 @@ staff.  For an explanation, refer to the snippet section in
 @ref{Clef}.
 
 @lilypond[verbatim,quote,relative=2]
 @ref{Clef}.
 
 @lilypond[verbatim,quote,relative=2]

-\new Staff {
-  \override Staff.StaffSymbol #'line-count = #3
-  d4 d d d
-}
-@end lilypond
-
-The vertical position of staff lines and the number of staff lines
-can be defined at the same time.  As the example shows, the
-positions of the notes are not influenced by the position of the
-staff lines.  Details for modifying this property are found in
-@rinternals{staff-symbol-interface}.
-
-@warning{The @code{'line-positions} property overrides the
-@code{'line-count} property.  The number of staff lines is
-implicitly defined by the number of elements in the list of values
-for @code{'line-positions}}
-
-@lilypond[verbatim,quote,relative=1]

 \new Staff \with {
 \new Staff \with {

-  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+  \override StaffSymbol #'line-count = #3

 }
 }

-{ a4 e' f b | d1 }
+{ d4 d d d }

 @end lilypond
 
 @end lilypond
 

-The staff line thickness can be modified.  The thickness of ledger
+Staff line thickness can be modified.  The thickness of ledger

 lines and stems are also affected, since they depend on staff line
 thickness.
 
 lines and stems are also affected, since they depend on staff line
 thickness.
 


@@ -413,9 +394,10 @@ thickness.
 { e4 d c b }
 @end lilypond
 
 { e4 d c b }
 @end lilypond
 

-The thickness of ledger lines can be set independently of staff
-line thickness.  A description of this property is also found in
-@rinternals{staff-symbol-interface}.
+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 {
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {


@@ -424,8 +406,8 @@ line thickness.  A description of this property is also found in
 { e4 d c b }
 @end lilypond
 
 { e4 d c b }
 @end lilypond
 

-The distance between staff lines can be changed.  The setting has
-influence on ledger lines as well.
+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 {
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {


@@ -434,16 +416,18 @@ influence on ledger lines as well.
 { a4 b c d }
 @end lilypond
 
 { a4 b c d }
 @end lilypond
 

-The width of a staff can be adjusted.  The unit is one staff
-space.  The spacing of objects inside the staff is not influenced
-by this setting.
+Further details about the properties of @code{StaffSymbol} can be
+found in @rinternals{staff-symbol-interface}.

 
 

-@lilypond[verbatim,quote,relative=1]
-\new Staff \with {
-  \override StaffSymbol #'width = #23
-}
-{ a4 e' f b | d1 }
-@end lilypond
+@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}:
 
 Modifications to staff properties in the middle of a score can be
 placed between @code{\stopStaff} and @code{\startStaff}:


@@ -460,13 +444,23 @@ b2 b
 a2 a
 @end lilypond
 
 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.

 
 

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

 
 

-@funindex \startStaff
+
+@predefined

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

-@funindex \stopStaff

 @code{\stopStaff}.
 @code{\stopStaff}.

+@endpredefined

 
 
 @snippets
 
 
 @snippets


@@ -476,27 +470,22 @@ a2 a
 
 
 @seealso
 
 
 @seealso

-

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

-@ref{Displaying pitches}.
+@ref{Clef}.
+
+Snippets:
+@rlsr{Staff notation}.

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

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

 @node Ossia staves
 @unnumberedsubsubsec Ossia staves
 
 @node Ossia staves
 @unnumberedsubsubsec Ossia staves
 


@@ -506,59 +495,132 @@ lines in either direction must be equal.
 @cindex staff, resizing of
 @cindex resizing of staves
 
 @cindex staff, resizing of
 @cindex resizing of staves
 

-Tweaking the staff object allows to resize the staff:
+@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]
 
 @lilypond[verbatim,quote]

-\new Staff \with {
-  fontSize = #-3
-  \override StaffSymbol #'staff-space = #(magstep -3)
-  \override StaffSymbol #'thickness = #(magstep -3)
-}
-\relative c {
-  \clef bass
-  c8 c c c  c c c c
+\new Staff \relative c'' {
+  c4 b d c
+  <<
+    { c4 b d c }
+    \new Staff { e4 d f e }
+  >>
+  c4 b c2

 }
 @end lilypond
 
 }
 @end lilypond
 

-This involves shrinking the staff spaces, the staff lines and the
-font size by the factor 3.  You find a more precise explanation in
-@ref{Setting the staff size}.
+@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 @emph{ossia} section in the next example are just put parallel
-to the main staff with @code{<<} and @code{>>} brackets.  The
-@emph{ossia} staff is stopped and started explicitely and white
-space is inserted with the @code{\skip} command.
+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]
 
 @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 \with
-  {
-    %No time signature in the ossia staff
+  \new Staff = ossia \with {

     \remove "Time_signature_engraver"
     \remove "Time_signature_engraver"

+    \override Clef #'transparent = ##t

     fontSize = #-3
     \override StaffSymbol #'staff-space = #(magstep -3)
     \override StaffSymbol #'thickness = #(magstep -3)
     fontSize = #-3
     \override StaffSymbol #'staff-space = #(magstep -3)
     \override StaffSymbol #'thickness = #(magstep -3)

-    firstClef = ##f

   }
   }

-  \relative c'' {
-    \stopStaff
-    \skip 2
+  { \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

 
 

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

 
 

-    s2
+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.  For more information about
+@code{\RemoveEmptyStaffContext}, see @ref{Hiding staves}.

 
 

-    \startStaff
-    f8 d g4
+@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'' {
-    \time 2/4
-    c4 c g' g a a g2
+  \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 {
+    \RemoveEmptyStaffContext
+    \override VerticalAxisGroup #'remove-first = ##t
+  }
+}

 @end lilypond
 
 
 @end lilypond
 
 


@@ -569,7 +631,6 @@ space is inserted with the @code{\skip} command.
 
 
 @seealso
 
 
 @seealso

-

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


@@ -581,7 +642,7 @@ Learning Manual:
 @rlearning{Length and thickness of objects}.
 
 Notation Reference:
 @rlearning{Length and thickness of objects}.
 
 Notation Reference:

-@ref{Setting the staff size}.
+@ref{Hiding staves}.

 
 Snippets:
 @rlsr{Staff notation}.
 
 Snippets:
 @rlsr{Staff notation}.


@@ -593,123 +654,101 @@ Internals Reference:
 @node Hiding staves
 @unnumberedsubsubsec Hiding staves
 
 @node Hiding staves
 @unnumberedsubsubsec Hiding staves
 

-@cindex Frenched scores
+@cindex Frenched score
+@cindex Frenched staff

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

-@cindex Frenched staves
-
-In orchestral scores, staff lines that only have rests are usually
-removed; this saves some space.  This style is called @q{French
-Score}.  For the @code{Lyrics}, @code{ChordNames}, and
-@code{FiguredBass} contexts, this is switched on by default.  When
-the lines of these contexts turn out empty after the line-breaking
-process, they are removed.
-
-For normal staves this behaviour is called with the
-@code{\RemoveEmptyStaffContext} command.  It is set in the
-@code{\layout} block.  As a result staves containing nothing or
-whole mesure rests are removed after a line break.
-
-@lilypond[verbatim,quote]
-\layout {
-  \context {
-    \RemoveEmptyStaffContext
-  }
-}
-\relative c'' {
-  <<
-    \new Staff { e4 f g a \break c1 }
-    \new Staff { c4 d e f \break R1 }
-  >>
-}
-@end lilypond
-
-To remove other types of contexts, use
-@code{\AncientRemoveEmptyStaffContext} or
-@code{\RemoveEmptyRhythmicStaffContext}.
-
-@cindex ossia

 
 

-@c FIXME Really? I need to see about this.  -pm
-
-Another application of the @code{\RemoveEmptyStaffContext} is to
-make ossia sections, i.e., alternative melodies on a separate
-piece of staff, with help of a Frenched staff.  See
-@ref{Ossia staves}.
+@funindex \RemoveEmptyStaffContext
+@funindex RemoveEmptyStaffContext
+@funindex Staff_symbol_engraver
+@funindex \stopStaff
+@funindex stopStaff

 
 

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

 
 

-You can make the staff lines invisible by removing the
-@code{Staff_symbol_engraver} from the @code{Staff} context.
+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]
 
 @lilypond[verbatim,quote]

-\score {
-  \new Staff \relative c'' { c8 c c16 c c c }
-  \layout{
-    \context {
-      \Staff
-      \remove Staff_symbol_engraver
-    }
-  }
+\new Staff \with {
+  \remove "Staff_symbol_engraver"

 }
 }

+\relative c''' { a8 f e16 d c b a2 }

 @end lilypond
 
 
 @end lilypond
 
 

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

 
 

-The first empty staff can also be removed from the score with a
-setting in the @code{VerticalAxisGroup} property.  This can be
-done globally inside the @code{\layout} block, or locally inside
-the specific staff that should be removed. In the latter case, you
-have to specify the context (@code{Staff} applies only to the
-current staff) in front of the property.
+@warning{A staff is considered empty when it contains only
+multi-measure rests, skips, spacer rests, or a combination of these
+elements.}

 
 

-The lower staff of the second staff group is not removed, because
-the setting applies only to the specific staff inside of which it
-is written.
-
-@lilypond[verbatim,quote]
+@lilypond[verbatim,quote,ragged-right]

 \layout {
   \context {
     \RemoveEmptyStaffContext
 \layout {
   \context {
     \RemoveEmptyStaffContext

-    %To use the setting globally, uncomment the following line:
-    %\override VerticalAxisGroup #'remove-first = ##t

   }
 }
   }
 }

-\new StaffGroup
-  \relative c'' <<
-    \new Staff {
-      e4 f g a \break c1 }
-    \new Staff {
-      %To use the setting globally, comment this line, uncomment the line above
-      \override Staff.VerticalAxisGroup #'remove-first = ##t
-      R1 \break R1 }
-  >>
-\new StaffGroup
-  <<
-    \new Staff { e4 f g a \break c1 }
-    \new Staff { R \break R1 }
-  >>
+
+\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
 
 @end lilypond
 

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

 
 

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

 
 

-@predefined
+@cindex hiding ancient staves
+@cindex hiding rhythmic staves

 
 @funindex \RemoveEmptyStaffContext
 
 @funindex \RemoveEmptyStaffContext

-@code{\RemoveEmptyStaffContext},
+@funindex RemoveEmptyStaffContext

 @funindex \AncientRemoveEmptyStaffContext
 @funindex \AncientRemoveEmptyStaffContext

-@code{\AncientRemoveEmptyStaffContext},
+@funindex AncientRemoveEmptyStaffContext

 @funindex \RemoveEmptyRhythmicStaffContext
 @funindex \RemoveEmptyRhythmicStaffContext

+@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}.
 @code{\RemoveEmptyRhythmicStaffContext}.

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

 
 
 @seealso
 
 
 @seealso

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

 
 Notation Reference:
 @ref{Staff symbol},
 
 Notation Reference:
 @ref{Staff symbol},


@@ -723,12 +762,30 @@ Internals Reference:
 @rinternals{FiguredBass},
 @rinternals{Lyrics},
 @rinternals{Staff},
 @rinternals{FiguredBass},
 @rinternals{Lyrics},
 @rinternals{Staff},

-@rinternals{VerticalAxisGroup}.
+@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
 
 
 
 @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::
 @menu
 * Metronome marks::
 * Instrument names::


@@ -742,46 +799,70 @@ Internals Reference:
 
 @cindex tempo
 @cindex beats per minute
 
 @cindex tempo
 @cindex beats per minute

-@cindex metronome marking
+@cindex metronome mark
+@cindex metronome marking with text

 
 

-Metronome settings can be entered as follows
+@funindex \tempo
+@funindex tempo

 
 

-@example
-\tempo @var{duration} = @var{per-minute}
-@end example
+A basic metronome mark is simple to write:

 
 

-In the MIDI output, they are interpreted as a tempo change.  In
-the layout output, a metronome marking is printed
+@lilypond[verbatim,quote,relative=1]
+\tempo 4 = 120
+c2 d
+e4. d8 c2
+@end lilypond

 
 

-@funindex \tempo
+Tempo indications with text can be used instead:

 
 @lilypond[verbatim,quote,relative=2]
 
 @lilypond[verbatim,quote,relative=2]

-\tempo 8. = 120
-c1
+\tempo "Allegretto"
+c4 e d c
+b4. a16 b c4 r4

 @end lilypond
 
 @end lilypond
 

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

 
 

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

 
 

-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
+In general, the text can be any markup object:

 
 

-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
-  ) }
+@lilypond[verbatim,quote,relative=2]
+\tempo \markup { \italic Faster } 4 = 132
+a8-. r8 b-. r gis-. r a-. r

 @end lilypond
 
 @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?
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-tempo-without-a-metronome-mark.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-metronome-marks-in-markup-mode.ly}
+

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

-

 Music Glossary:
 @rglos{metronome},
 @rglos{metronomic indication},
 Music Glossary:
 @rglos{metronome},
 @rglos{metronomic indication},


@@ -799,44 +880,23 @@ Internals Reference:
 @rinternals{MetronomeMark}.
 
 
 @rinternals{MetronomeMark}.
 
 

-@knownissues
-
-Collisions are not checked.  If you have notes above the top line
-of the staff (or notes with articulations, slurs, text, etc), then
-the metronome marking may be printed on top of musical symbols.
-If this occurs, increase the padding of the metronome mark to
-place it further away from the staff.
-
-@example
-\override Score.MetronomeMark #'padding = #2.5
-@end example
-
-@c perhaps also an example of how to move it horizontally?
-
-

 @node Instrument names
 @unnumberedsubsubsec Instrument names
 
 @cindex instrument names
 @cindex instrument names, short
 
 @node Instrument names
 @unnumberedsubsubsec Instrument names
 
 @cindex instrument names
 @cindex instrument names, short
 

-In an orchestral score, instrument names are printed at the left
-side of the staves.
-
-This can be achieved by setting @code{Staff}.@code{instrumentName}
-and @code{Staff}.@code{shortInstrumentName}, or
-@code{PianoStaff}.@code{instrumentName} and
-@code{PianoStaff}.@code{shortInstrumentName}.  This will print
-text before the start of the staff.  For the first staff,
-@code{instrumentName} is used.  If set, @code{shortInstrumentName}
-is used for the following staves.
+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,relative=1]
-\set Staff.instrumentName = "Ploink "
-\set Staff.shortInstrumentName = "Plk "
-c1
+@lilypond[verbatim,quote,ragged-right,relative=1]
+\set Staff.instrumentName = #"Violin "
+\set Staff.shortInstrumentName = #"Vln "
+c4.. g'16 c4.. g'16

 \break
 \break

-c''1
+c1

 @end lilypond
 
 Markup mode can be used to create more complicated instrument
 @end lilypond
 
 Markup mode can be used to create more complicated instrument


@@ -846,71 +906,131 @@ names:
 \set Staff.instrumentName = \markup {
   \column { "Clarinetti"
             \line { "in B" \smaller \flat } } }
 \set Staff.instrumentName = \markup {
   \column { "Clarinetti"
             \line { "in B" \smaller \flat } } }

-c1
+c4 c,16 d e f g2

 @end lilypond
 
 @cindex instrument names, centering
 
 @end lilypond
 
 @cindex instrument names, centering
 

-As instrument names are centered by default, multi line names are
-better entered using @code{\center-align}:
+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]
+@lilypond[verbatim,quote,indent=1.5\cm,relative=2]

 <<
   \new Staff {
 <<
   \new Staff {

-    \set Staff.instrumentName = \markup \center-align {
-      Clarinetti
-      \line { "in B" \smaller \flat }
-    }
-    c1
+    \set Staff.instrumentName = #"Flute"
+    f2 g4 f

   }
   \new Staff {
   }
   \new Staff {

-    \set Staff.instrumentName = "Vibraphone"
-    c1
+    \set Staff.instrumentName = \markup \center-column {
+      Clarinet
+      \line { "in B" \smaller \flat }
+    }
+    c4 b c2

   }
 >>
 @end lilypond
 
   }
 >>
 @end lilypond
 

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

 
 

-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.
+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{Horizontal dimensions}.

 
 

-To add instrument names to other contexts (such as
-@code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
-engraver must be added to that context.
+@lilypond[verbatim,quote,ragged-right]
+\layout {
+  indent = 3.0\cm
+  short-indent = 1.5\cm
+}

 
 

-@example
-\layout@{
-  \context @{\GrandStaff \consists "Instrument_name_engraver"@}
-@}
-@end example
+\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

 
 

-@noindent
-More information about adding and removing engravers can be found
-in @ref{Modifying context plug-ins}.
+@cindex instrument names, adding to other contexts
+
+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
 
 @cindex instrument names, changing

+@cindex changing instrument names

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

-@lilypond[verbatim,quote,relative=1]
-\set Staff.instrumentName = "First"
-\set Staff.shortInstrumentName = "one"
+@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
 c1 c c c \break
 c1 c c c \break

-\set Staff.instrumentName = "Second"
-\set Staff.shortInstrumentName = "two"
+\set Staff.instrumentName = #"Second"
+\set Staff.shortInstrumentName = #"two"

 c1 c c c \break
 c1 c c c \break
 @end lilypond
 
 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

 
 

+@seealso

 Notation Reference:
 Notation Reference:

+@ref{Horizontal dimensions},

 @ref{Modifying context plug-ins}.
 
 Snippets:
 @ref{Modifying context plug-ins}.
 
 Snippets:


@@ -930,99 +1050,106 @@ Internals Reference:
 @cindex fragments
 @cindex cue notes
 
 @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.
+@funindex \addQuote
+@funindex addQuote
+@funindex \quoteDuring
+@funindex quoteDuring
+@funindex \transposition
+@funindex transposition

 
 

-@example
-\addQuote @var{name} @var{music}
-@end example
+It is very common for one voice to double some of the music from
+another voice.  For example, the first and second violins may play the
+same notes during a passage of music.  In LilyPond this is accomplished
+by letting one voice @emph{quote} the other voice without having to
+re-enter it.

 
 

-@noindent
-Here, @var{name} is an identifying string.  The @var{music} is any
-kind of music.  Here is an example of @code{\addQuote}
+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
 
 @example

-\addQuote clarinet \relative c' @{
-  f4 fis g gis
+flute = \relative c'' @{
+  a4 gis g gis

 @}
 @}

+\addQuote "flute" @{ \flute @}

 @end example
 
 @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}:
+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
+that indicates the duration of the quote, usually spacer rests or
+multi-measure rests.  The corresponding music from the quoted voice is
+inserted into the music expression:

 
 

-@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.
+@lilypond[verbatim,quote]
+flute = \relative c'' {
+  a4 gis g gis
+}
+\addQuote "flute" { \flute }

 
 

-@example
-\quoteDuring #"clarinet" @{ s2. @}
-@end example
+\relative c' {
+  c4 cis \quoteDuring #"flute" { s2 }
+}
+@end lilypond

 
 

-This would cite three quarter notes (the duration of @code{s2.})
-of the previously added @code{clarinet} voice.
+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:

 
 

-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.
+@lilypond[verbatim,quote]
+flute = \relative c'' {
+  a4 gis g gis
+}
+\addQuote "flute" { \flute }

 
 

-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.
+\relative c' {
+  c4 cis \quoteDuring #"flute" { c4 b }
+}
+@end lilypond

 
 

-Quotations take into account the transposition of both source and
-target instruments, if they are specified using the
-@code{\transposition} command.
+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,relative=1]
-\addQuote clarinet
-{
+@lilypond[verbatim,quote]
+clarinet = \relative c'' {

   \transposition bes
   \transposition bes

-  f4 fis g gis
+  a4 gis g gis

 }
 }

+\addQuote "clarinet" { \clarinet }

 
 

-{
-  e8 f8 \quoteDuring #"clarinet" { s2 }
+\relative c' {
+  c4 cis \quoteDuring #"clarinet" { s2 }

 }
 @end lilypond
 
 }
 @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
+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}.

 
 

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

 
 

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

 
 

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

 
 

-@seealso
+@cindex note-event
+@cindex articulation-event
+@cindex dynamic-event
+@cindex rest-event
+
+@funindex quotedEventTypes

 
 

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

 Notation Reference:
 Notation Reference:

-@ref{Instrument transpositions}.
+@ref{Instrument transpositions},
+@ref{Using tags}.

 
 Snippets:
 @rlsr{Staff notation}.
 
 Snippets:
 @rlsr{Staff notation}.


@@ -1036,7 +1163,7 @@ Internals Reference:
 
 Only the contents of the first @code{Voice} occurring in an
 @code{\addQuote} command will be considered for quotation, so
 
 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}
+@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
 statements that would switch to a different Voice.
 
 Quoting grace notes is broken and can even cause LilyPond to


@@ -1058,107 +1185,150 @@ written entirely in lower-case letters: @code{\addquote}.
 @cindex quoting other voices
 @cindex cues, formatting
 
 @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.
+@funindex \cueDuring
+@funindex cueDuring
+@funindex \quoteDuring
+@funindex quoteDuring

 
 

-The syntax is
+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
 
 @example

-  \cueDuring #@var{name} #@var{updown} @var{music}
+\cueDuring #@var{partname} #@var{voice} @var{music}

 @end example
 
 @end example
 

-This will insert notes from the part @var{name} into a
-@code{Voice} called @code{cue}.  This happens simultaneously with
-@var{music}, which usually is a rest.  When the cue notes start,
-the staff in effect becomes polyphonic for a moment.  The argument
-@var{updown} determines whether the cue notes should be notated as
-a first or second voice.
-
-@lilypond[verbatim]
-smaller = {
-  \set fontSize = #-2
-  \override Stem #'length-fraction = #0.8
-  \override Beam #'thickness = #0.384
-  \override Beam #'length-fraction = #0.8
+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 }

 
 

-\addQuote clarinet
-\relative c' {
-  R1*20
-  r2 r8 c' f f
+\new Voice \relative c'' {
+  \cueDuring #"oboe" #UP { R1 }
+  g2 c,

 }
 }

+@end lilypond

 
 

-\new Staff \relative c' <<
+@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.

 
 

-  % setup a context for cue notes.
-  \new Voice = "cue" { \smaller \skip 1*21 }
+The name of the cued instrument can be printed by setting the
+@code{instrumentCueName} property in the @code{CueVoice} context.

 
 

-  \set Score.skipBars = ##t
+@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 {
   \new Voice {

-    R1*20
-    \cueDuring #"clarinet" #UP {
-      R1
-    }
-    g4 g2.
+    \cueDuring #"oboe" #UP { R1 }
+    g4. b8 d2

   }
 >>
 @end lilypond
 
   }
 >>
 @end lilypond
 

-Here are a couple of hints for successful cue notes:
+@cindex removing cues
+@cindex removing cue notes
+@cindex cue notes, removing

 
 

-@itemize
-@item
-Cue notes have smaller font sizes.
+@funindex \killCues
+@funindex killCues
+@funindex \transposedCueDuring
+@funindex transposedCueDuring

 
 

-@item
-The cued part is marked with the instrument playing the cue.
+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}.

 
 

-@item
-When the original part takes over again, this should be marked
-with the name of the original instrument.
+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.

 
 

-@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.
+@lilypond[verbatim,quote]
+flute = \relative c''' {
+  r2 cis2 r2 dis2
+}
+\addQuote "flute" { \flute }

 
 

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

 
 

-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).
+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]
 
 @lilypond[verbatim,quote]

-picc = \relative c''' {
+piccolo = \relative c''' {

   \clef "treble^8"
   \clef "treble^8"

-  R1 |
-  c8 c c e g2 |
-  a4 g g2 |
+  R1
+  c8 c c e g2
+  a4 g g2

 }
 }

-\addQuote "picc" { \picc }
+\addQuote "piccolo" { \piccolo }

 
 

-cbsn = \relative c, {
+cbassoon = \relative c, {

   \clef "bass_8"
   c4 r g r
   \clef "bass_8"
   c4 r g r

-  \transposedCueDuring #"picc" #UP c,, { R1 } |
-  c4 r g r |
+  \transposedCueDuring #"piccolo" #UP c,, { R1 }
+  c4 r g r

 }
 
 <<
 }
 
 <<

-  \new Staff = "picc" \picc
-  \new Staff = "cbsn" \cbsn
+  \new Staff = "piccolo" \piccolo
+  \new Staff = "cbassoon" \cbassoon

 >>
 @end lilypond
 
 >>
 @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
 
 @seealso

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

 
 Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:
 
 Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:

+@rinternals{CueVoice},

 @rinternals{Voice}.
 
 @rinternals{Voice}.
 

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