Minor editing.

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

diff --git a/Documentation/user/notation.itely b/Documentation/user/notation.itely
index c0f670baced5f38937edcd0d374ba6504d225a00..8af2acf8afc0a9fe22b5cfba8e64b798c45c1b76 100644 (file)
--- a/Documentation/user/notation.itely
+++ b/Documentation/user/notation.itely
@@ -107,6 +107,17 @@ cis
 cisis
 @end lilypond
 
 cisis
 @end lilypond
 

+In accordance with standard typsetting rules, a natural sign is printed
+before a sharp or flat if a previous accidental needs to be
+cancelled.  To change this behaviour, use
+@code{\set Staff.extraNatural = ##f}
+
+@lilypond[fragment,quote,raggedright,verbatim,relative=2]
+ceses4 ces cis c
+\set Staff.extraNatural = ##f
+ceses4 ces cis c
+@end lilypond
+

 There are predefined sets of note names for various other languages.
 To use them, include the language specific init file.  For
 example: @code{\include "english.ly"}.  The available language files
 There are predefined sets of note names for various other languages.
 To use them, include the language specific init file.  For
 example: @code{\include "english.ly"}.  The available language files


@@ -918,6 +929,24 @@ This command sets the context property
 @internalsref{Staff}.@code{keySignature}.  Non-standard key signatures
 can be specified by setting this property directly.
 
 @internalsref{Staff}.@code{keySignature}.  Non-standard key signatures
 can be specified by setting this property directly.
 

+A natural sign is printed to cancel any previous accidentals.  This
+can be suppressed by setting the @code{Staff.printKeyCancellation}
+property.
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+{
+  \key d \major
+  a b cis d
+  \key g \minor
+  a bes c d
+  \set Staff.printKeyCancellation = ##f
+  \key d \major
+  a b cis d
+  \key g \minor
+  a bes c d
+}
+@end lilypond
+

 Accidentals and key signatures often confuse new users, because
 unaltered notes get natural signs depending on the key signature.  For
 more information, see @ref{More about pitches}.
 Accidentals and key signatures often confuse new users, because
 unaltered notes get natural signs depending on the key signature.  For
 more information, see @ref{More about pitches}.


@@ -1001,6 +1030,9 @@ This command is equivalent to setting @code{clefGlyph},
 when any of these properties are changed.  The following example shows
 possibilities when setting properties manually.
 
 when any of these properties are changed.  The following example shows
 possibilities when setting properties manually.
 

+@ignore
+should to be fixed very quickly  -gp
+

 @lilypond[quote,raggedright,verbatim]
 {
   \set Staff.clefGlyph = #"clefs.F"
 @lilypond[quote,raggedright,verbatim]
 {
   \set Staff.clefGlyph = #"clefs.F"


@@ -1017,9 +1049,12 @@ possibilities when setting properties manually.
   c'4
   \clef "bass"
   c'4
   c'4
   \clef "bass"
   c'4

+  \set Staff.middleCPosition = #4
+  c'4

 }
 @end lilypond
 
 }
 @end lilypond
 

+@end ignore

 
 @seealso
 
 
 @seealso
 


@@ -1336,15 +1371,17 @@ indefinitely.
 Timing can be changed by setting any of these variables explicitly.
 In the next example, the 4/4 time signature is printed, but
 @code{measureLength} is set to 5/4.  After a while, the measure is
 Timing can be changed by setting any of these variables explicitly.
 In the next example, the 4/4 time signature is printed, but
 @code{measureLength} is set to 5/4.  After a while, the measure is

-shortened by 1/8, by setting @code{measurePosition} to -3/8 at 2/4 in
-the measure, so the next bar line will fall at 2/4 + 3/8.
+shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
+in the measure, so the next bar line will fall at 2/4 + 3/8.  The
+3/8 arises because 5/4 normally has 10/8, but we have manually
+set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.

 
 @lilypond[quote,raggedright,verbatim,relative,fragment]
 \set Score.measureLength = #(ly:make-moment 5 4)
 c1 c4
 c1 c4
 c4 c4
 
 @lilypond[quote,raggedright,verbatim,relative,fragment]
 \set Score.measureLength = #(ly:make-moment 5 4)
 c1 c4
 c1 c4
 c4 c4

-\set Score.measurePosition = #(ly:make-moment -3 8)
+\set Score.measurePosition = #(ly:make-moment 7 8)

 b8 b b
 c4 c1
 @end lilypond
 b8 b b
 c4 c1
 @end lilypond


@@ -1353,8 +1390,8 @@ c4 c1
 @node Controlling formatting of prefatory matter
 @subsection Controlling formatting of prefatory matter
 
 @node Controlling formatting of prefatory matter
 @subsection Controlling formatting of prefatory matter
 

-@c  This section will be moved to somewhere else soon.
-This example demonstrates how to place prefactory matter
+@c  This section will be moved to somewhere else soon. -gp
+This example demonstrates how to place prefatory matter

 (such as the clef and key signature) at the end of a line.
 
 @lilypond[quote,verbatim]
 (such as the clef and key signature) at the end of a line.
 
 @lilypond[quote,verbatim]


@@ -1420,7 +1457,21 @@ voices are sometimes called ``layers'' in other notation packages}
 @cindex layers
 to be instantiated.  They bear the names @code{"1"}, @code{"2"}, etc.  In
 each of these contexts, vertical direction of slurs, stems, etc., is set
 @cindex layers
 to be instantiated.  They bear the names @code{"1"}, @code{"2"}, etc.  In
 each of these contexts, vertical direction of slurs, stems, etc., is set

-appropriately.
+appropriately.  Specifically,
+
+@example
+<< \upper \\ \lower >>
+@end example
+
+@noindent
+is equivalent to
+
+@example
+<<
+  \context Voice = "1" @{ \voiceOne \upper @}
+  \context Voice = "2" @{ \voiceTwo \lower @}
+>>
+@end example

 
 @cindex @code{\voiceOne}
 @cindex @code{\voiceFour}
 
 @cindex @code{\voiceOne}
 @cindex @code{\voiceFour}


@@ -1442,6 +1493,11 @@ a stem directions and horizontal shift for each part
 The command @code{\oneVoice} will revert back to the normal setting.
 @cindex @code{\oneVoice}
 
 The command @code{\oneVoice} will revert back to the normal setting.
 @cindex @code{\oneVoice}
 

+Defining voices (either with the separator @code{\\} or with
+@code{\voiceXXX}) will set the direction of stems, slurs, ties,
+articulations, text annotations, augmentation dots of dotted
+notes, and fingerings.  @code{\voiceOne} makes these objects
+point upwards, while @code{\voiceTwo} makes them point down.

 
 Normally, note heads with a different number of dots are not merged, but
 when the object property @code{merge-differently-dotted} is set in
 
 Normally, note heads with a different number of dots are not merged, but
 when the object property @code{merge-differently-dotted} is set in


@@ -1690,12 +1746,15 @@ or at durations specified by the properties in
 @code{autoBeamSettings}.  The defaults for @code{autoBeamSettings}
 are defined in @file{scm/@/auto@/-beam@/.scm}.
 
 @code{autoBeamSettings}.  The defaults for @code{autoBeamSettings}
 are defined in @file{scm/@/auto@/-beam@/.scm}.
 

-The value of @code{autoBeamSettings} is changed with two functions,
+The value of @code{autoBeamSettings} is changed with three functions,

 @example
 #(override-auto-beam-setting
    '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}
    [@var{context}])
 @example
 #(override-auto-beam-setting
    '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}
    [@var{context}])

-#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m}))
+#(score-override-auto-beam-setting
+   '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b})
+#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m})
+   [@var{context}])

 @end example
 Here, @var{be} is the symbol @code{begin} or @code{end}, and
 @var{context} is an optional context (default: @code{'Voice}).  It
 @end example
 Here, @var{be} is the symbol @code{begin} or @code{end}, and
 @var{context} is an optional context (default: @code{'Voice}).  It


@@ -1706,7 +1765,9 @@ to a time signature (wildcards `@code{* *}' may be entered to
 designate all time signatures), @var{a}/@var{b} is a duration.  By
 default, this command changes settings for the current voice.  It is
 also possible to adjust settings at higher contexts, by adding a
 designate all time signatures), @var{a}/@var{b} is a duration.  By
 default, this command changes settings for the current voice.  It is
 also possible to adjust settings at higher contexts, by adding a

-@var{context} argument.
+@var{context} argument.  @code{score-override-auto-beam-setting} is
+equal to @code{override-auto-beam-setting} with the argument
+@var{context} set to @code{'Score}.

 
 For example, if automatic beams should end on every quarter note, use
 the following
 
 For example, if automatic beams should end on every quarter note, use
 the following


@@ -3724,6 +3785,7 @@ for complex vocal music.
 * Flexibility in alignment::    
 * More stanzas::                
 * Ambitus::                     
 * Flexibility in alignment::    
 * More stanzas::                
 * Ambitus::                     

+* Other vocal issues::          

 @end menu
 
 @node Setting simple songs
 @end menu
 
 @node Setting simple songs


@@ -3761,7 +3823,7 @@ More stanzas can be added by adding more
 
 The @code{\addlyrics} command is actually just a convienient way
 to write a more complicated LilyPond structure that sets up the
 
 The @code{\addlyrics} command is actually just a convienient way
 to write a more complicated LilyPond structure that sets up the

-lyrics.  You should use @code{\addlyrics} unless you need to
+lyrics.  You should use @code{\addlyrics} unless you need to do

 fancy things, in which case you should investigate
 @code{\lyricsto} or @code{\lyricmode}.
 
 fancy things, in which case you should investigate
 @code{\lyricsto} or @code{\lyricmode}.
 


@@ -3778,6 +3840,10 @@ is the same as
 \lyricsto "blah" \new lyrics @{ LYRICS @}
 @end example
 
 \lyricsto "blah" \new lyrics @{ LYRICS @}
 @end example
 

+@refbugs
+
+@code{\addlyrics} cannot handle polyphony.
+

 
 @node Entering lyrics
 @subsection Entering lyrics
 
 @node Entering lyrics
 @subsection Entering lyrics


@@ -3805,7 +3871,7 @@ is that a word can end with @code{@}}.  The following example is
 usually a mistake in the input file.  The syllable includes a @code{@}}, so the
 opening brace is not balanced
 @example
 usually a mistake in the input file.  The syllable includes a @code{@}}, so the
 opening brace is not balanced
 @example

-\lyricmode @{ twinkle @}
+\lyricmode @{ twinkle@}

 @end example
 
 @cindex @code{\property}, in @code{\lyricmode}
 @end example
 
 @cindex @code{\property}, in @code{\lyricmode}


@@ -4075,10 +4141,6 @@ Program reference: @internalsref{LyricCombineMusic},
 @internalsref{Lyrics}, @internalsref{Melisma_translator}.
 
 
 @internalsref{Lyrics}, @internalsref{Melisma_translator}.
 
 

-@c link broken:
-@c Examples: @ref{Small ensembles},
-
-

 @inputfileref{input/@/regression,lyric@/-combine@/-new@/.ly}.
 @c TODO: make separate section for melismata
 
 @inputfileref{input/@/regression,lyric@/-combine@/-new@/.ly}.
 @c TODO: make separate section for melismata
 


@@ -4327,9 +4389,12 @@ ambitus per staff rather than per each voice, add the
 rather than to the @internalsref{Voice} context.  Here is an example,
 
 @lilypond[verbatim,raggedright,quote]
 rather than to the @internalsref{Voice} context.  Here is an example,
 
 @lilypond[verbatim,raggedright,quote]

-\new Staff <<
+\new Staff \with {
+  \consists "Ambitus_engraver"
+}
+<<

   \new Voice \with {
   \new Voice \with {

-    \consists "Ambitus_engraver"
+    \remove "Ambitus_engraver"

   } \relative c'' {
     \override Ambitus #'X-offset-callbacks
       = #(list (lambda (grob axis) -1.0))
   } \relative c'' {
     \override Ambitus #'X-offset-callbacks
       = #(list (lambda (grob axis) -1.0))


@@ -4337,7 +4402,7 @@ rather than to the @internalsref{Voice} context.  Here is an example,
     c4 a d e f2
   }
   \new Voice \with {
     c4 a d e f2
   }
   \new Voice \with {

-    \consists "Ambitus_engraver"
+    \remove "Ambitus_engraver"

   } \relative c' {
     \voiceTwo
     es4 f g as b2
   } \relative c' {
     \voiceTwo
     es4 f g as b2


@@ -4371,6 +4436,61 @@ Examples: @inputfileref{input/@/regression,ambitus@/.ly}.
 There is no collision handling in the case of multiple per-voice
 ambitus.
 
 There is no collision handling in the case of multiple per-voice
 ambitus.
 

+@node Other vocal issues
+@subsection Other vocal issue
+
+@ignore
+yeah, I'm giving up somewhat by stuffing a bunch of things in
+here.  But at least they're in the manual now; it's easier to
+move them around in the manual once they're already here.
+
+Besides, if users complain about everything stuffed in here, I
+can ask them for specific instructions about where to move these
+examples, and that might get them more involved in the docs.  -gp
+@end ignore
+
+You can display alternate (or divisi) lyrics by naming voice
+contexts and attaching lyrics to those specific contexts.
+
+@lilypond[verbatim,raggedright,quote]
+\score{ <<
+  \context Voice = "melody" {
+    \relative c' {
+      c4
+      <<
+        { \voiceOne c8 e }
+        \context Voice = splitpart { \voiceTwo c4 }
+      >>
+      \oneVoice c4 c | c
+    }
+  }
+  \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
+  \new Lyrics \lyricsto "splitpart" { shall }
+>> }
+@end lilypond
+
+
+You can use this trick to display different lyrics for a repeated
+section.
+
+@lilypond[verbatim,raggedright,quote]
+\score{ <<
+  \context Voice = melody \relative c' {
+    c2 e | g e | c1 |
+    \context Voice = verse \repeat volta 2 {c4 d e f | g1 | }
+    a2 b | c1}
+  \lyricsto melody  \context Lyrics = mainlyrics \lyricmode {
+    do mi sol mi do
+    la si do }
+  \lyricsto verse \context Lyrics = mainlyrics \lyricmode {
+   do re mi fa sol }
+  \lyricsto verse \context Lyrics = repeatlyrics \lyricmode {
+   dodo rere mimi fafa solsol }
+>>
+}
+@end lilypond
+
+

 @node Other instrument specific notation, Tablatures, Vocal music, Notation manual
 @section Other instrument specific notation
 
 @node Other instrument specific notation, Tablatures, Vocal music, Notation manual
 @section Other instrument specific notation
 


@@ -5116,9 +5236,13 @@ c1 \mark \markup { \musicglyph #"scripts-ufermata" }
 c1
 @end lilypond
 
 c1
 @end lilypond
 

-In the case of a line break, marks must also be printed at the end of
-the line, and not at the beginning.  Use the following to force that
-behavior
+If the mark occurs at a line break, the mark will be printed at the
+beginning of the next line.
+@c  IMO this is a bug; hopefully it'll be fixed soon, so I can
+@c  delete this sentence.   -gp
+If there is no next line, then the mark will not be printed at all.
+To print the mark at the end of the current line, use
+

 @example
 \override Score.RehearsalMark
   #'break-visibility = #begin-of-line-invisible
 @example
 \override Score.RehearsalMark
   #'break-visibility = #begin-of-line-invisible


@@ -5502,7 +5626,7 @@ The first @code{g} appears only once, although it was
 specified twice (once in each part).  Stem, slur, and tie directions are
 set automatically, depending whether there is a solo or unisono.  The
 first part (with context called @code{one}) always gets up stems, and
 specified twice (once in each part).  Stem, slur, and tie directions are
 set automatically, depending whether there is a solo or unisono.  The
 first part (with context called @code{one}) always gets up stems, and

-`solo', while the second (called @code{two}) always gets down stems and
+`Solo', while the second (called @code{two}) always gets down stems and

 `Solo II'.
 
 If you just want the merging parts, and not the textual markings, you
 `Solo II'.
 
 If you just want the merging parts, and not the textual markings, you


@@ -5517,6 +5641,20 @@ may set the property @code{printPartCombineTexts} to false
 >>
 @end lilypond
 
 >>
 @end lilypond
 

+To change the text that is printed for solos or merging, you may
+set the @code{soloText}, @code{soloIIText}, and @code{aDueText}
+properties.
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+\new Staff <<
+  \set Score.soloText = #"ichi"
+  \set Score.soloIIText = #"ni"
+  \set Score.aDueText = #"tachi"
+  \partcombine
+    \relative g' { g4 g a( b) r }
+    \relative g' { g4 g r r f }
+>>
+@end lilypond

 
 Both arguments to @code{\partcombine} will be interpreted as
 @internalsref{Voice} contexts.  If using relative octaves,
 
 Both arguments to @code{\partcombine} will be interpreted as
 @internalsref{Voice} contexts.  If using relative octaves,


@@ -6061,7 +6199,7 @@ Examples: @inputfileref{input/@/test,ancient@/-accidentals@/.ly}.
 
 
 Use the @code{style} property of grob @internalsref{Rest} to select
 
 
 Use the @code{style} property of grob @internalsref{Rest} to select

-ancient accidentals.   Supported styles are @code{classical},
+ancient rests.   Supported styles are @code{classical},

 @code{neomensural}, and @code{mensural}.  @code{classical} differs
 from the @code{default} style only in that the quarter rest looks like
 a horizontally mirrored 8th rest.  The @code{neomensural} style suits
 @code{neomensural}, and @code{mensural}.  @code{classical} differs
 from the @code{default} style only in that the quarter rest looks like
 a horizontally mirrored 8th rest.  The @code{neomensural} style suits