X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fvocal.itely;h=3736331f836ad8867ef97c46b871345a512481f0;hb=1423508c355989fa26a8cfe5985b0d6e1ab0a538;hp=0ab25a2d9ccc9b626c01d45be23eee37aa61b3aa;hpb=de451af43aef0220738bfdd5329f0685bdaba3d2;p=lilypond.git

diff --git a/Documentation/user/vocal.itely b/Documentation/user/vocal.itely
index 0ab25a2d9c..3736331f83 100644
--- a/Documentation/user/vocal.itely
+++ b/Documentation/user/vocal.itely
@@ -6,7 +6,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.61"
+@c \version "2.12.0"
 
 @node Vocal music
 @section Vocal music
@@ -17,12 +17,123 @@ This section explains how to typeset vocal music, and make sure
 that the lyrics will be aligned with the notes of their melody.
 
 @menu
+* Common notation for vocal music::
 * Entering lyrics::
 * Aligning lyrics to a melody::
 * Specific uses of lyrics::
 * Stanzas::
 @end menu
 
+
+@node Common notation for vocal music
+@subsection Common notation for vocal music
+
+This section discusses issues related to vocal music in general, and
+to some particular styles of vocal music.
+
+@menu
+* References for vocal music and lyrics::
+* Opera::
+* Song books::
+* Spoken music::
+* Chants::
+* Ancient vocal music::
+@end menu
+
+
+@node References for vocal music and lyrics
+@unnumberedsubsubsec References for vocal music and lyrics
+
+@c TODO: split this section in two parts? -vv
+
+Various issues may arise when engraving vocal music.  Some of these
+are discussed in this section, while others are explained elsewhere:
+
+@itemize
+@item
+Most styles of vocal music use written text as lyrics.  An introduction
+to this notation is to be found in @rlearning{Setting simple songs}.
+
+@item
+Vocal music is likely to require the use of @code{markup} mode, either
+for lyrics of for other text elements (character's names, etc.).
+This syntax is described in @ref{Text markup introduction}.
+
+@item
+Lead sheets may be printed by combining vocal parts and @q{chord mode};
+this syntax is explained in @ref{Chord notation}.
+
+@item
+@q{Ambitus} may be added at the beginning of vocal staves, as explained
+in @ref{Ambitus}.
+
+@item
+Vocal parts may be printed using traditional clefs, as shown in @ref{Clef}.
+
+@item
+Ancient vocal music is supported, as explained in @ref{Ancient notation}.
+@end itemize
+
+
+@node Opera
+@unnumberedsubsubsec Opera
+
+@c TODO
+TBC
+
+@c add characters names snippet -vv
+
+@node Song books
+@unnumberedsubsubsec Song books
+
+@c TODO
+TBC
+
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{simple-lead-sheet.ly}
+
+
+@seealso
+Notation Reference:
+@ref{Chord notation}.
+
+
+@node Spoken music
+@unnumberedsubsubsec Spoken music
+@cindex parlato
+@cindex Sprechgesang
+Such effects as @q{parlato} or @q{Sprechgesang} require perfomers to speak
+without pitch but still with rhythm; these are notated by cross
+note heads, as demonstrated in @ref{Special note heads}.
+
+@c TODO add "marking-notes-on-spoken-parts" snippet -vv
+@c add "showing the rhythm of a melody" snip
+@c add "one staff-line notation"
+@c add "improvisation" ref
+@c add "lyrics independents of notes" ref
+
+@node Chants
+@unnumberedsubsubsec Chants
+
+@c TODO Add text from lsr and -user
+TBC
+
+@node Ancient vocal music
+@unnumberedsubsubsec Ancient vocal music
+
+@c TODO
+TBC
+
+@c Add "Printing both the ancient and the modern clef in vocal music" snippet,
+@c and "Transcription of Ancient music with incipit" snippet. -vv
+
+
+@seealso
+Notation Reference:
+@ref{Ancient notation}.
+
+
 @node Entering lyrics
 @subsection Entering lyrics
 
@@ -32,7 +143,6 @@ that the lyrics will be aligned with the notes of their melody.
 * Lyrics explained::
 * Setting simple songs::
 * Working with lyrics and variables::
-* References for vocal music::
 @end menu
 
 
@@ -47,11 +157,11 @@ that the lyrics will be aligned with the notes of their melody.
 
 @c FIXME: this section is to be rewritten.
 Since LilyPond input files are text, there is at least one
-issue to consider when working with vocal music: 
+issue to consider when working with vocal music:
 song texts must be interpreted as text, not notes.  For example, the
 input@tie{}@code{d} should be interpreted as a one letter syllable,
 not the note@tie{}D.
-Therefore, a special lyric mode has to be used, either explicitely
+Therefore, a special lyric mode has to be used, either explicitly
 or using some abbreviated methods.
 
 Lyrics are entered in a special input mode, which can be introduced
@@ -182,7 +292,6 @@ verseOne = \lyricmode @{ Joy to the world the Lord is come @}
 
 
 @seealso
-
 Notation Reference:
 @ref{Fonts}.
 
@@ -191,6 +300,7 @@ Internals Reference:
 @rinternals{LyricSpace}.
 
 
+@c FIXME: this title has to be changed (possible confusion with LM) -vv
 @node Setting simple songs
 @unnumberedsubsubsec Setting simple songs
 
@@ -315,28 +425,14 @@ remains empty.
 
 @end ignore
 
-@seealso
 
+@seealso
 @c TODO: document \new Staff << Voice \lyricsto >> bug
 Internals Reference:
 @rinternals{LyricCombineMusic},
 @rinternals{Lyrics}.
 
 
-@node References for vocal music
-@unnumberedsubsubsec References for vocal music
-
-TBC
-@c TODO Add @refs
-
-@c Nope -- this section is to be removed.
-@c With a vengeance :-) -vv
-
-@q{Parlato} is spoken without pitch but still with rhythm; it is
-notated by cross note heads.  This is demonstrated in
-@ref{Special note heads}.
-
-
 @node Aligning lyrics to a melody
 @subsection Aligning lyrics to a melody
 
@@ -372,6 +468,13 @@ or by specifying the duration of each syllable
 explicitly, using @code{\lyricmode}
 @end itemize
 
+The @code{Voice} context containing the melody to which the lyrics
+are being aligned must not have @qq{died}, or the lyrics after that
+point will be lost.  This can happen if there are periods when that
+voice has nothing to do.  For methods of keeping contexts alive, see
+@ref{Keeping contexts alive}.
+
+
 @menu
 * Automatic syllable durations::
 * Manual syllable durations::
@@ -413,7 +516,7 @@ The following example uses different commands for entering lyrics.
     c4 b8. a16 g4. f8 e4 d c2
   }
 
-% not recommended: left aligns syllables 
+% not recommended: left aligns syllables
   \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
 
 % wrong: durations needed
@@ -482,7 +585,10 @@ Here is an example demonstrating manual lyric durations,
  } >>
 @end lilypond
 
+
 @seealso
+Notation Reference:
+@ref{Keeping contexts alive}.
 
 Internals Reference:
 @rinternals{Lyrics}.
@@ -511,8 +617,8 @@ glyph.}.
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 
-@seealso
 
+@seealso
 Internals Reference:
 @rinternals{LyricCombineMusic}.
 
@@ -534,7 +640,7 @@ single syllable; such vocalises are called melismas, or melismata.
 @c it might be better to present it first - vv
 
 You can define melismata entirely in the lyrics, by entering @code{_}
-for every extra note that has to be added to the the melisma.
+for every extra note that has to be added to the melisma.
 
 @c FIXME: clarify: __ is used to crate a lyric extender,
 @c _ is used to add a note to a melisma, so both __ and _ are needed.
@@ -596,15 +702,17 @@ A complete example of a SATB score setup is in section
 
 
 @predefined
-
-@code{\melisma}, @code{\melismaEnd}
-@funindex \melismaEnd
 @funindex \melisma
+@code{\melisma},
+@funindex \melismaEnd
+@code{\melismaEnd}.
+@endpredefined
 
-@seealso
 
+@seealso
 @c @lsr{vocal,lyric@/-combine.ly}.
 
+
 @knownissues
 
 Melismata are not detected automatically, and extender lines must be
@@ -614,7 +722,7 @@ inserted by hand.
 @unnumberedsubsubsec Skipping notes
 
 Making a lyric line run slower than the melody can be achieved by
-inserting @code{\skip}s into the lyrics.  For every @code{\skip}, 
+inserting @code{\skip}s into the lyrics.  For every @code{\skip},
 the text will be delayed another note.  The @code{\skip} command
 must be followed by a valid duration, but this is ignored when
 @code{\skip} is used in lyrics.
@@ -662,12 +770,13 @@ happens can be controlled with the @code{minimum-distance} (minimum
 distance between two syllables) and the @code{minimum-length}
 (threshold below which hyphens are removed).
 
-@seealso
 
+@seealso
 Internals Reference:
 @rinternals{LyricExtender},
 @rinternals{LyricHyphen}
 
+
 @node Lyrics and repeats
 @unnumberedsubsubsec Lyrics and repeats
 
@@ -687,7 +796,6 @@ differing ways.  Such variations can still be captured with
 @menu
 * Divisi lyrics::
 * Lyrics independent of notes::
-* Chants::
 * Spacing out syllables::
 * Centering lyrics between staves::
 @end menu
@@ -781,13 +889,6 @@ the implicit melismata get ignored.
 
 @c this clarifies http://code.google.com/p/lilypond/issues/detail?id=248
 
-
-@node Chants
-@unnumberedsubsubsec Chants
-
-@c TODO Add text from lsr and -user
-TBC
-
 @node Spacing out syllables
 @unnumberedsubsubsec Spacing out syllables
 
@@ -883,12 +984,12 @@ TBC
 @subsection Stanzas
 
 @menu
-* Adding stanza numbers ::
+* Adding stanza numbers::
 * Adding dynamics marks to stanzas::
 * Adding singers' names to stanzas::
 * Stanzas with different rhythms::
-* Printing stanzas at the end ::
-* Printing stanzas at the end in multiple columns ::
+* Printing stanzas at the end::
+* Printing stanzas at the end in multiple columns::
 @end menu
 
 
@@ -903,10 +1004,10 @@ Stanza numbers can be added by setting @code{stanza}, e.g.,
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
-  \set stanza = "1. "
+  \set stanza = #"1. "
   Hi, my name is Bert.
 } \addlyrics {
-  \set stanza = "2. "
+  \set stanza = #"2. "
   Oh, ché -- ri, je t'aime
 }
 @end lilypond
@@ -916,7 +1017,7 @@ Stanza numbers can be added by setting @code{stanza}, e.g.,
 These numbers are put just before the start of the first syllable.
 
 @c TODO Create and add snippet to show how two lines of a
-@c stanza can be grouped together, along these lines: 
+@c stanza can be grouped together, along these lines:
 @c (might need improving a bit) -td
 
 @ignore
@@ -940,8 +1041,8 @@ stanzaOneThree =  {
 }
 
 \new Voice {
-  \repeat volta 2 { c'8 c' c' c' c' c' c'4 
-                    c'8 c' c' c' c' c' c'4   } 
+  \repeat volta 2 { c'8 c' c' c' c' c' c'4
+                    c'8 c' c' c' c' c' c'4   }
 }  \addlyrics { \stanzaOneOne }
    \addlyrics { \stanzaOneThree }
 
@@ -987,10 +1088,10 @@ the line, just like instrument names.  They are created by setting
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
-  \set vocalName = "Bert "
+  \set vocalName = #"Bert "
   Hi, my name is Bert.
 } \addlyrics {
-  \set vocalName = "Ernie "
+  \set vocalName = #"Ernie "
   Oh, ché -- ri, je t'aime
 }
 @end lilypond
@@ -1005,12 +1106,6 @@ multiple syllables in another one.  One solution is to make the faster
 voice ignore the melisma.  This is done by setting
 @code{ignoreMelismata} in the Lyrics context.
 
-There is one tricky aspect: the setting for @code{ignoreMelismata}
-must be set one syllable @emph{before} the non-melismatic syllable
-in the text, as shown here,
-
-@c  TODO: breaks compile
-@c seems to be fixed, does not break compile anymore --FV
 @lilypond[verbatim,ragged-right,quote]
 <<
   \relative c' \new Voice = "lahlah" {
@@ -1024,18 +1119,20 @@ in the text, as shown here,
     more slow -- ly
   }
   \new Lyrics \lyricsto "lahlah" {
-    \set ignoreMelismata = ##t % applies to "fas"
-    go fas -- ter
+    go
+    \set ignoreMelismata = ##t
+    fas -- ter
     \unset ignoreMelismata
     still
   }
 >>
 @end lilypond
 
-
-The @code{ignoreMelismata} applies to the syllable @q{fas}, so it
-should be entered before @q{go}.
-
+@knownissues
+Unlike most @code{\set} commands, @code{\set ignoreMelismata} does
+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 Switching to an alternative melody
 
@@ -1140,7 +1237,7 @@ d d e d | c1 |
 }
 
 text = \lyricmode {
-\set stanza = "1." Ma- ry had a lit- tle lamb,
+\set stanza = #"1." Ma- ry had a lit- tle lamb,
 its fleece was white as snow.
 }
 
@@ -1179,9 +1276,9 @@ output in LilyPond.
 melody = \relative c' {
   c c c c | d d d d
 }
- 
+
 text = \lyricmode {
-  \set stanza = "1." This is verse one.
+  \set stanza = #"1." This is verse one.
   It has two lines.
 }
 
@@ -1194,7 +1291,7 @@ text = \lyricmode {
 
 \markup {
   \fill-line {
-    \hspace #0.1 % moves the column off the left margin; 
+    \hspace #0.1 % moves the column off the left margin;
         % can be removed if space on the page is tight
      \column {
       \line { \bold "2."
@@ -1211,8 +1308,8 @@ text = \lyricmode {
         }
       }
     }
-    \hspace #0.1  % adds horizontal spacing between columns; 
-        % if they are still too close, add more " " pairs  
+    \hspace #0.1  % adds horizontal spacing between columns;
+        % if they are still too close, add more " " pairs
         % until the result looks good
      \column {
       \line { \bold "4."
@@ -1229,7 +1326,7 @@ text = \lyricmode {
         }
       }
     }
-  \hspace #0.1 % gives some extra space on the right margin; 
+  \hspace #0.1 % gives some extra space on the right margin;
       % can be removed if page space is tight
   }
 }
@@ -1237,7 +1334,6 @@ text = \lyricmode {
 
 
 @seealso
-
 Internals Reference:
 @rinternals{LyricText},
 @rinternals{StanzaNumber}.