Imported Upstream version 2.18.0

[lilypond.git] / Documentation / notation / staff.itely

diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index c7d799e47a0afb511edc98b47d8ce4568b7eafc1..278ffc97c0aefb0d3e148bfb684b37adfe377bf4 100644 (file)
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.16.0"
+@c \version "2.17.30"

 
 @node Staff notation
 @section Staff notation
 
 @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
 
 @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}:
 
 
 The basic staff context is @code{Staff}:
 


@@ -124,7 +124,7 @@ Music Glossary:
 @rglos{staves}.
 
 Notation Reference:
 @rglos{staves}.
 
 Notation Reference:

-@ref{Creating contexts},
+@ref{Creating and referencing contexts},

 @ref{Percussion staves},
 @ref{Showing melody rhythms},
 @ref{Default tablatures},
 @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
 @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.
 
 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
 
 @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
 \startStaff g, e |
 
 f'4 d \stopStaff

-\revert Staff.StaffSymbol #'line-count
+\revert Staff.StaffSymbol.line-count

 \startStaff g, e |
 @end lilypond
 
 \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
 
 @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
 \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
 
 \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 {
 
 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
 
 }
 { 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 {
 
 @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
 
 }
 { 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 {
 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
 }
 { 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 {
 
 @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
 
 }
 { 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
 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}.
 
 @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
 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
 
 d4 e f g
 @end lilypond
 


@@ -528,7 +536,7 @@ line spacing as well.
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff \with {
 
 @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
 }
 { 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]
 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 }
   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
       \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 }
       firstClef = ##f
     }
     { e4 d f e }


@@ -624,12 +632,12 @@ example.
 
 @lilypond[verbatim,quote,ragged-right]
 <<
 
 @lilypond[verbatim,quote,ragged-right]
 <<

-  \new Staff = ossia \with {
+  \new Staff = "ossia" \with {

     \remove "Time_signature_engraver"
     \remove "Time_signature_engraver"

-    \override Clef #'transparent = ##t
+    \hide Clef

     fontSize = #-3
     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 }
 
   }
   { \stopStaff s1*6 }
 


@@ -637,7 +645,7 @@ example.
     c4 b c2
     <<
       { e4 f e2 }
     c4 b c2
     <<
       { e4 f e2 }

-      \context Staff = ossia {
+      \context Staff = "ossia" {

         \startStaff e4 g8 f e2 \stopStaff
       }
     >>
         \startStaff e4 g8 f e2 \stopStaff
       }
     >>


@@ -645,7 +653,7 @@ example.
     c4 b c2
     <<
       { g4 a g2 }
     c4 b c2
     <<
       { g4 a g2 }

-      \context Staff = ossia {
+      \context Staff = "ossia" {

         \startStaff g4 e8 f g2 \stopStaff
       }
     >>
         \startStaff g4 e8 f g2 \stopStaff
       }
     >>


@@ -663,12 +671,12 @@ break.  For more information about
 
 @lilypond[verbatim,quote,ragged-right]
 <<
 
 @lilypond[verbatim,quote,ragged-right]
 <<

-  \new Staff = ossia \with {
+  \new Staff = "ossia" \with {

     \remove "Time_signature_engraver"
     \remove "Time_signature_engraver"

-    \override Clef #'transparent = ##t
+    \hide Clef

     fontSize = #-3
     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
   } \relative c'' {
     R1*3
     c4 e8 d c2


@@ -686,7 +694,7 @@ break.  For more information about
 \layout {
   \context {
     \Staff \RemoveEmptyStaves
 \layout {
   \context {
     \Staff \RemoveEmptyStaves

-    \override VerticalAxisGroup #'remove-first = ##t
+    \override VerticalAxisGroup.remove-first = ##t

   }
 }
 @end lilypond
   }
 }
 @end lilypond


@@ -839,8 +847,8 @@ this case, use the following overrides instead of removing the
 engraver:
 
 @example
 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
 @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 {
   { 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 }
     }
   }
   { 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
 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'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -1026,7 +1035,7 @@ expression to declare the instrument switch:
 
 @seealso
 Notation Reference:
 
 @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:
 @ref{Modifying context plug-ins}.
 
 Snippets: