X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fsimultaneous.itely;h=d843c29fc36baba571897d9e2742f6e879d6483e;hb=3ec271a5093ea9d3150d3dae7c9f7220df03d12f;hp=e73eab867ffe7c7d18c32bd7bef05b572e2c7129;hpb=1dea8bf1d7182f3d1a1c70bb2010f4585f56b3e6;p=lilypond.git

diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index e73eab867f..d843c29fc3 100644
--- 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.19.29"
 
 
 @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
@@ -52,30 +52,58 @@ A chord is formed by enclosing a set of pitches between @code{<}
 and @code{>}.  A chord may be followed by a duration just like simple
 notes.
 
-@lilypond[verbatim,quote,relative=2]
-<a c e>1 <a c e>2 <f a c e>4 <a c>8. <g c e>16
+@lilypond[verbatim,quote]
+\relative {
+  <a' c e>1 <a c e>2 <f a c e>4 <a c>8. <g c e>16
+}
 @end lilypond
 
 Chords may also be followed by articulations, again just like simple
 notes.
 
-@lilypond[verbatim,quote,relative=2]
-<a c e>1\fermata <a c e>2-> <f a c e>4\prall <a c>8.^| <g c e>16-.
+@lilypond[verbatim,quote]
+\relative {
+  <a' c e>1\fermata <a c e>2-> <f a c e>4\prall <a c>8.^! <g c e>16-.
+}
 @end lilypond
 
 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
+@lilypond[verbatim,quote]
+\relative {
+  <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
 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>\!
+@lilypond[verbatim,quote]
+\relative {
+  <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 {
+  \grace { g'8( a b }
+  <> ) \p \< -. -\markup \italic "sempre staccato"
+  \repeat unfold 4 { c4 e }  c1\f
+}
 @end lilypond
 
 @cindex relative pitch, chords
@@ -88,8 +116,10 @@ pitch of the last note that came before the chord.  All remaining notes
 in the chord are relative to the note that came before it
 @emph{within the same chord}.
 
-@lilypond[verbatim,quote,relative=2]
-<a c e>1 <f a c> <a c e> <f' a c> <b, e b,>
+@lilypond[verbatim,quote]
+\relative {
+  <a' c e>1 <f a c> <a c e> <f' a c> <b, e b,>
+}
 @end lilypond
 
 For more information about chords, see @ref{Chord notation}.
@@ -130,42 +160,94 @@ enharmonic transcription of one or more pitches,
 
 @end itemize
 
+
 @node Chord repetition
 @unnumberedsubsubsec Chord repetition
 
-@cindex Chord, repetition
+@cindex chord, repetition
 @cindex repetition, using @code{q}
+@cindex @code{q}, chord repetition
 
 In order to save typing, a shortcut can be used to repeat the preceding
 chord.  The chord repetition symbol is @code{q}:
 
-@lilypond[verbatim,quote,relative=2]
-<a c e>1 q <f a c>2 q
+@lilypond[verbatim,quote]
+\relative {
+  <a' c e>1 q <f a c>2 q
+}
 @end lilypond
 
 As with regular chords, the chord repetition symbol can be used with
 durations, articulations, markups, slurs, beams, etc. as only the
 pitches of the previous chord are duplicated.
 
-@lilypond[verbatim,quote,relative=2]
-<a c e>1\p^"text" q2\<( q8)[-| q8.]\! q16-1-2-3 q8\prall
+@lilypond[verbatim,quote]
+\relative {
+  <a' c e>1\p^"text" q2\<( q8)[-! q8.]\! q16-1-2-3 q8\prall
+}
 @end lilypond
 
 The chord repetition symbol always remembers the last instance of
 a chord so it is possible to repeat the most recent chord even if
 other non-chorded notes or rests have been added since.
 
-@lilypond[verbatim,quote,relative=2]
-<a c e>1 c4 q2 r8 q8
+@lilypond[verbatim,quote]
+\relative {
+  <a' c e>1 c'4 q2 r8 q8 |
+  q2 c, |
+}
 @end lilypond
 
 However, the chord repetition symbol does not retain any dynamics,
-articulation or ornamentation within, or attached to the previous chord.
+articulation or ornamentation within, or attached to, the previous
+chord.
+
+@lilypond[verbatim,quote]
+\relative {
+  <a'-. c\prall e>1\sfz c'4 q2 r8 q8 |
+  q2 c, |
+}
+@end lilypond
+
+To have some of them retained, the @code{\chordRepeats} function can be
+be called explicitly with an extra argument specifying a list of
+@var{event types} to keep unless events of that type are already
+present on the @code{q} chord itself.
+
+@lilypond[verbatim,quote]
+\relative {
+  \chordRepeats #'(articulation-event)
+  { <a'-. c\prall e>1\sfz c'4 q2 r8 q8-. } |
+  q2 c, |
+}
+@end lilypond
 
-@lilypond[verbatim,quote,relative=2]
-<a-. c\prall e>1\sfz c4 q2 r8 q8
+Here using @code{\chordRepeats} inside of a @code{\relative} construction
+produces unexpected results: once chord events have been expanded, they
+are indistinguishable from having been entered as regular chords, making
+@code{\relative} assign an octave based on their current context.
+
+Since nested instances of @code{\relative} don't affect one another,
+another @code{\relative} inside of @code{\chordRepeats} can be used for
+establishing the octave relations before expanding the repeat chords.
+In that case, the whole content of the inner @code{\relative} does not
+affect the outer one; hence the different octave entry of the final note
+in this example.
+
+@lilypond[verbatim,quote]
+\relative {
+  \chordRepeats #'(articulation-event)
+  \relative
+  { <a'-. c\prall e>1\sfz c'4 q2 r8 q8-. } |
+  q2 c'' |
+}
 @end lilypond
 
+Interactions with @code{\relative} occur only with explicit calls of
+@code{\chordRepeats}: the implicit expansion at the start of typesetting
+is done at a time where all instances of @code{\relative} have already
+been processed.
+
 @seealso
 Notation Reference:
 @ref{Chord notation},
@@ -187,47 +269,62 @@ expression are placed on separate staves.
 
 The following examples show simultaneous expressions on one staff:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 \new Voice {  % explicit single voice
-  << { a4 b g2 } { d4 g c,2 } >>
+  << \relative { a'4 b g2 }
+     \relative { d'4 g c,2 } >>
 }
 @end lilypond
 
-@lilypond[quote,verbatim,relative=2]
-% single first note
-a << { a4 b g } { d4 g c, } >>
+@lilypond[quote,verbatim]
+\relative {
+  % single first note
+  a' << \relative { a'4 b g }
+       \relative { d'4 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 {
+  <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:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 % no single first note
-<< { a4 b g2 } { d4 g2 c,4 } >>
+<< \relative { a'4 b g2 }
+   \relative { d'4 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
 
 @knownissues
-If notes from two or more voices, with stems in the same direction, are
-placed at the same position on the staff and have no shift (or have the
-same shift specified), the message:
+If notes from two or more voices, with no shifts specified,
+have stems in the same direction, the message
 
 @example
-warning: ignoring too many clashing note columns
+warning: This voice needs a \voiceXx or \shiftXx setting
 @end example
 
 will appear during compilation.  This message can be suppressed by:
 
 @example
-\override NoteColumn #'ignore-collision = ##t
+\override NoteColumn.ignore-collision = ##t
 @end example
 
 However, this not only suppresses the warning but will prevent any
@@ -249,15 +346,14 @@ 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,verbatim]
+\relative \makeClusters { <g' b>2 <c g'> }
 @end lilypond
 
 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.
 
-
 @seealso
 Music Glossary:
 @rglos{cluster}.
@@ -270,9 +366,7 @@ Internals Reference:
 @rinternals{ClusterSpannerBeacon},
 @rinternals{Cluster_spanner_engraver}.
 
-
 @knownissues
-
 Clusters look good only if they span at least two chords; otherwise
 they appear too narrow.
 
@@ -283,6 +377,7 @@ separating rest between them.
 
 Clusters do not produce MIDI output.
 
+
 @node Multiple voices
 @subsection Multiple voices
 
@@ -313,17 +408,17 @@ 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:
 
-@lilypond[quote,relative=3,verbatim]
+@lilypond[quote,verbatim]
 \new Staff <<
   \new Voice = "first"
-    { \voiceOne r8 r16 g e8. f16 g8[ c,] f e16 d }
+    \relative { \voiceOne r8 r16 g'' e8. f16 g8[ c,] f e16 d }
   \new Voice= "second"
-    { \voiceTwo d16 c d8~ d16 b c8~ c16 b c8~ c16 b8. }
+    \relative { \voiceTwo d''16 c d8~ 16 b c8~ 16 b c8~ 16 b8. }
 >>
 @end lilypond
 
@@ -337,14 +432,14 @@ 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:
 
 @example
-<< @{ \voiceOne ... @}
-  \new Voice @{ \voiceTwo ... @}
+<< @{ \voiceOne @dots{} @}
+  \new Voice @{ \voiceTwo @dots{} @}
 >> \oneVoice
 @end example
 
@@ -357,10 +452,10 @@ 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 <<
   \new Voice = "melody" {
-    a4
+    a'4
     <<
       {
         \voiceOne
@@ -384,9 +479,9 @@ 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
+The @code{<< @{@dots{}@} \\ @{@dots{}@} >>} 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 construct are assigned
@@ -396,11 +491,11 @@ are created implicitly and are given the fixed names @code{"1"},
 
 The first example could be typeset as follows:
 
-@lilypond[quote,relative=3,verbatim]
+@lilypond[quote,verbatim]
 <<
-  { r8 r16 g e8. f16 g8[ c,] f e16 d }
+  \relative { r8 r16 g'' e8. f16 g8[ c,] f e16 d }
   \\
-  { d16 c d8~ d16 b c8~ c16 b c8~ c16 b8. }
+  \relative { d''16 c d8~ 16 b c8~ 16 b c8~ 16 b8. }
 >>
 @end lilypond
 
@@ -415,13 +510,13 @@ 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,verbatim]
 <<
-  { r8 g g  g g f16 ees f8 d }
+  \relative { r8 g'' g  g g f16 ees f8 d }
   \\
-  { ees,8 r ees r d r d r }
+  \relative { ees'8 r ees r d r d r }
   \\
-  { d'8 s c s bes s a s }
+  \relative { d''8 s c s bes s a s }
 >>
 @end lilypond
 
@@ -429,7 +524,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:
@@ -465,17 +560,20 @@ upstems, and the even-numbered voices are given downstems:
 >>
 @end lilypond
 
-@strong{@i{Identical rhythms}}
+@warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
+created @q{across} voices.}
+
+@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
 @code{Voice} context, thus forming chords.  To achieve this, enclose
 them in a simple simultaneous music construct within an explicit voice:
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]
 \new Voice <<
-  { e4 f8 d e16 f g8 d4 }
-  { c4 d8 b c16 d e8 b4 }
+  \relative { e''4 f8 d e16 f g8 d4 }
+  \relative { c''4 d8 b c16 d e8 b4 }
 >>
 @end lilypond
 
@@ -491,7 +589,6 @@ music do not have the same rhythm.
 @code{\oneVoice}.
 @endpredefined
 
-
 @seealso
 Learning Manual:
 @rlearning{Voices contain music},
@@ -521,15 +618,15 @@ Snippets:
 Voices may be given distinct colors and shapes, allowing them to be
 easily identified:
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
-  { \voiceOneStyle d4 c2 b4 }
+  \relative { \voiceOneStyle d''4 c2 b4 }
   \\
-  { \voiceTwoStyle e,2 e }
+  \relative { \voiceTwoStyle e'2 e }
   \\
-  { \voiceThreeStyle b2. c4 }
+  \relative { \voiceThreeStyle b2. c4 }
   \\
-  { \voiceFourStyle g'2 g }
+  \relative { \voiceFourStyle g'2 g }
 >>
 @end lilypond
 
@@ -545,7 +642,6 @@ standard presentation.
 @code{\voiceNeutralStyle}.
 @endpredefined
 
-
 @seealso
 Learning Manual:
 @rlearning{I'm hearing Voices},
@@ -593,60 +689,68 @@ are shifted vertically.  The following example shows three
 different circumstances, on beats 1 and 3 in bar 1 and beat 1
 in bar 2, where the automatic merging fails.
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 <<
-  {
-    c8 d e d c d c4
+  \relative {
+    c''8 d e d c d c4
     g'2 fis
-  } \\ {
-    c2 c8. b16 c4
+  } \\
+  \relative {
+    c''2 c8. b16 c4
     e,2 r
-  } \\ {
+  } \\
+  \relative {
     \oneVoice
     s1
-    e8 a b c d2
+    e'8 a b c d2
   }
 >>
 @end lilypond
 
-Notes with different note heads may be merged, with the
-exception of half-note heads and quarter-note heads, as shown
-below.  Here the note heads on beat 1 of bar 1 are now merged:
+Notes with different note heads may be merged as shown
+below.  In this example the note heads on beat 1 of bar 1 are now merged:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 <<
-  {
+  \relative {
     \mergeDifferentlyHeadedOn
-    c8 d e d c d c4
+    c''8 d e d c d c4
     g'2 fis
-  } \\ {
-    c2 c8. b16 c4
+  } \\
+  \relative {
+    c''2 c8. b16 c4
     e,2 r
-  } \\ {
+  } \\
+  \relative {
     \oneVoice
     s1
-    e8 a b c d2
+    e'8 a b c d2
   }
 >>
 @end lilypond
 
+Quarter and half notes are not merged in this way, since it would be difficult
+to tell them apart.
+
 Note heads with different dots as shown in beat 3 of bar 1 may be
 also be merged:
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
-  {
+  \relative {
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
-    c8 d e d c d c4
+    c''8 d e d c d c4
     g'2 fis
-  } \\ {
-    c2 c8. b16 c4
+  } \\
+  \relative {
+    c''2 c8. b16 c4
     e,2 r
-  } \\ {
+  } \\
+  \relative {
     \oneVoice
     s1
-    e8 a b c d2
+    e'8 a b c d2
   }
 >>
 @end lilypond
@@ -661,21 +765,23 @@ 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,verbatim]
 <<
-  {
+  \relative {
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
-    c8 d e d c d c4
+    c''8 d e d c d c4
     \shiftOn
     g'2 fis
-  } \\ {
-    c2 c8. b16 c4
+  } \\
+  \relative {
+    c''2 c8. b16 c4
     e,2 r
-  } \\ {
+  } \\
+  \relative {
     \oneVoice
     s1
-    e8 a b c d2
+    e'8 a b c d2
   }
 >>
 @end lilypond
@@ -703,10 +809,10 @@ of voices in your input file should not be the same as the
 vertical order of voices on the staff!}
 
 @lilypond[quote,verbatim]
-\new Staff \relative c'' {
+\new Staff \relative {
   %% abbreviated entry
   <<
-    { f2  }  % 1: highest
+    { f''2  }  % 1: highest
     \\
     { g,2 }  % 2: lowest
     \\
@@ -772,14 +878,14 @@ Internals Reference:
 @cindex collisions, ignoring
 
 @knownissues
-Using @code{\override NoteColumn #'ignore-collision = ##t} will cause
+Using @code{\override NoteColumn.ignore-collision = ##t} will cause
 differently headed notes in different voices to merge incorrectly.
 
-@lilypond[quote,relative=1,verbatim]
+@lilypond[quote,verbatim,fragment]
 \mergeDifferentlyHeadedOn
-<< { c16 a' b a } \\ { c,2 } >>
-\override NoteColumn #'ignore-collision = ##t
-<< { c16 a' b a } \\ { c,2 } >>
+<< \relative { c'16 a' b a } \\ \relative { c'2 } >>
+\override NoteColumn.ignore-collision = ##t
+<< \relative { c'16 a' b a } \\ \relative { c'2 } >>
 @end lilypond
 
 @ignore
@@ -789,6 +895,7 @@ The requirements for successfully merging different note heads that
 are at the same time differently dotted are not clear.
 @end ignore
 
+
 @node Automatic part combining
 @unnumberedsubsubsec Automatic part combining
 
@@ -820,17 +927,17 @@ accordingly.  The same variables are used for the independent parts and
 the combined staff.
 
 @lilypond[quote,verbatim]
-instrumentOne = \relative c' {
-  c4 d e f |
+instrumentOne = \relative {
+  c'4 d e f |
   R1 |
   d'4 c b a |
   b4 g2 f4 |
   e1 |
 }
 
-instrumentTwo = \relative g' {
+instrumentTwo = \relative {
   R1 |
-  g4 a b c |
+  g'4 a b c |
   d4 c b a |
   g4 f( e) d |
   e1 |
@@ -853,6 +960,37 @@ and second parts get marked with @qq{Solo} and @qq{Solo II},
 respectively.  The unison (@notation{a due}) parts are marked with the
 text @qq{a2}.
 
+By default, the partcombiner merges two notes of the same pitch as an
+@notation{a due} note, combines notes with the same
+rhythm less than a ninth apart as chords and separates notes more than
+a ninth apart (or when the voices cross) into
+separate voices.  This can be overridden with an optional argument of a pair
+of numbers after the @code{\partcombine} command: the first specifies
+the interval where notes start to be combined (the default is zero) and the
+second where the notes are split into separate voices.  Setting the second
+argument to zero means that the partcombiner splits notes with an interval of
+a second or more, setting it to one splits notes of a third or more, and so on.
+
+@lilypond[quote,verbatim]
+instrumentOne = \relative {
+  a4 b c d |
+  e f g a |
+  b c d e |
+}
+
+instrumentTwo = \relative {
+  c'4 c c c |
+  c c c c |
+  c c c c |
+}
+
+<<
+  \new Staff \partcombine \instrumentOne \instrumentTwo
+  \new Staff \partcombine #'(2 . 3) \instrumentOne \instrumentTwo
+>>
+@end lilypond
+
+
 Both arguments to @code{\partcombine} will be interpreted as separate
 @code{Voice} contexts, so if the music is being specified in relative
 mode then @emph{both} parts must contain a @code{\relative} function,
@@ -890,33 +1028,33 @@ the @code{\partcombine} function considers each note separately. In this
 case the @code{\partcombine} function can be overriden with the
 following commands:
 
-Commands ending in @code{...Once} apply only to the next note in the
+Commands ending in @code{@dots{}Once} apply only to the next note in the
 music expression.
 
 @itemize
 @item
-@code{\partcombineApart} and @code{\partcombineApartOnce} keep the
+@code{\partcombineApart} and @code{\once \partcombineApart} keep the
 notes as two separate voices, even if they can be combined into a chord
 or unison.
 
 @item
-@code{\partcombineChords} and @code{\partcombineChordsOnce} combine the
+@code{\partcombineChords} and @code{\once \partcombineChords} combine the
 notes into a chord.
 
 @item
-@code{\partcombineUnisono} and @code{\partcombineUnisonoOnce} combine
+@code{\partcombineUnisono} and @code{\once \partcombineUnisono} combine
 both voices as @qq{unison}.
 
 @item
-@code{\partcombineSoloI} and @code{\partcombineSoloIOnce} print only
+@code{\partcombineSoloI} and @code{\once \partcombineSoloI} print only
 voice one, and mark it as a @qq{Solo}.
 
 @item
-@code{\partcombineSoloII} or @code{\partcombineSoloIIOnce} print only
+@code{\partcombineSoloII} or @code{\once \partcombineSoloII} print only
 voice two and mark it as a @qq{Solo}.
 
 @item
-@code{\partcombineAutomatic} and @code{\partcombineAutomaticOnce} end
+@code{\partcombineAutomatic} and @code{\once \partcombineAutomatic} end
 the functions of the commands above, and revert back to the standard
 @code{\partcombine} functionality.
 @end itemize
@@ -927,11 +1065,11 @@ instrumentOne = \relative c' {
   \partcombineAutomatic e2^"auto" e |
   \partcombineChords e'2^"chord" e |
   \partcombineAutomatic c2^"auto" c |
-  \partcombineApart c2^"apart" \partcombineChordsOnce e^"chord once" |
+  \partcombineApart c2^"apart" \once \partcombineChords e^"chord once" |
   c2 c |
 }
-instrumentTwo = \relative c' {
-  c2 c |
+instrumentTwo = \relative {
+  c'2 c |
   e2 e |
   a,2 c |
   c2 c' |
@@ -947,6 +1085,17 @@ instrumentTwo = \relative c' {
 @end lilypond
 
 
+@subsubsubheading Using \partcombine with lyrics
+
+@cindex \partcombine and lyrics
+
+The @code{\partcombine} command is not designed to work with
+lyrics; if one of the voices is explicitly named in order to
+attach lyrics to it, the partcombiner will stop working.  However,
+this effect can be achieved using a @code{NullVoice} context.  See
+@ref{Polyphony with shared lyrics}.
+
+
 @snippets
 
 @lilypondfile[verbatim,quote,texidoc,doctitle]
@@ -955,7 +1104,6 @@ instrumentTwo = \relative c' {
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {changing-partcombine-texts.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{a due},
@@ -972,13 +1120,9 @@ Internals Reference:
 @rinternals{Voice}.
 
 @knownissues
+All @code{\partcombine@dots{}} functions can only accept two voices.
 
-All @code{\partcombine...} functions can only accept two voices and are
-not designed to work with lyrics; such that when one of the voices is
-explicitly named in order to attach lyrics to it, the partcombiner will
-stop working.
-
-@code{\partcombine...} functions cannot be placed inside a @code{\times}
+@code{\partcombine@dots{}} functions cannot be placed inside a @code{\tuplet}
 or @code{\relative} block.
 
 If @code{printPartCombineTexts} is set and the two voices play the same
@@ -1030,12 +1174,12 @@ be of the same length.}
 \parallelMusic #'(voiceA voiceB voiceC) {
   % Bar 1
   r8 g'16 c'' e'' g' c'' e'' r8 g'16 c'' e'' g' c'' e'' |
-  r16 e'8.~   e'4            r16 e'8.~   e'4            |
+  r16 e'8.~   4              r16 e'8.~   4              |
   c'2                        c'2                        |
 
   % Bar 2
   r8 a'16 d'' f'' a' d'' f'' r8 a'16 d'' f'' a' d'' f'' |
-  r16 d'8.~   d'4            r16 d'8.~   d'4            |
+  r16 d'8.~   4              r16 d'8.~   4              |
   c'2                        c'2                        |
 
 }
@@ -1055,12 +1199,12 @@ note in the input -- in other words, relative notes for
 \parallelMusic #'(voiceA voiceB voiceC) {
   % Bar 1
   r8 g16 c e g, c e r8 g,16 c e g, c e  |
-  r16 e8.~ e4       r16 e8.~  e4        |
+  r16 e8.~ 4        r16 e8.~  4         |
   c2                c                   |
 
   % Bar 2
   r8 a,16 d f a, d f r8 a,16 d f a, d f |
-  r16 d8.~  d4       r16 d8.~  d4       |
+  r16 d8.~  4        r16 d8.~  4        |
   c2                 c                  |
 
  }
@@ -1117,7 +1261,6 @@ global = {
 }
 @end lilypond
 
-
 @seealso
 Learning Manual:
 @rlearning{Organizing pieces with variables}.