Doc: Added \cueClef command

Added usage of \cueClef and \cueClefUnset commands.

Added some @cindex and @funindex entries

Moved the small section for cueVoice to the top and updated the first two examples
to be more in keeping with the preceding examples added for
\cueDuringWithCleff.

Added new @lilyponds showing how to use \cueClef with CueVoice

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index 8b99a71d6608f69bdc08f4956e09a11bdd9275d6..56f493617d36022ac048837f9981d54f986bef60 100644 (file)
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -1191,49 +1191,112 @@ written entirely in lower-case letters: @code{\addquote}.
 @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 @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.
+and
+
+@example
+\cueDuringWithClef #@var{quotename} #@var{direction} #@var{clef} #@var{music}
+@end example
+
+The music from the corresponding measures of the @code{@var{quote name}}
+is added as @code{CueVoice} context and occurs simultaneously with the
+@code{@var{music}}, which creates a polyphonic situation.  The
+@code{@var{direction}} takes the argument @code{UP} or @code{DOWN}, and
+corresponds to first and second voices respectively determining how
+the cue notes are printed in relation to the other voice.
 
 @lilypond[verbatim,quote]
-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,
 }
+
+\addQuote "flute" { \fluteNotes }
+
+\new Staff {
+  \oboeNotes
+}
 @end lilypond
 
 @noindent
@@ -1273,6 +1336,7 @@ notes.
 fluteNotes = \relative c'' {
   r2. c4 d8 c d e fis2 g2 d2
 }
+
 bassoonNotes = \relative c {
   \clef bass
   R1
@@ -1282,7 +1346,9 @@ bassoonNotes = \relative c {
   \clef bass
   g4. b8 d2
 }
+
 \addQuote "flute" { \fluteNotes }
+
 \new Staff {
   \bassoonNotes
 }
@@ -1297,6 +1363,7 @@ print the original clef once the cue notes have finished.
 fluteNotes = \relative c'' {
   r2. c4 d8 c d e fis2 g2 d2
 }
+
 bassoonNotes = \relative c {
   \clef bass
   R1
@@ -1304,7 +1371,9 @@ bassoonNotes = \relative c {
   \cueDuringWithClef #"flute" #UP #"treble" { R1 }
   g4. b8 d2
 }
+
 \addQuote "flute" { \fluteNotes }
+
 \new Staff {
   \bassoonNotes
 }
@@ -1331,6 +1400,7 @@ piccoloNotes = \relative c''' {
   c8 c c e g2
   c4 g g2
 }
+
 bassClarinetNotes = \relative c' {
   \key d \major
   \transposition bes,
@@ -1347,33 +1417,13 @@ bassClarinetNotes = \relative c' {
 >>
 @end lilypond
 
-@cindex notes, smaller
-@cindex smaller notes
-
-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.
-
-@lilypond[verbatim,relative=2]
-\time 12/8
-\key ees \major
-g4 ees8 f4 g8
-\stemDown
-<<
-  { d4. bes4 c8 }
-  \new CueVoice
-  { g'4. f4 ees8 }
->>
-\stemUp
-d2. d2.
-@end lilypond
-
-@cindex removing cues
 @cindex removing cue notes
 @cindex cue notes, removing
 
 @funindex \killCues
 @funindex killCues
+@funindex \addInstrumentDefinition
+@funindex addInstrumentDefinition
 
 The @code{\killCues} command removes cue notes from a music
 expression, so the same music expression can be used to produce
@@ -1387,6 +1437,7 @@ tagged for selective inclusion in the score; see @ref{Using tags}.
 fluteNotes = \relative c'' {
   r2. c4 d8 c d e fis2 g2 d2
 }
+
 bassoonNotes = \relative c {
   \clef bass
   R1
@@ -1398,11 +1449,13 @@ bassoonNotes = \relative c {
   \tag #'part \clef bass
   g4. b8 d2
 }
+
 \addQuote "flute" { \fluteNotes }
 
 \new Staff {
   \bassoonNotes
 }
+
 \new StaffGroup <<
   \new Staff {
     \fluteNotes
@@ -1415,12 +1468,12 @@ bassoonNotes = \relative c {
 
 Alternatively, Clef changes and instrument labels can be
 collected into an instrument definition for repeated use, using
-@code{\addInstrumentDefinition} described in
-@ref{Instrument names}.
+@code{\addInstrumentDefinition} described in @ref{Instrument names}.
 
 
 @seealso
 Notation Reference:
+@ref{Quoting other voices},
 @ref{Instrument transpositions},
 @ref{Instrument names},
 @ref{Musical cues},