Merge branch 'stable/2.16' into staging

[lilypond.git] / Documentation / notation / simultaneous.itely

diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index 90669730a7f8682e0d43ae6f631d9cf43a8748fe..30e682b74ac5f69e87b5ab14a8b2f0a7bd582a4e 100644 (file)
--- a/Documentation/notation/simultaneous.itely
+++ b/Documentation/notation/simultaneous.itely
@@ -7,13 +7,13 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.16.0"
 
 
 @node Simultaneous notes
 @section Simultaneous notes
 
-@lilypondfile[quote]{simultaneous-headword.ly}
+@lilypondfile[quote,ragged-right,line-width=16\cm]{simultaneous-headword.ly}
 
 Polyphony in music refers to having more than one voice occurring
 in a piece of music.  Polyphony in LilyPond refers to having more
@@ -67,7 +67,8 @@ The notes within the chord themselves can also be followed by articulation
 and ornamentation.
 
 @lilypond[verbatim,quote,relative=2]
-<a c\prall e>1 <a-> c-^ e>2 <f-. a c-. e-.>4 <a-+ c-->8. <g\fermata c e\turn>16
+<a c\prall e>1 <a-> c-^ e>2 <f-. a c-. e-.>4
+<a-+ c-->8. <g\fermata c e\turn>16
 @end lilypond
 
 However some notation, such as dynamics, hairpins and slurs must be
@@ -75,7 +76,24 @@ attached to the chord, rather than notes within the chord, otherwise
 they will not print.
 
 @lilypond[verbatim,quote,relative=2]
-<a\f c( e>1 <a c) e>\f <a\< c e>( <a\! c e>) <a c e>\< <a c e> <a c e>\!
+<a\f c( e>1 <a c) e>\f <a\< c e>( <a\! c e>)
+<a c e>\< <a c e> <a c e>\!
+@end lilypond
+
+@cindex chords, empty
+@cindex placeholder events
+
+A chord acts merely as a container for its notes, its articulations and
+other attached elements.  Consequently, a chord without notes inside
+does not actually have a duration.  Any attached articulations will
+happen at the same musical time as the next following note or chord and
+be combined with them (for more complex possibilities of combining such
+elements, see @ref{Simultaneous expressions}):
+
+@lilypond[verbatim,quote,relative=2]
+\grace { g8[( a b] }
+<> ) \p \< -. -\markup \italic "sempre staccato"
+\repeat unfold 4 { c4 e }  c1\f
 @end lilypond
 
 @cindex relative pitch, chords
@@ -244,8 +262,17 @@ a << { a4 b g } { d4 g c, } >>
 @end lilypond
 
 This can be useful if the simultaneous sections have identical
-rhythms, but attempts to attach notes with different durations
-to the same stem will cause errors.
+rhythms, but attempts to attach notes with different durations to
+the same stem will cause errors.  Notes, articulations, and property
+changes in a @emph{single} @samp{Voice} are collected and engraved in
+musical order:
+
+@lilypond[quote,verbatim,relative=2]
+<a c>4-.  <>-. << c a >>  << { c-. <c a> } { a s-. } >>
+@end lilypond
+
+Multiple stems or beams or different note durations or properties at
+the same musical time require the use of multiple voices.
 
 The following example shows how simultaneous expressions can
 generate multiple staves implicitly:
@@ -255,7 +282,8 @@ generate multiple staves implicitly:
 << { a4 b g2 } { d4 g2 c,4 } >>
 @end lilypond
 
-Here different rhythms cause no problems.
+Here different rhythms cause no problems because they are
+interpreted in different voices.
 
 @cindex collisions, clashing note columns
 @cindex collisions, ignoring
@@ -356,7 +384,7 @@ multiple staves.
 @funindex \oneVoice
 @funindex oneVoice
 
-@strong{@i{Explicitly instantiating voices}}
+@subsubsubheading Explicitly instantiating voices
 
 The basic structure needed to achieve multiple independent
 voices in a single staff is illustrated in the following example:
@@ -380,7 +408,7 @@ automatically moved to avoid collisions.  The @code{\oneVoice}
 command returns all the voice settings to the neutral default
 directions.
 
-@strong{@i{Temporary polyphonic passages}}
+@subsubsubheading Temporary polyphonic passages
 
 A temporary polyphonic passage can be created with the following
 construct:
@@ -427,7 +455,7 @@ during and after a polyphonic section:
 Here, the @code{\voiceOne} and @code{\voiceTwo} commands are
 required to define the settings of each voice.
 
-@strong{@i{The double backslash construct}}
+@subsubsubheading The double backslash construct
 
 The @code{<< @{...@} \\ @{...@} >>} construct, where the two (or
 more) expressions are separated by double backslashes, behaves
@@ -472,7 +500,7 @@ In all but the simplest works it is advisable to create explicit
 @code{Voice} contexts as explained in @rlearning{Contexts and engravers} and
 @rlearning{Explicitly instantiating voices}.
 
-@strong{@i{Voice order}}
+@subsubsubheading Voice order
 
 When entering multiple voices in the input file, use the following
 order:
@@ -511,7 +539,7 @@ upstems, and the even-numbered voices are given downstems:
 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
 created @q{across} voices.}
 
-@strong{@i{Identical rhythms}}
+@subsubsubheading Identical rhythms
 
 In the special case that we want to typeset parallel pieces of music
 that have the same rhythm, we can combine them into a single