X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fstaff.itely;fp=Documentation%2Fnotation%2Fstaff.itely;h=278ffc97c0aefb0d3e148bfb684b37adfe377bf4;hb=0ac07f31e0f95fc18e5916ce756b9c746af7cc58;hp=c7d799e47a0afb511edc98b47d8ce4568b7eafc1;hpb=2f1263e2ccdddcac2eb9f7d8ce2ed92867d3d160;p=lilypond.git

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index c7d799e47a..278ffc97c0 100644
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.16.0"
+@c \version "2.17.30"
 
 @node Staff notation
 @section Staff notation
@@ -69,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}:
 
@@ -124,7 +124,7 @@ Music Glossary:
 @rglos{staves}.
 
 Notation Reference:
-@ref{Creating contexts},
+@ref{Creating and referencing contexts},
 @ref{Percussion staves},
 @ref{Showing melody rhythms},
 @ref{Default tablatures},
@@ -432,67 +432,75 @@ f'4 d \startStaff g, e
 @endpredefined
 
 The lines of a staff belong to the @code{StaffSymbol} grob (including
-ledger lines) can be modified using @code{StaffSymbol} properties, but
+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,
+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
 
-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.
+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=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
 
-The clef position and the position of middle C may need to be adjusted
-accordingly to fit the new lines.  See @ref{Clef}.
+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,relative=2]
 \new Staff \with {
-  \override StaffSymbol #'thickness = #3
+  \override StaffSymbol.thickness = #3
 }
 { f4 d g, e }
 @end lilypond
 
-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.
+It is also possible to set ledger line thickness independently of staff
+lines.
 
 @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
 
+@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.
+
 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,23 +511,23 @@ 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
 
-Legder lines can also be made to appear inside the staff where custom
+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{legder-position} is and is not set.
-The @code{stopStaff} is needed in the example to revert the
+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}.
 
-@lilypond[fragment,quote,relative=1]
-\override Staff.StaffSymbol #'line-positions =   #'(-8 0 2 4)
+@lilypond[verbatim,quote,relative=1]
+\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 +536,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
@@ -595,7 +603,7 @@ 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'' {
+\new Staff = "main" \relative c'' {
   c4 b d c
   <<
     { c4 b d c }
@@ -604,8 +612,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 }
@@ -624,12 +632,12 @@ example.
 
 @lilypond[verbatim,quote,ragged-right]
 <<
-  \new Staff = ossia \with {
+  \new Staff = "ossia" \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
+    \hide Clef
     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 }
 
@@ -637,7 +645,7 @@ example.
     c4 b c2
     <<
       { e4 f e2 }
-      \context Staff = ossia {
+      \context Staff = "ossia" {
         \startStaff e4 g8 f e2 \stopStaff
       }
     >>
@@ -645,7 +653,7 @@ example.
     c4 b c2
     <<
       { g4 a g2 }
-      \context Staff = ossia {
+      \context Staff = "ossia" {
         \startStaff g4 e8 f g2 \stopStaff
       }
     >>
@@ -663,12 +671,12 @@ break.  For more information about
 
 @lilypond[verbatim,quote,ragged-right]
 <<
-  \new Staff = ossia \with {
+  \new Staff = "ossia" \with {
     \remove "Time_signature_engraver"
-    \override Clef #'transparent = ##t
+    \hide Clef
     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 +694,7 @@ break.  For more information about
 \layout {
   \context {
     \Staff \RemoveEmptyStaves
-    \override VerticalAxisGroup #'remove-first = ##t
+    \override VerticalAxisGroup.remove-first = ##t
   }
 }
 @end lilypond
@@ -839,8 +847,8 @@ 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
@@ -910,8 +918,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 }
@@ -924,7 +933,7 @@ multi-line instrument names, @code{\center-column} must be used:
 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}.
+settings, see @ref{paper variables for shifts and indents,,@code{@bs{}paper} variables for shifts and indents}.
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
@@ -1026,7 +1035,7 @@ expression to declare the instrument switch:
 
 @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: