Fix 1214: Don't crash with \relative c' \new Voice {...}

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

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index 5d718aa1fd2fc8ad40aa512e416dcb4667e2150d..2ac12942588040d1c86c482b8be26963a7f7ef95 100644 (file)
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.13.36"
+@c \version "2.14.0"

 
 @node Staff notation
 @section Staff notation
 
 @node Staff notation
 @section Staff notation


@@ -1019,9 +1019,9 @@ Internals Reference:
 @node Quoting other voices
 @unnumberedsubsubsec Quoting other voices
 
 @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
 @cindex cue notes
 
 @funindex \addQuote


@@ -1031,113 +1031,128 @@ Internals Reference:
 @funindex \transposition
 @funindex transposition
 
 @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.
-
-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:
+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.

 
 

-@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
 
 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]
 
 @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
 
 }
 @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]
 
 @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
 
 }
 @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]
 
 @lilypond[verbatim,quote]

-clarinet = \relative c'' {
+clarinetNotes = \relative c'' {

   \transposition bes
   \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
 
 }
 @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 note-event
 @cindex articulation-event
 @cindex dynamic-event
 @cindex rest-event

+@cindex slur-event
+@cindex crescendo-event

 
 @funindex quotedEventTypes
 @funindex quotedCueEventTypes
 
 
 @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:
 
 @seealso
 Notation Reference:


@@ -1148,77 +1163,136 @@ Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:
 @rlsr{Staff notation}.
 
 Internals Reference:

+@rinternals{Music classes},

 @rinternals{QuoteMusic},
 @rinternals{Voice}.
 
 @rinternals{QuoteMusic},
 @rinternals{Voice}.
 

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

 
 

-@knownissues

 
 

+@knownissues

 Only the contents of the first @code{Voice} occurring in an
 Only the contents of the first @code{Voice} occurring in an

-@code{\addQuote} command will be considered for quotation, so
-@code{@var{music}} cannot contain @code{\new} and
-@code{\context Voice} statements that would switch to a different
-Voice.
-
-Quoting grace notes is broken and can even cause LilyPond to
-crash.
-
-Quoting nested triplets may result in poor notation.
-
-In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
-written entirely in lower-case letters: @code{\addquote}.
+@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
 
 
 
 @node Formatting cue notes
 @unnumberedsubsubsec Formatting cue notes
 

-@cindex cues

 @cindex cue notes
 @cindex cue notes

-@cindex cue notes, formatting

 @cindex fragments
 @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 \cueDuring
 @funindex cueDuring

+@funindex \cueClef
+@funindex cueClef
+@funindex \cueDuringWithClef
+@funindex cueDuringWithClef

 @funindex \quoteDuring
 @funindex quoteDuring
 
 @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{quotename} #@var{direction} #@var{music}
+@end example
+
+and

 
 @example
 
 @example

-\cueDuring #@var{partname} #@var{voice} @var{music}
+\cueDuringWithClef #@var{quotename} #@var{direction} #@var{clef} #@var{music}

 @end example
 
 @end example
 

-This command copies only the notes and rests from the
-corresponding measures from @code{@var{partname}} into a
-@code{CueVoice} context.  The @code{CueVoice} is created
-implicitly, and occurs simultaneously with @code{@var{music}},
-which creates a polyphonic situation.  The @code{@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.
+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]
 
 @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
+  s1*0^\markup { \tiny "flute" }
+  \cueDuring #"flute" #UP { R1 }

   g2 c,
 }
   g2 c,
 }

+
+\addQuote "flute" { \fluteNotes }
+
+\new Staff {
+  \oboeNotes
+}

 @end lilypond
 
 @noindent
 @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}
 
 It is possible to adjust which aspects of the music are quoted with
 @code{\cueDuring} by setting the @code{quotedCueEventTypes}


@@ -1227,12 +1301,16 @@ 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.
 
 notes, rests, ties, beams and tuplets are quoted, but not
 articulations, dynamic marks, markup etc.
 

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

-oboe = \relative c'' {
+oboeNotes = \relative c'' {

   r2 r8 d16(\f f e g f a)
   g8 g16 g g2.
 }
   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
 
 \new Voice \relative c'' {
   \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event


@@ -1244,14 +1322,16 @@ oboe = \relative c'' {
 @end lilypond
 
 Markup can be used to show the name of the quoted instrument.  Also,
 @end lilypond
 
 Markup can be used to show the name of the quoted instrument.  Also,

-if the cue notes require a change in clef, the original clef should
-be restored at the end of the cue notes.
+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]
 
 @lilypond[verbatim,quote]

-flute = \relative c'' {
+fluteNotes = \relative c'' {

   r2. c4 d8 c d e fis2 g2 d2
 }
   r2. c4 d8 c d e fis2 g2 d2
 }

-bassoon = \relative c {
+
+bassoonNotes = \relative c {

   \clef bass
   R1
   \clef treble
   \clef bass
   R1
   \clef treble


@@ -1260,62 +1340,39 @@ bassoon = \relative c {
   \clef bass
   g4. b8 d2
 }
   \clef bass
   g4. b8 d2
 }

-\addQuote "flute" { \flute }
+
+\addQuote "flute" { \fluteNotes }
+

 \new Staff {
 \new Staff {

-  \bassoon
+  \bassoonNotes

 }
 @end lilypond
 
 }
 @end lilypond
 

-@cindex removing cues
-@cindex removing cue notes
-@cindex cue notes, removing
-
-@funindex \killCues
-@funindex killCues
-
-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}.
+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]
 
 @lilypond[verbatim,quote]

-flute = \relative c'' {
+fluteNotes = \relative c'' {

   r2. c4 d8 c d e fis2 g2 d2
 }
   r2. c4 d8 c d e fis2 g2 d2
 }

-bassoon = \relative c {
+
+bassoonNotes = \relative c {

   \clef bass
   R1
   \clef bass
   R1

-  \tag #'part {
-    \clef treble
-    s1*0^\markup { \tiny "flute" }
-  }
-  \cueDuring #"flute" #UP { R1 }
-  \tag #'part \clef bass
+  s1*0^\markup { \tiny "flute" }
+  \cueDuringWithClef #"flute" #UP #"treble" { R1 }

   g4. b8 d2
 }
   g4. b8 d2
 }

-\addQuote "flute" { \flute }
+
+\addQuote "flute" { \fluteNotes }

 
 \new Staff {
 
 \new Staff {

-  \bassoon
+  \bassoonNotes

 }
 }

-\new StaffGroup <<
-  \new Staff {
-    \flute
-  }
-  \new Staff {
-    \removeWithTag #'part { \killCues { \bassoon } }
-  }
->>

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

 @funindex \transposedCueDuring
 @funindex transposedCueDuring
 
 @funindex \transposedCueDuring
 @funindex transposedCueDuring
 


@@ -1331,13 +1388,14 @@ 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]
 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
   c4 g g2
 }
   \clef "treble^8"
   R1
   c8 c c e g2
   c4 g g2
 }

-bassClarinet = \relative c' {
+
+bassClarinetNotes = \relative c' {

   \key d \major
   \transposition bes,
   d4 r a r
   \key d \major
   \transposition bes,
   d4 r a r


@@ -1345,40 +1403,74 @@ bassClarinet = \relative c' {
   d4 r a r
 }
 
   d4 r a r
 }
 

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

 
 <<
 
 <<

-  \new Staff \piccolo
-  \new Staff \bassClarinet
+  \new Staff \piccoloNotes
+  \new Staff \bassClarinetNotes

 >>
 @end lilypond
 
 >>
 @end lilypond
 

-@cindex notes, smaller
-@cindex smaller notes
+@cindex removing cue notes
+@cindex cue notes, removing

 
 

-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.
+@funindex \killCues
+@funindex killCues
+@funindex \addInstrumentDefinition
+@funindex addInstrumentDefinition

 
 

-@lilypond[verbatim,relative=2]
-\time 12/8
-\key ees \major
-g4 ees8 f4 g8
-\stemDown
-<<
-  { d4. bes4 c8 }
-  \new CueVoice
-  { g'4. f4 ees8 }
+The @code{\killCues} command removes cue notes from a music
+expression, so the same music expression can be used to produce
+the instrument part with cues and the score.  The @code{\killCues}
+command removes only the notes and events that were quoted by
+@code{\cueDuring}.  Other markup associated with cues, such as clef
+changes and a label identifying the source instrument, can be
+tagged for selective inclusion in the score; see @ref{Using tags}.
+
+@lilypond[verbatim,quote]
+fluteNotes = \relative c'' {
+  r2. c4 d8 c d e fis2 g2 d2
+}
+
+bassoonNotes = \relative c {
+  \clef bass
+  R1
+  \tag #'part {
+    \clef treble
+    s1*0^\markup { \tiny "flute" }
+  }
+  \cueDuring #"flute" #UP { R1 }
+  \tag #'part \clef bass
+  g4. b8 d2
+}
+
+\addQuote "flute" { \fluteNotes }
+
+\new Staff {
+  \bassoonNotes
+}
+
+\new StaffGroup <<
+  \new Staff {
+    \fluteNotes
+  }
+  \new Staff {
+    \removeWithTag #'part { \killCues { \bassoonNotes } }
+  }

 >>
 >>

-\stemUp
-d2. d2.

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

+@ref{Quoting other voices},

 @ref{Instrument transpositions},
 @ref{Instrument names},
 @ref{Instrument transpositions},
 @ref{Instrument names},

+@ref{Clef},

 @ref{Musical cues},
 @ref{Using tags}.
 
 @ref{Musical cues},
 @ref{Using tags}.
 


@@ -1393,5 +1485,8 @@ Internals Reference:
 @knownissues
 
 Collisions can occur with rests, when using @code{\cueDuring},
 @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.