Doc: NR 1.6.3 - edit eg.s in quoting other voices

Doc: NR 1.6.3 - edit eg.s in quoting other voices

Suggestion from Keith O'Hara.

An attempt to give a more realistic example than what was previously there.

It also helps emphasise that it must be made at the top level but also that the
order of the \quoteDurings and \addQuotes is not prescribed.

Minor improvements of syntax and I moved around some of the information
to make it flow more easily. Removed unnecessary text (either redundant,
repeated or shown in the example).

[Graham Percival (old account), 2011-05-10 19:59:35]

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

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1022: @cindex quote, voices
could we keep the old @cindex as well?  I'm fine with adding the new ones; just
don't remove the old ones.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1045: \addQuote "flute" @{ \fluteNotes @}
could we keep a definition for \fluteNotes ?  again, I'm happy to have the name
change, but I'd like to see some notes actually being defined.

alternately, remove the @example and just go directly into the @lilypond.  That
would be my first instinct, actually, although I can't claim to have looked at
this in detail.

[Keith, 2011-05-11 03:26:40]

My suggestion was tiny compared to this patch.

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

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1086: Quotations recognize instrument
transposition settings for both
I added this text only a couple months ago, so of course I suggest to keep it.
I think we need to amplify the point that \quoteDuring handles transpositions of
both quoted and quoting parts.  This is the main point of the \transposition
command, but the section @ref{instrument transpositions} does not explain it
very well because it does not have this example showing how \quoteDuring works.

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

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1040: Before a part can be quoted, the
@code{\addQuote} command must be used,
In the original, 'before' was misleading, and we are not initializing a
'fragment'. A true statement is:
  The @code{\addQuote} command, used in the top level scope, defines a stream of
music from which fragments can be quoted.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1045: \addQuote "flute" @{ \fluteNotes @}
> remove the @example and just go directly into the @lilypond.  

That would be better.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1072: If the music expression used in
@code{\quoteDuring} contains notes
I suggest removing this whole paragraph and @lilypond.
1. The original text was wrong: \quoteDuring does not create another Voice for
polyphony; instead it adds notes to the existing Voice to make chords.
2. Using \cueDuring, by contrast, *does* add a voice and create a polyphonic
situation, and in fact I have found that to be useful, but was discouraged from
trying it because of the old text.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1082: c4 cis c b \quoteDuring #"flute" { e4
dis b a }
  c4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
If you do decide to keep this @lilypond, at least make it output something
sensible.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1101: a4 gis g gis | b4^"quoted" r8 ais\p a4(
f)
  \key d\major
  b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
so that this example realistically shows the same concert-pitch notes as the
earlier examples. 
(I should have caught this error months ago.)

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1120: markups, etc. and is inserted into the
music expression.  It is possible
markups, etc. --[and is inserted into the music expression]--

[pkx166h, 2011-05-11 16:15:25]

Second Draft

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

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1022: @cindex quote, voices
On 2011/05/10 19:59:35, Graham Percival wrote:
> could we keep the old @cindex as well?  I'm fine with adding the new ones;
just
> don't remove the old ones.

I didn't remove as much as reword for clarity. Else we get into semantics about
(for example) cues vs cue notes (cues means nothing - snooker cues? 'cue notes'
is what they are properly called). Again 'Fragments' is meaningless in an index
without some context - which I added (Fragments, quoting).

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1045: \addQuote "flute" @{ \fluteNotes @}
On 2011/05/11 03:26:40, Keith wrote:
> > remove the @example and just go directly into the @lilypond.  
> 
> That would be better.

Done.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1045: \addQuote "flute" @{ \fluteNotes @}
On 2011/05/10 19:59:35, Graham Percival wrote:
> could we keep a definition for \fluteNotes ?  again, I'm happy to have the
name
> change, but I'd like to see some notes actually being defined.
> 
> alternately, remove the @example and just go directly into the @lilypond. 
That
> would be my first instinct, actually, although I can't claim to have looked at
> this in detail.

Done.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1072: If the music expression used in
@code{\quoteDuring} contains notes
On 2011/05/11 03:26:40, Keith wrote:
> I suggest removing this whole paragraph and @lilypond.
> 1. The original text was wrong: \quoteDuring does not create another Voice for
> polyphony; instead it adds notes to the existing Voice to make chords.
> 2. Using \cueDuring, by contrast, *does* add a voice and create a polyphonic
> situation, and in fact I have found that to be useful, but was discouraged
from
> trying it because of the old text.

I think we need something, somewhere about this, as it would appear that this is
a nice way to add polyphony - even if it isn't and to be honest I don't know
what the difference is, or the subtlety is lost on me. It LOOKS like polyphony.

Maybe an appropriate @KNOWNISSUE?

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1082: c4 cis c b \quoteDuring #"flute" { e4
dis b a }
On 2011/05/11 03:26:40, Keith wrote:
>   c4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
> If you do decide to keep this @lilypond, at least make it output something
> sensible.

Kept it in for now until we decide on the last comment.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1101: a4 gis g gis | b4^"quoted" r8 ais\p a4(
f)
On 2011/05/11 03:26:40, Keith wrote:
>   \key d\major
>   b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
> so that this example realistically shows the same concert-pitch notes as the
> earlier examples. 
> (I should have caught this error months ago.)

Done.

http://codereview.appspot.com/4518053/diff/1/Documentation/notation/staff.ite...
Documentation/notation/staff.itely:1120: markups, etc. and is inserted into the
music expression.  It is possible
On 2011/05/11 03:26:40, Keith wrote:
> markups, etc. --[and is inserted into the music expression]--

Not sure what you wanted here, but I have improved this awkward sentence anyway.

[Keith, 2011-05-11 17:47:14]

LGTM

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

http://codereview.appspot.com/4518053/diff/5001/Documentation/notation/staff....
Documentation/notation/staff.itely:1090: The @code{\transposition} command can
also be used with quotes.  See
I added the former text at this point only a couple months ago, so I think we
need a bit more explanation.  Maybe :
  "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."

Section @ref{instrument transpositions} does not explain this point very well,
because an example of quoting is required to really explain it.

[pkx166h, 2011-05-12 12:24:22]

Nearly there I hope.

Third draft.

James

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

http://codereview.appspot.com/4518053/diff/5001/Documentation/notation/staff....
Documentation/notation/staff.itely:1090: The @code{\transposition} command can
also be used with quotes.  See
On 2011/05/11 17:47:14, Keith wrote:
> I added the former text at this point only a couple months ago, so I think we
> need a bit more explanation.  Maybe :
>   "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."
> 
> Section @ref{instrument transpositions} does not explain this point very well,
> because an example of quoting is required to really explain it.

Done. 

I also removed the @ref from this para so as to not infer that this @ref gives
more explanation for quoted examples. I can leave it in the @seealso for users
who want to know more about transposition generally.

[Graham Percival (old account), 2011-05-12 13:35:03]

LGTM

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

http://codereview.appspot.com/4518053/diff/1002/Documentation/notation/staff....
Documentation/notation/staff.itely:1144: Quotes can also be tagged see
@ref{Using tags}.
add comma or semicolon after "tagged".

[pkx166h, 2011-05-12 15:20:55]

Number 4.

James

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

http://codereview.appspot.com/4518053/diff/1002/Documentation/notation/staff....
Documentation/notation/staff.itely:1144: Quotes can also be tagged see
@ref{Using tags}.
On 2011/05/12 13:35:03, Graham Percival wrote:
> add comma or semicolon after "tagged".

Done.

[Graham Percival (old account), 2011-05-12 16:41:07]

On 2011/05/12 15:20:55, J_lowe wrote:
> Number 4.

oops, I didn't mean that you had to upload a new draft -- if Trevor and Keith
don't complain, then go ahead and push this.

[Trevor Daniels, 2011-05-12 16:52:34]

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

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1044: quotation begins.  It is followed by
two arguments; the name of the
The colon was correct here.

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1046: that for the duration of the quote.
Doesn't make sense.  The original looked OK to me.

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1090: The @code{\quoteDuring} command uses
the @\code{\transposition} settings
@code

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1092: that have the same sounding pitch as
those in the quoted part.
Shouldn't the "quoting" and "quoted" be the other way 
around?

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1117: markups, etc. and insert them into the
music expression.  It is possible
markups, etc., in the quoted expression.  It is possible

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1119: not) by using the
@code{quotedEventTypes} context property.
drop (or not)

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1122: expression in the other voice using the
@code{\quoteDuring} function.
Move this rather obscure comment after the following
example, or maybe delete it.

[Keith, 2011-05-12 17:41:10]

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

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1092: that have the same sounding pitch as
those in the quoted part.
On 2011/05/12 16:52:34, Trevor Daniels wrote:
> Shouldn't the "quoting" and "quoted" be the other way 
> around?
Probably doesn't matter much in this sentence, as it says how they are the
same.
My thinking was that, in the example below, oboe is quoting the clarinet,
clarinet is being quoted. \quoteDuring produces notes for the oboe that have the
same sounding pitch as those played by the clarinet.

[pkx166h, 2011-05-13 11:23:24]

5th Draft

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

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1044: quotation begins.  It is followed by
two arguments; the name of the
On 2011/05/12 16:52:34, Trevor Daniels wrote:
> The colon was correct here.

Done.

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1046: that for the duration of the quote.
On 2011/05/12 16:52:34, Trevor Daniels wrote:
> Doesn't make sense.  The original looked OK to me.

Removed the word 'that'.

What I am trying to do here is use 'music expression' than just explicitly state
'spacer rest' or 'multimeasure rest'.

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1090: The @code{\quoteDuring} command uses
the @\code{\transposition} settings
On 2011/05/12 16:52:34, Trevor Daniels wrote:
> @code

Done.

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1117: markups, etc. and insert them into the
music expression.  It is possible
On 2011/05/12 16:52:34, Trevor Daniels wrote:
> markups, etc., in the quoted expression.  It is possible

Done.

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1119: not) by using the
@code{quotedEventTypes} context property.
On 2011/05/12 16:52:34, Trevor Daniels wrote:
> drop (or not)

Done.

http://codereview.appspot.com/4518053/diff/9002/Documentation/notation/staff....
Documentation/notation/staff.itely:1122: expression in the other voice using the
@code{\quoteDuring} function.
On 2011/05/12 16:52:34, Trevor Daniels wrote:
> Move this rather obscure comment after the following
> example, or maybe delete it.

I don't think this is obscure, the point here was telling (and then showing
users) something that they may not have thought about - that by using eventypes
judicially you can get some really flexible behaviour with quotes you don't have
to just quote 'verbatim', so this kills two birds with one stone - shows how to
use eventypes and shows how you can use eventypes for some not-so-obvious
tweaking. It is common to have different dynamics for instance in a part of the
same notes for different parts of an ensemble (esp, if there are more
instruments of one type than another).

[pkx166h, 2011-05-19 16:57:15]

Can I push?

Trevor, do you still object to my last comment about that para?

I am happy for any suggestions, but hopefully have explained my reasoning.

James

[t.daniels_treda.co.uk, 2011-05-20 07:52:22]

pkx166h@gmail.com wrote Thursday, May 19, 2011 5:57 PM

> Trevor, do you still object to my last comment about that para?

The main use for adjusting quotedEventTypes is to
prevent irrelevant clutter being inserted into the 
quoting score, for example dynamics or markup might 
not be appropriate in some cases.  I felt your 
new example failed to make this main point as clear 
as the original.  It also seems rather unrealistic - 
would you ever want to remove ties and rests?  It
leaves people wondering if they have understood it
correctly if they can't see the point of the example.
  
> Can I push?

OK, I'll accept whatever you decide after you've 
considered this again.
 
> James

Trevor

> http://codereview.appspot.com/4518053/

[pkx166h, 2011-05-23 20:37:46]

On 2011/05/20 07:52:22, t.daniels_treda.co.uk wrote:
> mailto:pkx166h@gmail.com wrote Thursday, May 19, 2011 5:57 PM
> 
> > Trevor, do you still object to my last comment about that para?
> 
> The main use for adjusting quotedEventTypes is to
> prevent irrelevant clutter being inserted into the 
> quoting score, for example dynamics or markup might 
> not be appropriate in some cases.  I felt your 
> new example failed to make this main point as clear 
> as the original.  It also seems rather unrealistic - 
> would you ever want to remove ties and rests?  It
> leaves people wondering if they have understood it
> correctly if they can't see the point of the example.
>   
> > Can I push?
> 
> OK, I'll accept whatever you decide after you've 
> considered this again.

I've made a change to the example. I wasn't sure which file I could @ref to as
it wasn't really obvious (to me) to see which default values quoteDuring used -
the text says 'etc.' and it may use them all by default. So if you think we
could @ref a ly file let me know, else this could be good to go?

James

[pkx166h, 2011-05-23 20:38:30]

6th Draft.

James

[Keith, 2011-05-24 05:16:43]

On 2011/05/23 20:38:30, J_lowe wrote:
> 6th Draft.

Still looks fine to me.

[t.daniels_treda.co.uk, 2011-05-24 08:34:42]

<pkx166h@gmail.com> wrote Monday, May 23, 2011 9:37 PM


> I've made a change to the example. I wasn't sure which file I 
> could @ref
> to as it wasn't really obvious (to me) to see which default values
> quoteDuring used - the text says 'etc.' and it may use them all by
> default. So if you think we could @ref a ly file let me know, else 
> this
> could be good to go?

I think it is worth adding Music classes to the
Internal Reference section.  This lists all the
event classes linearly.

You could add at the end of the See Also section:

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

as this shows the hierarchy.

I suggest you push after that :)

Trevor

[Graham Percival (old account), 2011-05-24 09:14:59]

On 2011/05/24 08:34:42, t.daniels_treda.co.uk wrote:
> 
> I think it is worth adding Music classes to the
> Internal Reference section.  This lists all the
> event classes linearly.

That would be a separate issue, of course.
 
> You could add at the end of the See Also section:
> 
> Installed Files: @file{scm/define-event-classes.scm}.

Agreed.
 
> I suggest you push after that :)

Yes.

For clarity, James: add the Installed files bit that Trevor suggested, then
push.  Don't upload another patch for review.

Cheers,
- Graham

[t.daniels_treda.co.uk, 2011-05-24 09:52:51]

percival.music.ca@gmail.com wrote  Tuesday, May 24, 2011 10:14 AM


> On 2011/05/24 08:34:42, t.daniels_treda.co.uk wrote:
> 
>> I think it is worth adding Music classes to the
>> Internal Reference section.  This lists all the
>> event classes linearly.
> 
> That would be a separate issue, of course.

Sorry, I didn't make this clear enough.  There
already is a Music classes in the IR.  All I meant
was add an @ref to it under Internal Reference:

Trevor

[Graham Percival, 2011-05-24 12:00:47]

On Tue, May 24, 2011 at 10:52:56AM +0100, Trevor Daniels wrote:
> percival.music.ca@gmail.com wrote  Tuesday, May 24, 2011 10:14 AM
> >On 2011/05/24 08:34:42, t.daniels_treda.co.uk wrote:
> >
> >>I think it is worth adding Music classes to the
> >>Internal Reference section.  This lists all the
> >>event classes linearly.
> >
> >That would be a separate issue, of course.
> 
> Sorry, I didn't make this clear enough.  There
> already is a Music classes in the IR.  All I meant
> was add an @ref to it under Internal Reference:

oh, I didn't realize that!  Yes, adding such a @ref is the right
solution.

Cheers,
- Graham

[pkx166h, 2011-05-24 18:03:32]

Thanks everyone

Pushed

c7edeb3d1c298262efc6c077a3f6d2d62e072a96