X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fstaff.itely;h=a8111bd7c47a7a1a096521fb9b4c5fe5b0727537;hb=b83bb147ef00d2d3df5b9bb82abb1951ee279396;hp=b4e471f7b09233c22d62a24c6ffe5cfc72346e7f;hpb=df70b08e0bce5a0ef4b37d976d7fd3c5e2db527b;p=lilypond.git

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index b4e471f7b0..a8111bd7c4 100644
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -116,7 +116,6 @@ 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},
@@ -235,10 +234,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 +245,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},
@@ -315,10 +313,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 +333,7 @@ Internals Reference:
 @rinternals{SystemStartBracket},
 @rinternals{SystemStartSquare}.
 
+
 @node Separating systems
 @unnumberedsubsubsec Separating systems
 
@@ -404,125 +402,139 @@ 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
+
+@funindex \startStaff
+@funindex startStaff
+@funindex \stopStaff
+@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=2]
-\new Staff \with {
-  \override StaffSymbol #'line-count = #3
-}
-{ d4 d d d }
+\stopStaff f4 d \startStaff g, e
+f'4 d \stopStaff g, e
+f'4 d \startStaff g, e
+@end lilypond
+
+@predefined
+@code{\startStaff},
+@code{\stopStaff}.
+@endpredefined
+
+The lines of a staff belong to the @code{StaffSymbol} grob (including
+ledger lines) 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=2]
+f4 d \stopStaff
+\override Staff.StaffSymbol #'line-count = #2
+\startStaff g, e |
+
+f'4 d \stopStaff
+\revert Staff.StaffSymbol #'line-count
+\startStaff g, e |
 @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.
+The position of each the staff lines can also be altered.  The values
+used are @emph{half} staff line spaces and the new position is relative
+to the normal center line.  A single staff line is printed for every
+value entered so that the number of staff lines, as well as their
+position in the staff, can be changed with a single override.
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,relative=2]
+f4 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
+
+The clef position and the position of middle 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,relative=2]
 \new Staff \with {
   \override StaffSymbol #'thickness = #3
 }
-{ e4 d c b }
+{ f4 d g, e }
 @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.
+However, it is possible to set ledger line thickness independently of
+staff lines.  The two values required multiply the staff line thickness
+with the staff line spacing and are then added together to give the
+ledger line thickness.
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
+  \override StaffSymbol #'thickness = #2
+  \override StaffSymbol #'ledger-line-thickness = #'(0.5 . 0.4)
 }
-{ e4 d c b }
+{ f'4 a, a,, f }
 @end lilypond
 
-The distance between staff lines can be changed.  This setting
-affects the spacing of ledger lines as well.
+The vertical positions of ledger lines can be altered,
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'staff-space = #1.5
+  \override StaffSymbol #'ledger-positions = #'(-3 -2 -1 2 5 6)
 }
-{ a4 b c d }
+{ f'4 a, a,, f }
 @end lilypond
 
-Further details about the properties of @code{StaffSymbol} can be
-found in @rinternals{staff-symbol-interface}.
-
-@cindex stopping a staff
-@cindex starting a staff
-@cindex staff, starting
-@cindex staff, stopping
-
-@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}:
+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,relative=2]
-c2 c
-\stopStaff
-\override Staff.StaffSymbol #'line-count = #2
-\startStaff
-b2 b
-\stopStaff
-\revert Staff.StaffSymbol #'line-count
-\startStaff
-a2 a
+\new Staff \with {
+  \override StaffSymbol #'ledger-extra = #4
+}
+{ f'4 a, d, 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.
+Legder 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{legder-position} is and is not set.
+The @code{stopStaff} is needed in the example to revert the
+@code{\override} for the whole @code{StaffSymbol}.
 
-@lilypond[verbatim,quote,relative=2]
-c4 b a2
+@lilypond[fragment,quote,relative=1]
+\override Staff.StaffSymbol #'line-positions =   #'(-8 0 2 4)
+d4 e f g
 \stopStaff
-b4 c d2
 \startStaff
-e4 d c2
+\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.
 
-@predefined
-@code{\startStaff},
-@code{\stopStaff}.
-@endpredefined
-
+@lilypond[verbatim,quote,relative=2]
+\new Staff \with {
+  \override StaffSymbol #'staff-space = #1.5
+}
+{ f'4 d, g, e, }
+@end lilypond
 
 @snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {making-some-staff-lines-thicker-than-the-others.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{line},
@@ -680,10 +692,9 @@ break.  For more information about
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {vertically-aligning-ossias-and-lyrics.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{ossia},
@@ -790,10 +801,9 @@ hide empty staves in ancient music contexts.  Similarly,
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {removing-the-first-empty-line.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{Frenched staff}.
@@ -820,9 +830,7 @@ 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
@@ -837,6 +845,7 @@ For the Known issues and warnings associated with
 @code{\Staff \RemoveEmptyStaves} see
 @ref{Changing context default settings}.
 
+
 @node Writing parts
 @subsection Writing parts
 
@@ -863,100 +872,112 @@ and @code{ChoirStaff} contexts.  The value of
 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
+\new Staff \with {
+  instrumentName = #"Violin "
+  shortInstrumentName = #"Vln. "
+}
+{ c4.. 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
+\new Staff \with {
+  instrumentName = \markup {
+    \column { "Clarinetti"
+      \line { "in B" \smaller \flat }
+    }
+  }
+}
+{ c4 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]
 <<
-  \new Staff {
-    \set Staff.instrumentName = #"Flute"
-    f2 g4 f
+  \new Staff \with {
+    instrumentName = #"Flute"
   }
-  \new Staff {
-    \set Staff.instrumentName = \markup \center-column {
-      Clarinet
+  { f2 g4 f }
+  \new Staff \with {
+    instrumentName = \markup {
+      \center-column { "Clarinet" }
       \line { "in B" \smaller \flat }
     }
-    c4 b c2
   }
+  { c4 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}.
 
 @lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+  <<
+    \new Staff \with {
+      instrumentName = #"Alto Flute in G"
+      shortInstrumentName = #"Flt."
+    }
+    {
+      f2 g4 f \break
+      g4 f g2
+    }
+    \new Staff \with {
+      instrumentName = #"Clarinet"
+      shortInstrumentName = #"Clar."
+    }
+    {
+      c,4 b c2 \break
+      c2 b4 c
+    }
+  >>
+}
+
 \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
-    g4 f g2
-  }
-  \new Staff {
-    \set Staff.instrumentName = #"Clarinet"
-    \set Staff.shortInstrumentName = #"Clar."
-    c,4 b c2 \break
-    c2 b4 c
-  }
->>
 @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:
+The @code{shortInstrumentName} may be changed in the middle of a piece.
+However, only the first instance of @code{instrumentName} will be
+printed and subsequent changes will be ignored:
 
 @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
+\new Staff \with {
+  instrumentName = #"Flute"
+  shortInstrumentName = #"Flt."
+}
+{
+  c1 c c c \break
+  c1 c c c \break
+  \set Staff.instrumentName = #"Clarinet"
+  \set Staff.shortInstrumentName = #"Clt."
+  c1 c c c \break
+  c1 c c c \break
+}
 @end lilypond
 
 @cindex instrument switch
@@ -1001,7 +1022,6 @@ expression to declare the instrument switch:
 }
 @end lilypond
 
-
 @seealso
 Notation Reference:
 @ref{\paper variables for shifts and indents},
@@ -1159,6 +1179,9 @@ Notation Reference:
 @ref{Instrument transpositions},
 @ref{Using tags}.
 
+Installed Files:
+@file{scm/define-event-classes.scm}.
+
 Snippets:
 @rlsr{Staff notation}.
 
@@ -1167,15 +1190,11 @@ 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 the music
-expression must not contain @code{\new} and @code{\context Voice}
-statements which would switch to a different Voice.  Quoting grace notes
+@code{\addQuote} command will be considered for quotation, so if the music
+expression contains @code{\new} or @code{\context Voice}
+statements, their contents will not be quoted.  Quoting grace notes
 is unsupported and may cause LilyPond to crash whereas quoting nested
 triplets may result in poor notation.
 
@@ -1296,14 +1315,15 @@ 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.
 
-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'' {
@@ -1464,7 +1484,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 +1500,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