Doc: NR 1.6.3 Added cueDuringWithClef

Doc: NR 1.6.3 Added cueDuringWithClef and cueClef

Documented how to use cueDuringWithClef

Tracker issue 1658

Also updated some of the original examples to differentiate between
strings used for music and those used for the variables in order
to make the examples clearer

Added appropriate @funindex

Also moved \killcues to the end as it seemed more appropriate to have
'how to create all the cue stuff' first and then how to 'kill' them
at the end. Also added an @knownissue about making sure that certain
arguments are in the correct order.

[Graham Percival (old account), 2011-06-01 22:29:49]

LGTM, wait maybe a day then push.

[Trevor Daniels, 2011-06-02 07:10:26]

LGTM, apart from minor changes noted

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.itely
File Documentation/notation/staff.itely (right):

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1285: g4. b8 d2
Restore the R1.  A cue is used to indicate when a part
should begin playing again, so it is more realistic to
show cue notes after a period of resting.

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1301: print the original clef once the cur
notes have finished.
cue

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1309: g4. b8 d2
R1

[pkx166h, 2011-06-02 09:18:06]

Second Draft

I also just want to check with Reinhold as all I have done here is document the
\cueDuringWithClef function (as that is what is in the Reg tests).

So is there an explicit \cueClef command that would be used in a different case
and should we be bothering to document that or not with an example?

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.itely
File Documentation/notation/staff.itely (right):

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1285: g4. b8 d2
On 2011/06/02 07:10:26, Trevor Daniels wrote:
> Restore the R1.  A cue is used to indicate when a part
> should begin playing again, so it is more realistic to
> show cue notes after a period of resting.

Done.

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1301: print the original clef once the cur
notes have finished.
On 2011/06/02 07:10:26, Trevor Daniels wrote:
> cue

Done.

http://codereview.appspot.com/4568046/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1309: g4. b8 d2
On 2011/06/02 07:10:26, Trevor Daniels wrote:
> R1

Done.

[Reinhold, 2011-06-02 13:27:38]

On 2011/06/02 09:18:06, J_lowe wrote:
> Second Draft
> 
> I also just want to check with Reinhold as all I have done here is document
the
> \cueDuringWithClef function (as that is what is in the Reg tests).
> 
> So is there an explicit \cueClef command that would be used in a different
case
> and should we be bothering to document that or not with an example?

Yes, there is a \cueClef command, which I actually intended to be an internal
function (together with \cueClefUnset) for the \cueDuringWithClef. As it turns
out, however, it has some real-world use if you want to add cue notes explicitly
rather than quoting some other voice. 

Here's a simple example:
\version "2.13.60"

Solo = \relative c' { 
  c4 c c c |

  % Manually written cue notes, not quoted from another lilypond voice:
  << 
    { \voiceTwo R1 \oneVoice }
    \new CueVoice 
    {
      \cueClef "bass"
      \voiceOne
      c4 c c c |
      \cueClefUnset 
    }
  >>
  c4 c c c |
}

\score {
  <<
    \new Staff \Solo
  >>
}


The other snippet that might be added is to show how the cue-clef can be changed
to be printed after the barline rather than before:

\version "2.13.45"

instrument = \relative c' {
  \repeat unfold 40 { c8 }
}
\addQuote "instrQuote" \instrument

Solo = \relative c' { 
  c2 c |
  
  % Change the break-align-orders of the score so that cue-clef comes after
bar-line
  \override Score.BarLine #'space-alist #'cue-clef = #'(minimum-space . 1.0)
  \override Score.BreakAlignment #'break-align-orders  =
    ##(( ;; end-of-line:
         left-edge cue-end-clef ambitus breathing-sign clef staff-bar
         key-cancellation key-signature time-signature cue-clef custos)
       ( ;; unbroken
         left-edge cue-end-clef ambitus breathing-sign clef staff-bar
         key-cancellation key-signature time-signature cue-clef custos)
       ( ;; begin of line
         left-edge ambitus breathing-sign clef key-cancellation
         key-signature staff-bar time-signature cue-clef custos))

  \cueDuringWithClef #"instrQuote" #UP #"bass" { R1 }
  c2 c2 |
  
  % Revert back to default
  \revert Score.BarLine #'space-alist #'cue-clef 
  \revert Score.BreakAlignment #'break-align-orders
  \cueDuringWithClef #"instrQuote" #UP #"bass" { R1 }
  c2 c2 |
}

\score {
  <<
    \new Staff \Solo
  >>
}


I'll add both snippets to the regtests a little later.

[pkx166h, 2011-06-06 15:19:07]

Pushed as 

ffd9d60d597d14bef71efed7b623ab4a93efb12

Solved this one I'll update the tracker. Thanks.