Resolve conflict

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

diff --git a/Documentation/user/vocal.itely b/Documentation/user/vocal.itely
index fbdb90f4c7db9d712ca259e17992689fbd83ddd0..0ab25a2d9ccc9b626c01d45be23eee37aa61b3aa 100644 (file)
--- a/Documentation/user/vocal.itely
+++ b/Documentation/user/vocal.itely
@@ -6,157 +6,38 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.51"
+@c \version "2.11.61"

 
 @node Vocal music
 @section Vocal music
 
 
 @node Vocal music
 @section Vocal music
 

-@c TODO: CLARIFY
-@c TODO: delete this comment block
-@c http://code.google.com/p/lilypond/issues/detail?id=248
-@c Done, see @node Lyrics independent of notes ----FV
+@c TODO: inspirational headword

 
 

-@c http://code.google.com/p/lilypond/issues/detail?id=329
-@c Done, see @node Working with lyrics and variables ----FV
-
-@c partially done, needs improvement, see Switching to an alternative melody ----FV
-@ignore
-
-> I think the issue here is that changing the associatedVoice
-> happens one step
-> later than expected.  I could be wrong, but I don't think this
-> is obviously
-> documented.
-
-If you read section "Switching the melody associated with a lyrics
-line"
-it indeed says "Again, the command must be one syllable too
-early,..."!
-One problem with the current formulation is that the "Again"
-refers to what's described 2 subsections earlier in "Lyrics to
-multiple notes of a melisma", which isn't obvious unless you have
-read all the sections
-sequentially.
-
-
-@c Done in @node Extenders and hyphens ---FV
-@c also done (duplicated) in @node Multiple notes to one syllable --FV
-I don't know who's working on the vocal music right now, but I
-found something that should be clarified in NR 2.1.2.4.
-
-It should be made clear that __ is used to crate a lyric extender,
-and _ is used to add a note to a melisma, so both __ and _ are
-used.  The example shows it, but there is no description of the
-lyrics extender in this section.
-@end ignore
-
-
-Since LilyPond input files are text, there are two issues to
-consider when working with vocal music:
-
-@itemize
-@item
-Song texts must be entered as text, not notes.  For example, the
-input@tie{}@code{d} should be interpreted as a one letter syllable, not the
-note@tie{}D.
-
-@item
-Song texts must be aligned with the notes of their melody.
-@end itemize
-
-There are a few different ways to define lyrics; we shall begin
-by examining the simplest method, and gradually increase complexity.
+This section explains how to typeset vocal music, and make sure
+that the lyrics will be aligned with the notes of their melody.

 
 @menu
 
 @menu

-* Common notation for vocals::
+* Entering lyrics::

 * Aligning lyrics to a melody::
 * Aligning lyrics to a melody::

-* Placement of lyrics::
+* Specific uses of lyrics::

 * Stanzas::
 @end menu
 
 * Stanzas::
 @end menu
 

-@snippets
-
-Checking to make sure that text scripts and lyrics are within the margins is
-a relatively large computational task.  To speed up processing, LilyPond does
-not perform such calculations by default; to enable it, use
-
-@example
-\override Score.PaperColumn #'keep-inside-line = ##t
-@end example
-
-To make lyrics avoid bar lines as well, use
-
-@example
-\layout @{
-  \context @{
-    \Lyrics
-      \consists "Bar_engraver"
-      \consists "Separating_line_group_engraver"
-      \override BarLine #'transparent = ##t
-  @}
-@}
-@end example
+@node Entering lyrics
+@subsection Entering lyrics

 
 

-@node Common notation for vocals
-@subsection Common notation for vocals
+@c TODO add one sentence here. -vv

 
 @menu
 
 @menu

-* References for vocal music::
+* Lyrics explained::

 * Setting simple songs::
 * Setting simple songs::

-* Entering lyrics::

 * Working with lyrics and variables::
 * Working with lyrics and variables::

+* References for vocal music::

 @end menu
 
 @end menu
 

-@node References for vocal music
-@subsubsection References for vocal music
-
-TBC
-@c TODO Add @refs
-
-@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 Setting simple songs
-@subsubsection Setting simple songs
-
-@cindex \addlyrics
-
-The easiest way to add lyrics to a melody is to append
-
-@example
-\addlyrics @{ @var{the lyrics} @}
-@end example
-
-@noindent
-to a melody.  Here is an example,
-
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative c' { c2 e4 g2. }
-\addlyrics { play the game }
-@end lilypond
-
-More stanzas can be added by adding more
-@code{\addlyrics} sections
-
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative c' { c2 e4 g2. }
-\addlyrics { play the game }
-\addlyrics { speel het spel }
-\addlyrics { joue le jeu }
-@end lilypond
-
-The command @code{\addlyrics} cannot handle polyphony settings.  For these
-cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
-introduced in @ref{Entering lyrics}.
-
-

 
 

-@node Entering lyrics
-@subsubsection Entering lyrics
+@node Lyrics explained
+@unnumberedsubsubsec Lyrics explained

 
 @cindex lyrics
 @funindex \lyricmode
 
 @cindex lyrics
 @funindex \lyricmode


@@ -164,6 +45,15 @@ introduced in @ref{Entering lyrics}.
 @cindex spaces, in lyrics
 @cindex quotes, in lyrics
 
 @cindex spaces, in lyrics
 @cindex quotes, in lyrics
 

+@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: 
+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
+or using some abbreviated methods.
+

 Lyrics are entered in a special input mode, which can be introduced
 by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
 @code{\lyricsto}.  In this mode you can enter lyrics,
 Lyrics are entered in a special input mode, which can be introduced
 by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
 @code{\lyricsto}.  In this mode you can enter lyrics,


@@ -236,9 +126,11 @@ between syllables, or use tilde  symbol (@code{~}) to get a lyric tie.
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 

-The lyric tie is implemented with the Unicode character U+203F, so be
-sure to have a font (Like DejaVuLGC) installed that includes this
-glyph.
+@noindent
+The lyric tie is implemented with the Unicode character
+@code{U+203F}; therefore a font that includes this glyph
+(such as DejaVuLGC) has to be used.  More explanations about
+text and non-text fonts can be found in @ref{Fonts}.

 
 
 To enter lyrics with characters from non-English languages, or with
 
 
 To enter lyrics with characters from non-English languages, or with


@@ -291,12 +183,54 @@ verseOne = \lyricmode @{ Joy to the world the Lord is come @}
 
 @seealso
 
 
 @seealso
 

+Notation Reference:
+@ref{Fonts}.
+

 Internals Reference:
 @rinternals{LyricText},
 @rinternals{LyricSpace}.
 
 Internals Reference:
 @rinternals{LyricText},
 @rinternals{LyricSpace}.
 

+
+@node Setting simple songs
+@unnumberedsubsubsec Setting simple songs
+
+@cindex \addlyrics
+
+The easiest way to add lyrics to a melody is to append
+
+@example
+\addlyrics @{ @var{the lyrics} @}
+@end example
+
+@noindent
+to a melody.  Here is an example,
+
+@lilypond[ragged-right,verbatim,fragment,quote]
+\time 3/4
+\relative c' { c2 e4 g2. }
+\addlyrics { play the game }
+@end lilypond
+
+More stanzas can be added by adding more
+@code{\addlyrics} sections
+
+@lilypond[ragged-right,verbatim,fragment,quote]
+\time 3/4
+\relative c' { c2 e4 g2. }
+\addlyrics { play the game }
+\addlyrics { speel het spel }
+\addlyrics { joue le jeu }
+@end lilypond
+
+The command @code{\addlyrics} cannot handle polyphony settings.  For these
+cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
+introduced in @ref{Lyrics explained}.
+
+@c TODO: one additional section may be needed here,
+@c such as "advanced lyric syntax" or whatever -vv
+

 @node Working with lyrics and variables
 @node Working with lyrics and variables

-@subsubsection Working with lyrics and variables
+@unnumberedsubsubsec Working with lyrics and variables

 
 @cindex lyrics, variables
 
 
 @cindex lyrics, variables
 


@@ -350,7 +284,7 @@ The final input would resemble
 @end example
 
 @ignore
 @end example
 
 @ignore

-
+@c FIXME

 http://code.google.com/p/lilypond/issues/detail?id=329
 The problem cannot be reproduced.
 The following has no sense, because the issue seems to be fixed.
 http://code.google.com/p/lilypond/issues/detail?id=329
 The problem cannot be reproduced.
 The following has no sense, because the issue seems to be fixed.


@@ -389,6 +323,20 @@ Internals Reference:
 @rinternals{Lyrics}.
 
 
 @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
 
 @node Aligning lyrics to a melody
 @subsection Aligning lyrics to a melody
 


@@ -396,6 +344,12 @@ Internals Reference:
 @funindex \addlyrics
 @funindex \lyricsto
 
 @funindex \addlyrics
 @funindex \lyricsto
 

+@c FIXME: this stuff is to be rewritten. -vv
+
+Aligning of text with melodies can be made automatically, but if you
+specify the durations of the syllables it can also be made manually.
+Lyrics aligning and typesetting are prepared with the help of skips,
+hyphens and extender lines.

 
 Lyrics are printed by interpreting them in the context called
 @rinternals{Lyrics}.
 
 Lyrics are printed by interpreting them in the context called
 @rinternals{Lyrics}.


@@ -429,7 +383,7 @@ explicitly, using @code{\lyricmode}
 @end menu
 
 @node Automatic syllable durations
 @end menu
 
 @node Automatic syllable durations

-@subsubsection Automatic syllable durations
+@unnumberedsubsubsec Automatic syllable durations

 
 @cindex automatic syllable durations
 @cindex lyrics and melodies
 
 @cindex automatic syllable durations
 @cindex lyrics and melodies


@@ -491,7 +445,7 @@ is the same as
 @end example
 
 @node Manual syllable durations
 @end example
 
 @node Manual syllable durations

-@subsubsection Manual syllable durations
+@unnumberedsubsubsec Manual syllable durations

 
 Lyrics can also be entered without @code{\addlyrics} or
 @code{\lyricsto}.  In this case,
 
 Lyrics can also be entered without @code{\addlyrics} or
 @code{\lyricsto}.  In this case,


@@ -535,7 +489,7 @@ Internals Reference:
 
 
 @node Multiple syllables to one note
 
 
 @node Multiple syllables to one note

-@subsubsection Multiple syllables to one note
+@unnumberedsubsubsec Multiple syllables to one note

 
 
 @funindex _
 
 
 @funindex _


@@ -567,7 +521,7 @@ Internals Reference:
 
 
 @node Multiple notes to one syllable
 
 
 @node Multiple notes to one syllable

-@subsubsection Multiple notes to one syllable
+@unnumberedsubsubsec Multiple notes to one syllable

 
 @cindex melisma
 @cindex melismata
 
 @cindex melisma
 @cindex melismata


@@ -580,7 +534,10 @@ 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{_}
 @c it might be better to present it first - vv
 
 You can define melismata entirely in the lyrics, by entering @code{_}

-for every note that is part of the melisma.
+for every extra note that has to be added to the 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.

 
 @c verbose! --FV
 @c duplicated: TODO fix
 
 @c verbose! --FV
 @c duplicated: TODO fix


@@ -591,6 +548,7 @@ that are used for this purpose (all of them surrounded by spaces):
 double hyphens to separate syllables in a word, underscores to add
 notes to a melisma, and a double underscore to put an extender line.
 
 double hyphens to separate syllables in a word, underscores to add
 notes to a melisma, and a double underscore to put an extender line.
 

+@c wrong: extender line only on last syllable of a word. Change example

 @lilypond[relative=1,verbatim,fragment,quote]
 { \set melismaBusyProperties = #'()
  c d( e) f f( e) e e  }
 @lilypond[relative=1,verbatim,fragment,quote]
 { \set melismaBusyProperties = #'()
  c d( e) f f( e) e e  }


@@ -628,8 +586,7 @@ In addition, notes are considered a melisma if they are manually
 beamed, and automatic beaming (see @ref{Setting automatic beam
 behavior}) is switched off.
 
 beamed, and automatic beaming (see @ref{Setting automatic beam
 behavior}) is switched off.
 

-@c TODO: there might be some more relevant place for
-@c the following link (?)
+@c FIXME: this now links to LM -vv

 
 @cindex SATB
 @cindex choral score
 
 @cindex SATB
 @cindex choral score


@@ -646,9 +603,6 @@ A complete example of a SATB score setup is in section
 
 @seealso
 
 
 @seealso
 

-Internals Reference:
-@rinternals{Melisma_translator}.
-

 @c @lsr{vocal,lyric@/-combine.ly}.
 
 @knownissues
 @c @lsr{vocal,lyric@/-combine.ly}.
 
 @knownissues


@@ -657,11 +611,13 @@ Melismata are not detected automatically, and extender lines must be
 inserted by hand.
 
 @node Skipping notes
 inserted by hand.
 
 @node Skipping notes

-@subsubsection Skipping notes
+@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}, 
 
 Making a lyric line run slower than the melody can be achieved by
 inserting @code{\skip}s into the lyrics.  For every @code{\skip}, 

-the text will be delayed another note.
+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.

 
 For example,
 
 
 For example,
 


@@ -675,16 +631,17 @@ For example,
 
 
 @node Extenders and hyphens
 
 
 @node Extenders and hyphens

-@subsubsection Extenders and hyphens
+@unnumberedsubsubsec Extenders and hyphens

 
 @cindex melisma
 @cindex extender
 
 @c leave this as samp. -gp
 
 @cindex melisma
 @cindex extender
 
 @c leave this as samp. -gp

-Melismata are sometimes indicated with a long horizontal line starting
-in the melisma syllable, and ending in the next one.  Such a line is
-called an extender line, and it is entered as @samp{ __ } (note the
-spaces before and after the two underscore characters).
+In the last syllable of a word, melismata are sometimes indicated with
+a long horizontal line starting in the melisma syllable, and ending in
+the next one.  Such a line is called an extender line, and it is
+entered as @samp{ __ } (note the spaces before and after the two
+underscore characters).

 
 @warning{Melismata are indicated in the score with extender lines,
 which are entered as one double underscore; but short melismata can
 
 @warning{Melismata are indicated in the score with extender lines,
 which are entered as one double underscore; but short melismata can


@@ -712,14 +669,16 @@ Internals Reference:
 @rinternals{LyricHyphen}
 
 @node Lyrics and repeats
 @rinternals{LyricHyphen}
 
 @node Lyrics and repeats

-@subsubsection Lyrics and repeats
+@unnumberedsubsubsec Lyrics and repeats

 
 @c TODO New section.  Add text
 TBC
 
 
 
 @c TODO New section.  Add text
 TBC
 
 

-@node Placement of lyrics
-@subsection Placement of lyrics
+@node Specific uses of lyrics
+@subsection Specific uses of lyrics
+
+@c FIXME This whole section is to be reorganized. -vv

 
 Often, different stanzas of one song are put to one melody in slightly
 differing ways.  Such variations can still be captured with
 
 Often, different stanzas of one song are put to one melody in slightly
 differing ways.  Such variations can still be captured with


@@ -736,7 +695,7 @@ differing ways.  Such variations can still be captured with
 
 
 @node Divisi lyrics
 
 
 @node Divisi lyrics

-@subsubsection Divisi lyrics
+@unnumberedsubsubsec Divisi lyrics

 
 You can display alternate (or divisi) lyrics by naming voice
 contexts and attaching lyrics to those specific contexts.
 
 You can display alternate (or divisi) lyrics by naming voice
 contexts and attaching lyrics to those specific contexts.


@@ -782,7 +741,7 @@ section.
 
 
 @node Lyrics independent of notes
 
 
 @node Lyrics independent of notes

-@subsubsection Lyrics independent of notes
+@unnumberedsubsubsec Lyrics independent of notes

 
 @cindex Devnull context
 
 
 @cindex Devnull context
 


@@ -824,13 +783,13 @@ the implicit melismata get ignored.
 
 
 @node Chants
 
 
 @node Chants

-@subsubsection Chants
+@unnumberedsubsubsec Chants

 
 @c TODO Add text from lsr and -user
 TBC
 
 @node Spacing out syllables
 
 @c TODO Add text from lsr and -user
 TBC
 
 @node Spacing out syllables

-@subsubsection Spacing out syllables
+@unnumberedsubsubsec Spacing out syllables

 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between


@@ -872,9 +831,35 @@ layout.
 }
 @end lilypond
 
 }
 @end lilypond
 

+@c @snippets
+@c This snippet has been renamed to "lyrics-alignment.ly"
+@c update as soon as lsr/is updated -vv
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@c {lyrics-alignment.ly}
+
+@c TODO: move to LSR -vv

 @snippets
 @snippets

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{aligning-lyrics.ly}
+
+Checking to make sure that text scripts and lyrics are within the margins is
+a relatively large computational task.  To speed up processing, LilyPond does
+not perform such calculations by default; to enable it, use
+
+@example
+\override Score.PaperColumn #'keep-inside-line = ##t
+@end example
+
+To make lyrics avoid bar lines as well, use
+
+@example
+\layout @{
+  \context @{
+    \Lyrics
+      \consists "Bar_engraver"
+      \consists "Separating_line_group_engraver"
+      \override BarLine #'transparent = ##t
+  @}
+@}
+@end example

 
 @c TODO Create and add lsr example of lyricMelismaAlignment
 @c It's used like this to center-align all lyric syllables,
 
 @c TODO Create and add lsr example of lyricMelismaAlignment
 @c It's used like this to center-align all lyric syllables,


@@ -887,8 +872,9 @@ layout.
 }
 @end ignore
 
 }
 @end ignore
 

+

 @node Centering lyrics between staves
 @node Centering lyrics between staves

-@subsubsection Centering lyrics between staves
+@unnumberedsubsubsec Centering lyrics between staves

 
 @c TODO Add text from -user
 TBC
 
 @c TODO Add text from -user
 TBC


@@ -907,7 +893,7 @@ TBC
 
 
 @node Adding stanza numbers
 
 
 @node Adding stanza numbers

-@subsubsection Adding stanza numbers
+@unnumberedsubsubsec Adding stanza numbers

 
 @cindex stanza number
 
 
 @cindex stanza number
 


@@ -962,7 +948,7 @@ stanzaOneThree =  {
 @end ignore
 
 @node Adding dynamics marks to stanzas
 @end ignore
 
 @node Adding dynamics marks to stanzas

-@subsubsection Adding dynamics marks to stanzas
+@unnumberedsubsubsec Adding dynamics marks to stanzas

 
 Stanzas differing in loudness may be indicated by putting a
 dynamics mark before each stanza.  In LilyPond, everything coming in
 
 Stanzas differing in loudness may be indicated by putting a
 dynamics mark before each stanza.  In LilyPond, everything coming in


@@ -988,7 +974,7 @@ text = {
 @end lilypond
 
 @node Adding singers' names to stanzas
 @end lilypond
 
 @node Adding singers' names to stanzas

-@subsubsection Adding singers' names to stanzas
+@unnumberedsubsubsec Adding singers' names to stanzas

 
 @cindex singer name
 @cindex name of singer
 
 @cindex singer name
 @cindex name of singer


@@ -1010,7 +996,7 @@ the line, just like instrument names.  They are created by setting
 @end lilypond
 
 @node Stanzas with different rhythms
 @end lilypond
 
 @node Stanzas with different rhythms

-@subsubsection Stanzas with different rhythms
+@unnumberedsubsubsec Stanzas with different rhythms

 
 @subsubheading Ignoring melismata
 
 
 @subsubheading Ignoring melismata
 


@@ -1114,6 +1100,7 @@ This is achieved with
 Here, @code{alternative} is the name of the @code{Voice} context
 containing the triplet.
 
 Here, @code{alternative} is the name of the @code{Voice} context
 containing the triplet.
 

+@c FIXME: make this easier to understand -vv

 This command must be one syllable too early, before @q{Ty} in this
 case.  In other words, changing the associatedVoice happens one step
 later than expected.  This is for technical reasons, and it is not a
 This command must be one syllable too early, before @q{Ty} in this
 case.  In other words, changing the associatedVoice happens one step
 later than expected.  This is for technical reasons, and it is not a


@@ -1136,7 +1123,7 @@ The underlay is switched back to the starting situation by assigning
 
 
 @node Printing stanzas at the end
 
 
 @node Printing stanzas at the end

-@subsubsection Printing stanzas at the end
+@unnumberedsubsubsec Printing stanzas at the end

 
 Sometimes it is appropriate to have one stanza set
 to the music, and the rest added in verse form at
 
 Sometimes it is appropriate to have one stanza set
 to the music, and the rest added in verse form at


@@ -1181,7 +1168,7 @@ its fleece was white as snow.
 
 
 @node Printing stanzas at the end in multiple columns
 
 
 @node Printing stanzas at the end in multiple columns

-@subsubsection Printing stanzas at the end in multiple columns
+@unnumberedsubsubsec Printing stanzas at the end in multiple columns

 
 When a piece of music has many verses, they are often printed in
 multiple columns across the page.  An outdented verse number often
 
 When a piece of music has many verses, they are often printed in
 multiple columns across the page.  An outdented verse number often


@@ -1253,8 +1240,7 @@ text = \lyricmode {
 
 Internals Reference:
 @rinternals{LyricText},
 
 Internals Reference:
 @rinternals{LyricText},

-@rinternals{StanzaNumber},
-@rinternals{VocalName}.
+@rinternals{StanzaNumber}.