Doc-es: Update Notation/Expressive.

[lilypond.git] / Documentation / learning / fundamental.itely

diff --git a/Documentation/learning/fundamental.itely b/Documentation/learning/fundamental.itely
index 6b74fe954a8a312b2c62d7158c9544128d572507..9a990ac9de5634d3d9663ebede32cf2cdc7717bd 100644 (file)
--- a/Documentation/learning/fundamental.itely
+++ b/Documentation/learning/fundamental.itely
@@ -1436,11 +1436,12 @@ Notation Reference: @ruser{Contexts explained}.
 @cindex creating contexts
 @cindex contexts, creating
 
-In an input file a score block, introduced with a @code{\score}
-command, contains a single music expression and an associated
-output definition (either a @code{\layout} or a @code{\midi} block).
-The @code{Score} context is usually left to be created automatically
-when the interpretation of that music expression starts.
+In an input file, a score block (introduced with a @code{\score}
+command) contains a single music expression; but it can also contain
+associated output definitions too -- either a @code{\layout} block, a
+@code{\midi} block or both.  The @code{Score} context is usually left to
+be created automatically when the interpretation of that music
+expression starts.
 
 For scores with only one voice and one staff, the @code{Voice} and
 @code{Staff} contexts may also be left to be created automatically,
@@ -1705,27 +1706,28 @@ in which context they operate.  Sometimes this is obvious,
 but occasionally it can be tricky.  If the wrong context
 is specified, no error message is produced, but the expected
 action will not take place.  For example, the
-@code{instrumentName} clearly lives in the @code{Staff} context, since
-it is the staff that is to be named.
-In this example the first staff is labeled, but not the second,
-because we omitted the context name.
+@code{clefGlyph} clearly lives in the @code{Staff} context, since
+it is the staff's clef glyph that is to be changed.
+In this example the first staff's clef is printed correctly, but not the
+second -- which prints the default treble clef instead of the
+expected bass (or F) clef -- because we omitted the context name.
 
 @lilypond[quote,verbatim,ragged-right]
 <<
   \new Staff \relative {
-    \set Staff.instrumentName = #"Soprano"
+    \set Staff.clefGlyph = "clefs.C"
     c''2 c
   }
   \new Staff \relative {
-    \set instrumentName = #"Alto"  % Wrong!
+    \set clefGlyph = "clefs.F"  % Wrong!
     d'2 d
   }
 >>
 @end lilypond
 
 Remember the default context name is @code{Voice}, so the second
-@code{\set} command set the property @code{instrumentName} in the
-@code{Voice} context to @qq{Alto}, but as LilyPond does not look
+@code{\set} command set the property @code{clefGlyph} in the
+@code{Voice} context to @code{clefs.F}, but as LilyPond does not look
 for any such property in the @code{Voice} context, no
 further action took place.  This is not an error, and no error
 message is logged in the log file.
@@ -1743,7 +1745,7 @@ such features, it is recommended to check the property name in the
 Internals Reference: see @rinternals{Tunable context properties}, or
 @rinternals{Contexts}.
 
-The @code{instrumentName} property will take effect only
+The @code{clefGlyph} property will take effect only
 if it is set in the @code{Staff} context, but
 some properties can be set in more than one context.
 For example, the property @code{extraNatural} is by
@@ -2377,8 +2379,9 @@ lower = \relative {
 \score {
   <<  % combine ChoirStaff and PianoStaff in parallel
     \new ChoirStaff <<
-      \new Staff = "sopranos" <<
-        \set Staff.instrumentName = #"Soprano"
+      \new Staff = "sopranos"
+      \with { instrumentName = #"Soprano" }
+      <<
         \new Voice = "sopranos" {
           \global
           \sopranoMusic
@@ -2387,24 +2390,31 @@ lower = \relative {
       \new Lyrics \lyricsto "sopranos" {
         \sopranoWords
       }
-      \new Staff = "altos" <<
-        \set Staff.instrumentName = #"Alto"
+      \new Staff = "altos"
+      \with { instrumentName = #"Alto" }
+      <<
         \new Voice = "altos" {
           \global
           \altoMusic
         }
       >>
-      \new Lyrics \lyricsto "altos" { \altoWords }
-      \new Staff = "tenors" <<
-        \set Staff.instrumentName = #"Tenor"
+      \new Lyrics \lyricsto "altos" {
+        \altoWords
+      }
+      \new Staff = "tenors"
+      \with { instrumentName = #"Tenor" }
+      <<
         \new Voice = "tenors" {
           \global
           \tenorMusic
         }
       >>
-      \new Lyrics \lyricsto "tenors" { \tenorWords }
-      \new Staff = "basses" <<
-        \set Staff.instrumentName = #"Bass"
+      \new Lyrics \lyricsto "tenors" {
+        \tenorWords
+      }
+      \new Staff = "basses"
+      \with { instrumentName = #"Bass" }
+      <<
         \new Voice = "basses" {
           \global
           \bassMusic
@@ -2414,8 +2424,8 @@ lower = \relative {
         \bassWords
       }
     >>  % end ChoirStaff
-    \new PianoStaff <<
-      \set PianoStaff.instrumentName = #"Piano"
+    \new PianoStaff \with { instrumentName = #"Piano" }
+    <<
       \new Staff = "upper" \upper
       \new Staff = "lower" \lower
     >>
@@ -2453,8 +2463,9 @@ Doing this gives for our ChoirStaff:
 
 @example
 \new ChoirStaff <<
-  \new Staff = "sopranos" <<
-    \set Staff.instrumentName = #"Soprano"
+  \new Staff = "sopranos"
+  \with @{ instrumentName = #"Soprano" @}
+  <<
     \new Voice = "sopranos" @{
       \global
       \sopranoMusic
@@ -2463,8 +2474,9 @@ Doing this gives for our ChoirStaff:
   \new Lyrics \lyricsto "sopranos" @{
     \sopranoWords
   @}
-  \new Staff = "altos" <<
-    \set Staff.instrumentName = #"Alto"
+  \new Staff = "altos"
+  \with @{ instrumentName = #"Alto" @}
+  <<
     \new Voice = "altos" @{
       \global
       \altoMusic
@@ -2473,8 +2485,9 @@ Doing this gives for our ChoirStaff:
   \new Lyrics \lyricsto "altos" @{
     \altoWords
   @}
-  \new Staff = "tenors" <<
-    \set Staff.instrumentName = #"Tenor"
+  \new Staff = "tenors"
+  \with @{ instrumentName = #"Tenor" @}
+  <<
     \new Voice = "tenors" @{
       \global
       \tenorMusic
@@ -2483,8 +2496,9 @@ Doing this gives for our ChoirStaff:
   \new Lyrics \lyricsto "tenors" @{
     \tenorWords
   @}
-  \new Staff = "basses" <<
-    \set Staff.instrumentName = #"Bass"
+  \new Staff = "basses"
+  \with @{ instrumentName = #"Bass" @}
+  <<
     \new Voice = "basses" @{
       \global
       \bassMusic
@@ -2501,8 +2515,8 @@ easy - we just pull out the piano part from the
 @q{Solo piano} template:
 
 @example
-\new PianoStaff <<
-  \set PianoStaff.instrumentName = #"Piano  "
+\new PianoStaff \with @{ instrumentName = #"Piano  " @}
+<<
   \new Staff = "upper" \upper
   \new Staff = "lower" \lower
 >>
@@ -2558,8 +2572,8 @@ stacked one above the other:
     @}
   >>  % end ChoirStaff
 
-  \new PianoStaff <<
-    \set PianoStaff.instrumentName = #"Piano"
+  \new PianoStaff \with @{ instrumentName = #"Piano" @}
+  <<
     \new Staff = "upper" \upper
     \new Staff = "lower" \lower
   >>
@@ -2611,8 +2625,9 @@ lower = \relative {
 \score {
   <<  % combine ChoirStaff and PianoStaff in parallel
     \new ChoirStaff <<
-      \new Staff = "sopranos" <<
-        \set Staff.instrumentName = #"Soprano"
+      \new Staff = "sopranos"
+      \with { instrumentName = #"Soprano" }
+      <<
         \new Voice = "sopranos" {
           \global
           \sopranoMusic
@@ -2621,8 +2636,9 @@ lower = \relative {
       \new Lyrics \lyricsto "sopranos" {
         \sopranoWords
       }
-      \new Staff = "altos" <<
-        \set Staff.instrumentName = #"Alto"
+      \new Staff = "altos"
+      \with { instrumentName = #"Alto" }
+      <<
         \new Voice = "altos" {
           \global
           \altoMusic
@@ -2631,8 +2647,9 @@ lower = \relative {
       \new Lyrics \lyricsto "altos" {
         \altoWords
       }
-      \new Staff = "tenors" <<
-        \set Staff.instrumentName = #"Tenor"
+      \new Staff = "tenors"
+      \with { instrumentName = #"Tenor" }
+      <<
         \new Voice = "tenors" {
           \global
           \tenorMusic
@@ -2641,8 +2658,9 @@ lower = \relative {
       \new Lyrics \lyricsto "tenors" {
         \tenorWords
       }
-      \new Staff = "basses" <<
-        \set Staff.instrumentName = #"Bass"
+      \new Staff = "basses"
+      \with { instrumentName = #"Bass" }
+      <<
         \new Voice = "basses" {
           \global
           \bassMusic
@@ -2653,8 +2671,9 @@ lower = \relative {
       }
     >>  % end ChoirStaff
 
-    \new PianoStaff <<
-      \set PianoStaff.instrumentName = #"Piano  "
+    \new PianoStaff
+    \with { instrumentName = #"Piano  " }
+    <<
       \new Staff = "upper" \upper
       \new Staff = "lower" \lower
     >>