X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fstaff.itely;h=d7ed3e6738b55b9cb8ac7bbc3cc496625c8d0eaf;hb=90e4d7057f3857da049dfda3d130017d4719bd6b;hp=2ac12942588040d1c86c482b8be26963a7f7ef95;hpb=5edacf4c1908d0fe988d0ef9b3d6a9820a1e8734;p=lilypond.git

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index 2ac1294258..d7ed3e6738 100644
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -7,12 +7,14 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.19.21"
 
 @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
@@ -57,7 +59,6 @@ grouping staves.
 @cindex tablature
 
 @funindex \drummode
-@funindex drummode
 @funindex DrumStaff
 @funindex RhythmicStaff
 @funindex TabStaff
@@ -67,12 +68,12 @@ 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}:
 
-@lilypond[verbatim,quote,relative=2]
-\new Staff { c4 d e f }
+@lilypond[verbatim,quote]
+\new Staff \relative { c''4 d e f }
 @end lilypond
 
 The @code{DrumStaff} context creates a five-line staff set up for
@@ -91,15 +92,15 @@ For details, see @ref{Percussion staves}.
 displays the rhythmic values of the input.  Real durations are
 preserved.  For details, see @ref{Showing melody rhythms}.
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote]
 \new RhythmicStaff { c4 d e f }
 @end lilypond
 
 @code{TabStaff} creates a tablature with six strings in standard
 guitar tuning.  For details, see @ref{Default tablatures}.
 
-@lilypond[verbatim,quote,relative=2]
-\new TabStaff { c4 d e f }
+@lilypond[verbatim,quote]
+\new TabStaff \relative { c''4 d e f }
 @end lilypond
 
 There are two staff contexts specific for the notation of ancient
@@ -109,21 +110,20 @@ described in @ref{Pre-defined contexts}.
 The @code{GregorianTranscriptionStaff} context creates a staff to
 notate modern Gregorian chant.  It does not show bar lines.
 
-@lilypond[verbatim,quote,relative=2]
-\new GregorianTranscriptionStaff { c4 d e f e d }
+@lilypond[verbatim,quote]
+\new GregorianTranscriptionStaff \relative { c''4 d e f e d }
 @end lilypond
 
 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},
@@ -173,40 +173,40 @@ If no context is specified, the default properties will be used:
 the group is started with a vertical line, and the bar lines are
 not connected.
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote]
 <<
-  \new Staff { c1 c }
-  \new Staff { c1 c }
+  \new Staff \relative { c''1 c }
+  \new Staff \relative { c''1 c }
 >>
 @end lilypond
 
 In the @code{StaffGroup} context, the group is started with a
 bracket and bar lines are drawn through all the staves.
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote]
 \new StaffGroup <<
-  \new Staff { c1 c }
-  \new Staff { c1 c }
+  \new Staff \relative { c''1 c }
+  \new Staff \relative { c''1 c }
 >>
 @end lilypond
 
 In a @code{ChoirStaff}, the group starts with a bracket, but bar
 lines are not connected.
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote]
 \new ChoirStaff <<
-  \new Staff { c1 c }
-  \new Staff { c1 c }
+  \new Staff \relative { c''1 c }
+  \new Staff \relative { c''1 c }
 >>
 @end lilypond
 
 In a @code{GrandStaff}, the group begins with a brace, and bar
 lines are connected between the staves.
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote]
 \new GrandStaff <<
-  \new Staff { c1 c }
-  \new Staff { c1 c }
+  \new Staff \relative { c''1 c }
+  \new Staff \relative { c''1 c }
 >>
 @end lilypond
 
@@ -214,11 +214,11 @@ The @code{PianoStaff} is identical to a @code{GrandStaff}, except
 that it supports printing the instrument name directly.  For
 details, see @ref{Instrument names}.
 
-@lilypond[verbatim,quote,relative=2]
-\new PianoStaff <<
-  \set PianoStaff.instrumentName = #"Piano"
-  \new Staff { c1 c }
-  \new Staff { c1 c }
+@lilypond[verbatim,quote]
+\new PianoStaff \with { instrumentName = #"Piano" }
+<<
+  \new Staff \relative { c''1 c }
+  \new Staff \relative { \clef bass c1 c }
 >>
 @end lilypond
 
@@ -235,10 +235,10 @@ New staff group contexts may be defined.  For details, see
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {use-square-bracket-at-the-start-of-a-staff-group.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {display-bracket-with-only-one-staff-in-a-system.ly}
 
 @cindex mensurstriche layout
@@ -246,10 +246,9 @@ New staff group contexts may be defined.  For details, see
 @cindex transcription of mensural music
 @cindex mensural music, transcription of
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {mensurstriche-layout-bar-lines-between-the-staves.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{brace},
@@ -274,9 +273,6 @@ Internals Reference:
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
-@knownissues
-@code{PianoStaff} does not, by default, accept @code{ChordNames}.
-
 
 @node Nested staff groups
 @unnumberedsubsubsec Nested staff groups
@@ -293,17 +289,17 @@ Staff-group contexts can be nested to arbitrary depths.  In this
 case, each child context creates a new bracket adjacent to the
 bracket of its parent group.
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote]
 \new StaffGroup <<
-  \new Staff { c2 c | c2 c }
+  \new Staff \relative { c''2 c | c2 c }
   \new StaffGroup <<
-    \new Staff { g2 g | g2 g }
+    \new Staff \relative { g'2 g | g2 g }
     \new StaffGroup \with {
       systemStartDelimiter = #'SystemStartSquare
     }
     <<
-      \new Staff { e2 e | e2 e }
-      \new Staff { c2 c | c2 c }
+      \new Staff \relative { e'2 e | e2 e }
+      \new Staff \relative { c'2 c | c2 c }
     >>
   >>
 >>
@@ -315,10 +311,9 @@ New nested staff group contexts can be defined.  For details, see
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {nesting-staves.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Grouping staves},
@@ -336,6 +331,7 @@ Internals Reference:
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
+
 @node Separating systems
 @unnumberedsubsubsec Separating systems
 
@@ -353,15 +349,15 @@ turned on with a @code{\paper} option.
   \score {
     \new StaffGroup <<
       \new Staff {
-        \relative c'' {
-          c4 c c c
+        \relative {
+          c''4 c c c
           \break
           c4 c c c
         }
       }
       \new Staff {
-        \relative c'' {
-          c4 c c c
+        \relative {
+          c''4 c c c
           \break
           c4 c c c
         }
@@ -404,125 +400,158 @@ sections are also described.
 @node Staff symbol
 @unnumberedsubsubsec Staff symbol
 
-@cindex adjusting staff symbol
-@cindex drawing staff symbol
-@cindex staff symbol, setting of
-@cindex staff symbol, drawing
-@cindex stop staff lines
-@cindex start staff lines
-@cindex staff lines, amount of
-@cindex staff lines, number of
-@cindex staff line, thickness of
-@cindex amount of staff lines
-@cindex thickness of staff lines
-@cindex ledger lines, setting
-@cindex setting of ledger lines
-@cindex spacing of ledger lines
-@cindex number of staff lines
-
-The lines of a staff belong to the @code{StaffSymbol} grob.
-@code{StaffSymbol} properties can be modified to change the
-appearance of a staff, but they must be modified before the staff
-is created.
-
-The number of staff lines may be changed.  The clef position and
-the position of middle C may need to be modified to fit the new
-staff.  For an explanation, refer to the snippet section in
-@ref{Clef}.
+@cindex staff symbol
+@cindex staff lines, stopping and starting
+@cindex staff lines, modifying
+@cindex ledger lines
+@cindex ledger lines, internal
+@cindex ledger lines, modifying
 
-@lilypond[verbatim,quote,relative=2]
-\new Staff \with {
-  \override StaffSymbol #'line-count = #3
+@funindex \startStaff
+@funindex \stopStaff
+
+The @code{\stopStaff} and @code{\startStaff} commands can be used to
+stop or (re)start the staff lines respectively, from being printed at
+any point witin a score.
+
+@lilypond[verbatim,quote]
+\relative {
+  \stopStaff f''4 d \startStaff g, e
+  f'4 d \stopStaff g, e
+  f'4 d \startStaff g, e
 }
-{ d4 d d d }
 @end lilypond
 
-Staff line thickness can be modified.  The thickness of ledger
-lines and stems are also affected, since they depend on staff line
-thickness.
+@predefined
+@code{\startStaff},
+@code{\stopStaff}.
+@endpredefined
 
-@lilypond[verbatim,quote,relative=1]
-\new Staff \with {
-  \override StaffSymbol #'thickness = #3
+The lines of a staff belong to the @code{StaffSymbol} grob (including
+ledger lines) and can be modified using @code{StaffSymbol} properties, but
+these modifications must be made before the staff is (re)started.
+
+The number of staff lines can be altered:
+
+@lilypond[verbatim,quote]
+\relative {
+  f''4 d \stopStaff
+  \override Staff.StaffSymbol.line-count = #2
+  \startStaff g, e |
+
+  f'4 d \stopStaff
+  \revert Staff.StaffSymbol.line-count
+  \startStaff g, e |
 }
-{ e4 d c b }
 @end lilypond
 
-Ledger line thickness can be set independently of staff line
-thickness.  In the example the two numbers are factors multiplying
-the staff line thickness and the staff line spacing.  The two
-contributions are added to give the ledger line thickness.
+The position of each staff line can also be altered.  A list of
+numbers sets each line's position.  @code{0}@tie{}corresponds to the normal
+center line, and the normal line positions are
+@code{(-4@tie{}-2@tie{}0@tie{}2@tie{}4)}.  A single staff line is
+printed for every value entered so that the number of staff lines, as
+well as their position, can be changed with a single override.
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
+\relative {
+  f''4 d \stopStaff
+  \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)
+  \startStaff g, e |
+}
+@end lilypond
+
+To preserve typical stem directions (in the bottom half of the staff
+stems point up, in the top half they point down), align the center
+line (or space) of the customized staff with the position of the
+normal center line (0).  The clef position and the position of
+middle@tie{}C may need to be adjusted accordingly to fit the new
+lines.  See @ref{Clef}.
+
+Staff line thickness can be altered.  Ledger lines and note stems, by
+default, are also affected.
+
+@lilypond[verbatim,quote]
 \new Staff \with {
-  \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
+  \override StaffSymbol.thickness = #3
+} \relative {
+  f''4 d g, e
 }
-{ e4 d c b }
 @end lilypond
 
-The distance between staff lines can be changed.  This setting
-affects the spacing of ledger lines as well.
+It is also possible to set ledger line thickness independently of staff
+lines.
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
 \new Staff \with {
-  \override StaffSymbol #'staff-space = #1.5
+  \override StaffSymbol.thickness = #2
+  \override StaffSymbol.ledger-line-thickness = #'(0.5 . 0.4)
+} \relative {
+  f'''4 a, a,, f
 }
-{ a4 b c d }
 @end lilypond
 
-Further details about the properties of @code{StaffSymbol} can be
-found in @rinternals{staff-symbol-interface}.
+@noindent
+The first value is multiplied by the staff line thickness, the second by
+the staff space and then the two values are added together to give the
+new thickness of the ledger line.
 
-@cindex stopping a staff
-@cindex starting a staff
-@cindex staff, starting
-@cindex staff, stopping
+The vertical positions of ledger lines can be altered,
 
-@funindex \startStaff
-@funindex startStaff
-@funindex \stopStaff
-@funindex stopStaff
-
-Modifications to staff properties in the middle of a score can be
-placed between @code{\stopStaff} and @code{\startStaff}:
-
-@lilypond[verbatim,quote,relative=2]
-c2 c
-\stopStaff
-\override Staff.StaffSymbol #'line-count = #2
-\startStaff
-b2 b
-\stopStaff
-\revert Staff.StaffSymbol #'line-count
-\startStaff
-a2 a
+@lilypond[verbatim,quote]
+\new Staff \with {
+  \override StaffSymbol.ledger-positions = #'(-3 -2 -1 2 5 6)
+} \relative {
+  f'''4 a, a,, f
+}
 @end lilypond
 
-@noindent
-In general, @code{\startStaff} and @code{\stopStaff} can be used
-to stop or start a staff in the middle of a score.
-
-@lilypond[verbatim,quote,relative=2]
-c4 b a2
-\stopStaff
-b4 c d2
-\startStaff
-e4 d c2
+Additional ledger lines can be made to appear above or below note heads
+depending on the current position relative to other note heads that
+also have their own ledger lines.
+
+@lilypond[verbatim,quote]
+\new Staff \with {
+  \override StaffSymbol.ledger-extra = #4
+} \relative {
+  f'''4 a, d, f,
+}
 @end lilypond
 
+Ledger lines can also be made to appear inside the staff where custom
+staff lines are required.  The example shows the default position of
+ledger lines when the explicit @code{ledger-position} is and is not set.
+The @code{\stopStaff} is needed in the example to revert the
+@code{\override} for the whole @code{StaffSymbol}.
 
-@predefined
-@code{\startStaff},
-@code{\stopStaff}.
-@endpredefined
+@lilypond[verbatim,quote]
+\relative d' {
+  \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)
+  d4 e f g
+}
+@end lilypond
 
+The distance between staff lines can be altered.  This affects ledger
+line spacing as well.
 
-@snippets
+@lilypond[verbatim,quote]
+\new Staff \with {
+  \override StaffSymbol.staff-space = #1.5
+} \relative {
+  f'''4 d, g, e,
+}
+@end lilypond
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@snippets
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {making-some-staff-lines-thicker-than-the-others.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{line},
@@ -550,16 +579,14 @@ Internals Reference:
 @cindex resizing of staves
 
 @funindex \startStaff
-@funindex startStaff
 @funindex \stopStaff
-@funindex stopStaff
 
 @notation{Ossia} staves can be set by creating a new simultaneous
 staff in the appropriate location:
 
 @lilypond[verbatim,quote]
-\new Staff \relative c'' {
-  c4 b d c
+\new Staff \relative {
+  c''4 b d c
   <<
     { c4 b d c }
     \new Staff { e4 d f e }
@@ -581,17 +608,15 @@ to align the ossia staff.  This method is most appropriate when
 only a few ossia staves are needed.
 
 @lilypond[verbatim,quote]
-\new Staff = main \relative c'' {
-  c4 b d c
+\new Staff = "main" \relative {
+  c''4 b d c
   <<
     { c4 b d c }
 
     \new Staff \with {
       \remove "Time_signature_engraver"
       alignAboveContext = #"main"
-      fontSize = #-3
-      \override StaffSymbol #'staff-space = #(magstep -3)
-      \override StaffSymbol #'thickness = #(magstep -3)
+      \magnifyStaff #2/3
       firstClef = ##f
     }
     { e4 d f e }
@@ -610,20 +635,18 @@ example.
 
 @lilypond[verbatim,quote,ragged-right]
 <<
-  \new Staff = ossia \with {
+  \new Staff = "ossia" \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
-    fontSize = #-3
-    \override StaffSymbol #'staff-space = #(magstep -3)
-    \override StaffSymbol #'thickness = #(magstep -3)
+    \hide Clef
+    \magnifyStaff #2/3
   }
   { \stopStaff s1*6 }
 
-  \new Staff \relative c' {
-    c4 b c2
+  \new Staff \relative {
+    c'4 b c2
     <<
       { e4 f e2 }
-      \context Staff = ossia {
+      \context Staff = "ossia" {
         \startStaff e4 g8 f e2 \stopStaff
       }
     >>
@@ -631,7 +654,7 @@ example.
     c4 b c2
     <<
       { g4 a g2 }
-      \context Staff = ossia {
+      \context Staff = "ossia" {
         \startStaff g4 e8 f g2 \stopStaff
       }
     >>
@@ -641,26 +664,25 @@ example.
 @end lilypond
 
 
-Using the @code{\Staff \RemoveEmptyStaves} command to create ossia
+Using the @code{\RemoveAllEmptyStaves} command to create ossia
 staves may be used as an alternative.  This method is most
 convenient when ossia staves occur immediately following a line
 break.  For more information about
-@code{\Staff \RemoveEmptyStaves}, see @ref{Hiding staves}.
+@code{\RemoveAllEmptyStaves}, see @ref{Hiding staves}.
 
 @lilypond[verbatim,quote,ragged-right]
 <<
-  \new Staff = ossia \with {
+  \new Staff = "ossia" \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
-    fontSize = #-3
-    \override StaffSymbol #'staff-space = #(magstep -3)
-    \override StaffSymbol #'thickness = #(magstep -3)
-  } \relative c'' {
+    \hide Clef
+    \magnifyStaff #2/3
+    \RemoveAllEmptyStaves
+  } \relative {
     R1*3
-    c4 e8 d c2
+    c''4 e8 d c2
   }
-  \new Staff \relative c' {
-    c4 b c2
+  \new Staff \relative {
+    c'4 b c2
     e4 f e2
     g4 a g2 \break
     c4 b c2
@@ -668,22 +690,14 @@ break.  For more information about
     e4 d c2
   }
 >>
-
-\layout {
-  \context {
-    \Staff \RemoveEmptyStaves
-    \override VerticalAxisGroup #'remove-first = ##t
-  }
-}
 @end lilypond
 
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {vertically-aligning-ossias-and-lyrics.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{ossia},
@@ -712,13 +726,16 @@ Internals Reference:
 @cindex Frenched staff
 @cindex staff, hiding
 @cindex staff, empty
-@cindex hiding of staves
+@cindex hiding staves
+@cindex hiding ancient staves
+@cindex hiding rhythmic staves
+@cindex hiding vaticana staves
 @cindex empty staves
 
 @funindex \RemoveEmptyStaves
+@funindex \RemoveAllEmptyStaves
 @funindex Staff_symbol_engraver
 @funindex \stopStaff
-@funindex stopStaff
 
 
 Staff lines can be hidden by removing the
@@ -729,15 +746,18 @@ alternative, @code{\stopStaff} may be used.
 \new Staff \with {
   \remove "Staff_symbol_engraver"
 }
-\relative c''' { a8 f e16 d c b a2 }
+\relative { a''8 f e16 d c b a2 }
 @end lilypond
 
 
-Empty staves can be hidden by setting the
-@code{\Staff \RemoveEmptyStaves} command in the @code{\layout}
-block.  In orchestral scores, this style is known as @q{Frenched
-Score}.  By default, this command hides and removes all empty
-staves in a score except for those in the first system.
+Empty staves can be hidden (for a so-called @q{Frenched Score})
+by applying the @code{\RemoveEmptyStaves} command on a context, which
+can be done globally (in a @code{\layout} block) as well as for
+specific staves only (in a @code{\with} block).  This command removes
+all empty staves in a score except for those in the first system.  If
+you want those in the first system to be hidden also, use
+@code{\RemoveAllEmptyStaves}.  Supported contexts are @code{Staff},
+@code{RhythmicStaff} and @code{VaticanaStaff}.
 
 @warning{A staff is considered empty when it contains only
 multi-measure rests, rests, skips, spacer rests, or a combination of these
@@ -746,13 +766,14 @@ elements.}
 @lilypond[verbatim,quote,ragged-right]
 \layout {
   \context {
-    \Staff \RemoveEmptyStaves
+    \Staff
+    \RemoveEmptyStaves
   }
 }
 
-\relative c' <<
+\relative <<
   \new Staff {
-    e4 f g a \break
+    e'4 f g a \break
     b1 \break
     a4 b c2
   }
@@ -767,33 +788,15 @@ elements.}
 @cindex ossia
 
 @noindent
-@code{\Staff \RemoveEmptyStaves} can also be used to create ossia
+@code{\RemoveAllEmptyStaves} can also be used to create ossia
 sections for a staff.  For details, see @ref{Ossia staves}.
 
-@cindex hiding ancient staves
-@cindex hiding rhythmic staves
-
-@funindex \RemoveEmptyStaves
-
-The @code{\VaticanaStaff \RemoveEmptyStaves} command may be used to
-hide empty staves in ancient music contexts.  Similarly,
-@code{\RhythmicStaff \RemoveEmptyStaves} may be used to hide empty
-@code{RhythmicStaff} contexts.
-
 
 @predefined
-@code{\Staff \RemoveEmptyStaves},
-@code{\VaticanaStaff \RemoveEmptyStaves},
-@code{\RhythmicStaff \RemoveEmptyStaves}.
+@code{\RemoveEmptyStaves},
+@code{\RemoveAllEmptyStaves}.
 @endpredefined
 
-
-@snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{removing-the-first-empty-line.ly}
-
-
 @seealso
 Music Glossary:
 @rglos{Frenched staff}.
@@ -820,23 +823,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
+\omit StaffSymbol
+\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
 
@@ -862,149 +864,138 @@ and @code{ChoirStaff} contexts.  The value of
 @code{instrumentName} is used for the first staff, and the value
 of @code{shortInstrumentName} is used for all succeeding staves.
 
-@lilypond[verbatim,quote,ragged-right,relative=1]
-\set Staff.instrumentName = #"Violin "
-\set Staff.shortInstrumentName = #"Vln "
-c4.. g'16 c4.. g'16
-\break
-c1
+@lilypond[verbatim,quote,ragged-right]
+\new Staff \with {
+  instrumentName = #"Violin "
+  shortInstrumentName = #"Vln. "
+} \relative {
+  c'4.. g'16 c4.. g'16 \break | c1 |
+}
 @end lilypond
 
-Markup mode can be used to create more complicated instrument
-names:
+@cindex instrument names, complex
+
+@code{\markup} can be used to create more complex instrument names:
 
-@lilypond[verbatim,quote,relative=2]
-\set Staff.instrumentName = \markup {
-  \column { "Clarinetti"
-            \line { "in B" \smaller \flat } } }
-c4 c,16 d e f g2
+@lilypond[verbatim,quote]
+\new Staff \with {
+  instrumentName = \markup {
+    \column { "Clarinetti"
+      \line { "in B" \smaller \flat }
+    }
+  }
+} \relative {
+  c''4 c,16 d e f g2
+}
 @end lilypond
 
 @cindex instrument names, centering
 
-When two or more staff contexts are grouped together, the
-instrument names and short instrument names are centered by
-default.  To center multi-line instrument names,
-@code{\center-column} must be used:
+When two or more staff contexts are grouped together, the instrument
+names and short instrument names are centered by default.  To center
+multi-line instrument names, @code{\center-column} must be used:
 
-@lilypond[verbatim,quote,indent=1.5\cm,relative=2]
+@lilypond[verbatim,quote,indent=1.5\cm]
 <<
-  \new Staff {
-    \set Staff.instrumentName = #"Flute"
-    f2 g4 f
-  }
-  \new Staff {
-    \set Staff.instrumentName = \markup \center-column {
-      Clarinet
-      \line { "in B" \smaller \flat }
+  \new Staff \with {
+    instrumentName = #"Flute"
+  } \relative {
+    f''2 g4 f
+}
+  \new Staff \with {
+    instrumentName = \markup {
+      \center-column { "Clarinet"
+        \line { "in B" \smaller \flat }
+      }
     }
-    c4 b c2
-  }
+  } \relative { c''4 b c2 }
 >>
 @end lilypond
 
 @funindex indent
 @funindex short-indent
 
-However, if the instrument names are longer, the instrument names
-in a staff group may not be centered unless the @code{indent} and
-@code{short-indent} settings are increased.  For details about
-these settings, see @ref{\paper variables for shifts and indents}.
+However, if the instrument names are longer, the instrument names in a
+staff group may not be centered unless the @code{indent} and
+@code{short-indent} settings are increased.  For details about these
+settings, see @ref{paper variables for shifts and indents,,@code{@bs{}paper} variables for shifts and indents}.
 
 @lilypond[verbatim,quote,ragged-right]
-\layout {
-  indent = 3.0\cm
-  short-indent = 1.5\cm
-}
-
-\relative c'' <<
-  \new Staff {
-    \set Staff.instrumentName = #"Alto Flute in G"
-    \set Staff.shortInstrumentName = #"Fl."
-    f2 g4 f \break
+<<
+  \new Staff \with {
+    instrumentName = #"Alto Flute in G"
+    shortInstrumentName = #"Flt."
+  } \relative {
+    f''2 g4 f \break
     g4 f g2
   }
-  \new Staff {
-    \set Staff.instrumentName = #"Clarinet"
-    \set Staff.shortInstrumentName = #"Clar."
-    c,4 b c2 \break
+  \new Staff \with {
+    instrumentName = #"Clarinet"
+    shortInstrumentName = #"Clar."
+  } \relative {
+    c''4 b c2 \break
     c2 b4 c
   }
 >>
+
+\layout {
+  indent = 3.0\cm
+  short-indent = 1.5\cm
+}
 @end lilypond
 
 @cindex instrument names, adding to other contexts
 
-To add instrument names to other contexts (such as
-@code{ChordNames} or @code{FiguredBass}),
-@code{Instrument_name_engraver} must be added to that context.
-For details, see @ref{Modifying context plug-ins}.
+To add instrument names to other contexts (such as @code{ChordNames} or
+@code{FiguredBass}), @code{Instrument_name_engraver} must be added to
+that context.  For details, see @ref{Modifying context plug-ins}.
 
 @cindex instrument names, changing
 @cindex changing instrument names
 
-Instrument names may be changed in the middle of a piece.
-However, remember that @code{instrumentName} will not be
-displayed in the middle of the piece, as it only appears
-on the first staff:
-
-@lilypond[verbatim,quote,ragged-right,relative=1]
-\set Staff.instrumentName = #"First"
-\set Staff.shortInstrumentName = #"one"
-c1 c c c \break
-c1 c c c \break
-\set Staff.instrumentName = #"Second"
-\set Staff.shortInstrumentName = #"two"
-c1 c c c \break
-c1 c c c \break
-@end lilypond
+The @code{shortInstrumentName} may be changed in the middle of a piece,
+along with other settings as needed for the new instrument.
+However, only the first instance of @code{instrumentName} will be
+printed and subsequent changes will be ignored:
 
-@cindex instrument switch
-@cindex switching instruments
+@lilypond[verbatim,quote,ragged-right]
+prepPiccolo = <>^\markup \italic { muta in Piccolo }
 
-@funindex \addInstrumentDefinition
-@funindex addInstrumentDefinition
-@funindex \instrumentSwitch
-@funindex instrumentSwitch
+prepFlute = <>^\markup \italic { muta in Flauto }
 
-If an instrument @emph{switch} is needed,
-@code{\addInstrumentDefinition} may be used in combination with
-@code{\instrumentSwitch} to create a detailed list of the
-necessary changes for the switch.  The
-@code{\addInstrumentDefinition} command has two arguments: an
-identifying string, and an association list of context properties
-and values to be used for the instrument.  It must be placed in
-the toplevel scope.  @code{\instrumentSwitch} is used in the music
-expression to declare the instrument switch:
+setPiccolo = {
+  <>^\markup \bold { Piccolo }
+  \transposition c''
+}
 
-@lilypond[verbatim,quote,ragged-right]
-\addInstrumentDefinition #"contrabassoon"
-  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
-     (shortInstrumentName . "Cbsn.")
-     (clefGlyph . "clefs.F")
-     (middleCPosition . 6)
-     (clefPosition . 2)
-     (instrumentCueName . ,(make-bold-markup "cbsn."))
-     (midiInstrument . "bassoon"))
+setFlute = {
+  <>^\markup \bold { Flute }
+  \transposition c'
+}
 
 \new Staff \with {
-  instrumentName = #"Bassoon"
+  instrumentName = #"Flute"
+  shortInstrumentName = #"Flt."
 }
-\relative c' {
-  \clef tenor
-  \compressFullBarRests
-  c2 g'
-  R1*16
-  \instrumentSwitch "contrabassoon"
-  c,,2 g \break
-  c,1 ~ | c1
+\relative {
+  g'1 g g g \break
+  g1 g \prepPiccolo R R \break
+  \set Staff.instrumentName = #"Piccolo"
+  \set Staff.shortInstrumentName = #"Picc."
+  \setPiccolo
+  g1 g g g \break
+  g1 g \prepFlute R R \break
+  \set Staff.instrumentName = #"Flute"
+  \set Staff.shortInstrumentName = #"Flt."
+  \setFlute
+  g1 g g g
 }
 @end lilypond
 
 
 @seealso
 Notation Reference:
-@ref{\paper variables for shifts and indents},
+@ref{paper variables for shifts and indents,,@code{@bs{}paper} variables for shifts and indents},
 @ref{Modifying context plug-ins}.
 
 Snippets:
@@ -1025,11 +1016,8 @@ Internals Reference:
 @cindex cue notes
 
 @funindex \addQuote
-@funindex addQuote
 @funindex \quoteDuring
-@funindex quoteDuring
 @funindex \transposition
-@funindex transposition
 
 It is very common for one voice to use the same notes as those from
 another voice.  For example, first and second violins playing the same
@@ -1046,12 +1034,12 @@ quoted voice, as defined with @code{\addQuote}, and a music expression
 for the duration of the quote.
 
 @lilypond[verbatim,quote]
-fluteNotes = \relative c'' {
-  a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
+fluteNotes = \relative {
+  a'4 gis g gis | b4^"quoted" r8 ais\p a4( f)
 }
 
-oboeNotes = \relative c'' {
-  c4 cis c b \quoteDuring #"flute" { s1 }
+oboeNotes = \relative {
+  c''4 cis c b \quoteDuring #"flute" { s1 }
 }
 
 \addQuote "flute" { \fluteNotes }
@@ -1069,12 +1057,12 @@ instead of spacer or multimeasure rests then the quote will appear as
 polyphony and may produce unexpected results.
 
 @lilypond[verbatim,quote]
-fluteNotes = \relative c'' {
-  a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
+fluteNotes = \relative {
+  a'4 gis g gis | b4^"quoted" r8 ais\p a4( f)
 }
 
-oboeNotes = \relative c'' {
-  c4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
+oboeNotes = \relative {
+  c''4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
 }
 
 \addQuote "flute" { \fluteNotes }
@@ -1087,6 +1075,41 @@ oboeNotes = \relative c'' {
 }
 @end lilypond
 
+If an @code{\unfoldRepeats} command in a music expression is required to
+be printed when using @code{\quoteDuring}, then it too must also contain
+its own @code{\unfoldRepeats} command;
+
+@lilypond[verbatim,quote]
+fluteNotes = \relative {
+  \repeat volta 2 { a'4 gis g gis }
+}
+
+oboeNotesDW = \relative {
+  \repeat volta 2 \quoteDuring #"incorrect" { s1 }
+}
+
+oboeNotesW = \relative {
+  \repeat volta 2 \quoteDuring #"correct" { s1 }
+}
+
+
+\addQuote "incorrect" { \fluteNotes }
+
+\addQuote "correct" { \unfoldRepeats \fluteNotes }
+
+\score {
+  \unfoldRepeats
+  <<
+    \new Staff \with { instrumentName = "Flute" }
+    \fluteNotes
+    \new Staff \with { instrumentName = "Oboe (incorrect)" }
+    \oboeNotesDW
+    \new Staff \with { instrumentName = "Oboe (correct)" }
+    \oboeNotesW
+  >>
+}
+@end lilypond
+
 The @code{\quoteDuring} command uses the @code{\transposition} settings
 of both quoted and quoting parts to produce notes for the quoting part
 that have the same sounding pitch as those in the quoted part.
@@ -1098,8 +1121,8 @@ clarinetNotes = \relative c'' {
   b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
 }
 
-oboeNotes = \relative c'' {
-  c4 cis c b \quoteDuring #"clarinet" { s1 }
+oboeNotes = \relative {
+  c''4 cis c b \quoteDuring #"clarinet" { s1 }
 }
 
 \addQuote "clarinet" { \clarinetNotes }
@@ -1129,13 +1152,13 @@ of these objects from the quoted music are displayed by using the
 @code{quotedEventTypes} context property.
 
 @lilypond[verbatim,quote]
-fluteNotes = \relative c'' {
-  a2 g2 |
+fluteNotes = \relative {
+  a'2 g2 |
   b4\<^"quoted" r8 ais a4\f( c->)
  }
 
-oboeNotes = \relative c'' {
-  c2. b4 |
+oboeNotes = \relative {
+  c''2. b4 |
   \quoteDuring #"flute" { s1 }
 }
 
@@ -1159,6 +1182,9 @@ Notation Reference:
 @ref{Instrument transpositions},
 @ref{Using tags}.
 
+Installed Files:
+@file{scm/define-event-classes.scm}.
+
 Snippets:
 @rlsr{Staff notation}.
 
@@ -1167,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
@@ -1191,13 +1213,9 @@ triplets may result in poor notation.
 
 
 @funindex \cueDuring
-@funindex cueDuring
 @funindex \cueClef
-@funindex cueClef
 @funindex \cueDuringWithClef
-@funindex cueDuringWithClef
 @funindex \quoteDuring
-@funindex quoteDuring
 
 @cindex notes, smaller
 @cindex smaller notes
@@ -1206,15 +1224,17 @@ triplets may result in poor notation.
 The simplest way to format cue notes is to explicitly create a
 @code{CueVoice} context within the part.
 
-@lilypond[verbatim,relative=1]
-R1
-<<
-  { e2\rest r4. e8 }
-  \new CueVoice {
-    \stemUp d'8^"flute" c d e fis2
-  }
->>
-d,4 r a r
+@lilypond[verbatim]
+\relative {
+  R1
+  <<
+    { e'2\rest r4. e8 }
+    \new CueVoice {
+      \stemUp d'8^"flute" c d e fis2
+    }
+  >>
+  d,4 r a r
+}
 @end lilypond
 
 The @code{\cueClef} command can also be used with an explict
@@ -1223,28 +1243,32 @@ an appropriately sized clef for the cue notes.  The @code{\cueClefUnset}
 command can then be used to switch back to the original clef, again with
 an appropriately sized clef.
 
-@lilypond[verbatim,noragged-right,relative=1]
-\clef "bass"
-R1
-<<
-  { e2\rest r4. \cueClefUnset e,8 }
-  \new CueVoice {
-    \cueClef "treble" \stemUp d''8^"flute" c d e fis2
-  }
->>
-d,,4 r a r
+@lilypond[verbatim,noragged-right]
+\relative {
+  \clef "bass"
+  R1
+  <<
+    { e'2\rest r4. \cueClefUnset e,8 }
+    \new CueVoice {
+      \cueClef "treble" \stemUp d''8^"flute" c d e fis2
+    }
+  >>
+  d,,4 r a r
+}
 @end lilypond
 
 The @code{\cueClef} and @code{\cueClefUnset} command can also be used
 without a @code{CueVoice} if required.
 
-@lilypond[verbatim,noragged-right,relative=1]
-\clef "bass"
-R1
-\cueClef "treble"
-d'8^"flute" c d e fis2
-\cueClefUnset
-d,,4 r a r
+@lilypond[verbatim,noragged-right]
+\relative {
+  \clef "bass"
+  R1
+  \cueClef "treble"
+  d''8^"flute" c d e fis2
+  \cueClefUnset
+  d,,4 r a r
+}
 @end lilypond
 
 For more complex cue note placement, e.g including transposition, or
@@ -1273,13 +1297,13 @@ corresponds to the first and second voices respectively, determining how
 the cue notes are printed in relation to the other voice.
 
 @lilypond[verbatim,quote]
-fluteNotes = \relative c'' {
-  r2. c4 | d8 c d e fis2 | g2 d |
+fluteNotes = \relative {
+  r2. c''4 | d8 c d e fis2 | g2 d |
 }
 
 oboeNotes = \relative c'' {
   R1
-  s1*0^\markup { \tiny "flute" }
+  <>^\markup \tiny { flute }
   \cueDuring #"flute" #UP { R1 }
   g2 c,
 }
@@ -1296,18 +1320,19 @@ oboeNotes = \relative c'' {
 
 It is possible to adjust which aspects of the music are quoted with
 @code{\cueDuring} by setting the @code{quotedCueEventTypes}
-property.  Its default value is @code{#'(note-event rest-event
+property.  Its default value is @code{'(note-event rest-event
 tie-event beam-event tuplet-span-event)}, which means that only
 notes, rests, ties, beams and tuplets are quoted, but not
-articulations, dynamic marks, markup etc.
+articulations, dynamic marks, markup, etc.
 
-In this example, the @code{Voice} context must be
-explicitly declared, or else the entire music expression would
-belong to the @code{CueVoice} context.
+@warning{When a @code{Voice} starts with @code{\cueDuring}, as in the
+following example, the @code{Voice} context must be explicitly declared,
+or else the entire music expression would belong to the @code{CueVoice}
+context.}
 
 @lilypond[verbatim,quote]
-oboeNotes = \relative c'' {
-  r2 r8 d16(\f f e g f a)
+oboeNotes = \relative {
+  r2 r8 d''16(\f f e g f a)
   g8 g16 g g2.
 }
 \addQuote "oboe" { \oboeNotes }
@@ -1321,21 +1346,21 @@ 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.
+Markup can be used to show the name of the quoted instrument.
+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'' {
-  r2. c4 d8 c d e fis2 g2 d2
+fluteNotes = \relative {
+  r2. c''4 d8 c d e fis2 g2 d2
 }
 
 bassoonNotes = \relative c {
   \clef bass
   R1
   \clef treble
-  s1*0^\markup { \tiny "flute" }
+  <>^\markup \tiny { flute }
   \cueDuring #"flute" #UP { R1 }
   \clef bass
   g4. b8 d2
@@ -1354,14 +1379,14 @@ clef that needs to be printed for the cue notes but will automatically
 print the original clef once the cue notes have finished.
 
 @lilypond[verbatim,quote]
-fluteNotes = \relative c'' {
-  r2. c4 d8 c d e fis2 g2 d2
+fluteNotes = \relative {
+  r2. c''4 d8 c d e fis2 g2 d2
 }
 
 bassoonNotes = \relative c {
   \clef bass
   R1
-  s1*0^\markup { \tiny "flute" }
+  <>^\markup { \tiny "flute" }
   \cueDuringWithClef #"flute" #UP #"treble" { R1 }
   g4. b8 d2
 }
@@ -1374,7 +1399,6 @@ bassoonNotes = \relative c {
 @end lilypond
 
 @funindex \transposedCueDuring
-@funindex transposedCueDuring
 
 Like @code{\quoteDuring}, @code{\cueDuring} takes instrument
 transpositions into account.  Cue notes are produced at the
@@ -1388,10 +1412,10 @@ represent the sound of a concert middle C.  This is useful for
 taking cues from an instrument in a completely different register.
 
 @lilypond[verbatim,quote]
-piccoloNotes = \relative c''' {
+piccoloNotes = \relative {
   \clef "treble^8"
   R1
-  c8 c c e g2
+  c'''8 c c e g2
   c4 g g2
 }
 
@@ -1415,9 +1439,6 @@ bassClarinetNotes = \relative c' {
 @cindex cue notes, removing
 
 @funindex \killCues
-@funindex killCues
-@funindex \addInstrumentDefinition
-@funindex addInstrumentDefinition
 
 The @code{\killCues} command removes cue notes from a music
 expression, so the same music expression can be used to produce
@@ -1428,8 +1449,8 @@ changes and a label identifying the source instrument, can be
 tagged for selective inclusion in the score; see @ref{Using tags}.
 
 @lilypond[verbatim,quote]
-fluteNotes = \relative c'' {
-  r2. c4 d8 c d e fis2 g2 d2
+fluteNotes = \relative {
+  r2. c''4 d8 c d e fis2 g2 d2
 }
 
 bassoonNotes = \relative c {
@@ -1437,7 +1458,7 @@ bassoonNotes = \relative c {
   R1
   \tag #'part {
     \clef treble
-    s1*0^\markup { \tiny "flute" }
+    <>^\markup \tiny { flute }
   }
   \cueDuring #"flute" #UP { R1 }
   \tag #'part \clef bass
@@ -1464,7 +1485,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},
@@ -1481,9 +1501,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