@menu
* Instantiating new staves::
* Grouping staves::
-* Deeper nested staff groups::
+* Nested staff groups::
@end menu
@node Instantiating new staves
>>
@end lilypond
-@node Deeper nested staff groups
-@unnumberedsubsubsec Deeper nested staff groups
+@node Nested staff groups
+@unnumberedsubsubsec Nested staff groups
@untranslated
<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}.
themselves. Separate clusters would need a separating rest between
them.
+Clusters do not produce MIDI output.
@node Multiple voices
@subsection Multiple voices
>>
@end lilypond
-Spacer rests are often used to avoid too many rests, as seen in the
+@noindent
+Spacer rests are often used to avoid having too many rests, as seen in the
example above.
In all but simplest works it is advisable to create explicit
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).
@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.
@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.
-
-@c IIRC in users list someone pointed out more issues. TODO: lookup FV
+@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.
+
+@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
@menu
* Instantiating new staves::
* Grouping staves::
-* Deeper nested staff groups::
+* Nested staff groups::
@end menu
@rinternals{SystemStartSquare}.
-@node Deeper nested staff groups
-@unnumberedsubsubsec Deeper nested staff groups
+@node Nested staff groups
+@unnumberedsubsubsec Nested staff groups
@cindex staff, nested
@cindex staves, nested
{ a4 b c d }
@end lilypond
-The width of a staff can be modified. The unit is one staff
-space. The spacing of objects inside the staff is not affected by
+The width of a staff can be modified. The units are staff
+spaces. The spacing of objects inside the staff is not affected by
this setting.
@lilypond[verbatim,quote,relative=1]
@end lilypond
Further details about the properties of @code{StaffSymbol} can be
-found here: @rinternals{staff-symbol-interface}.
+found in @rinternals{staff-symbol-interface}.
@funindex \startStaff
@funindex \stopStaff
@cindex fragments
@cindex cue notes
-Fragments of other parts can be inserted directly into a music
-expression; this is called @emph{quotation}. Before a part can be
-quoted, the @code{\addQuote} command must be used to initialize
-the quoted fragment. This command must be used in the toplevel
-scope. The first argument is an identifying string, and the
-second is a music expression:
+It is very common for one voice to double the some of the music from
+another voice. For example, the first and second violins may play the
+same notes during a passage of music. In LilyPond this is accomplished
+by letting one voice @emph{quote} the other voice without having to
+re-enter it.
+
+Before a part can be quoted, the @code{\addQuote} command must be used
+to initialize the quoted fragment. This command must be used in the
+toplevel scope. The first argument is an identifying string, and the
+second is a music expression:
@example
flute = \relative c'' @{
\addQuote "flute" @{ \flute @}
@end example
-The @code{\quoteDuring} command is used to indicate when the
-quotation should take place. The corresponding measures from the
-quotation are inserted into the music expression. The syntax is
-similar to @code{\addQuote}:
+The @code{\quoteDuring} command is used to indicate the point where the
+quotation begins. It is followed by two arguments: the name of the
+quoted voice, as defined with @code{\addQuote}, and a music expression
+that indicates the duration of the quote, usually spacer rests or
+multi-measure rests. The corresponding music from the quoted voice is
+inserted into the music expression:
@lilypond[verbatim,quote]
flute = \relative c'' {