Merge branch 'lilypond/translation' of ssh://trettig@git.sv.gnu.org/srv/git/lilypond...

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

diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely
index 8953a977f1d62b53881054bd54fed6c124f8f7e3..c013f4b2f34d141c5b1b91fb149086cf5da80218 100644 (file)
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -6,6 +6,8 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@c \version "2.11.38"
+

 @node Staff notation
 @section Staff notation
 
 @node Staff notation
 @section Staff notation
 


@@ -31,53 +33,104 @@ staves into groups, which can be marked in the beginning of each
 line with either a bracket or a brace.
 
 @menu
 line with either a bracket or a brace.
 
 @menu

-* Initiating new staves::       
-* Grouping staves::             
+* Instantiating new staves::
+* Grouping staves:: 
+* Deeper nested staff groups::  

 @end menu
 
 @end menu
 

-@node Initiating new staves
-@subsubsection Initiating new staves
+@node Instantiating new staves
+@subsubsection Instantiating new staves

 
 @cindex new staff
 @cindex staff initiation
 
 @cindex new staff
 @cindex staff initiation

+@cindex staff instantiation

 @cindex staff, new
 @cindex staff, new

+@cindex staff, single
+@cindex drum staff
+@cindex percussion staff
+@cindex Gregorian transcription staff
+@cindex rhythmic staff
+@cindex tabstaff
+@cindex tablature
+
+Staves (sg. staff) are created with the @code{\new} or
+@code{\context} commands.  For an explanation on these commands,
+see @ref{Creating contexts}.
+
+There are different predefined staff contexts available in LilyPond:
+
+@itemize
+@item
+The default is @code{Staff}:

 
 

-The lines of a staff (pl. staves) are produced by a @code{staff symbol} 
-layout object.
-LilyPond ensures that all music is printed on staff lines so if you just
-type in some notes, the staff symbol is added automatically to the output.
-This is just a shortcut to make the program usage more easy, but in most
-cases where you want to print more complex music on more than on staff
-it is better to create the staff explicitly at the beginning of your
-music inside of the @code{\score} environment.
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new Staff { c d e f }
+@end lilypond

 
 

-With the command @code{\new Staff @{ ... @}} you actually call a new 
-Staff context that has already everything set up to the default 
-engraving rules. @ref{Creating contexts} explains how different contexts
-are called.
+@item
+@code{DrumStaff} creates a five line staff set up for a typical drum set.
+It uses different names for each instrument.  The instrument names have to
+be set using the @code{drummode}.  See @ref{Percussion staves}.
+
+@lilypond[verbatim,ragged-right,quote]
+\new DrumStaff { 
+  \drummode { cymc hh ss tomh }
+}
+@end lilypond
+
+@c FIXME: remove when mentioned in NR 2.8
+@item
+@code{GregorianTranscriptionStaff} sets up a staff to notate modern
+Gregorian chant.  It does not show bar lines.
+
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new GregorianTranscriptionStaff { c d e f }
+@end lilypond
+
+@item
+@code{RhythmicStaff} can be used to show the rhythm of some music.  The
+notes are printed on one line regardless of their pitch, but the duration
+is preserved.  See @ref{Showing melody rhythms}.
+
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new RhythmicStaff { c d e f }
+@end lilypond
+
+@item
+@code{TabStaff} creates by default a tablature with six strings in 
+standard guitar tuning.  See @ref{Guitar tablatures}.
+
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new TabStaff { c d e f }
+@end lilypond
+
+@end itemize
+
+@noindent
+Besides these staves there are two staff contexts specific for the notation
+of ancient music: @code{MensuralStaff} and @code{VaticanaStaff}.  They are
+described in @ref{Pre-defined contexts}.

 
 Once a staff is instantiated it can be started or stopped at every point
 
 Once a staff is instantiated it can be started or stopped at every point

-in the score. This is done with the commands @code{\startStaff} and 
-@code{\stopStaff}. How to use it is shown in @ref{Staff symbol}.
+in the score.  This is done with the commands @code{\startStaff} and 
+@code{\stopStaff}.  How to use it is explained in @ref{Staff symbol}.

 
 

-Besides the default @code{Staff} context there are also
-specialized staff contexts for setting percussion, Guitar music,
-and ancient music.
-See @ref{Printing chord names}, @ref{Percussion staves}, 
-@ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
-@ref{Mensural contexts} for an explanation.

 
 @seealso
 
 Music Glossary: @rglos{staff}, @rglos{staves}.
 
 
 @seealso
 
 Music Glossary: @rglos{staff}, @rglos{staves}.
 

-Notation Reference: @ref{Printing chord names}, @ref{Percussion staves}, 
-@ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
+Notation Reference: @ref{Percussion staves}, 
+@ref{Guitar tablatures}, @ref{Gregorian chant contexts},

 @ref{Mensural contexts}.
 
 @ref{Mensural contexts}.
 

-Snippets: @lsrdir{Staff,Staff-notation}.
+Snippets:
+@rlsr{Staff notation}.

 
 

-Internals Reference: @internalsref{Staff}.
+Internals Reference: @rinternals{Staff}, @rinternals{DrumStaff},
+@rinternals{GregorianTranscriptionStaff}, @rinternals{RhythmicStaff},
+@rinternals{TabStaff}, @rinternals{MensuralStaff},
+@rinternals{VaticanaStaff}, @rinternals{StaffSymbol}.

 
 
 
 
 
 


@@ -98,171 +151,226 @@ Internals Reference: @internalsref{Staff}.
 @cindex system
 
 LilyPond provides different types of contexts to group single staves 
 @cindex system
 
 LilyPond provides different types of contexts to group single staves 

-together. These contexts influence in the first place the appearance
+together.  These contexts influence in the first place the appearance

 of the system start delimiter, but they have also influence on the
 of the system start delimiter, but they have also influence on the

-behaviour of the bar lines.
-
+behavior of the bar lines.

 
 @itemize
 @item
 If no context is specified, the default properties for the score
 will be used: the group is started with a vertical line, and the
 
 @itemize
 @item
 If no context is specified, the default properties for the score
 will be used: the group is started with a vertical line, and the

-bar lines are not connected.  
+bar lines are not connected.  The name of the beginning bar line 
+grob is @code{SystemStartBar}.  

 
 

-@lilypond[verbatim,ragged-right,quote]
-\relative c'' { <<
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+<<

   \new Staff { c1 c }
   \new Staff { c c }
   \new Staff { c1 c }
   \new Staff { c c }

->> }
+>>

 @end lilypond
 
 @item
 In a @code{StaffGroup}, the bar lines will be drawn through
 all the staves, and the group is started with a bracket.
 
 @end lilypond
 
 @item
 In a @code{StaffGroup}, the bar lines will be drawn through
 all the staves, and the group is started with a bracket.
 

-@lilypond[verbatim,ragged-right,quote]
-\new StaffGroup {
-  \relative c'' <<
-    \new Staff { c1 c }
-    \new Staff { c c }
-  >>
-}
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new StaffGroup <<
+  \new Staff { c1 c }
+  \new Staff { c c }
+>>

 @end lilypond
 
 @item
 In a @code{ChoirStaff}, the group is 
 started with a bracket, but bar lines are not connected. 
 
 @end lilypond
 
 @item
 In a @code{ChoirStaff}, the group is 
 started with a bracket, but bar lines are not connected. 
 

-@lilypond[verbatim,ragged-right,quote]
-\new ChoirStaff {
-  \relative c'' <<
-    \new Staff { c1 c }
-    \new Staff { c c }
-  >>
-}
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new ChoirStaff <<
+  \new Staff { c1 c }
+  \new Staff { c c }
+>>

 @end lilypond
 
 @item
 In a @code{GrandStaff}, the group is started with a brace
 at the left, and bar lines are connected between the staves. 
 
 @end lilypond
 
 @item
 In a @code{GrandStaff}, the group is started with a brace
 at the left, and bar lines are connected between the staves. 
 

-@lilypond[verbatim,ragged-right,quote]
-\new GrandStaff {
-  \relative c'' <<
-    \new Staff { c1 c }
-    \new Staff { c c }
-  >>
-}
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new GrandStaff <<
+  \new Staff { c1 c }
+  \new Staff { c c }
+>>

 @end lilypond
 
 @item
 The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is
 @end lilypond
 
 @item
 The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is

-optimized for setting piano music.
+optimized for setting piano music. In particular it supports the printing
+of an instrument name directly, see @ref{Instrument names}.

 
 

-@lilypond[verbatim,ragged-right,quote]
-\new PianoStaff
-\relative c'' <<
+@lilypond[verbatim,ragged-right,quote,fragment,relative=2]
+\new PianoStaff <<

   \new Staff { c1 c }
   \new Staff { c c }
   \new Staff { c1 c }
   \new Staff { c c }

->> }
+>>

 @end lilypond
 
 @end itemize
 
 @end lilypond
 
 @end itemize
 

+Each staff group context sets the property
+@code{systemStartDelimiter} to one of the values
+@code{SystemStartBar}, @code{SystemStartBrace},
+and @code{SystemStartBracket}.  A fourth delimiter,
+@code{systemStartSquare}, is also available, but must be
+instantiated manually.  The usage of this last delimiter is shown further
+down in the snippet section.
+

 According to classic engraver rules an orchestral score consists of
 According to classic engraver rules an orchestral score consists of

-staves connected only with a single line at the beginning of the system.
+staves connected only with a single line at the beginning of the system. 

 In LilyPond this is produced grouping the @code{Staff} contexts with
 @code{<< ... >>}.
 
 Each instrument family is grouped inside of a @code{StaffGroup} with a 
 In LilyPond this is produced grouping the @code{Staff} contexts with
 @code{<< ... >>}.
 
 Each instrument family is grouped inside of a @code{StaffGroup} with a 

-starting bracket. A group of same instruments or an instrument using
+starting bracket.  A group of same instruments or an instrument using

 more than one staff is grouped with braces in a @code{GrandStaff}.
 
 As the context names tell, @code{PianoStaff} is used for notating
 piano music and @code{ChoirStaff} for all kind of vocal ensemble music.
 
 more than one staff is grouped with braces in a @code{GrandStaff}.
 
 As the context names tell, @code{PianoStaff} is used for notating
 piano music and @code{ChoirStaff} for all kind of vocal ensemble music.
 

-Here is an example of an orchestral score using groupings. Note that the
-instrument names are omited here, see @ref{Instrument names} how to set 
-them.

 
 

-@lilypond[verbatim,ragged-right,quote]
-\score{ \relative c' {
-<<
-  \new StaffGroup %the woodwinds group
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{use-square-bracket-at-the-start-of-a-staff-group.ly}
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{display-bracket-with-only-one-staff-in-a-system.ly}
+
+@cindex mensurstriche layout
+@cindex renaissance music
+@cindex transcription of mensural music
+@cindex mensural music, transcription of
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{mensurstriche-layout-bar-lines-between-the-staves.ly}
+@c FIXME: move to NR 2.8.x when sectioning is ready
+
+@seealso
+
+Music Glossary: @rglos{brace}, 
+@rglos{bracket}, @rglos{grand staff}.
+
+Snippets:
+@rlsr{Staff notation}.
+
+Internals Reference: @rinternals{Staff}, @rinternals{ChoirStaff},
+@rinternals{GrandStaff}, @rinternals{PianoStaff}, 
+@rinternals{StaffGroup}, @rinternals{systemStartDelimiter},
+@rinternals{SystemStartBar}, @rinternals{SystemStartBrace},
+@rinternals{SystemStartBracket}, @rinternals{systemStartSquare}.
+
+
+@node Deeper nested staff groups
+@subsubsection Deeper nested staff groups
+
+There are also two inner staff contexts named @code{InnerStaffGroup}
+and @code{InnerChoirStaffGroup} besides the grouping contexts mentioned
+in @ref{Grouping staves}.  They behave in the same way as their simple
+counterparts, except that they are contained in another staff grouping
+context, thus producing one more bracket on top of the existing one. 
+Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
+grouping contexts.  They can both be inside any other staff context, 
+including inner staff groups, though.
+
+Here is an example of an orchestral score using groupings and nesting
+of these groupings.  Note that the instrument names are omitted from the
+source code, for instructions how to set them see @ref{Instrument names}.
+
+@cindex staff, nested
+@cindex staves, nested
+@cindex nesting of staves
+@cindex system start delimiters, nested
+@cindex nested staff brackets
+@cindex brackets, nesting of
+@cindex braces, nesting of
+@cindex inner staff group
+@cindex inner choir staff group
+
+
+@example
+\score @{ <<
+  \new StaffGroup %woodwinds

   <<
   <<

-    \new Staff { c1 c }
-    \new Staff { c c }
-    \new Staff { c c }
+  \new Staff @{ c'1 d' @} %flute
+  \new InnerStaffGroup <<
+    \new Staff @{ c' d' @} %sax 
+    \new Staff @{ c' d' @} %oboe
+    \new Staff @{ c' d' @} %English horn
+    >>
+  \new Staff @{ \clef bass c d @} %bassoon

   >>
   \new StaffGroup %the brass group
   <<
   >>
   \new StaffGroup %the brass group
   <<

-    \new Staff { c c }
-    \new Staff { c c }
+    \new Staff @{ c' d' @} %trumpet
+    \new Staff @{ \clef bass c d @} %trombone

     \new GrandStaff %the horns need a GrandStaff (same instrument)
     <<
     \new GrandStaff %the horns need a GrandStaff (same instrument)
     <<

-      \new Staff { c c }
-      \new Staff {\clef bass c c }
+      \new Staff @{ c' d' @}
+      \new Staff @{ \clef bass c d @}

     >>
   >>
     >>
   >>

-  \new ChoirStaff %for a vocal part
+  \new ChoirStaff %for setting vocal music

   <<
   <<

-    \new Staff { c c }
-    \new Staff {\clef alto c c }
-    \new Staff {\clef bass c c }
+   \new Staff @{ c' d' @}
+    \new InnerChoirStaff <<
+     \new Staff @{ c' d' @}
+     \new Staff @{ c' d' @}
+    >>
+   \new Staff @{ c' d' @}

   >>
   \new PianoStaff %for the piano
   <<
   >>
   \new PianoStaff %for the piano
   <<

-    \new Staff { c c }
-    \new Staff {\clef bass c c }
+    \new Staff @{ c' d' @}
+    \new Staff @{\clef bass c d @}

   >>
   >>

->>
-} }
-@end lilypond
-
-The different staff contexts are already nested in this example, as
-the @q{horn section} is contained both in a @code{StaffGroup} and a 
-@code{GrandStaff}.
-
-@cindex staff, nested
-
-It is also possible to nest staves of the same type with the contexts
-@code{InnerStaffGroup} and @code{InnerChoirStaffGroup}. These behave like
-the corresponding normal staff groups but can only initiated inside of
-another staff context. Again LilyPond would add a normal @code{StaffGroup}
-to the output, if you would start a score with an @code{InnerStaffGroup}. 
-
-Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
-grouping contexts. They can both be inside an inner staff context, though.
+>> @}
+@end example

 
 

-@c snippet staff-brackets.ly
-@lilypond[verbatim,ragged-right,quote]
-\score { 
-<<
-  \new StaffGroup << 
-  \new Staff {c' d' e' f'}
+@c no verbatim so instrument names are only in the music
+@lilypond[ragged-right,quote]
+\score { <<
+  \new StaffGroup %woodwinds
+  <<
+  \new Staff {\set Staff.instrumentName = "fl" c'1 d' } %flute

   \new InnerStaffGroup <<
   \new InnerStaffGroup <<

-   \new Staff {c' d' e' f'}
-   \new GrandStaff <<
-     \new Staff {c' d' e' f'}
-     \new Staff {c' d' e' f'}
-   >>
-  \new Staff {c' d' e' f'}
+    \new Staff { \set Staff.instrumentName = "sax" c' d' } %sax 1
+    \new Staff { \set Staff.instrumentName = "ob" c' d' } %sax 2
+    \new Staff { \set Staff.instrumentName = "ca" c' d' }
+    >>
+  \new Staff {\set Staff.instrumentName = "bs" \clef bass c d } %bassoon

   >>
   >>

-  \new ChoirStaff <<
-   \new Staff {c' d' e' f'}
-    \new InnerStaffGroup <<
-     \new Staff {c' d' e' f'}
+  \new StaffGroup %the brass group
+  <<
+    \new Staff {\set Staff.instrumentName = "tr" c' d' } %trumpet
+    \new Staff {\set Staff.instrumentName = "tb" \clef bass c d } %trombone
+    \new GrandStaff %the horns need a GrandStaff (same instrument)
+    <<
+      \new Staff {\set Staff.instrumentName = "cor1" c' d' }
+      \new Staff {\set Staff.instrumentName = "cor2" \clef bass c d }

     >>
     >>

-   \new Staff {c' d' e' f'}

   >>
   >>

+  \new ChoirStaff %for setting vocal music
+  <<
+   \new Staff {\set Staff.instrumentName = "S" c' d' }
+    \new InnerChoirStaff <<
+     \new Staff {\set Staff.instrumentName = "A1" c' d' }
+     \new Staff {\set Staff.instrumentName = "A2" c' d' }
+    >>
+   \new Staff {\set Staff.instrumentName = "T" c' d' }

   >>
   >>

-  \new ChoirStaff << 
-   \new Staff {c' d' e' f'}
-   \new InnerChoirStaff <<
-    \new Staff {c' d' e' f'}
-    \new Staff {c' d' e' f'}
-   >>
-   \new Staff {c' d' e' f'}
+  \new PianoStaff %for the piano
+  <<
+    \new Staff { c' d' }
+    \new Staff {\clef bass c d }

   >>
 >> }
 @end lilypond
   >>
 >> }
 @end lilypond


@@ -270,141 +378,234 @@ grouping contexts. They can both be inside an inner staff context, though.
 
 @snippets
 
 
 @snippets
 

-@c FIXME: not yet in master
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {nesting-staves.ly}
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{nesting-staves.ly}

 
 
 
 

-More complex nesting can be accomplished using the property
-@code{systemStartDelimiterHierarchy}: 
+@seealso

 
 

-@lilypond[quote,ragged-right,verbatim]
-\new StaffGroup
-\relative <<
-  \set StaffGroup.systemStartDelimiterHierarchy
-    = #'(SystemStartSquare (SystemStartBracket a
-                             (SystemStartSquare b)) d)
-  \new Staff { c1 }
-  \new Staff { c1 }
-  \new Staff { c1 }
-  \new Staff { c1 }
-  \new Staff { c1 }
->>
-@end lilypond
+Snippets:
+@rlsr{Staff notation}.

 
 

-Each staff group context sets the property
-@code{systemStartDelimiter} to one of the values
-@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
-and @internalsref{SystemStartBracket}.  A fourth delimiter,
-@code{systemStartSquare}, is also available, but must be
-instantiated manually
+Internals Reference: @rinternals{InnerChoirStaffGroup}, 
+@rinternals{InnerStaffGroup}, @rinternals{SystemStartBar}, 
+@rinternals{SystemStartBrace}, @rinternals{SystemStartBracket},
+@rinternals{systemStartDelimiterHierarchy}.

 
 
 
 
 
 

-@cindex mensurstriche layout
-@cindex renaissance music
-@cindex transcription of mensural music
-@cindex mensural music, transcription of
+@node Modifying single staves
+@subsection Modifying single staves

 
 

+This section explains how to change specific attributes of one 
+staff like the staff lines, starting and stopping of staves, sizing
+of staves, and setting ossia sections.

 
 

-@c FIXME: not yet in master
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {mensurstriche-layout.ly}
+@menu
+* Staff symbol::   
+* Ossia staves::             
+* Hiding staves::    
+@end menu

 
 

-Other groupings may be achieved by changing various properties.
-E.g., the
-@q{Mensurstriche} layout common in Renaissance music, with
-bar lines running between but not through the staves, can be
-produced from a @code{StaffGroup} or @code{GrandStaff} context if
-the bar lines are made transparent in the @code{Staff} itself:
+@node Staff symbol
+@subsubsection Staff symbol

 
 

-@lilypond[verbatim,ragged-right,quote]
-global = {\override Staff.BarLine #'transparent = ##t
-          s1 s
-          %the final bar line is not interupted
-          \once \override Staff.BarLine #'transparent = ##f
-          \bar "|."}
-\new StaffGroup
-\relative c'' <<
-  \new Staff {<< \global { c1 c } >>}
-  \new Staff {<< \global { c c } >>}
->>
-@end lilypond
+@cindex adjusting staff symbol
+@cindex drawing staff symbol
+@cindex staff symbol, setting of
+@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 layout object which draws the lines of a staff is called
+@code{staff symbol}.  The staff symbol may be tuned in number,
+thickness and distance of lines, using properties.  It may also
+be started and stopped at every point in the score.

 
 

+@itemize
+@item
+Changing the number of staff lines is done by overriding 
+@code{line-count}.  You may need to adjust the clef position
+and the position of the middle C to fit to the new staff.  For
+an explanation, see the snippet section in @ref{Displaying pitches}.

 
 

-@c FIXME: Graham will deal with this.  -gp
-@c snippet 201
-To display a bracket even if there is only one staff, see
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {staff,display-bracket-with-only-one-staff-in-a system.ly}
+@lilypond[verbatim,ragged-right,quote]
+\new Staff {
+  \override Staff.StaffSymbol  #'line-count = #3
+  d d d d
+}
+@end lilypond

 
 

-@seealso
+@item
+The placement and amount of the staff lines can also set totally 
+manually by defining their positions explicitly.  The middle
+of the staff has the value of 0, each half staff space up and down
+adds an integer.  The default values are 4 2 0 -2 -4.  Bar lines
+are drawn according to the calculated width of the system, but
+they are always centered.  As the
+example shows, the positions of the notes are not influenced
+by the position of the staff lines.

 
 

-Music Glossary: @rglos{brace}, 
-@rglos{bracket}.
+@lilypond[verbatim,ragged-right,quote]
+\new Staff \with {
+  \override StaffSymbol #' line-positions = #' ( 7 3 0 -4 -6 -7 )
+  }{
+  a e' f' b' d''
+}
+@end lilypond

 
 

-Snippets: @lsrdir{Staff,Staff-notation}
+@item
+The staff line thickness can be set by overriding the @code{thickness}
+property.  Note that it gets applied also to ledger lines and stems, 
+since they depend on the staff line thickness.  The argument of 
+@code{thickness} is a factor of @code{line-thickness} which defaults
+to the normal staff line thickness.

 
 

-Internals Reference: @internalsref{ChoirStaff},
-@internalsref{GrandStaff}, @internalsref{PianoStaff}, 
-@internalsref{StaffGroup},
-@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
-@internalsref{SystemStartBracket}, @internalsref{SystemStartSquare}.
+@lilypond[verbatim,ragged-right,quote]
+\new Staff \with {
+  \override StaffSymbol #'thickness = #3
+  }{
+  d d d d
+}
+@end lilypond

 
 

+@item
+The thickness of the ledger lines can also be set independent of the
+settings for staff lines.  The setting is calculated from a pair of
+values which will be added for the final thickness.  The first value 
+is the staff line thickness multiplied by a factor, the second is
+the staff space multiplied by a factor.  In the example the ledger
+lines get their thickness from one staff line thickness plus 1/5 
+staff space, so they are heavier than a normal staff line.

 
 

+@lilypond[verbatim,ragged-right,quote]
+\new Staff \with {
+  \override StaffSymbol #'  ledger-line-thickness = #' ( 1 . 0.2 ) }
+  {
+  d d d d
+}
+@end lilypond

 
 

-@node Modifying single staves
-@subsection Modifying single staves
+@item
+The distance of the stafflines can be changed with the 
+@code{staff-space} property. Its argument is the amount
+of staff spaces that should be inserted between the lines.
+The default value is 1. Setting the distance has
+influence on the staff lines as well as on ledger lines.

 
 

-@menu
-* Staff symbol::                
-* Ossia staves::                
-* Hiding staves::               
-@end menu
+@lilypond[verbatim,ragged-right,quote]
+\new Staff \with {
+  \override StaffSymbol #' staff-space  = #1.5
+  }{
+  a b c' d'
+}
+@end lilypond

 
 

-@node Staff symbol
-@subsubsection Staff symbol
+@item
+The length of the staff line can also be adjusted
+manually.  The unit is one staff space.  Spacing 
+of the objects inside the staff does not get influenced 
+by this setting.

 
 

-@cindex adjusting staff symbol
+@lilypond[verbatim,ragged-right,quote]
+\new Staff \with {
+  \override StaffSymbol #' width = #23
+  }{
+  a e' f' b' d''
+}
+@end lilypond

 
 

-The layout object which draws the lines of a staff is called
-@code{staff symbol}.  The staff symbol may be tuned in the number,
-thickness and distance of lines, using properties.  This is
-demonstrated in the example files
-@c @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
-@c @lsr{staff,changing-the-staff-size.ly}.
+@end itemize

 
 

-In addition, staves may be started and stopped at will.  This is
-done with @code{\startStaff} and @code{\stopStaff}.
+These properties can only be set before instantiating the staff symbol.
+But it is possible to start and stop staves in the middle of a score,
+so each new setting will be applied to the newly instantiated staff.

 
 @lilypond[verbatim,relative=2,fragment]
 b4 b
 
 @lilypond[verbatim,relative=2,fragment]
 b4 b

+%Set here the overrides for the staff 

 \override Staff.StaffSymbol #'line-count = 2
 \stopStaff \startStaff
 b b
 \override Staff.StaffSymbol #'line-count = 2
 \stopStaff \startStaff
 b b

+%Revert to the default

 \revert Staff.StaffSymbol #'line-count
 \stopStaff \startStaff
 b b
 @end lilypond
 \revert Staff.StaffSymbol #'line-count
 \stopStaff \startStaff
 b b
 @end lilypond

+ 
+@predefined
+
+@code{\stopStaff}, @code{\startStaff}
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{making-some-staff-lines-thicker-than-the-others.ly}
+
+@seealso
+
+Glossary: @rglos{line}, @rglos{ledger line}, @rglos{staff}.
+
+Internals Reference: @rinternals{StaffSymbol}.
+
+@knownissues
+
+When setting staff lines manually, bar lines are
+always drawn centered on the position 0, so the
+maximum distance of the bar lines in either direction 
+must be equal.
+

 
 @node Ossia staves
 @subsubsection Ossia staves
 
 
 @node Ossia staves
 @subsubsection Ossia staves
 

-@cindex staves, Frenched
+@cindex staff, Frenched

 @cindex ossia
 @cindex Frenched staves
 @cindex ossia
 @cindex Frenched staves

+@cindex staff, resizing of
+@cindex resizing of staves

 
 

-In combination with Frenched staves, this may be used to typeset
-@emph{ossia} sections.  An example is shown here
+Tweaking the staff object allows to resize the staff:

 
 

-@lilypond[verbatim,relative=2,quote]
+@lilypond[verbatim,ragged-right,quote]
+  \new Staff \with {
+    fontSize = #-3
+    \override StaffSymbol #'staff-space = #(magstep -3)
+    \override StaffSymbol #'thickness = # (magstep -3)
+  }
+  {
+    \clef bass
+    c8 c c c  c c c c
+  }
+@end lilypond
+
+@noindent
+This involves shrinking the staff spaces, the staff lines and
+the font size by the factor 3.  You find a more precise explanation
+in @ref{Setting the staff size}.
+
+The @emph{ossia} section in the next example are just put parallel
+to the main staff with @code{<<} and @code{>>} brackets.  The @emph{ossia}
+staff is stopped and started explicitely and white space is inserted 
+with the @code{\skip} command.
+
+@lilypond[verbatim,quote]

 <<
   \new Staff \with
   {
 <<
   \new Staff \with
   {

+    %No time signature in the ossia staff

     \remove "Time_signature_engraver"
     \remove "Time_signature_engraver"

-    fontSize = #-2
-    \override StaffSymbol #'staff-space = #(magstep -2)
+    fontSize = #-3
+    \override StaffSymbol #'staff-space = #(magstep -3)
+    \override StaffSymbol #'thickness = # (magstep -3)

     firstClef = ##f
   }
   \relative c'' {
     firstClef = ##f
   }
   \relative c'' {


@@ -421,70 +622,63 @@ In combination with Frenched staves, this may be used to typeset
     \startStaff
     f8 d g4 
   }
     \startStaff
     f8 d g4 
   }

-  \new Staff  \relative
-  {
+  \new Staff  \relative c'' {

     \time 2/4
     c4 c g' g a a g2
   }
     \time 2/4
     c4 c g' g a a g2
   }

-

 >>
 @end lilypond
 
 >>
 @end lilypond
 

-@cindex staff lines, setting number of
-@cindex staff lines, setting thickness of
-@cindex thickness of staff lines, setting
-@cindex number of staff lines, setting
+
+@snippets
+
+@c  lilypondfile{Making-some-staff-lines-thicker-than-the-others.ly}
+@c snippet 277

 
 @seealso
 
 Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
 
 
 @seealso
 
 Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
 

-Snippets: @lsrdir{Staff,Staff-notation}
+Snippets:
+@rlsr{Staff notation}.

 
 

-Internals Reference: @internalsref{StaffSymbol},
-@internalsref{DrumStaff}.
+Internals Reference: @rinternals{StaffSymbol}.

 
 
 @node Hiding staves
 @subsubsection Hiding staves
 
 @cindex Frenched scores
 
 
 @node Hiding staves
 @subsubsection Hiding staves
 
 @cindex Frenched scores

-@cindex staves, hiding
-@cindex staves, empty 
+@cindex staff, hiding
+@cindex staff, empty 
+@cindex hiding of staves
+@cindex empty staves
+@cindex Frenched staves

 
 In orchestral scores, staff lines that only have rests are usually
 removed; this saves some space.  This style is called @q{French
 
 In orchestral scores, staff lines that only have rests are usually
 removed; this saves some space.  This style is called @q{French

-Score}.  For @code{Lyrics}, @code{ChordNames} and
-@code{FiguredBass}, this is switched on by default.  When
+Score}.  For the @code{Lyrics}, @code{ChordNames}, and
+@code{FiguredBass} contexts, this is switched on by default.  When

 the lines of these contexts turn out empty after the line-breaking
 process, they are removed.
 
 the lines of these contexts turn out empty after the line-breaking
 process, they are removed.
 

-For normal staves, a specialized @code{Staff} context is
-available, which does the same: staves containing nothing (or only
-multi-measure rests) are removed.  The context definition is
-stored in @code{\RemoveEmptyStaffContext} variable.  Observe how
-the second staff in this example disappears in the second line
+For normal staves this behaviour is called
+with the @code{\RemoveEmptyStaffContext} command.  It is set
+in the @code{\layout} block.  As a result staves containing 
+nothing or whole mesure rests are removed after a line break.

 
 @lilypond[quote,ragged-right,verbatim]
 \layout {
   \context { \RemoveEmptyStaffContext }
 }
 
 @lilypond[quote,ragged-right,verbatim]
 \layout {
   \context { \RemoveEmptyStaffContext }
 }

-
-{
-  \relative c' <<
+\relative c'' {
+  <<

     \new Staff { e4 f g a \break c1 }
     \new Staff { c4 d e f \break R1 }
     \new Staff { e4 f g a \break c1 }
     \new Staff { c4 d e f \break R1 }

-  >>
+  >>  

 }
 @end lilypond
 
 }
 @end lilypond
 

-The first system shows all staves in full.  If empty staves should
-be removed from the first system too, set @code{remove-first} to
-true in @code{VerticalAxisGroup}.
-
-@example
-\override Score.VerticalAxisGroup #'remove-first = ##t
-@end example

 
 To remove other types of contexts, use
 @code{\AncientRemoveEmptyStaffContext} or
 
 To remove other types of contexts, use
 @code{\AncientRemoveEmptyStaffContext} or


@@ -494,8 +688,7 @@ To remove other types of contexts, use
 
 Another application of the @code{\RemoveEmptyStaffContext} is to
 make ossia sections, i.e., alternative melodies on a separate
 
 Another application of the @code{\RemoveEmptyStaffContext} is to
 make ossia sections, i.e., alternative melodies on a separate

-piece of staff, with help of a Frenched staff.  See @ref{Staff
-symbol}. 
+piece of staff, with help of a Frenched staff.  See @ref{Ossia staves}. 

 
 You can make the staff lines invisible by removing the
 @code{Staff_symbol_engraver} from the @code{Staff} context.
 
 You can make the staff lines invisible by removing the
 @code{Staff_symbol_engraver} from the @code{Staff} context.


@@ -503,7 +696,7 @@ You can make the staff lines invisible by removing the
 
 @lilypond[quote,ragged-right,verbatim]
 \score {
 
 @lilypond[quote,ragged-right,verbatim]
 \score {

-  \context Staff \relative c'' { c8 c c16 c c c }
+  \new Staff \relative c'' { c8 c c16 c c c }

   \layout{
     \context {
       \Staff
   \layout{
     \context {
       \Staff


@@ -513,15 +706,63 @@ You can make the staff lines invisible by removing the
 }
 @end lilypond
 
 }
 @end lilypond
 

+@snippets
+
+The first empty staff can also be removed from the score with a 
+setting in the @code{VerticalAxisGroup} property.  This can be done 
+globally inside the @code{\layout} block, or locally inside the 
+specific staff that should be removed. In the latter case, 
+you have to specify the context (@code{Staff} applies only to the 
+current staff) in front of the property.
+
+The lower staff of the second staff group is not removed, 
+because the setting applies only to the specific staff inside 
+of which it is written.
+
+@lilypond[quote,ragged-right,verbatim]
+\layout {
+  \context { 
+    \RemoveEmptyStaffContext 
+    %To use the setting globally, uncomment the following line:
+    %\override VerticalAxisGroup #'remove-first = ##t
+  }
+}
+\new StaffGroup
+  \relative c'' <<
+    \new Staff {    
+      e4 f g a \break c1 }
+    \new Staff {
+      %To use the setting globally, comment this line, uncomment the line above
+      \override Staff.VerticalAxisGroup #'remove-first = ##t
+      R1 \break R1 }
+  >>
+\new StaffGroup
+  <<
+    \new Staff { e4 f g a \break c1 }
+    \new Staff { R \break R1 }
+  >>
+@end lilypond
+
+@c FIXME not yet in master
+@c lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@c {remove-the-first-empy-line.ly}
+
+@predefined
+
+@code{\RemoveEmptyStaffContext},
+@code{\AncientRemoveEmptyStaffContext},
+@code{\RemoveEmptyRhythmicStaffContext},
+

 @seealso
 
 Notation Reference: @ref{Staff symbol}.
 
 @seealso
 
 Notation Reference: @ref{Staff symbol}.
 

-Snippets: @lsrdir{Staff,Staff-notation}
+Snippets:
+@rlsr{Staff notation}.

 
 

-Internals Reference: @internalsref{ChordNames},
-@internalsref{FiguredBass}, @internalsref{Lyrics},
-@internalsref{Staff}, @internalsref{VerticalAxisGroup}.
+Internals Reference: @rinternals{ChordNames},
+@rinternals{FiguredBass}, @rinternals{Lyrics},
+@rinternals{Staff}, @rinternals{VerticalAxisGroup}.

 
 @node Writing parts
 @subsection Writing parts
 
 @node Writing parts
 @subsection Writing parts


@@ -573,7 +814,7 @@ c4^\markup {
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-For more details, see @ref{Text markup}.
+For more details, see @ref{Formatting text}.

 
 
 @seealso
 
 
 @seealso


@@ -581,11 +822,12 @@ For more details, see @ref{Text markup}.
 Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
 @rglos{tempo indication}, @rglos{metronome mark}.
 
 Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
 @rglos{tempo indication}, @rglos{metronome mark}.
 

-Notation Reference: @ref{Text markup}.
+Notation Reference: @ref{Formatting text}.

 
 

-Snippets: @lsrdir{Staff,Staff-notation}.
+Snippets:
+@rlsr{Staff notation}.

 
 

-Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
+Internals Reference: @rinternals{MetronomeMark}, @ref{MIDI

 output}.
 
 
 output}.
 
 


@@ -702,10 +944,11 @@ c1 c c c \break
 
 Notation Reference: @ref{Modifying context plug-ins}.
 
 
 Notation Reference: @ref{Modifying context plug-ins}.
 

-Snippets: @lsrdir{Staff,Staff-notation}
+Snippets:
+@rlsr{Staff notation}.

 
 

-Internals Reference: @internalsref{InstrumentName},
-@internalsref{PianoStaff}, @internalsref{Staff}.
+Internals Reference: @rinternals{InstrumentName},
+@rinternals{PianoStaff}, @rinternals{Staff}.

 
 
 @node Quoting other voices
 
 
 @node Quoting other voices


@@ -824,9 +1067,10 @@ written entirely in lower-case letters: @code{\addquote}.
 
 Notation Reference: @ref{Instrument transpositions}.
 
 
 Notation Reference: @ref{Instrument transpositions}.
 

-Snippets: @lsrdir{Staff,Staff-notation}
+Snippets:
+@rlsr{Staff notation}.

 
 

-Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
+Internals Reference: @rinternals{QuoteMusic}, @rinternals{Voice}.

 
 
 @node Formatting cue notes
 
 
 @node Formatting cue notes


@@ -930,15 +1174,16 @@ cbsn = \relative c, {
 }
 
 <<
 }
 
 <<

-  \context Staff = "picc" \picc
-  \context Staff = "cbsn" \cbsn
+  \new Staff = "picc" \picc
+  \new Staff = "cbsn" \cbsn

 >>
 @end lilypond
 
 @seealso
 
 >>
 @end lilypond
 
 @seealso
 

-Snippets: @lsrdir{Staff,Staff-notation}.
+Snippets:
+@rlsr{Staff notation}.

 
 

-Internals Reference: @internalsref{Voice}.
+Internals Reference: @rinternals{Voice}.