LM: Replace \set Staff.instrumentName

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

diff --git a/Documentation/learning/fundamental.itely b/Documentation/learning/fundamental.itely
index 2f7b4b66de5badf170372e310f2b658873f5afbf..07d604e873e26396bac1c39b2f01a22db9f2d5d6 100644 (file)
--- a/Documentation/learning/fundamental.itely
+++ b/Documentation/learning/fundamental.itely
@@ -68,9 +68,7 @@ There are many variations of this basic pattern, but this
 example serves as a useful starting place.
 
 @funindex \book
-@funindex book
 @funindex \score
-@funindex score
 @cindex book
 @cindex score
 
@@ -154,11 +152,8 @@ things, such as
 @end example
 
 @funindex \header
-@funindex header
 @funindex \layout
-@funindex layout
 @funindex \midi
-@funindex midi
 @cindex header
 @cindex layout
 @cindex midi
@@ -184,7 +179,6 @@ Notation Reference -- @ruser{Score layout}, and
 @cindex book block, implicit
 @cindex implicit book block
 @funindex \book
-@funindex book
 
 You may code multiple @code{\score} blocks.  Each will be
 treated as a separate score, but they will be all combined into
@@ -252,7 +246,6 @@ For a complete definition of the input format, see
 @subsection Score is a (single) compound musical expression
 
 @funindex \score
-@funindex score
 @cindex score
 @cindex contents of a score block
 @cindex score block, contents of
@@ -628,7 +621,7 @@ the passing note and a slur:
 @lilypond[quote,verbatim,ragged-right]
 \relative {
   \key g \major
-  %    Voice "1"               Voice "2"
+  %    Voice = "1"             Voice = "2"
   << { g'4 fis8( g) a4 g } \\ { d4 d d d }  >>
 }
 @end lilypond
@@ -640,7 +633,7 @@ Here's another simple example:
 @lilypond[quote,verbatim,ragged-right]
 \relative {
   \key d \minor
-  %    Voice "1"             Voice "2"
+  %    Voice = "1"           Voice = "2"
   << { r4 g' g4. a8 }   \\ { d,2 d4 g }       >> |
   << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
   << { a2. r4 }         \\ { fis2. s4 }       >> |
@@ -656,12 +649,12 @@ separately, like this:
 @lilypond[quote,verbatim,ragged-right]
 <<
   \key d \minor
-  \relative { % Voice "1"
+  \relative { % Voice = "1"
     r4 g' g4. a8 |
     bes4 bes c bes |
     a2. r4 |
   } \\
-  \relative { % Voice "2"
+  \relative { % Voice = "2"
     d'2 d4 g |
     g4 g g8( a) g4 |
     fis2. s4 |
@@ -690,7 +683,7 @@ of slurs, stems, ties, dynamics etc., is set appropriately.
 \new Staff \relative {
   % Main voice
   c'16 d e f
-  %    Voice "1"     Voice "2"                Voice "3"
+  %    Voice = "1"   Voice = "2"              Voice = "3"
   << { g4 f e } \\ { r8 e4 d c8~ } >> |
   << { d2 e }   \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
 }
@@ -944,15 +937,10 @@ Notation Reference: @ruser{Multiple voices}.
 @subsection Explicitly instantiating voices
 
 @funindex \voiceOne
-@funindex voiceOne
 @funindex \voiceTwo
-@funindex voiceTwo
 @funindex \voiceThree
-@funindex voiceThree
 @funindex \voiceFour
-@funindex voiceFour
 @funindex \oneVoice
-@funindex oneVoice
 @funindex \new Voice
 @cindex voice contexts, creating
 
@@ -1139,13 +1127,9 @@ as here:
 @cindex collisions, notes
 @cindex shift commands
 @funindex \shiftOff
-@funindex shiftOff
 @funindex \shiftOn
-@funindex shiftOn
 @funindex \shiftOnn
-@funindex shiftOnn
 @funindex \shiftOnnn
-@funindex shiftOnnn
 
 Closely spaced notes in a chord, or notes occurring at the same
 time in different voices, are arranged in two, occasionally more,
@@ -1196,7 +1180,6 @@ expressions -- notes and lyrics.
 
 @funindex \new Lyrics
 @funindex \lyricsto
-@funindex lyricsto
 @funindex Lyrics
 @cindex Lyrics context, creating
 @cindex lyrics, linking to voice
@@ -1232,7 +1215,6 @@ explicitly.
 @cindex lyrics and beaming
 @cindex beaming and lyrics
 @funindex \autoBeamOff
-@funindex autoBeamOff
 
 The automatic beaming which LilyPond uses by default works well
 for instrumental music, but not so well for music with lyrics,
@@ -1243,7 +1225,6 @@ melismata in the lyrics.  In the example above we use the command
 @funindex \new ChoirStaff
 @funindex ChoirStaff
 @funindex \lyricmode
-@funindex lyricmode
 @cindex vocal score structure
 @cindex choir staff
 
@@ -1451,7 +1432,6 @@ Notation Reference: @ruser{Contexts explained}.
 @subsection Creating contexts
 
 @funindex \new
-@funindex new
 @cindex new contexts
 @cindex creating contexts
 @cindex contexts, creating
@@ -1653,9 +1633,7 @@ Internals reference: @rinternals{Engravers and Performers}.
 @cindex context properties, modifying
 @cindex modifying context properties
 @funindex \set
-@funindex set
 @funindex \unset
-@funindex unset
 
 Contexts are responsible for holding the values of a number of
 context @emph{properties}.  Many of them can be changed to
@@ -1727,27 +1705,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.
@@ -1765,7 +1744,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
@@ -1849,7 +1828,6 @@ general way by using the very powerful @code{\markup} command.
 @subsubheading Setting context properties with @code{\with}
 
 @funindex \with
-@funindex with
 @cindex context properties, setting with \with
 
 The default value of context properties may be set at the time the
@@ -1898,7 +1876,6 @@ with @code{\set}, this new default value may be restored with the
 
 @cindex context properties, setting with \context
 @funindex \context
-@funindex context
 
 The values of context properties may be set in @emph{all} contexts
 of a particular type, such as all @code{Staff} contexts, with a single
@@ -1977,9 +1954,7 @@ Internals Reference:
 @cindex removing engravers
 
 @funindex \consists
-@funindex consists
 @funindex \remove
-@funindex remove
 
 We have seen that contexts each contain several engravers, each
 of which is responsible for producing a particular part of the
@@ -2075,7 +2050,6 @@ the notes in all the voices on that staff:
 @subsubheading Changing all contexts of the same type
 
 @funindex \layout
-@funindex layout
 
 The examples above show how to remove or add engravers to
 individual contexts.  It is also possible to remove or add
@@ -2404,8 +2378,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
@@ -2414,24 +2389,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
@@ -2441,8 +2423,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
     >>
@@ -2480,8 +2462,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
@@ -2490,8 +2473,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
@@ -2500,8 +2484,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
@@ -2510,8 +2495,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
@@ -2528,8 +2514,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
 >>
@@ -2585,8 +2571,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
   >>
@@ -2638,8 +2624,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
@@ -2648,8 +2635,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
@@ -2658,8 +2646,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
@@ -2668,8 +2657,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
@@ -2680,8 +2670,9 @@ lower = \relative {
       }
     >>  % end ChoirStaff
 
-    \new PianoStaff <<
-      \set PianoStaff.instrumentName = #"Piano  "
+    \new PianoStaff
+    \with { instrumentName = #"Piano  " }
+    <<
       \new Staff = "upper" \upper
       \new Staff = "lower" \lower
     >>