X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fstaff.itely;h=b1558e72dfef9f3fae3886e528f9020a4385690b;hb=01df8ad908c92687d0c352e5ad5f067e52809423;hp=55bea3c9af6b3b913fd18e6edc5b8109a09427e1;hpb=c89a1808d10c9a5e60c74e20668e136623db12f2;p=lilypond.git

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index 55bea3c9af..b1558e72df 100644
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -7,12 +7,14 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.17.6"
 
 @node Staff notation
 @section Staff notation
 
-@lilypondfile[quote]{staff-headword.ly}
+@c The line width is a bit of a hack to allow space for the
+@c  instrument names.
+@lilypondfile[quote,ragged-right,line-width=14.5\cm,staffsize=16]{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
@@ -116,7 +118,6 @@ notate modern Gregorian chant.  It does not show bar lines.
 New single staff contexts may be defined.  For details, see
 @ref{Defining new contexts}.
 
-
 @seealso
 Music Glossary:
 @rglos{staff},
@@ -235,10 +236,10 @@ New staff group contexts may be defined.  For details, see
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {use-square-bracket-at-the-start-of-a-staff-group.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {display-bracket-with-only-one-staff-in-a-system.ly}
 
 @cindex mensurstriche layout
@@ -246,10 +247,9 @@ New staff group contexts may be defined.  For details, see
 @cindex transcription of mensural music
 @cindex mensural music, transcription of
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {mensurstriche-layout-bar-lines-between-the-staves.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{brace},
@@ -274,6 +274,9 @@ Internals Reference:
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
+@knownissues
+@code{PianoStaff} does not, by default, accept @code{ChordNames}.
+
 
 @node Nested staff groups
 @unnumberedsubsubsec Nested staff groups
@@ -312,10 +315,9 @@ New nested staff group contexts can be defined.  For details, see
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {nesting-staves.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Grouping staves},
@@ -333,6 +335,7 @@ Internals Reference:
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
+
 @node Separating systems
 @unnumberedsubsubsec Separating systems
 
@@ -377,7 +380,7 @@ turned on with a @code{\paper} option.
 
 @seealso
 Notation Reference:
-@ref{Page formatting}.
+@ref{Page layout}.
 
 Snippets:
 @rlsr{Staff notation}.
@@ -401,125 +404,139 @@ sections are also described.
 @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}.
+@cindex staff symbol
+@cindex staff lines, stopping and starting
+@cindex staff lines, modifying
+@cindex ledger lines
+@cindex ledger lines, internal
+@cindex ledger lines, modifying
+
+@funindex \startStaff
+@funindex startStaff
+@funindex \stopStaff
+@funindex stopStaff
+
+The @code{\stopStaff} and @code{\startStaff} commands can be used to
+stop or (re)start the staff lines respectively, from being printed at
+any point witin a score.
 
 @lilypond[verbatim,quote,relative=2]
-\new Staff \with {
-  \override StaffSymbol #'line-count = #3
-}
-{ d4 d d d }
+\stopStaff f4 d \startStaff g, e
+f'4 d \stopStaff g, e
+f'4 d \startStaff g, e
 @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.
+@predefined
+@code{\startStaff},
+@code{\stopStaff}.
+@endpredefined
 
-@lilypond[verbatim,quote,relative=1]
-\new Staff \with {
-  \override StaffSymbol #'thickness = #3
-}
-{ e4 d c b }
+The lines of a staff belong to the @code{StaffSymbol} grob (including
+ledger lines) can be modified using @code{StaffSymbol} properties, but
+these modifications must be made before the staff is (re)started.
+
+The number of staff lines can be altered,
+
+@lilypond[verbatim,quote,relative=2]
+f4 d \stopStaff
+\override Staff.StaffSymbol.line-count = #2
+\startStaff g, e |
+
+f'4 d \stopStaff
+\revert Staff.StaffSymbol.line-count
+\startStaff g, e |
+@end lilypond
+
+The position of each the staff lines can also be altered.  The values
+used are @emph{half} staff line spaces and the new position is relative
+to the normal center line.  A single staff line is printed for every
+value entered so that the number of staff lines, as well as their
+position in the staff, can be changed with a single override.
+
+@lilypond[verbatim,quote,relative=2]
+f4 d \stopStaff
+\override Staff.StaffSymbol.line-positions = #'(1 3 5 -1 -3)
+\startStaff g, e |
+f'4 d \stopStaff
+\override Staff.StaffSymbol.line-positions = #'(8 6.5 -6 -8 -0.5)
+\startStaff g, e
 @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.
+The clef position and the position of middle C may need to be adjusted
+accordingly to fit the new lines.  See @ref{Clef}.
 
-@lilypond[verbatim,quote,relative=1]
+Staff line thickness can be altered.  Ledger lines and note stems, by
+default, are also affected.
+
+@lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
+  \override StaffSymbol.thickness = #3
 }
-{ e4 d c b }
+{ f4 d g, e }
 @end lilypond
 
-The distance between staff lines can be changed.  This setting
-affects the spacing of ledger lines as well.
+However, it is possible to set ledger line thickness independently of
+staff lines.  The two values required multiply the staff line thickness
+with the staff line spacing and are then added together to give the
+ledger line thickness.
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'staff-space = #1.5
+  \override StaffSymbol.thickness = #2
+  \override StaffSymbol.ledger-line-thickness = #'(0.5 . 0.4)
 }
-{ a4 b c d }
+{ f'4 a, a,, f }
 @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
+The vertical positions of ledger lines can be altered,
 
-@funindex \startStaff
-@funindex startStaff
-@funindex \stopStaff
-@funindex stopStaff
+@lilypond[verbatim,quote,relative=2]
+\new Staff \with {
+  \override StaffSymbol.ledger-positions = #'(-3 -2 -1 2 5 6)
+}
+{ f'4 a, a,, f }
+@end lilypond
 
-Modifications to staff properties in the middle of a score can be
-placed between @code{\stopStaff} and @code{\startStaff}:
+Additional ledger lines can be made to appear above or below note heads
+depending on the current position relative to other note heads that
+also have their own ledger lines.
 
 @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
+\new Staff \with {
+  \override StaffSymbol.ledger-extra = #4
+}
+{ f'4 a, d, f, }
 @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.
+Legder lines can also be made to appear inside the staff where custom
+staff lines are required.  The example shows the default position of
+ledger lines when the explicit @code{legder-position} is and is not set.
+The @code{stopStaff} is needed in the example to revert the
+@code{\override} for the whole @code{StaffSymbol}.
 
-@lilypond[verbatim,quote,relative=2]
-c4 b a2
+@lilypond[fragment,quote,relative=1]
+\override Staff.StaffSymbol.line-positions =   #'(-8 0 2 4)
+d4 e f g
 \stopStaff
-b4 c d2
 \startStaff
-e4 d c2
+\override Staff.StaffSymbol.ledger-positions = #'(-8 -6 (-4 -2) 0)
+d4 e f g
 @end lilypond
 
+The distance between staff lines can be altered.  This affects ledger
+line spacing as well.
 
-@predefined
-@code{\startStaff},
-@code{\stopStaff}.
-@endpredefined
-
+@lilypond[verbatim,quote,relative=2]
+\new Staff \with {
+  \override StaffSymbol.staff-space = #1.5
+}
+{ f'4 d, g, e, }
+@end lilypond
 
 @snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {making-some-staff-lines-thicker-than-the-others.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{line},
@@ -587,8 +604,8 @@ only a few ossia staves are needed.
       \remove "Time_signature_engraver"
       alignAboveContext = #"main"
       fontSize = #-3
-      \override StaffSymbol #'staff-space = #(magstep -3)
-      \override StaffSymbol #'thickness = #(magstep -3)
+      \override StaffSymbol.staff-space = #(magstep -3)
+      \override StaffSymbol.thickness = #(magstep -3)
       firstClef = ##f
     }
     { e4 d f e }
@@ -609,10 +626,10 @@ example.
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
+    \override Clef.transparent = ##t
     fontSize = #-3
-    \override StaffSymbol #'staff-space = #(magstep -3)
-    \override StaffSymbol #'thickness = #(magstep -3)
+    \override StaffSymbol.staff-space = #(magstep -3)
+    \override StaffSymbol.thickness = #(magstep -3)
   }
   { \stopStaff s1*6 }
 
@@ -638,20 +655,20 @@ example.
 @end lilypond
 
 
-Using the @code{\RemoveEmptyStaffContext} command to create ossia
+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{\RemoveEmptyStaffContext}, see @ref{Hiding staves}.
+@code{\Staff \RemoveEmptyStaves}, see @ref{Hiding staves}.
 
 @lilypond[verbatim,quote,ragged-right]
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
+    \override Clef.transparent = ##t
     fontSize = #-3
-    \override StaffSymbol #'staff-space = #(magstep -3)
-    \override StaffSymbol #'thickness = #(magstep -3)
+    \override StaffSymbol.staff-space = #(magstep -3)
+    \override StaffSymbol.thickness = #(magstep -3)
   } \relative c'' {
     R1*3
     c4 e8 d c2
@@ -668,8 +685,8 @@ break.  For more information about
 
 \layout {
   \context {
-    \RemoveEmptyStaffContext
-    \override VerticalAxisGroup #'remove-first = ##t
+    \Staff \RemoveEmptyStaves
+    \override VerticalAxisGroup.remove-first = ##t
   }
 }
 @end lilypond
@@ -677,10 +694,9 @@ break.  For more information about
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {vertically-aligning-ossias-and-lyrics.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{ossia},
@@ -712,8 +728,7 @@ Internals Reference:
 @cindex hiding of staves
 @cindex empty staves
 
-@funindex \RemoveEmptyStaffContext
-@funindex RemoveEmptyStaffContext
+@funindex \RemoveEmptyStaves
 @funindex Staff_symbol_engraver
 @funindex \stopStaff
 @funindex stopStaff
@@ -732,7 +747,7 @@ alternative, @code{\stopStaff} may be used.
 
 
 Empty staves can be hidden by setting the
-@code{\RemoveEmptyStaffContext} command in the @code{\layout}
+@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.
@@ -744,7 +759,7 @@ elements.}
 @lilypond[verbatim,quote,ragged-right]
 \layout {
   \context {
-    \RemoveEmptyStaffContext
+    \Staff \RemoveEmptyStaves
   }
 }
 
@@ -765,38 +780,32 @@ elements.}
 @cindex ossia
 
 @noindent
-@code{\RemoveEmptyStaffContext} can also be used to create ossia
+@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 \RemoveEmptyStaffContext
-@funindex RemoveEmptyStaffContext
-@funindex \AncientRemoveEmptyStaffContext
-@funindex AncientRemoveEmptyStaffContext
-@funindex \RemoveEmptyRhythmicStaffContext
-@funindex RemoveEmptyRhythmicStaffContext
+@funindex \RemoveEmptyStaves
 
-The @code{\AncientRemoveEmptyStaffContext} command may be used to
+The @code{\VaticanaStaff \RemoveEmptyStaves} command may be used to
 hide empty staves in ancient music contexts.  Similarly,
-@code{\RemoveEmptyRhythmicStaffContext} may be used to hide empty
+@code{\RhythmicStaff \RemoveEmptyStaves} may be used to hide empty
 @code{RhythmicStaff} contexts.
 
 
 @predefined
-@code{\RemoveEmptyStaffContext},
-@code{\AncientRemoveEmptyStaffContext},
-@code{\RemoveEmptyRhythmicStaffContext}.
+@code{\Staff \RemoveEmptyStaves},
+@code{\VaticanaStaff \RemoveEmptyStaves},
+@code{\RhythmicStaff \RemoveEmptyStaves}.
 @endpredefined
 
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {removing-the-first-empty-line.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{Frenched staff}.
@@ -823,22 +832,21 @@ Internals Reference:
 @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
+\override StaffSymbol.stencil = ##f
+\override NoteHead.no-ledgers = ##t
 @end example
 
 For the Known issues and warnings associated with
-@code{\RemoveEmptyStaffContext} see @ref{Changing context default
-settings}.
+@code{\Staff \RemoveEmptyStaves} see
+@ref{Changing context default settings}.
+
 
 @node Writing parts
 @subsection Writing parts
@@ -860,105 +868,119 @@ format cue notes are also described.
 @cindex instrument names, short
 
 Instrument names can be printed on the left side of staves in the
-@code{Staff} and @code{PianoStaff} contexts.  The value of
+@code{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
+\new Staff \with {
+  instrumentName = #"Violin "
+  shortInstrumentName = #"Vln. "
+}
+{ c4.. g'16 c4.. g'16 \break | c1 }
 @end lilypond
 
-Markup mode can be used to create more complicated instrument
-names:
+@cindex instrument names, complex
+
+@code{\markup} can be used to create more complex 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
+\new Staff \with {
+  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:
+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 \with {
+    instrumentName = #"Flute"
   }
-  \new Staff {
-    \set Staff.instrumentName = \markup \center-column {
-      Clarinet
-      \line { "in B" \smaller \flat }
+  { f2 g4 f }
+  \new Staff \with {
+    instrumentName = \markup {
+      \center-column { "Clarinet"
+        \line { "in B" \smaller \flat }
+      }
     }
-    c4 b c2
   }
+  { 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{Horizontal dimensions}.
+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]
+\relative c'' {
+  <<
+    \new Staff \with {
+      instrumentName = #"Alto Flute in G"
+      shortInstrumentName = #"Flt."
+    }
+    {
+      f2 g4 f \break
+      g4 f g2
+    }
+    \new Staff \with {
+      instrumentName = #"Clarinet"
+      shortInstrumentName = #"Clar."
+    }
+    {
+      c,4 b c2 \break
+      c2 b4 c
+    }
+  >>
+}
+
 \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{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}),
-@code{Instrument_name_engraver} must be added to that context.
-For details, see @ref{Modifying context plug-ins}.
+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:
+The @code{shortInstrumentName} may be changed in the middle of a piece.
+However, only the first instance of @code{instrumentName} will be
+printed and subsequent changes will be ignored:
 
 @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
+\new Staff \with {
+  instrumentName = #"Flute"
+  shortInstrumentName = #"Flt."
+}
+{
+  c1 c c c \break
+  c1 c c c \break
+  \set Staff.instrumentName = #"Clarinet"
+  \set Staff.shortInstrumentName = #"Clt."
+  c1 c c c \break
+  c1 c c c \break
+}
 @end lilypond
 
 @cindex instrument switch
@@ -1003,10 +1025,9 @@ expression to declare the instrument switch:
 }
 @end lilypond
 
-
 @seealso
 Notation Reference:
-@ref{Horizontal dimensions},
+@ref{\paper variables for shifts and indents},
 @ref{Modifying context plug-ins}.
 
 Snippets:
@@ -1021,9 +1042,9 @@ Internals Reference:
 @node Quoting other voices
 @unnumberedsubsubsec Quoting other voices
 
-@cindex cues
-@cindex quoting other voices
-@cindex fragments
+@cindex quote, voices
+@cindex voices, quoting
+@cindex fragments, quoting
 @cindex cue notes
 
 @funindex \addQuote
@@ -1033,205 +1054,286 @@ Internals Reference:
 @funindex \transposition
 @funindex transposition
 
-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.
+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.
 
-Before a part can be quoted, the @code{\addQuote} command must be used
-to initialize the quoted fragment.  This command must be used in the
-toplevel scope.  The first argument is an identifying string, and the
-second is a music expression:
-
-@example
-flute = \relative c'' @{
-  a4 gis g gis
-@}
-\addQuote "flute" @{ \flute @}
-@end example
+The @code{\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
-that indicates the duration of the quote, usually spacer rests or
-multi-measure rests.  The corresponding music (including all articulations,
-dynamics, markup, etc.) from the quoted voice is inserted into the music
-expression:
+for the duration of the quote.
 
 @lilypond[verbatim,quote]
-flute = \relative c'' {
-  a4 gis g->\f gis^\markup{quoted}
+fluteNotes = \relative c'' {
+  a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
 }
-\addQuote "flute" { \flute }
 
-\relative c' {
-  c4 cis \quoteDuring #"flute" { s2 }
+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 for @code{\quoteDuring} contains
-anything but a spacer rest or multi-measure rest, a polyphonic
-situation is created, which is often not desirable:
+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]
-flute = \relative c'' {
-  a4 gis g gis
+fluteNotes = \relative c'' {
+  a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
 }
-\addQuote "flute" { \flute }
 
-\relative c' {
-  c4 cis \quoteDuring #"flute" { c4 b }
+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
 
-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}.
+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]
-clarinet = \relative c'' {
+clarinetNotes = \relative c'' {
   \transposition bes
-  a4 gis g gis
+  \key d \major
+  b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
 }
-\addQuote "clarinet" { \clarinet }
 
-\relative c' {
-  c4 cis \quoteDuring #"clarinet" { s2 }
+oboeNotes = \relative c'' {
+  c4 cis c b \quoteDuring #"clarinet" { s1 }
 }
-@end lilypond
 
-It is possible to tag quotations with unique names in order to
-process them in different ways.  For details about this procedure,
-see @ref{Using tags}.
+\addQuote "clarinet" { \clarinetNotes }
 
-It is also possible to adjust which objects from the original voice are quoted
-by changing the @code{quotedEventTypes} property.  By default, its value is
-@code{#'(StreamEvent)}, which means that everything is quoted.  Setting it
-to e.g. @code{#'(note-event rest-event tie-event)} causes lilypond to quote
-only notes, rests and ties, but no articulations, markup or dynamics.
 
-@lilypond[verbatim,quote]
-clarinet = \relative c'' {
-  a4 gis g->\f gis^\markup{quoted}
-}
-\addQuote "clarinet" { \clarinet }
-
-\relative c' {
-  \set Score.quotedEventTypes = #'(note-event rest-event tie-event)
-  c4 cis \quoteDuring #"clarinet" { s2 }
+\score {
+  <<
+    \new Staff \with { instrumentName = "Clarinet" } \clarinetNotes
+    \new Staff \with { instrumentName = "Oboe" } \oboeNotes
+  >>
 }
 @end lilypond
 
-@snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{quoting-another-voice-with-transposition.ly}
-
 @cindex note-event
 @cindex articulation-event
 @cindex dynamic-event
 @cindex rest-event
+@cindex slur-event
+@cindex crescendo-event
 
 @funindex quotedEventTypes
 @funindex quotedCueEventTypes
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{quoting-another-voice.ly}
+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}.
 
+Installed Files:
+@file{scm/define-event-classes.scm}.
+
 Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:
+@rinternals{Music classes},
 @rinternals{QuoteMusic},
 @rinternals{Voice}.
 
-
 @knownissues
-
 Only the contents of the first @code{Voice} occurring in an
-@code{\addQuote} command will be considered for quotation, so
-@var{music} cannot contain @code{\new} and @code{\context Voice}
-statements that would switch to a different Voice.
-
-Quoting grace notes is broken and can even cause LilyPond to
-crash.
-
-Quoting nested triplets may result in poor notation.
-
-In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
-written entirely in lower-case letters: @code{\addquote}.
+@code{\addQuote} command will be considered for quotation, so if the music
+expression contains @code{\new} or @code{\context Voice}
+statements, their contents will not be quoted.  Quoting grace notes
+is unsupported and may cause LilyPond to crash whereas quoting nested
+triplets may result in poor notation.
 
 
 @node Formatting cue notes
 @unnumberedsubsubsec Formatting cue notes
 
-@cindex cues
 @cindex cue notes
-@cindex cue notes, formatting
 @cindex fragments
-@cindex quoting other voices
-@cindex cues, formatting
+@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
 
-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:
+@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{partname} #@var{voice} @var{music}
+\cueDuring #@var{quotename} #@var{direction} #@var{music}
 @end example
 
-This command copies only the notes and rests from 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.
+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 a @code{CueVoice} context and occurs simultaneously with the
+@code{@var{music}}, which then creates a polyphonic situation.  The
+@code{@var{direction}} takes the argument @code{UP} or @code{DOWN}, and
+corresponds to the first and second voices respectively, determining how
+the cue notes are printed in relation to the other voice.
 
 @lilypond[verbatim,quote]
-oboe = \relative c'' {
-  r2 r8 d16(\f f e g f a)
-  g8 g16 g g2.
+fluteNotes = \relative c'' {
+  r2. c4 | d8 c d e fis2 | g2 d |
 }
-\addQuote "oboe" { \oboe }
 
-\new Voice \relative c'' {
-  \cueDuring #"oboe" #UP { R1 }
+oboeNotes = \relative c'' {
+  R1
+  \new CueVoice { \set instrumentCueName = "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, rest, ties, beams and
-tuplets are quoted, but not articulations, dynamic marks, markup etc.
+@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.
+
+@warning{When a @code{Voice} starts with @code{\cueDuring}, as in the
+following example, the @code{Voice} context must be explicitly declared,
+or else the entire music expression would belong to the @code{CueVoice}
+context.}
 
 @lilypond[verbatim,quote]
-oboe = \relative c'' {
+oboeNotes = \relative c'' {
   r2 r8 d16(\f f e g f a)
   g8 g16 g g2.
 }
-\addQuote "oboe" { \oboe }
+\addQuote "oboe" { \oboeNotes }
 
 \new Voice \relative c'' {
   \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
@@ -1242,121 +1344,159 @@ oboe = \relative c'' {
 }
 @end lilypond
 
-
-
-The name of the cued instrument can be printed by setting the
-@code{instrumentCueName} property in the @code{CueVoice} context.
+The name of the instrument playing the cue can be printed by setting
+the @code{instrumentCueName} property in a temporary @code{CueVoice}
+context.  The placement and style of the @code{instrumentCueName} is
+controlled by the @code{\instrumentSwitch} object, see
+@ref{Instrument names}.  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]
-oboe = \relative c''' {
-  g4 r8 e16 f e4 d
+fluteNotes = \relative c'' {
+  r2. c4 d8 c d e fis2 g2 d2
 }
-\addQuote "oboe" { \oboe }
 
-\new Staff \relative c'' <<
-  \new CueVoice \with {
-    instrumentCueName = "ob."
-  }
-  \new Voice {
-    \cueDuring #"oboe" #UP { R1 }
-    g4. b8 d2
-  }
->>
-@end lilypond
+bassoonNotes = \relative c {
+  \clef bass
+  R1
+  \clef treble
+  \new CueVoice { \set instrumentCueName = "flute" }
+  \cueDuring #"flute" #UP { R1 }
+  \clef bass
+  g4. b8 d2
+}
 
-@cindex removing cues
-@cindex removing cue notes
-@cindex cue notes, removing
+\addQuote "flute" { \fluteNotes }
 
-@funindex \killCues
-@funindex killCues
-@funindex \transposedCueDuring
-@funindex transposedCueDuring
-
-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}.
+\new Staff {
+  \bassoonNotes
+}
+@end lilypond
 
-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.
+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]
-flute = \relative c''' {
-  r2 cis2 r2 dis2
+fluteNotes = \relative c'' {
+  r2. c4 d8 c d e fis2 g2 d2
 }
-\addQuote "flute" { \flute }
 
-\new Voice \relative c'' {
-  \killCues {
-    \cueDuring #"flute" #UP { R1 }
-    g4. b8 d2
-  }
+bassoonNotes = \relative c {
+  \clef bass
+  R1
+  \new CueVoice { \set instrumentCueName = "flute" }
+  \cueDuringWithClef #"flute" #UP #"treble" { R1 }
+  g4. b8 d2
+}
+
+\addQuote "flute" { \fluteNotes }
+
+\new Staff {
+  \bassoonNotes
 }
 @end lilypond
 
-The @code{\transposedCueDuring} command is useful for adding
-instrumental cues from a completely different register.  The
-syntax is similar to @code{\cueDuring}, but it requires one extra
-argument to specify the transposition of the cued instrument.  For
-more information about transposition, see
-@ref{Instrument transpositions}.
+@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]
-piccolo = \relative c''' {
+piccoloNotes = \relative c''' {
   \clef "treble^8"
   R1
   c8 c c e g2
-  a4 g g2
+  c4 g g2
 }
-\addQuote "piccolo" { \piccolo }
 
-cbassoon = \relative c, {
-  \clef "bass_8"
-  c4 r g r
-  \transposedCueDuring #"piccolo" #UP c,, { R1 }
-  c4 r g r
+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 = "piccolo" \piccolo
-  \new Staff = "cbassoon" \cbassoon
+  \new Staff \piccoloNotes
+  \new Staff \bassClarinetNotes
 >>
 @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}.
+@cindex removing cue notes
+@cindex cue notes, removing
 
-@cindex notes, smaller
-@cindex smaller notes
+@funindex \killCues
+@funindex killCues
+@funindex \addInstrumentDefinition
+@funindex addInstrumentDefinition
 
-A @code{CueVoice} context may be created explicitly if notes of a
-smaller size are required, for example to set an alternative
-sequence of notes more suitable for a higher or lower voice.
+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,relative=2]
-\time 12/8
-\key ees \major
-g4 ees8 f4 g8
-\stemDown
-<<
-  { d4. bes4 c8 }
-  \new CueVoice
-  { g'4. f4 ees8 }
+@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
+    \new CueVoice { \set instrumentCueName = "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 } }
+  }
 >>
-\stemUp
-d2. d2.
 @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:
@@ -1366,9 +1506,10 @@ Internals Reference:
 @rinternals{CueVoice},
 @rinternals{Voice}.
 
-
 @knownissues
-
 Collisions can occur with rests, when using @code{\cueDuring},
-between @code{Voice} and @code{CueVoice} contexts.
+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.