Re: Doc: Issue 3324: Add explanation of clashing note columns warning (issue 154640043 by address@hidden)

[tdanielsmusic]

Reviewers: Keith,

Message:
On 2014/10/22 05:58:54, Keith wrote:

> Just for your interest, I have been thinking that when the user gives
explicit
> \voiceOne or \shiftOn to the voices, Lily should set those voices at
the shifts
> requested, even if two voices have the same shift

Not sure I understand this.  Doesn't \voiceThree already set the shifts?

> Currently users are required to set 'ignore-note-collision in these
cases, but
> then that turns off all the other chord-collision code.

Yes, I don't think we should advocate this.


https://codereview.appspot.com/154640043/diff/1/Documentation/usage/running.itely#newcode1112
> Documentation/usage/running.itely:1112: (@code{\stemDown}, etc) or
implicitly
> (@code{\voiceOne}, etc.)
> People tend to use \stemDown when they want \voiceTwo, so maybe skip
mention of
> \stemDown.

Agreed.  I'll remove \stemDown.

> I wish there were no shorthand for changing just the stem direction
without the
> other changes required for consistency.

It's used 6 times in the LM and 9 times in the NR, and masses of times
in the regression tests.  Maybe we should try to reduce the number of
times \stemDown (and Up) is mentioned in the LM and NR.


Description:
Doc: Issue 3324: Add explanation of clashing note columns warning

Please review this at https://codereview.appspot.com/154640043/

Affected files (+37, -0 lines):
  M Documentation/usage/running.itely


Index: Documentation/usage/running.itely
diff --git a/Documentation/usage/running.itely  
b/Documentation/usage/running.itely
index  
7f42d14bdd8e83bf2807f281f649fd78f9f51636..9417b2846ff090ab2b407d01bc7b7ffbb7145526  
100644
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -947,6 +947,7 @@ are easily handled.
 * Error message FT_Get_Glyph_Name::
 * Warning staff affinities should only decrease::
 * Error message unexpected new::
+* Warning ignoring too many clashing note columns::
 @end menu

 @node Music runs off the page
@@ -1030,6 +1031,7 @@ UTF-8 encoding.  For details, see @ruser{Text  
encoding}.

 @node Warning staff affinities should only decrease
 @unnumberedsubsec Warning staff affinities should only decrease
+
 This warning can appear if there are no staves in the printed
 output, for example if there are just a @code{ChordName} context
 and a @code{Lyrics} context as in a lead sheet.  The warning
@@ -1093,3 +1095,38 @@ staves are introduced in parallel, i.e.  
simultaneously:
   >>
 }
 @end lilypond
+
address@hidden Warning ignoring too many clashing note columns
address@hidden Warning ignoring too many clashing note columns
+
+If notes from two different voices with stems in the same direction
+occur at the same musical moment, but the voices have no
+voice-specific shifts specified, the warning message
address@hidden: ignoring too many clashing note columns} will appear
+when compiling the LilyPond file.  This warning will appear even when
+the notes have no visible stems, e.g. whole notes, if the stems for
+shorter notes at the same pitch would be in the same direction.
+
+Remember that the stem direction depends on the position of the
+note on the staff unless the stem direction is explicitly
+(@code{\stemDown}, etc) or implicitly (@code{\voiceOne}, etc.)
+specified.  In this case the warning will appear only when the
+stems happen to be in the same direction, i.e. when the notes are in
+the same half of the staff.
+
+By placing the notes in voices with stem directions and shifts
+specified, for example by using @code{\voiceOne}, etc., these warnings
+may be avoided.
+
+Notes in higher numbered voices, @code{\voiceThree} etc., are
+automatically shifted to avoid clashing note columns.  This causes a
+visible shift for notes with stems, but whole notes are not visibly
+shifted unless an actual clash of the note heads occurs, or when the
+voices cross over from their natural order (when @code{\voiceThree}
+is higher than @code{\voiceOne}, etc.)
+
address@hidden
address@hidden instantiating voices},
address@hidden music example},
address@hidden polyphony},
address@hidden resolution}.