]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/staff.itely
Doc: Clarify Context creation (3006)
[lilypond.git] / Documentation / notation / staff.itely
index 7093338b967912d3f394234106074cc7932c0356..6c7753e719715a3f980d43a36932915b0fe50c4e 100644 (file)
@@ -7,12 +7,14 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.17.6"
 
 @node Staff notation
 @section Staff notation
 
-@lilypondfile[quote]{staff-headword.ly}
+@c The line width is a bit of a hack to allow space for the
+@c  instrument names.
+@lilypondfile[quote,ragged-right,line-width=14.5\cm,staffsize=16]{staff-headword.ly}
 
 This section explains how to influence the appearance of staves,
 how to print scores with more than one staff, and how to add tempo
@@ -67,7 +69,7 @@ grouping staves.
 
 @notation{Staves} (singular: @notation{staff}) are created with
 the @code{\new} or @code{\context} commands.  For details, see
-@ref{Creating contexts}.
+@ref{Creating and referencing contexts}.
 
 The basic staff context is @code{Staff}:
 
@@ -116,14 +118,13 @@ notate modern Gregorian chant.  It does not show bar lines.
 New single staff contexts may be defined.  For details, see
 @ref{Defining new contexts}.
 
-
 @seealso
 Music Glossary:
 @rglos{staff},
 @rglos{staves}.
 
 Notation Reference:
-@ref{Creating contexts},
+@ref{Creating and referencing contexts},
 @ref{Percussion staves},
 @ref{Showing melody rhythms},
 @ref{Default tablatures},
@@ -249,7 +250,6 @@ New staff group contexts may be defined.  For details, see
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {mensurstriche-layout-bar-lines-between-the-staves.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{brace},
@@ -318,7 +318,6 @@ New nested staff group contexts can be defined.  For details, see
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {nesting-staves.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Grouping staves},
@@ -336,6 +335,7 @@ Internals Reference:
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
+
 @node Separating systems
 @unnumberedsubsubsec Separating systems
 
@@ -439,11 +439,11 @@ The number of staff lines can be altered,
 
 @lilypond[verbatim,quote,relative=2]
 f4 d \stopStaff
-\override Staff.StaffSymbol #'line-count = #2
+\override Staff.StaffSymbol.line-count = #2
 \startStaff g, e |
 
 f'4 d \stopStaff
-\revert Staff.StaffSymbol #'line-count
+\revert Staff.StaffSymbol.line-count
 \startStaff g, e |
 @end lilypond
 
@@ -455,10 +455,10 @@ position in the staff, can be changed with a single override.
 
 @lilypond[verbatim,quote,relative=2]
 f4 d \stopStaff
-\override Staff.StaffSymbol #'line-positions = #'(1 3 5 -1 -3)
+\override Staff.StaffSymbol.line-positions = #'(1 3 5 -1 -3)
 \startStaff g, e |
 f'4 d \stopStaff
-\override Staff.StaffSymbol #'line-positions = #'(8 6.5 -6 -8 -0.5)
+\override Staff.StaffSymbol.line-positions = #'(8 6.5 -6 -8 -0.5)
 \startStaff g, e
 @end lilypond
 
@@ -470,7 +470,7 @@ default, are also affected.
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'thickness = #3
+  \override StaffSymbol.thickness = #3
 }
 { f4 d g, e }
 @end lilypond
@@ -482,8 +482,8 @@ ledger line thickness.
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'thickness = #2
-  \override StaffSymbol #'ledger-line-thickness = #'(0.5 . 0.4)
+  \override StaffSymbol.thickness = #2
+  \override StaffSymbol.ledger-line-thickness = #'(0.5 . 0.4)
 }
 { f'4 a, a,, f }
 @end lilypond
@@ -492,7 +492,7 @@ The vertical positions of ledger lines can be altered,
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'ledger-positions = #'(-3 -2 -1 2 5 6)
+  \override StaffSymbol.ledger-positions = #'(-3 -2 -1 2 5 6)
 }
 { f'4 a, a,, f }
 @end lilypond
@@ -503,7 +503,7 @@ also have their own ledger lines.
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'ledger-extra = #4
+  \override StaffSymbol.ledger-extra = #4
 }
 { f'4 a, d, f, }
 @end lilypond
@@ -515,11 +515,11 @@ The @code{stopStaff} is needed in the example to revert the
 @code{\override} for the whole @code{StaffSymbol}.
 
 @lilypond[fragment,quote,relative=1]
-\override Staff.StaffSymbol #'line-positions =   #'(-8 0 2 4)
+\override Staff.StaffSymbol.line-positions =   #'(-8 0 2 4)
 d4 e f g
 \stopStaff
 \startStaff
-\override Staff.StaffSymbol #'ledger-positions = #'(-8 -6 (-4 -2) 0)
+\override Staff.StaffSymbol.ledger-positions = #'(-8 -6 (-4 -2) 0)
 d4 e f g
 @end lilypond
 
@@ -528,7 +528,7 @@ line spacing as well.
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'staff-space = #1.5
+  \override StaffSymbol.staff-space = #1.5
 }
 { f'4 d, g, e, }
 @end lilypond
@@ -604,8 +604,8 @@ only a few ossia staves are needed.
       \remove "Time_signature_engraver"
       alignAboveContext = #"main"
       fontSize = #-3
-      \override StaffSymbol #'staff-space = #(magstep -3)
-      \override StaffSymbol #'thickness = #(magstep -3)
+      \override StaffSymbol.staff-space = #(magstep -3)
+      \override StaffSymbol.thickness = #(magstep -3)
       firstClef = ##f
     }
     { e4 d f e }
@@ -626,10 +626,10 @@ example.
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
+    \override Clef.transparent = ##t
     fontSize = #-3
-    \override StaffSymbol #'staff-space = #(magstep -3)
-    \override StaffSymbol #'thickness = #(magstep -3)
+    \override StaffSymbol.staff-space = #(magstep -3)
+    \override StaffSymbol.thickness = #(magstep -3)
   }
   { \stopStaff s1*6 }
 
@@ -665,10 +665,10 @@ break.  For more information about
 <<
   \new Staff = ossia \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
+    \override Clef.transparent = ##t
     fontSize = #-3
-    \override StaffSymbol #'staff-space = #(magstep -3)
-    \override StaffSymbol #'thickness = #(magstep -3)
+    \override StaffSymbol.staff-space = #(magstep -3)
+    \override StaffSymbol.thickness = #(magstep -3)
   } \relative c'' {
     R1*3
     c4 e8 d c2
@@ -686,7 +686,7 @@ break.  For more information about
 \layout {
   \context {
     \Staff \RemoveEmptyStaves
-    \override VerticalAxisGroup #'remove-first = ##t
+    \override VerticalAxisGroup.remove-first = ##t
   }
 }
 @end lilypond
@@ -697,7 +697,6 @@ break.  For more information about
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {vertically-aligning-ossias-and-lyrics.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{ossia},
@@ -807,7 +806,6 @@ hide empty staves in ancient music contexts.  Similarly,
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {removing-the-first-empty-line.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{Frenched staff}.
@@ -834,23 +832,22 @@ Internals Reference:
 @rinternals{VerticalAxisGroup},
 @rinternals{Staff_symbol_engraver}.
 
-
 @knownissues
-
 Removing @code{Staff_symbol_engraver} also hides bar lines.  If
 bar line visibility is forced, formatting errors may occur.  In
 this case, use the following overrides instead of removing the
 engraver:
 
 @example
-\override StaffSymbol #'stencil = ##f
-\override NoteHead #'no-ledgers = ##t
+\override StaffSymbol.stencil = ##f
+\override NoteHead.no-ledgers = ##t
 @end example
 
 For the Known issues and warnings associated with
 @code{\Staff \RemoveEmptyStaves} see
 @ref{Changing context default settings}.
 
+
 @node Writing parts
 @subsection Writing parts
 
@@ -913,8 +910,9 @@ multi-line instrument names, @code{\center-column} must be used:
   { f2 g4 f }
   \new Staff \with {
     instrumentName = \markup {
-      \center-column { "Clarinet" }
-      \line { "in B" \smaller \flat }
+      \center-column { "Clarinet"
+        \line { "in B" \smaller \flat }
+      }
     }
   }
   { c4 b c2 }
@@ -1027,7 +1025,6 @@ expression to declare the instrument switch:
 }
 @end lilypond
 
-
 @seealso
 Notation Reference:
 @ref{\paper variables for shifts and indents},
@@ -1185,6 +1182,9 @@ Notation Reference:
 @ref{Instrument transpositions},
 @ref{Using tags}.
 
+Installed Files:
+@file{scm/define-event-classes.scm}.
+
 Snippets:
 @rlsr{Staff notation}.
 
@@ -1193,10 +1193,6 @@ Internals Reference:
 @rinternals{QuoteMusic},
 @rinternals{Voice}.
 
-Installed Files:
-@file{scm/define-event-classes.scm}.
-
-
 @knownissues
 Only the contents of the first @code{Voice} occurring in an
 @code{\addQuote} command will be considered for quotation, so if the music
@@ -1305,7 +1301,7 @@ fluteNotes = \relative c'' {
 
 oboeNotes = \relative c'' {
   R1
-  s1*0^\markup { \tiny "flute" }
+  \new CueVoice { \set instrumentCueName = "flute" }
   \cueDuring #"flute" #UP { R1 }
   g2 c,
 }
@@ -1348,10 +1344,13 @@ oboeNotes = \relative c'' {
 }
 @end lilypond
 
-Markup can be used to show the name of the quoted instrument.  Also,
-if the cue notes require a change in clef, this can be done manually but
-the original clef should also be restored manually at the end of the cue
-notes.
+The name of the instrument playing the cue can be printed by setting
+the @code{instrumentCueName} property in a temporary @code{CueVoice}
+context.  The placement and style of the @code{instrumentCueName} is
+controlled by the @code{\instrumentSwitch} object, see
+@ref{Instrument names}.  If the cue notes require a change in clef,
+this can be done manually but the original clef should also be
+restored manually at the end of the cue notes.
 
 @lilypond[verbatim,quote]
 fluteNotes = \relative c'' {
@@ -1362,7 +1361,7 @@ bassoonNotes = \relative c {
   \clef bass
   R1
   \clef treble
-  s1*0^\markup { \tiny "flute" }
+  \new CueVoice { \set instrumentCueName = "flute" }
   \cueDuring #"flute" #UP { R1 }
   \clef bass
   g4. b8 d2
@@ -1388,7 +1387,7 @@ fluteNotes = \relative c'' {
 bassoonNotes = \relative c {
   \clef bass
   R1
-  s1*0^\markup { \tiny "flute" }
+  \new CueVoice { \set instrumentCueName = "flute" }
   \cueDuringWithClef #"flute" #UP #"treble" { R1 }
   g4. b8 d2
 }
@@ -1464,7 +1463,7 @@ bassoonNotes = \relative c {
   R1
   \tag #'part {
     \clef treble
-    s1*0^\markup { \tiny "flute" }
+    \new CueVoice { \set instrumentCueName = "flute" }
   }
   \cueDuring #"flute" #UP { R1 }
   \tag #'part \clef bass
@@ -1491,7 +1490,6 @@ Alternatively, Clef changes and instrument labels can be
 collected into an instrument definition for repeated use, using
 @code{\addInstrumentDefinition} described in @ref{Instrument names}.
 
-
 @seealso
 Notation Reference:
 @ref{Quoting other voices},
@@ -1508,9 +1506,7 @@ Internals Reference:
 @rinternals{CueVoice},
 @rinternals{Voice}.
 
-
 @knownissues
-
 Collisions can occur with rests, when using @code{\cueDuring},
 between @code{Voice} and @code{CueVoice} contexts.  When using
 @code{\cueDuringWithClef} or @code{\transposedCueDuring} the extra