Docs: NR various: links to Stems

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

diff --git a/Documentation/user/simultaneous.itely b/Documentation/user/simultaneous.itely
index 68a1c03432e489437b94503a084c025b694ea015..01e2c8d07dc0c4ab0289d60471170951d823fc5c 100644 (file)
--- a/Documentation/user/simultaneous.itely
+++ b/Documentation/user/simultaneous.itely
@@ -6,7 +6,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.51"
+@c \version "2.12.0"

 
 
 @node Simultaneous notes
 
 
 @node Simultaneous notes


@@ -31,6 +31,7 @@ This section discusses simultaneous notes inside the same voice.
 
 @menu
 * Chorded notes::
 
 @menu
 * Chorded notes::

+* Simultaneous expressions::

 * Clusters::
 @end menu
 
 * Clusters::
 @end menu
 


@@ -40,28 +41,30 @@ This section discusses simultaneous notes inside the same voice.
 
 @cindex chords
 @cindex brackets, angle
 
 @cindex chords
 @cindex brackets, angle

+@cindex angle brackets

 @cindex relative pitch in chords
 @cindex relative pitch in chords

+

 @funindex <
 @funindex >
 @funindex <...>
 
 @funindex <
 @funindex >
 @funindex <...>
 

-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:
+A chord is formed by 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,quote,relative=1]
 <c e g>2 <c f a>4-> <e g c>-.
 @end lilypond
 
 
 @lilypond[verbatim,quote,relative=1]
 <c e g>2 <c f a>4-> <e g c>-.
 @end lilypond
 

-Relative mode can be used for pitches in chords; the preceding pitch
-into the same chord is still used as a reference for relative pitches,
-but when a chord is completed, the reference pitch for relative mode
-is the first note of this chord --not the last note of the chord.
+Relative mode can be used for pitches in chords. The octave of each
+pitch is chosen using the preceding pitch as a reference except in
+the case of the first pitch in a chord: the reference for the first
+pitch is the @emph{first} pitch of the preceding chord.

 
 For more information about chords, see @ref{Chord notation}.
 
 
 For more information about chords, see @ref{Chord notation}.
 

-@seealso

 
 

+@seealso

 Music Glossary:
 @rglos{chord}.
 
 Music Glossary:
 @rglos{chord}.
 


@@ -74,14 +77,43 @@ Notation Reference:
 Snippets:
 @rlsr{Simultaneous notes}.
 
 Snippets:
 @rlsr{Simultaneous notes}.
 

-@ignore
-@knownissues

 
 

-For some reason, music expressions like @code{<< @{ g8 e8 @} a4 >>}
-that should automatically turn into chords, appear split in two
-staves.  To avoid this, use explicit chords instead as in
-@code{<g a>8 <e a>8}.
-@end ignore
+@node Simultaneous expressions
+@unnumberedsubsubsec Simultaneous expressions
+
+One or more music expressions enclosed in double angle brackets are
+taken to be simultaneous.  If the first expression begins with a
+single note or if the whole simultaneous expression appears
+explicitly within a single voice, the whole expression is placed on
+a single staff; otherwise the elements of the simultaneous
+expression are placed on separate staves.
+
+The following examples show simultaneous expressions on one staff:
+
+@lilypond[quote,verbatim,relative=2]
+\new Voice {  % explicit single voice
+  << {a4 b g2} {d4 g c,2} >>
+}
+@end lilypond
+
+@lilypond[quote,verbatim,relative=2]
+% single first note
+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.
+
+The following example shows how simultaneous expressions can
+generate multiple staves implicitly:
+
+@lilypond[quote,verbatim,relative=2]
+% no single first note
+<< {a4 b g2}  {d4 g2 c,4} >>
+@end lilypond
+
+Here different rhythms cause no problems.

 
 
 @node Clusters
 
 
 @node Clusters


@@ -89,13 +121,14 @@ staves.  To avoid this, use explicit chords instead as in
 
 @cindex cluster
 @cindex note cluster
 
 @cindex cluster
 @cindex note cluster

+

 @funindex \makeClusters
 @funindex makeClusters
 
 @funindex \makeClusters
 @funindex makeClusters
 

-A cluster indicates a continuous range of pitches to be played.  They
-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.,
+A cluster indicates a continuous range of pitches to be played.
+They 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,relative=2,verbatim]
 \makeClusters { <g b>2 <c g'> }
 
 @lilypond[quote,relative=2,verbatim]
 \makeClusters { <g b>2 <c g'> }


@@ -105,8 +138,8 @@ Ordinary notes and clusters can be put together in the same staff,
 even simultaneously.  In such a case no attempt is made to
 automatically avoid collisions between ordinary notes and clusters.
 
 even simultaneously.  In such a case no attempt is made to
 automatically avoid collisions between ordinary notes and clusters.
 

-@seealso

 
 

+@seealso

 Music Glossary:
 @rglos{cluster}.
 
 Music Glossary:
 @rglos{cluster}.
 


@@ -118,15 +151,18 @@ Internals Reference:
 @rinternals{ClusterSpannerBeacon},
 @rinternals{Cluster_spanner_engraver}.
 
 @rinternals{ClusterSpannerBeacon},
 @rinternals{Cluster_spanner_engraver}.
 

+

 @knownissues
 
 Clusters look good only if they span at least two chords; otherwise
 they appear too narrow.
 
 Clusters do not have a stem and cannot indicate durations by
 @knownissues
 
 Clusters look good only if they span at least two chords; otherwise
 they appear too narrow.
 
 Clusters do not have a stem and cannot indicate durations by

-themselves.  Separate clusters would need a separating rest between
-them.
+themselves, but the length of the printed cluster is determined by
+the durations of the defining chords.  Separate clusters need a
+separating rest between them.

 
 

+Clusters do not produce MIDI output.

 
 @node Multiple voices
 @subsection Multiple voices
 
 @node Multiple voices
 @subsection Multiple voices


@@ -150,6 +186,7 @@ multiple staves.
 @cindex polyphony, single-staff
 @cindex voice
 @cindex lyrics assigned to one voice
 @cindex polyphony, single-staff
 @cindex voice
 @cindex lyrics assigned to one voice

+

 @funindex \voiceOne
 @funindex voiceOne
 @funindex \voiceOne ... \voiceFour
 @funindex \voiceOne
 @funindex voiceOne
 @funindex \voiceOne ... \voiceFour


@@ -157,7 +194,9 @@ multiple staves.
 @funindex \oneVoice
 @funindex oneVoice
 
 @funindex \oneVoice
 @funindex oneVoice
 

-The basic structure of code needed to achieve multiple, independent
+@strong{@i{Explicitly instantiating voices}}
+
+The basic structure needed to achieve multiple independent

 voices in a single staff is illustrated in the following example:
 
 @lilypond[quote,relative=3,verbatim]
 voices in a single staff is illustrated in the following example:
 
 @lilypond[quote,relative=3,verbatim]


@@ -169,27 +208,33 @@ voices in a single staff is illustrated in the following example:
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-Here, voices are instantiated explicitly and are given a name. The
-@code{\voiceOne} ... @code{\voiceFour} commands set up the voices so
-that first and third voices get stems up, second and fourth voices get
-stems down, third and fourth voice note heads are horizontally
-shifted, and rests in the respective voices are automatically moved to
-avoid collisions.  Using the @code{\oneVoice} command, all the voice
-settings are put back to the neutral directions typical of a
-single-voice passage.
-
-We can make a voice to be in the same @code{Voice} context before
-and after a temporary polyphonic passage.  For example, the following
-construct keeps a voice alive throughout the polyphonic section.  Said
-voice is the first one inside of the two-voice section, and the extra
-voice is the second one.
+Here, voices are instantiated explicitly and are given names. The
+@code{\voiceOne} ... @code{\voiceFour} commands set up the voices
+so that first and third voices get stems up, second and fourth
+voices get stems down, third and fourth voice note heads are
+horizontally shifted, and rests in the respective voices are
+automatically moved to avoid collisions.  The @code{\oneVoice}
+command returns all the voice settings to the neutral default
+directions.
+
+@strong{@i{Temporary polyphonic passages}}
+
+A temporary polyphonic passage can be created with the following
+construct:

 
 @example
 
 @example

-<< @{ \voiceOne ... @} \new Voice @{ \voiceTwo ... @} >> \oneVoice
+<< @{ \voiceOne ... @}
+  \new Voice @{ \voiceTwo ... @}
+>> \oneVoice

 @end example
 
 @end example
 

-Using the name given when created, this allows lyrics to be assigned
-to one consistent voice.
+Here, the first expression within a temporary polyphonic passage is
+placed into the @code{Voice} context which was in use immediately
+before the polyphonic passage, and that same @code{Voice} context
+continues after the temporary section.  Other expressions within
+the angle brackets are assigned to distinct temporary voices.
+This allows lyrics to be assigned to one continuing voice before,
+during and after a polyphonic section:

 
 @lilypond[quote, verbatim, relative=2]
 <<
 
 @lilypond[quote, verbatim, relative=2]
 <<


@@ -202,11 +247,11 @@ to one consistent voice.
       }
       \new Voice {
         \voiceTwo
       }
       \new Voice {
         \voiceTwo

-        e d
+        d2

       }
     >>
     \oneVoice
       }
     >>
     \oneVoice

-    e
+    e4

   }
   \new Lyrics \lyricsto "melody" {
   This is my song.
   }
   \new Lyrics \lyricsto "melody" {
   This is my song.


@@ -214,13 +259,20 @@ to one consistent voice.
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-Here, the \voiceOne and \voiceTwo commands help to make clear what
-settings does each voice receive.
+Here, the @code{\voiceOne} and @code{\voiceTwo} commands are
+required to define the settings of each voice.

 
 

-The @code{<<@{...@} \\ @{...@}>>} construction, where the two (or
-more) voices are separated by double backslashes, can be used as a
-simplified method to print multiple voices in a single staff.  Our
-first example could be typeset as follows:
+@strong{@i{The double backslash construct}}
+
+The @code{<< @{...@} \\ @{...@} >>} construct, where the two (or
+more) expressions are separated by double backslashes, behaves
+differently to the similar construct without the double backslashes:
+@emph{all} the expressions within this contruct are assigned
+to new @code{Voice} contexts.  These new @code{Voice} contexts
+are created implicitly and are given the fixed names @code{"1"},
+@code{"2"}, etc.
+
+The first example could be typeset as follows:

 
 @lilypond[quote,relative=3,verbatim]
 <<
 
 @lilypond[quote,relative=3,verbatim]
 <<


@@ -230,37 +282,37 @@ first example could be typeset as follows:
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-This syntax is simpler and can be used where it does not matter that
-temporary voices are created and then discarded.  These implicitly
-created voices are given the settings equivalent to the effect of the
-@code{\voiceOne} ... @code{\voiceFour} commands, in the order in which
-they appear in the code.  In the following example, the intermediate
-voice has stems up, therefore we enter it in the third place, so it
-becomes voice three which has the stems up as desired.
+This syntax can be used where it does not matter that temporary
+voices are created and then discarded.  These implicitly created
+voices are given the settings equivalent to the effect of the
+@code{\voiceOne} ... @code{\voiceFour} commands, in the order in
+which they appear in the code.
+
+In the following example, the intermediate voice has stems up,
+therefore we enter it in the third place, so it becomes voice
+three, which has the stems up as desired.  Spacer rests are
+used to avoid printing doubled rests.

 
 @lilypond[quote,relative=3,verbatim]
 <<
 
 @lilypond[quote,relative=3,verbatim]
 <<

-  { r8 g g  g g f16 es f8 d }
+  { r8 g g  g g f16 ees f8 d }

   \\
   \\

-  { es,8 r es r d r d r }
+  { ees,8 r ees r d r d r }

   \\
   { d'8 s c s bes s a s }
 >>
 @end lilypond
 
   \\
   { d'8 s c s bes s a s }
 >>
 @end lilypond
 

-Spacer rests are often used to avoid too many rests, as seen in the
-example above.
-
-In all but simplest works it is advisable to create explicit
-@code{Voice} contexts using the @code{\new} and @code{\context}
-commands as it is explained in @rlearning{Contexts and engravers} and
+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}.
 
 @rlearning{Explicitly instantiating voices}.
 

+@strong{@i{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
 @code{Voice} context, thus forming chords.  To achieve this, enclose
 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
 @code{Voice} context, thus forming chords.  To achieve this, enclose

-them in a simple simultaneous music construction and make it to be an
-explicit voice:
+them in a simple simultaneous music construct within an explicit voice:

 
 @lilypond[quote,relative=2,verbatim]
 \new Voice <<
 
 @lilypond[quote,relative=2,verbatim]
 \new Voice <<


@@ -272,23 +324,25 @@ explicit voice:
 This method leads to strange beamings and warnings if the pieces of
 music do not have the same rhythm.
 
 This method leads to strange beamings and warnings if the pieces of
 music do not have the same rhythm.
 

-@predefined

 
 

+@predefined

 @code{\voiceOne},
 @code{\voiceTwo},
 @code{\voiceThree},
 @code{\voiceFour},
 @code{\oneVoice}.
 @code{\voiceOne},
 @code{\voiceTwo},
 @code{\voiceThree},
 @code{\voiceFour},
 @code{\oneVoice}.

+@endpredefined

 
 

-@seealso

 
 

+@seealso

 Learning Manual:
 @rlearning{Voices contain music},
 @rlearning{Explicitly instantiating voices}.
 
 Notation Reference:
 @ref{Percussion staves},
 Learning Manual:
 @rlearning{Voices contain music},
 @rlearning{Explicitly instantiating voices}.
 
 Notation Reference:
 @ref{Percussion staves},

-@ref{Invisible rests}.
+@ref{Invisible rests},
+@ref{Stems}.

 
 Snippets:
 @rlsr{Simultaneous notes}.
 
 Snippets:
 @rlsr{Simultaneous notes}.


@@ -321,21 +375,20 @@ easily identified:
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-To revert the standard presentation, the @code{\voiceNeutralstyle}
-command is used.
-
-@predefined
+The @code{\voiceNeutralstyle} command is used to revert to the
+standard presentation.

 
 
 
 

+@predefined

 @code{\voiceOneStyle},
 @code{\voiceOneStyle},

-

 @code{\voiceTwoStyle},
 @code{\voiceThreeStyle},
 @code{\voiceFourStyle},
 @code{\voiceNeutralStyle}.
 @code{\voiceTwoStyle},
 @code{\voiceThreeStyle},
 @code{\voiceFourStyle},
 @code{\voiceNeutralStyle}.

+@endpredefined

 
 

-@seealso

 
 

+@seealso

 Learning Manual:
 @rlearning{I'm hearing Voices},
 @rlearning{Other sources of information}.
 Learning Manual:
 @rlearning{I'm hearing Voices},
 @rlearning{Other sources of information}.


@@ -374,9 +427,11 @@ Snippets:
 @funindex \mergeDifferentlyHeadedOff
 @funindex mergeDifferentlyHeadedOff
 
 @funindex \mergeDifferentlyHeadedOff
 @funindex mergeDifferentlyHeadedOff
 

-Note heads with equal durations are automatically merged, while
-note heads with unequal durations are not merged.  Rests opposite
-a stem are shifted vertically.
+The note heads of notes in different voices with the same pitch,
+same note head and opposite stem direction are automatically
+merged, but notes with different note heads or the same stem
+direction are not.  Rests opposite a stem in a different voice
+are shifted vertically.

 
 @lilypond[quote,verbatim,relative=2]
 <<
 
 @lilypond[quote,verbatim,relative=2]
 <<


@@ -394,7 +449,7 @@ a stem are shifted vertically.
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-Note heads with different note heads may be merged, with the
+Notes with different note heads may be merged, with the

 exception of half-note heads and quarter-note heads:
 
 @lilypond[quote,verbatim,relative=2]
 exception of half-note heads and quarter-note heads:
 
 @lilypond[quote,verbatim,relative=2]


@@ -435,14 +490,14 @@ Note heads with different dots may be merged:
 @end lilypond
 
 
 @end lilypond
 
 

-The collision on the second measure happens because
-@code{\mergeDifferentlyHeadedOn} cannot successfully complete the
-merge when three or more notes line up in the same column -- in
-fact, you will obtain a warning for this reason.  To allow the
-merge to work properly, apply a @code{\shift} to the note that
-should not be merged.  Here, @code{\shiftOn} is applied to move
-the top @code{g} out of the column, and
-@code{\mergeDifferentlyHeadedOn} works properly.
+The half note and eighth note at the start of the second measure
+are incorrectly merged because @code{\mergeDifferentlyHeadedOn}
+cannot successfully complete the merge when three or more notes
+line up in the same column, and in this case a warning is given.
+To allow the merge to work properly a @code{\shift} must be applied
+to the note that should not be merged.  Here, @code{\shiftOn} is
+applied to move the top @notation{g} out of the column, and
+@code{\mergeDifferentlyHeadedOn} then works properly.

 
 @lilypond[quote,relative=2,verbatim]
 <<
 
 @lilypond[quote,relative=2,verbatim]
 <<


@@ -471,12 +526,11 @@ two) have @code{\shiftOff}, while the inner voices (three and
 four) have @code{\shiftOn}.  @code{\shiftOnn} and
 @code{\shiftOnnn} define further shift levels.
 
 four) have @code{\shiftOn}.  @code{\shiftOnn} and
 @code{\shiftOnnn} define further shift levels.
 

-Notes are only merged if they have opposing stem directions (i.e., in
+Notes are only merged if they have opposing stem directions (e.g. in

 @code{Voice} 1 and 2).
 
 
 @predefined
 @code{Voice} 1 and 2).
 
 
 @predefined

-

 @code{\mergeDifferentlyDottedOn},
 @code{\mergeDifferentlyDottedOff},
 @code{\mergeDifferentlyHeadedOn},
 @code{\mergeDifferentlyDottedOn},
 @code{\mergeDifferentlyDottedOff},
 @code{\mergeDifferentlyHeadedOn},


@@ -486,6 +540,8 @@ Notes are only merged if they have opposing stem directions (i.e., in
 @code{\shiftOnn},
 @code{\shiftOnnn},
 @code{\shiftOff}.
 @code{\shiftOnn},
 @code{\shiftOnnn},
 @code{\shiftOff}.

+@endpredefined
+

 
 @snippets
 
 
 @snippets
 


@@ -495,8 +551,8 @@ Notes are only merged if they have opposing stem directions (i.e., in
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {forcing-horizontal-shift-of-notes.ly}
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {forcing-horizontal-shift-of-notes.ly}
 

-@seealso

 
 

+@seealso

 Music Glossary:
 @rglos{polyphony}.
 
 Music Glossary:
 @rglos{polyphony}.
 


@@ -513,6 +569,7 @@ Internals Reference:
 @rinternals{NoteCollision},
 @rinternals{RestCollision}.
 
 @rinternals{NoteCollision},
 @rinternals{RestCollision}.
 

+

 @knownissues
 
 When using @code{\mergeDifferentlyHeadedOn} with an upstem eighth
 @knownissues
 
 When using @code{\mergeDifferentlyHeadedOn} with an upstem eighth


@@ -520,9 +577,11 @@ 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.
 
 gets a slightly wrong offset because of the different width of the
 half note head symbol.
 

-@c investigate! Sometimes it works, sometimes not. --FV
+@ignore
+@c TODO investigate! Sometimes it works, sometimes not. --FV

 The requirements for successfully merging different note heads that
 are at the same time differently dotted are not clear.
 The requirements for successfully merging different note heads that
 are at the same time differently dotted are not clear.

+@end ignore

 
 There is no support for chords where the same note occurs with
 different accidentals in the same chord.  In this case, it is
 
 There is no support for chords where the same note occurs with
 different accidentals in the same chord.  In this case, it is


@@ -617,8 +676,8 @@ has no effect on the pitches of @var{musicexpr1} and
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {changing-partcombine-texts.ly}
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {changing-partcombine-texts.ly}
 

-@seealso

 
 

+@seealso

 Music Glossary:
 @rglos{a due},
 @rglos{part}.
 Music Glossary:
 @rglos{a due},
 @rglos{part}.


@@ -633,8 +692,11 @@ Internals Reference:
 @rinternals{PartCombineMusic},
 @rinternals{Voice}.
 
 @rinternals{PartCombineMusic},
 @rinternals{Voice}.
 

+

 @knownissues
 
 @knownissues
 

+@code{\partcombine} can only accept two voices.
+

 When @code{printPartCombineTexts} is set, if the two voices play
 the same notes on and off, the part combiner may typeset @code{a2}
 more than once in a measure.
 When @code{printPartCombineTexts} is set, if the two voices play
 the same notes on and off, the part combiner may typeset @code{a2}
 more than once in a measure.


@@ -644,12 +706,17 @@ more than once in a measure.
 @code{\partcombine} cannot be inside @code{\relative}.
 
 Internally, the @code{\partcombine} interprets both arguments as
 @code{\partcombine} cannot be inside @code{\relative}.
 
 Internally, the @code{\partcombine} interprets both arguments as

-@code{Voice}s named @code{one} and @code{two}, and then decides
-when the parts can be combined.  Consequently, if the arguments
-switch to differently named @rinternals{Voice} contexts, the
-events in those will be ignored.
+@code{Voice}s and decides when the parts can be combined.  When they have
+different durations they cannot be combined and are given the names
+@code{one} and @code{two}.  Consequently, if the arguments switch to
+differently named @rinternals{Voice} contexts, the events in those will
+be ignored.  Likewise, partcombining isn't designed to work with lyrics;
+when one of the voices is explicitly named in order to attach lyrics to
+it, the partcombining stops working.

 
 

-@c IIRC in users list someone pointed out more issues. TODO: lookup FV
+@code{\partcombine} only observes onset times of notes. It cannot
+determine whether a previously started note is playing or not, leading
+to various problems.

 
 
 @node Writing music in parallel
 
 
 @node Writing music in parallel


@@ -762,8 +829,8 @@ global = {
 }
 @end lilypond
 
 }
 @end lilypond
 

-@seealso

 
 

+@seealso

 Learning Manual:
 @rlearning{Organizing pieces with variables}.
 
 Learning Manual:
 @rlearning{Organizing pieces with variables}.