DOC: NR 1.5.2 Multiple voices - part combining

DOC: NR 1.5.2 Multiple voices - part combining

Adds explanations and examples of part combine functions to
NR 1.5.2 Multiple voices - Automatic part combining

Patch based on issue 4132045 by Reinhold

[Colin Campbell, 2011-02-16 03:04:13]

Add documentation of partcombine functions.
See issue 1518 on the bug tracker.

[Graham Percival (old account), 2011-02-16 03:50:29]

LGTM.

http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:846: change the state permanently.
Hmm.  5 commas in 4 sentences.

Just kidding, I can't see anything wrong with that paragraph.

[Keith, 2011-02-16 06:08:03]

Looks good as it is, 
better if you can add one markup that Reinhold missed in the example.

http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:873: from the left one of each pair of
commands above.
I had trouble understanding after the comma, but think the first part of the
sentence says it all.

http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:882: \partcombineAutomatic c c |
c^"auto"

[Reinhold, 2011-02-16 10:54:15]

http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
Documentation/notation/simultaneous.itely:846: change the state permanently.
On 2011/02/16 03:50:29, Graham Percival wrote:
> Hmm.  5 commas in 4 sentences.

You don't know German, do you? Here it's totally common to have 5 commas in one
sentence!

[Colin Campbell, 2011-02-16 13:53:26]

On 2011/02/16 06:08:03, Keith wrote:
> Looks good as it is, 
> better if you can add one markup that Reinhold missed in the example.
> 
>
http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
> File Documentation/notation/simultaneous.itely (right):
> 
>
http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
> Documentation/notation/simultaneous.itely:873: from the left one of each pair
of
> commands above.
> I had trouble understanding after the comma, but think the first part of the
> sentence says it all.
> 
AGree, Keith: I've trimmed it.
>
http://codereview.appspot.com/4188056/diff/1/Documentation/notation/simultane...
> Documentation/notation/simultaneous.itely:882: \partcombineAutomatic c c |
> c^"auto"
done, and thanks!

[pkx166h, 2011-02-21 17:56:04]

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

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:846: change the state permanently.
If I may make a suggestion for this whole paragraph?

--snip--

In professional scores, voices are often kept apart for long periods - even if
one or two notes actually coincide and could easily be printed as
@emph{unisono}.  Combining notes into a chord, or to print one voice as solo is
therefore not ideal as the @code{\partcombine} function considers each note
separately.  

For this reason, the @code{\partcombine} function can be overriden with the
following commands:

--snip--

I have moved that final sentence below the list

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:852: chord or unisono.
Again do we @emph{} unisono? I assume this is a musical term and not just a
mis-translation of foreign usage?

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:856: Combine the notes to a chord.
There was much discussion on 'chord' vs 'not chord' unrelated to this, but still
enough to worry some. So is 'chord' the correct term here? I have no preference
but am just pre-empting discussion.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:860: The two voices are unisono.
@emph{unisono}

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:872: Use the combination strategy
automatically determined.
Can we be more descriptive on what the 'automatic' strategy is? Or we could
simply say

"Let the software decide which is the best option". I want to not use the word
'strategy'.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:874: @end itemize
Now add the final sentence from above:

All commands ending in @code{...Once} apply only to the following note.

---

It is therefore implicit and unnecessary to state what the code that doesn't end
in 'once' does. So I have removed that sentence.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:880: \partcombineChords e'^"chord" e |
If we do change the word 'chord' above then we need to change it here too.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:891: c2 c
If we're going to have bar checks then we need one on the last bar

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:897: \new Staff \partcombine
\instrumentOne \instrumentTwo
If we do keep this @lilypond (see comment below) I'd like to see {} after the
new Staff for clarity.

<<
  \new Staff { \instrumentOne }
  \new Staff { \instrumentTwo }
  \new Staff { \partcombine \instrumentOne \instrumentTwo }
>>

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:899: @end lilypond
Maybe I have missed something but this looks a tad complicated for an @lilypond
and would be better served as a snippet instead. We don't often use variables
like this in @lilypond except when explicitly discussing variables.

[Colin Campbell, 2011-02-21 20:29:42]

revised patch uploaded.

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

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:846: change the state permanently.
On 2011/02/21 17:56:05, pkx166h wrote:
> If I may make a suggestion for this whole paragraph?
> 
> --snip--
> 
> In professional scores, voices are often kept apart for long periods - even if
> one or two notes actually coincide and could easily be printed as
> @emph{unisono}.  Combining notes into a chord, or to print one voice as solo
is
> therefore not ideal as the @code{\partcombine} function considers each note
> separately.  
> 
> For this reason, the @code{\partcombine} function can be overriden with the
> following commands:
> 
> --snip--
> 
> I have moved that final sentence below the list

Done.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:852: chord or unisono.
On 2011/02/21 17:56:05, pkx166h wrote:
> Again do we @emph{} unisono? I assume this is a musical term and not just a
> mis-translation of foreign usage?

I believe "unisono" is a Dutch usage, so I've changed it to "unison", although
it is hardwired into the names of functions like \partCombineUnisono.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:856: Combine the notes to a chord.
On 2011/02/21 17:56:05, pkx166h wrote:
> There was much discussion on 'chord' vs 'not chord' unrelated to this, but
still
> enough to worry some. So is 'chord' the correct term here? I have no
preference
> but am just pre-empting discussion.

I think it's safe, given the names of the commands.  Whether the commands are
correctly named may be another discussion!

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:860: The two voices are unisono.
On 2011/02/21 17:56:05, pkx166h wrote:
> @emph{unisono}

As above.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:872: Use the combination strategy
automatically determined.
On 2011/02/21 17:56:05, pkx166h wrote:
> Can we be more descriptive on what the 'automatic' strategy is? Or we could
> simply say
> 
> "Let the software decide which is the best option". I want to not use the word
> 'strategy'.
> 

Done.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:874: @end itemize
On 2011/02/21 17:56:05, pkx166h wrote:
> Now add the final sentence from above:
> 
> All commands ending in @code{...Once} apply only to the following note.
> 
> ---
> 
> It is therefore implicit and unnecessary to state what the code that doesn't
end
> in 'once' does. So I have removed that sentence. 
> 

Done.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:880: \partcombineChords e'^"chord" e |
On 2011/02/21 17:56:05, pkx166h wrote:
> If we do change the word 'chord' above then we need to change it here too.

Done.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:891: c2 c
On 2011/02/21 17:56:05, pkx166h wrote:
> If we're going to have bar checks then we need one on the last bar

Done.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:897: \new Staff \partcombine
\instrumentOne \instrumentTwo
On 2011/02/21 17:56:05, pkx166h wrote:
> If we do keep this @lilypond (see comment below) I'd like to see {} after the
> new Staff for clarity.
> 
> <<
>   \new Staff { \instrumentOne }
>   \new Staff { \instrumentTwo }
>   \new Staff { \partcombine \instrumentOne \instrumentTwo }
> >>

Done.

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:899: @end lilypond
On 2011/02/21 17:56:05, pkx166h wrote:
> Maybe I have missed something but this looks a tad complicated for an
@lilypond
> and would be better served as a snippet instead. We don't often use variables
> like this in @lilypond except when explicitly discussing variables.

It may be more confusing to write it without variables; \partcombine is
certainly easier to do *with* than without, and I believe the example is nearly
unreadable without variables.  Other tastes are of course different!

[pkx166h, 2011-02-22 11:23:44]

one correction.

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

http://codereview.appspot.com/4188056/diff/2004/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:820: unison (@notation{a due}) parts
are marked by default with the text
I think this is meant to be 'a deux' also there is an aigue accent on the 'a'.

[Reinhold, 2011-02-22 11:49:04]

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

http://codereview.appspot.com/4188056/diff/2004/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:820: unison (@notation{a due}) parts
are marked by default with the text
On 2011/02/22 11:23:44, pkx166h wrote:
> I think this is meant to be 'a deux' also there is an aigue accent on the 'a'.

Nope, "a due" is the conventional Italian phrase for "by both", just like
"unisono" is the term for "unison".

[Reinhold, 2011-02-22 12:15:31]

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

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:852: chord or unisono.
On 2011/02/21 20:29:42, Colin Campbell wrote:
> I believe "unisono" is a Dutch usage, so I've changed it to "unison", although
> it is hardwired into the names of functions like \partCombineUnisono.

Unisono is the usual Italian term, as opposed to "divisi".

http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
Documentation/notation/simultaneous.itely:872: Use the combination strategy
automatically determined.
On 2011/02/21 17:56:05, pkx166h wrote:
> Can we be more descriptive on what the 'automatic' strategy is? Or we could
> simply say
> 
> "Let the software decide which is the best option". I want to not use the word
> 'strategy'.

Actually, it's not easy to describe the default (combine, if it is possible, but
not for voice crossings or for different spanners or dynamics, or if the notes
are further apart than an octave or so).

Also, lilypond does not usually decide what's the best option, but rather the
simplest.

[Colin Campbell, 2011-02-24 04:29:24]

On 2011/02/22 12:15:31, Reinhold wrote:
>
http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
> File Documentation/notation/simultaneous.itely (right):
> 
>
http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
> Documentation/notation/simultaneous.itely:852: chord or unisono.
> On 2011/02/21 20:29:42, Colin Campbell wrote:
> > I believe "unisono" is a Dutch usage, so I've changed it to "unison",
although
> > it is hardwired into the names of functions like \partCombineUnisono.
> 
> Unisono is the usual Italian term, as opposed to "divisi".
> 

FWIW, "unisono" only appears in code, never in open text, per git grep 'unisono
'; I feel that using the Italian term in this context would detract from the
purpose of explaining the commands.

>
http://codereview.appspot.com/4188056/diff/1003/Documentation/notation/simult...
> Documentation/notation/simultaneous.itely:872: Use the combination strategy
> automatically determined.
> On 2011/02/21 17:56:05, pkx166h wrote:
> > Can we be more descriptive on what the 'automatic' strategy is? Or we could
> > simply say
> > 
> > "Let the software decide which is the best option". I want to not use the
word
> > 'strategy'.
> 
> Actually, it's not easy to describe the default (combine, if it is possible,
but
> not for voice crossings or for different spanners or dynamics, or if the notes
> are further apart than an octave or so).
> 
> Also, lilypond does not usually decide what's the best option, but rather the
> simplest.

Perhaps I should add something like: decide, but the results may need adjustment
in some cases."?

[pkx166h, 2011-02-26 06:52:46]

On 2011/02/24 04:29:24, Colin Campbell 
> Perhaps I should add something like: decide, but the results may need
adjustment
> in some cases."?

Yes that sounds like a better way of putting it.

[James.Lowe_datacore.com, 2011-02-26 11:23:00]

Hello,
________________________________________
From: lilypond-devel-bounces+james.lowe=datacore.com@gnu.org
[lilypond-devel-bounces+james.lowe=datacore.com@gnu.org] on behalf of
pkx166h@gmail.com [pkx166h@gmail.com]
Sent: 26 February 2011 06:52
To: ColinPKCampbell@gmail.com; reinhold.kainhofer@gmail.com
Cc: reply@codereview.appspotmail.com; lilypond-devel@gnu.org
Subject: Re: DOC: NR 1.5.2 Multiple voices - part combining (issue4188056)

On 2011/02/24 04:29:24, Colin Campbell
> Perhaps I should add something like: decide, but the results may need
adjustment
> in some cases."?

Yes that sounds like a better way of putting it.


-------

Actually thinking about it more would it make more sense to have the auto
function listed first then add the words "... May need some manual adjustment.'
and then list the rest?

James

[Colin Campbell, 2011-02-26 20:01:39]

> Actually thinking about it more would it make more sense to have the auto
> function listed first then add the words "... May need some manual
adjustment.'
> and then list the rest?
> 
> James

I like that very much, James, thanks!  A question for Reinhold, though: do I
gather correctly that \partcombine is applied to a Staff, and turns the
combining mechanism on, while \partcombineAutomatic is applied to a single
Voice?  That being so, does it "turn off" a previous \partcombineApart, e.g.?

[Carl, 2011-02-26 20:10:30]

On 2011/02/26 20:01:39, Colin Campbell wrote:
> I like that very much, James, thanks!  A question for Reinhold, though: do I
> gather correctly that \partcombine is applied to a Staff, and turns the
> combining mechanism on, while \partcombineAutomatic is applied to a single
> Voice?  That being so, does it "turn off" a previous \partcombineApart, e.g.?

I would say that \partcombine is a function that applies to two music
expressions.
It creates Voices as necessary for the combined music.  \partcombineAutomatic
applies to the combined music at a given musical moment, and applies to both of
the arguments to \partcombine at that time.

The reason I would not say that \partcombine applies to a staff is that it
doesn't set anything special for the Staff.  It converts two separate music
expressions into a set of music expressions necessary to support the appropriate
combined Voices.

Carl

[reinhold_kainhofer.com, 2011-02-26 20:38:38]

Am Samstag, 26. Februar 2011, um 21:01:40 schrieben Sie:
> A question for Reinhold, though:
> do I gather correctly that \partcombine is applied to a Staff, and turns
> the combining mechanism on, while \partcombineAutomatic is applied to a
> single Voice?

Not really. When part-combining does its job, there are no voices or staves 
yet. \partcombine rather takes two music expressions and decides to which 
voices the note events (and of course also all other events in the music 
expressions) are sent later on. \partcombineAutomatic and the other functions 
simply tell the part-combiner where to send the events.

> That being so, does it "turn off" a previous
> \partcombineApart, e.g.?

Yes, that's correct. If you use \partcombineApart (which tells the part-
combiner to send all events of the first music expression to voice one and the 
events of the second expression to the second voice, even if they could be 
combined to a chord), you need to use \partcombineAutomatic to return to the 
default part-combining mechanism.

Cheers,
Reinhold

-- 
------------------------------------------------------------------
Reinhold Kainhofer, reinhold@kainhofer.com, http://reinhold.kainhofer.com/
 * Financial & Actuarial Math., Vienna Univ. of Technology, Austria
 * http://www.fam.tuwien.ac.at/, DVR: 0005886
 * LilyPond, Music typesetting, http://www.lilypond.org

[Graham Percival (old account), 2011-02-28 10:15:11]

http://codereview.appspot.com/4188056/diff/20001/scripts/auxiliar/doc-section.sh
File scripts/auxiliar/doc-section.sh (right):

http://codereview.appspot.com/4188056/diff/20001/scripts/auxiliar/doc-section...
scripts/auxiliar/doc-section.sh:33: FROMDIR="$HOME/lilypond-git"
I totally agree that this should be done, but please not in the same patch as
doc stuff.

I'll do this right now, separately.  This might cause merge problems for you,
but I think it'll be cleaner in the long run.

[Colin Campbell, 2011-03-06 02:46:30]

Patch revised to remove the doc-section.sh bits which were pushed separately.
The remainder is just the partcombine explanation. Ordinarily, I suppose this
needn't go on reitveld, but wotthehell archie, it started here so I'm putting
the last bit up to close out the process.

[Graham Percival (old account), 2011-03-06 08:24:43]

LGTM, let's push.  Please send the final patch to James for pushing.

[Trevor Daniels, 2011-03-06 09:31:14]

LGTM, apart from a minor nitpick in original text

http://codereview.appspot.com/4188056/diff/22001/Documentation/notation/simul...
File Documentation/notation/simultaneous.itely (left):

http://codereview.appspot.com/4188056/diff/22001/Documentation/notation/simul...
Documentation/notation/simultaneous.itely:821: @qq{a2}.
@q{a2} for consistency
or change the quotes above to @qq{}

[Reinhold, 2011-03-06 12:13:15]

http://codereview.appspot.com/4188056/diff/22001/Documentation/notation/simul...
File Documentation/notation/simultaneous.itely (right):

http://codereview.appspot.com/4188056/diff/22001/Documentation/notation/simul...
Documentation/notation/simultaneous.itely:871: previous part combining
mechanism.
Actually, it never returns to the previous mechanism, but rather to the default
built-in mechanism (just like \revert always resets a grob property to the
default an not to the value before the previous \override).

[Colin Campbell, 2011-03-07 01:38:36]

On 2011/03/06 12:13:15, Reinhold wrote:
>
http://codereview.appspot.com/4188056/diff/22001/Documentation/notation/simul...
> File Documentation/notation/simultaneous.itely (right):
> 
>
http://codereview.appspot.com/4188056/diff/22001/Documentation/notation/simul...
> Documentation/notation/simultaneous.itely:871: previous part combining
> mechanism.
> Actually, it never returns to the previous mechanism, but rather to the
default
> built-in mechanism (just like \revert always resets a grob property to the
> default an not to the value before the previous \override).

Ah, I was thinking that \partcombineautomatic once would go automatic for one
note, then return to whatever was in force before it was called.  If you would
confirm that, I'll reword the explanation to suit.

[pkx166h, 2011-03-07 19:48:23]

Layout wise - Looks fine.

[Colin Campbell, 2011-03-11 02:29:16]

On 2011/03/07 19:48:23, J_lowe wrote:
> Layout wise - Looks fine.

Colin,


From: Colin Campbell [mailto:cpkc@shaw.ca]
Sent: 10 March 2011 13:57
To: James Lowe
Subject: Fwd: part combine doc patch

 

Good morning, James

Attached is a patch which needs pushing, if you would oblige

 

-------

 

Pushed as commit

 

d0c8e3162e9d2c0c7195ce8d58e3dd63bf57aca4

 

In case you want to mention this on Reitveld?

 

James

[Reinhold, 2011-03-11 16:32:12]

On 2011/03/07 01:38:36, Colin Campbell wrote:
> Ah, I was thinking that \partcombineautomatic once would go automatic for one
> note, then return to whatever was in force before it was called.  If you would
> confirm that, I'll reword the explanation to suit.

Yes, that's exactly how it works:
-) \partcombineAutomatic resets the part-combiner to use the default built-in
mechanism.
-) \partcombineAutomaticOnce uses the built-in mechanism for just one moment.

Your wording:
> @code{\partcombineAutomatic}, @code{\partcombineAutomaticOnce}:
>  Ends the effect of the special commands above, and returns to the default or
>  previous part combining mechanism.

sounds wrong for the *Once case, as the *once case does NOT end the effect of
the special commands above... It rather overrides the setting from those
commands for just one moment.

Cheers,
Reinhold