Doc: NR 1.5.2: Clarify voice order; \shiftOn etc.

Doc: NR 1.5.2: Clarify voice order; \shiftOn etc.

In response to: http://lists.gnu.org/archive/html/lilypond-devel/2010-09/msg00194.html

[Trevor Daniels, 2010-09-21 07:44:52]

I'm not particularly opposed to placing this in the
NR, but it's not clear what you are suggesting here.
Do you mean to leave the LM unchanged, or do you intend
to remove or change the corresponding section there?


Also, if it is to go in the NR it needs a separate
section heading.  At the moment it appears under
"The double backslash construct", whereas it applies
equally to explicitly instantiated voices.  Maybe
something like "Voice order"?

[Mark Polesky, 2010-09-22 02:27:23]

New patch set uploaded.

On 2010/09/21 07:44:52, Trevor Daniels wrote:
> I'm not particularly opposed to placing this in the
> NR, but it's not clear what you are suggesting here.
> Do you mean to leave the LM unchanged, or do you intend
> to remove or change the corresponding section there?

I mean to leave the LM unchanged, for now.  Carl has
convinced me that the NR is a higher priority for
containing this information.  We can always add a less
comprehensive version to the LM later.

> Also, if it is to go in the NR it needs a separate
> section heading.  At the moment it appears under
> "The double backslash construct", whereas it applies
> equally to explicitly instantiated voices.  Maybe
> something like "Voice order"?

Done.

I also removed some cruft.  It looked neat but wasn't
necessary.  What do you guys think?

- Mark

[Carl, 2010-09-22 12:59:42]

I like it.

Have you experimented with (or do you have any examples involving) voices that
cross (i.e. you have voices with one order at a given time, but a different
order at the next time)?

Thanks,

Carl

[Carl, 2010-09-22 13:05:01]

While you're working on this, I've got a question.

The snippet "Additional voices to avoid collisions" appears to be unneeded now,
since voices 5 and 6 are already available.  Is there any limit to the number of
automatically-instantiated voices now (perhaps voice 8, which corresponds to
\shiftOnnn)?

I think it would be good to identify the limit, if there is one, and then modify
the snippet so it shows going beyond the limit.  If there is no limit, then just
eliminate the snippet.

Thanks,

Carl

[Graham Percival (old account), 2010-09-22 14:53:15]

http://codereview.appspot.com/2226045/diff/3001/Documentation/notation/simult...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/2226045/diff/3001/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:392: @example
Can't this @example be removed, now that there's the @lilypond just below it?

http://codereview.appspot.com/2226045/diff/3001/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:419: { g'2  }  % 6: third-lowest
... if you remove the @example, then I guess technically you should have a:
  % etc.
here.  :)

http://codereview.appspot.com/2226045/diff/3001/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:658: on the staff!
I'm ok with this sentence being inside a @warning -- we should only use them
rarely, but I think in this case it's a well-deserved @warning.

[Mark Polesky, 2010-09-22 16:49:00]

On 2010/09/22 13:05:01, Carl wrote:
> Have you experimented with (or do you have any examples
> involving) voices that cross (i.e. you have voices with one
> order at a given time, but a different order at the next
> time)?

I think it's possible to exhaust the reasonable expectations
of this automatic layout functionality.  If you enter your
voices in the correct order, but the voices end up crossing
each other, then you have what I like to call a "Real music
example" and you may have to override the defaults with
higher levels of \shiftOn*.

> While you're working on this, I've got a question.
> 
> Is there any limit to the number of automatically-instantiated
> voices now (perhaps voice 8, which corresponds to \shiftOnnn)?

I *think* voices three and above use \shiftOn by default.  I
*think* the other levels of \shiftOn* are for the user to
move things beyond the already shifted defaults, and I *think*
that they're never activated by default.

By the way, with 10 voices the output still looks great:

\new Staff <<
  \time 2/4
  { c'''2 }
  \\
  { f2 }
  \\
  { a''2 }
  \\
  { a2 }
  \\
  { f''2 }
  \\
  { c'2 }
  \\
  { d''2 }
  \\
  { e'2 }
  \\
  { b'2 }
  \\
  { g'2 }
>>

- Mark

[Carl, 2010-09-22 17:02:38]

On 2010/09/22 16:49:00, Mark Polesky wrote:
> On 2010/09/22 13:05:01, Carl wrote:
> > Have you experimented with (or do you have any examples
> > involving) voices that cross (i.e. you have voices with one
> > order at a given time, but a different order at the next
> > time)?
> 
> I think it's possible to exhaust the reasonable expectations
> of this automatic layout functionality.  If you enter your
> voices in the correct order, but the voices end up crossing
> each other, then you have what I like to call a "Real music
> example" and you may have to override the defaults with
> higher levels of \shiftOn*.

OK -- that's fine.

> 
> > While you're working on this, I've got a question.
> > 
> > Is there any limit to the number of automatically-instantiated
> > voices now (perhaps voice 8, which corresponds to \shiftOnnn)?
> 
> I *think* voices three and above use \shiftOn by default.  I
> *think* the other levels of \shiftOn* are for the user to
> move things beyond the already shifted defaults, and I *think*
> that they're never activated by default.
> 
> By the way, with 10 voices the output still looks great:
> 

OK, then let's just get rid of the snippet that shows how to add an extra voice,
since that's not necessary any more.

Thanks,

Carl

[Mark Polesky, 2010-09-23 03:17:16]

On 2010/09/22 17:02:38, Carl wrote:
> OK, then let's just get rid of the snippet that shows how
> to add an extra voice, since that's not necessary any more.

Hold on a minute.  Isn't that snippet still useful when the
voices are explicitly instantiated, and you're *not* using
the double-backslash construct?

- Mark

[Carl, 2010-09-23 03:20:50]

On 2010/09/23 03:17:16, Mark Polesky wrote:
> On 2010/09/22 17:02:38, Carl wrote:
> > OK, then let's just get rid of the snippet that shows how
> > to add an extra voice, since that's not necessary any more.
> 
> Hold on a minute.  Isn't that snippet still useful when the
> voices are explicitly instantiated, and you're *not* using
> the double-backslash construct?

I don't know.  I haven't tested it in that circumstance.  The snippet uses the
double-backslash construct.

If it's needed when not using double-backslash, then let's keep it, but
eliminate the double backslashes.

Thanks,

Carl

[Carl, 2010-09-23 03:20:52]

On 2010/09/23 03:17:16, Mark Polesky wrote:
> On 2010/09/22 17:02:38, Carl wrote:
> > OK, then let's just get rid of the snippet that shows how
> > to add an extra voice, since that's not necessary any more.
> 
> Hold on a minute.  Isn't that snippet still useful when the
> voices are explicitly instantiated, and you're *not* using
> the double-backslash construct?

I don't know.  I haven't tested it in that circumstance.  The snippet uses the
double-backslash construct.

If it's needed when not using double-backslash, then let's keep it, but
eliminate the double backslashes.

Thanks,

Carl

[Mark Polesky, 2010-09-23 04:15:47]

On 2010/09/23 03:20:52, Carl wrote:
> If it's needed when not using double-backslash, then
> let's keep it, but eliminate the double backslashes.

Carl, if you want to do the dirty work of updating the
snippet, you can use this edited version.  On a side
note, it might be nice to mention in the description
that the argument to make-voice-props-set is one less
than the voice number.

voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)

\new Staff {
  \key d \minor
  \time 3/4
  \partial 2
  <<
    \new Voice = "1" \relative a' {
      \voiceOne
      a4. a8 | e'4 e4. e8 | f4 d4. c8 |
    }
    \new Voice = "2" \relative d' {
      \voiceTwo
      d2 | d4 cis2 | d4 bes2 |
    }
    \new Voice = "3" \relative f' {
      \voiceThree
      f2 | bes4 a2 | a4 s2 |
    }
    \new Voice = "5" \relative g' {
      \voiceFive
      s2 | g4 g2 | f4 f2 |
    }
  >>
}

[Trevor Daniels, 2010-09-23 08:08:31]

With my correction I'm happy with this.

http://codereview.appspot.com/2226045/diff/3001/Documentation/notation/simult...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/2226045/diff/3001/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:685: @ruser{Real music example}.
@rlearning{ .. }

[Mark Polesky, 2010-09-23 14:51:59]

On 2010/09/22 14:53:15, Graham Percival wrote:
> Documentation/notation/simultaneous.itely:392: @example
> Can't this @example be removed, now that there's the
> @lilypond just below it?

Graham,

as I think more about visual-impairment accessibility, I
feel that the @example is immediately readable without the
code clutter.  I'll remove it if you feel strongly.

All other requested changes have been made (I think), and
I made a slight clarification to the collision stuff.

Okay to push?
- Mark

[t.daniels_treda.co.uk, 2010-09-23 15:22:52]

markpolesky wrote Thursday, September 23, 2010 3:51 PM


> On 2010/09/22 14:53:15, Graham Percival wrote:
>> Documentation/notation/simultaneous.itely:392: @example
>> Can't this @example be removed, now that there's the
>> @lilypond just below it?
> 
> as I think more about visual-impairment accessibility, I
> feel that the @example is immediately readable without the
> code clutter.  I'll remove it if you feel strongly.

As this is the only point of this small section
I'd prefer to keep the @example.
 
> Okay to push?

OK by me.

Trevor

[Graham Percival (old account), 2010-09-24 13:29:01]

On 2010/09/23 15:22:52, t.daniels_treda.co.uk wrote:
> markpolesky wrote Thursday, September 23, 2010 3:51 PM
> 
> > as I think more about visual-impairment accessibility, I
> > feel that the @example is immediately readable without the
> > code clutter.  I'll remove it if you feel strongly.
> 
> As this is the only point of this small section
> I'd prefer to keep the @example.

I see I'm outvoted.  :)
  
> > Okay to push?
> 
> OK by me.

Ok by me, sorry for the delay.

Cheers,
- Graham