includeGraceNotes: lyrics syllables of grace notes

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

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 34f6cc4938227d2a3b6d3eee3a612688b9de6430..974de3bdbccc0f658f4049386efa52ee050cc56c 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -1152,6 +1152,52 @@ not work if prefixed with @code{\once}.  It is necessary to use
 @code{\set} and @code{\unset} to bracket the lyrics where melismata
 are to be ignored.
 
+@subsubheading Adding syllables to grace notes
+
+By default, grace notes (e.g. via @code{\grace}) do not get assigned
+syllables when using @code{\lyricsto}, but this behavior can be
+changed:
+
+@lilypond[verbatim,ragged-right,quote]
+\relative c' {
+  f4 \appoggiatura a32 b4
+  \grace { f16[ a16] } b2
+  \afterGrace b2 { f16[ a16] }
+  \appoggiatura a32 b4
+  \acciaccatura a8 b4
+}
+\addlyrics {
+  normal
+  \set includeGraceNotes = ##t
+  case,
+  gra -- ce case,
+  after -- grace case,
+  \set ignoreMelismata = ##t
+  app. case,
+  acc. case.
+}
+@end lilypond
+
+@knownissues
+Like for @code{associatedVoice}, @code{includeGraceNotes} needs to be
+set at latest one syllable before the one which is to be put under a
+grace note.  For the case of a grace note at the very beginning of a
+piece of music, consider using a @code{\with} or @code{\context}
+block:
+
+@lilypond[verbatim,ragged-right,quote]
+<<
+  \new Voice = melody \relative c' {
+    \grace { c16[( d e f] }
+    g1) f
+  }
+  \new Lyrics \with { includeGraceNotes = ##t }
+  \lyricsto melody {
+    Ah __ fa
+  }
+>>
+@end lilypond
+
 @subsubheading Switching to an alternative melody
 
 More complex variations in text underlay are possible.  It is possible