From 661b60b40def1e84fe8c35b8396c1ec667e54751 Mon Sep 17 00:00:00 2001
From: Valentin Villenave <address@hidden>
Date: Tue, 26 Oct 2010 23:15:45 +0200
Subject: [PATCH] CueVoice Documentation improvement.

---
 Documentation/notation/staff.itely |  169 ++----------------------------------
 1 files changed, 7 insertions(+), 162 deletions(-)

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index f256e56..5d6af07 100644
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -1180,173 +1180,18 @@ written entirely in lower-case letters: @code{\addquote}.
 @funindex \quoteDuring
 @funindex quoteDuring
 
-The previous section explains how to create quotations.  The
address@hidden command is a more specialized form of
address@hidden, being particularly useful for inserting cue
-notes into a part.  The syntax is as follows:
address@hidden
 
address@hidden
-\cueDuring address@hidden address@hidden @var{music}
address@hidden example
-
-This command copies only the notes and rests from the
-corresponding measures from @address@hidden into a
address@hidden context.  The @code{CueVoice} is created
-implicitly, and occurs simultaneously with @address@hidden,
-which creates a polyphonic situation.  The @address@hidden
-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.
-
address@hidden,quote]
-oboe = \relative c'' {
-  r2 r8 d16(\f f e g f a)
-  g8 g16 g g2.
-}
-\addQuote "oboe" { \oboe }
-
-\new Voice \relative c'' {
-  \cueDuring #"oboe" #UP { R1 }
-  g2 c,
-}
address@hidden lilypond
-
address@hidden
-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
address@hidden 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.
-
address@hidden,quote]
-oboe = \relative c'' {
-  r2 r8 d16(\f f e g f a)
-  g8 g16 g g2.
-}
-\addQuote "oboe" { \oboe }
-
-\new Voice \relative c'' {
-  \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
-                                      beam-event tuplet-span-event
-                                      dynamic-event slur-event)
-  \cueDuring #"oboe" #UP { R1 }
-  g2 c,
-}
address@hidden lilypond
-
-
-
-The name of the cued instrument can be printed by setting the
address@hidden property in the @code{CueVoice} context.
-
address@hidden,quote]
-oboe = \relative c''' {
-  g4 r8 e16 f e4 d
-}
-\addQuote "oboe" { \oboe }
-
-\new Staff \relative c'' <<
-  \new CueVoice \with {
-    instrumentCueName = "ob."
-  }
-  \new Voice {
-    \cueDuring #"oboe" #UP { R1 }
-    g4. b8 d2
-  }
->>
address@hidden lilypond
+The first rule of using CueVoice is:
+don't use CueVoice.
 
address@hidden removing cues
address@hidden removing cue notes
address@hidden cue notes, removing
+The second rule of using CueVoice is:
+do NOT use CueVoice.
 
address@hidden \killCues
address@hidden killCues
address@hidden \transposedCueDuring
address@hidden 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
address@hidden and @code{\instrumentSwitch}.  For
-an example and explanation, see @ref{Instrument names}.
-
-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.
-
address@hidden,quote]
-flute = \relative c''' {
-  r2 cis2 r2 dis2
-}
-\addQuote "flute" { \flute }
-
-\new Voice \relative c'' {
-  \killCues {
-    \cueDuring #"flute" #UP { R1 }
-    g4. b8 d2
-  }
-}
address@hidden 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
address@hidden transpositions}.
-
address@hidden,quote]
-piccolo = \relative c''' {
-  \clef "treble^8"
-  R1
-  c8 c c e g2
-  a4 g g2
+The third rule of
+... well, you get the picture.
 }
-\addQuote "piccolo" { \piccolo }
 
-cbassoon = \relative c, {
-  \clef "bass_8"
-  c4 r g r
-  \transposedCueDuring #"piccolo" #UP c,, { R1 }
-  c4 r g r
-}
-
-<<
-  \new Staff = "piccolo" \piccolo
-  \new Staff = "cbassoon" \cbassoon
->>
address@hidden 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}.
-
address@hidden notes, smaller
address@hidden 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.
-
address@hidden,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.
address@hidden lilypond
 
 
 @seealso
-- 
1.7.3.1