* Page layout::
* Sound::
* Music entry::
+* Skipping corrected music::
* Interpretation context::
* Syntactic details::
* Lexical details::
@c . {Polyphony}
@node Polyphony
@section Polyphony
-@cindex Polyphony
+@cindex polyphony
-[TODO: collisions, rest-collisinos, voiceX identifiers, how to
-which contexts to instantiate. some small examples? ]
+Polyphonic parts, i.e. parts with more than one voice on a staff can be
+typeset with LilyPond. To use this, instantiate a separate Voice
+context for each part, and assign a stem direction to each part.
+@lilypond[fragment,verbatim]
+\context Staff
+< \context Voice = VA { \stemUp b'4 a' g' f' e' }
+ \context Voice = VB { \stemDown g'4 g' g' g' g' } >
+@end lilypond
+
+When there are more than two voices on a staff, you must also indicate
+which voice should moved horizontally in case of a collision. This can
+be done with the identifiers @code{\shiftOff}, @code{\shiftOn},
+@code{\shiftOnn}, etc. (which sets grob property @code{horizontal-shift}
+in @code{NoteColumn}).
+
+@lilypond[fragment, verbatim]
+ \context Staff \notes\relative c''<
+ \context Voice=one {
+ \shiftOff \stemUp e4
+ }
+ \context Voice=two {
+ \shiftOn \stemUp cis
+ }
+ \context Voice=three {
+ \shiftOnn \stemUp ais
+ }
+ \context Voice=four {
+ \shiftOnnn \stemUp fis-2
+ }
+ >
+@end lilypond
+The most convenient way is to use the identifiers @code{\voiceOne}
+through @code{\voiceFour}, which also set slur and tie directions in the
+correct manner.
+
+@lilypond[singleline, verbatim]
+\relative c''
+\context Staff < \context Voice = VA { \voiceOne cis2 b }
+ \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
+ \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
+@end lilypond
+
+
+LilyPond also vertically shifts rests that are opposite of a stem.
+
+@lilypond[singleline,verbatim]
+\context Staff <
+\context Voice { \stemUp c''4 }
+\context Voice =VB { r4 }
+>
+@end lilypond
+
+Note head collisions (horizontal shifting of note heads) are handled by
+the @code{NoteCollision} grob. @code{RestCollision} handles vertical
+shifting of rests.
+
+@cindex @code{NoteCollision}
+@cindex @code{RestCollision}
-@table @code
-@cindex @code{\shiftOff}
- @item @code{\shiftOff}
- Disable horizontal shifting of note heads that collide.
-
-@cindex @code{\shiftOn}
- @item @code{\shiftOn}
- Enable note heads that collide with other note heads to be
- shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
-set different shift values.
-
-@cindex @code{\stemBoth}
- @item @code{\stemBoth}
- Allow stems and beams to point either upwards or
- downwards, decided automatically by LilyPond.
-
-@cindex @code{\stemDown}
- @item @code{\stemDown}
- Force stems and beams to point down.
-
-@cindex @code{\stemUp}
- @item @code{\stemUp}
- Force stems and beams to point up.
-@end table
-@cindex @code{\slurBoth}
-@cindex @code{\slurDown}
-@cindex @code{\slurUp}
-Similarly, for slurs use
-@code{\slurBoth},
-@code{\slurDown},
-@code{\slurUp}.
-
-@cindex @code{\tieBoth}
-@cindex @code{\tieDown}
-@cindex @code{\tieUp}
-For ties use
-@code{\tieBoth},
-@code{\tieDown},
-@code{\tieUp}.
-
-@cindex @code{\dynacmicBoth}
-@cindex @code{\dynamicDown}
-@cindex @code{\dynamicUp}
-For dynamics use
-@code{\dynamicBoth},
-@code{\dynamicDown},
-@code{\dynamicUp}.
-
-@c text scripts? articulation scripts? fingering?
-
-@cindex @code{\voiceOne}
-@cindex @code{\voiceTwo}
-@cindex @code{\voiceThree}
-@cindex @code{\voiceFour}
-@cindex @code{\oneVoice}
-@cindex @code{\shiftOn}
-@cindex @code{\shiftOff}
-
-If two voices sharing one staff have the same stem directions, their
-note heads may collide. You can shift the note heads of one voice by
-setting @code{\shiftOn}. This can be undone by setting
-@code{\shiftOff}.
-
-For simple polyphonic music, shorthands are available that combine
-directions and shift settings: @code{\voiceOne}, @code{\voiceTwo},
-@code{\voiceThree}, @code{\voiceFour} and @code{\oneVoice}.
+@refbugs
+
+Resolving collisions is a very intricate subject, and LilyPond only
+handles a few situations. When it can not cope, you are advised to use
+@code{force-hshift} of the NoteColumn grob and @code{staff-position} of
+the Rest grob to override typesetting decisions.
+[TODO: doc merge-differently-dotted]
@node Beaming
@section Beaming
@end lilypond
This requires that you add the @code{Instrument_name_engraver} to the
-staff context.
+staff context. You can also use markup texts:
+
+
+@lilypond[verbatim,singleline]
+#(define text-flat
+ '((font-relative-size . -2 ) (music "accidentals--1")))
+
+\score { \notes {
+ \property Staff.instrument = #`((kern . 0.5) (lines
+ "2 Clarinetti" (rows " (B" ,text-flat ")")))
+ c'' 4 }
+ \paper {
+ \translator { \StaffContext
+ \consists "Instrument_name_engraver"; } } }
+@end lilypond
@node Transpose
you can change the resulting grobs.
@lilypond[verbatim, fragment]
-c'4 \property Voice.Stem \override #'meta = #'((interfaces . ())) c'4
+c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
@end lilypond
-The @code{\property} statement effectively empties the definition of the
-Stem object. One of the effects is that property specifying how it
+The @code{\property} assignment effectively empties the definition of
+the Stem object. One of the effects is that property specifying how it
should be printed is erased, with the effect of rendering it invisible.
+The above assignment is available as a standard identifier, lest you
+find this useful:
+@example
+ \property Voice.Stem = \turnOff
+@end example
@cindex \override
@cindex \revert
exact length of the string, which may lead to collisions. Also, @TeX{}
commands won't work with direct postscript output.
+@cindex metronome mark
+
+One practical application of complicated markup is to fake a metronome
+marking:
+
+@lilypond[verbatim]
+#(define note '(rows
+ (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
+#(define eight-note `(rows ,note ((kern . -0.1)
+ (music ((raise . 3.5) "flags-u3")))))
+#(define dotted-eight-note
+ `(rows ,eight-note (music "dots-dot")))
+
+\score {
+ \notes\relative c'' {
+ a1^#`((rows (font-relative-size . -1)) ,dotted-eight-note " = 64")
+ }
+ \paper {
+ linewidth = -1.;
+ \translator{
+ \ScoreContext
+ TextScript \override #'font-shape = #'upright
+ }
+ }
+}
+@end lilypond
+
+
+
@c . {Page layout}
@node Page layout
@section Page layout
A bar check is entered using the bar symbol, @code{|}
-
-
@c . {Point and click}
@node Point and click
@subsection Point and click
harmless, and can be ignored.
+@node Skipping corrected music
+@section Skipping corrected music
+
+The property @code{Score.skipTypesetting} can be used to switch on and
+off typesetting completely during the interpretation phase. When
+typesetting is switched off, the music is processed much more quickly.
+You can use this to skip over the parts of a score that you have already
+checked for errors.
+
+@lilypond[fragment,singleline,verbatim]
+\relative c'' { c8 d
+\property Score.skipTypesetting = ##t
+ e f g a g c, f e d
+\property Score.skipTypesetting = ##f
+c d b bes a g c2 }
+@end lilypond
+
+
@node Interpretation context
@section Interpretation context
This example replaces the text string of a script. It also shows a dump
of the music it processes, which is useful if you want to know more
about how music is stored.
-@lilypond[verbatim]
+
+@lilypond[verbatim,singleline]
#(define (testfunc x)
(if (equal? (ly-get-mus-property x 'text) "foo")
(ly-set-mus-property x 'text "bar"))
}
@end lilypond
-For more information on what is possible, see the @ref{Tricks} and the
-automatically generated documentation.
+For more information on what is possible, see the automatically
+generated documentation.
Directly accessing internal representations is dangerous: the
implementation is subject to changes, so you should avoid this feature
if possible.
-
-
+
+A final example is a function that reverses a piece of music in time:
+
+@lilypond[verbatim,singleline]
+#(define (reverse-music music)
+ (let* ((elements (ly-get-mus-property music 'elements))
+ (reversed (reverse elements))
+ (span-dir (ly-get-mus-property music 'span-direction)))
+ (ly-set-mus-property music 'elements reversed)
+ (if (dir? span-dir)
+ (ly-set-mus-property music 'span-direction (- span-dir)))
+ (map reverse-music reversed)
+ music))
+
+music = \notes { c'4 d'4( e'4 f'4 }
+
+\score { \context Voice {
+ \music
+ \apply #reverse-music \music
+ }
+}
+@end lilypond
+
@c . {Span requests}
@menu