Update from Francisco.

diff --git a/Documentation/user/simultaneous.itely b/Documentation/user/simultaneous.itely
index ddc9f48e263e9a34e53204919c24013b7263ea49..841877c775d8123be005cdb13633aaabbbd269bc 100644 (file)
--- a/Documentation/user/simultaneous.itely
+++ b/Documentation/user/simultaneous.itely
@@ -44,7 +44,7 @@ A chord is formed by a enclosing a set of pitches between @code{<} and
 @code{>}.  A chord may be followed by a duration and/or a set of
 articulations, just like simple notes:
 
-@lilypond[verbatim,ragged-right,fragment,quote,relative=1]
+@lilypond[verbatim,quote,relative=1]
 <c e g>2 <c f a>4-> <e g c>-.
 @end lilypond
 
@@ -83,7 +83,7 @@ can be denoted as the envelope of a set of notes.  They are entered by
 applying the function @code{\makeClusters} to a sequence of chords,
 e.g.,
 
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[quote,relative=2,verbatim]
 \makeClusters { <g b>2 <c g'> }
 @end lilypond
 
@@ -129,57 +129,72 @@ them.
 
 @cindex merging notes
 @cindex note collisions
+@cindex collisions
+@funindex \shiftOn
+@funindex \shiftOnn
+@funindex \shiftOnnn
+@funindex \shiftOff
 
-Normally, note heads with a different number of dots are not
-merged, but when the object property
-@code{merge-differently-dotted} is set in the
-@rinternals{NoteCollision} object, they are merged:
-
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
-\new Voice << {
-  g8 g8
-  \override Staff.NoteCollision
-    #'merge-differently-dotted = ##t
-  g8 g8
-} \\ { g8.[ f16] g8.[ f16] } >>
+Normally, equal note heads with the same number of dots are
+automatically merged, but note heads with a different number of dots
+are not. To merge differently dotted note heads, you can set the
+@code{merge-differently-dotted} property of the
+@rinternals{NoteCollision} object:
+
+@lilypond[quote,verbatim,relative=2]
+<<
+  { g2 g4 g8 g
+    \override Staff.NoteCollision #'merge-differently-dotted = ##t
+    g2 g4 g8 g }
+  \\
+  { g2. g8. g16
+    g2. g8. g16 }
+>>
 @end lilypond
 
 Similarly, you can merge half note heads with eighth notes, by
 setting @code{merge-differently-headed}:
 
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\new Voice << {
-  c8 c4.
-  \override Staff.NoteCollision
-    #'merge-differently-headed = ##t
-c8 c4. } \\ { c2 c2 } >>
+@lilypond[quote,relative=2,verbatim]
+<<
+  { c8 d e d
+    \override Staff.NoteCollision #'merge-differently-headed = ##t
+    c8 d e d
+  }
+  \\
+  { c2 c }
+>>
 @end lilypond
 
 @noindent
-@code{merge-differently-headed} and
-@code{merge-differently-dotted} only apply to opposing stem
-directions (i.e. Voice 1 & 2).
+Merging notes by setting @code{merge-differently-headed} and
+@code{merge-differently-dotted} only works for opposing stem
+directions (i.e., to @code{Voice}s 1 and 2).
 
-LilyPond also vertically shifts rests that are opposite of a stem,
-for example
+@cindex shift rest, automatic
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-\new Voice << c''4 \\ r4 >>
+LilyPond also vertically shifts rests that are opposite of a stem, for
+example:
+
+@lilypond[quote,verbatim]
+<< c''4 \\ r4 >>
 @end lilypond
 
 @cindex shift note
 
 If three or more notes line up in the same column,
-@code{merge-differently-headed} cannot successfully complete the
-merge of the two notes that should be merged.  To allow the merge
-to work properly, apply a @code{\shift} to the note that should
-not be merged.  In the first measure of following example,
-@code{merge-differently-headed} does not work (the half-note head
-is solid).  In the second measure, @code{\shiftOn} is applied to
-move the top @code{g} out of the column, and
-@code{merge-differently-headed} works properly.
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+@code{merge-differently-headed} cannot successfully complete the merge
+of the two notes that should be merged.  To allow the merge to work
+properly, apply a @code{\shift} to the note that should not be merged.
+In the first measure of following example,
+@code{merge-differently-headed} does not work (the half-note head is
+solid).  In the second measure, @code{\shiftOn} is applied to move the
+top @code{g} out of the column, and @code{merge-differently-headed}
+works properly.
+
+@c IMO this uglyfies the typesetting. Look for a better example. FV
+
+@lilypond[quote,verbatim,relative=2]
 \override Staff.NoteCollision #'merge-differently-headed = ##t
 <<
   { d=''2 g2 } \\
@@ -201,19 +216,18 @@ In some instances of complex polyphonic music, you may need
 additional voices to avoid collisions between notes.  Additional
 voices are added by defining an variable, as shown below:
 
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[quote,verbatim]
 voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)
-
-\relative c''' <<
-  { \voiceOne g4 ~  \stemDown g32[ f( es d c b a b64 )g] } \\
-  { \voiceThree  b4} \\
-  { \voiceFive d,} \\
-  { \voiceTwo g,}
+\relative c'''
+<< 
+  { \voiceOne g2. ~ \stemDown g32[ f( es d c b a b64) g] } \\
+  { \voiceThree b4 } \\
+  { \voiceFive d,  } \\
+  { \voiceTwo g,   }
 >>
 @end lilypond
 
 
-
 @predefined
 
 @funindex \oneVoice
@@ -227,6 +241,7 @@ voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)
 @funindex \voiceFour
 @code{\voiceFour}.
 
+@c undocumented?: --FV
 @funindex \voiceNeutralStyle
 @funindex \voiceOneStyle
 @funindex \voiceTwoStyle
@@ -249,7 +264,7 @@ voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)
 @funindex \shiftOff
 @code{\shiftOff}: these commands specify the degree to which
 chords of the current voice should be shifted.  The outer voices
-(normally: voice one and two) have @code{\shiftOff}, while the
+(normally: voices one and two) have @code{\shiftOff}, while the
 inner voices (three and four) have @code{\shiftOn}.
 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
 levels.
@@ -258,25 +273,35 @@ When LilyPond cannot cope, the @code{force-hshift} property of the
 @rinternals{NoteColumn} object and pitched rests can be used to
 override typesetting decisions.
 
-@lilypond[quote,verbatim,ragged-right]
-\relative <<
-{
-  <d g>
-  <d g>
-} \\ {
-  <b f'>
-  \once \override NoteColumn #'force-hshift = #1.7
-  <b f'>
-} >>
+@lilypond[quote,verbatim,relative=1]
+<<
+  { <d g>2
+    <d g>  }
+  \\
+  { <b f'>2
+    \once \override NoteColumn #'force-hshift = #1.7
+    <b f'> }
+>>
+
 @end lilypond
 
 
 @seealso
 
+Music Glossary:
+@rglos{polyphony}
+
+Learning Manual:
+@rlearning{Multiple notes at once},
+@rlearning{Voices contain music},
+@rlearning{Collisions of objects}.
+
 Snippets:
 @rlsr{Simultaneous notes}.
 
-Internals Reference: the objects responsible for resolving collisions
+Internals Reference:
+@rinternals{NoteColumn}.
+The objects responsible for resolving collisions
 are
 @rinternals{NoteCollision} and
 @rinternals{RestCollision}.
@@ -284,9 +309,10 @@ are
 
 @knownissues
 
-When using @code{merge-differently-headed} with an upstem eighth
-or a shorter note, and a downstem half note, the eighth note gets
-the wrong offset.
+When using @code{merge-differently-headed} with an upstem eighth or a
+shorter note, and a downstem half note, the eighth note stem gets a
+slightly wrong offset because of the different width of the half note
+head symbol.
 
 There is no support for clusters where the same note occurs with
 different accidentals in the same chord.  In this case, it is
@@ -319,7 +345,7 @@ combiner: putting parts on one staff and setting stem directions and
 polyphony.  The same variables are used for the independent
 parts and the combined staff.
 
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[quote,verbatim]
 instrumentOne = \relative c' {
   c4 d e f
   R1
@@ -372,7 +398,7 @@ has no effect on the pitches of @var{musicexpr1} and
 
 Parts may be merged without printing text:
 
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[quote,verbatim]
 \new Staff <<
   \set Staff.printPartCombineTexts = ##f
   \partcombine
@@ -383,7 +409,7 @@ Parts may be merged without printing text:
 
 The printed text may be changed:
 
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[quote,verbatim]
 \new Staff <<
   \set Score.soloText = #"girl"
   \set Score.soloIIText = #"boy"
@@ -447,7 +473,7 @@ music.
 @warning{Bar checks @code{|} must be used, and the measures must
 be of the same length.}
 
-@lilypond[quote,fragment,verbatim]
+@lilypond[quote,verbatim]
 \parallelMusic #'(voiceA voiceB) {
   % Bar 1
   r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] |
@@ -469,7 +495,7 @@ relative to the preceding note in the voice, not to the previous
 note in the input -- in other words, relative notes for
 @code{voiceA} ignore the notes in @code{voiceB}.
 
-@lilypond[quote,fragment,verbatim]
+@lilypond[quote,verbatim]
 \parallelMusic #'(voiceA voiceB) {
   % Bar 1
   r8 g16 c e g, c e r8 g,16 c e g, c e  |