Merge branch 'master' of ssh://jeancharlesm@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 b1d47765da5a93a44bc020566946c2f4b257938f..d025bda0d8effb471df2d760d117f9067c8c9715 100644 (file)
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -6,23 +6,20 @@
     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.51"
+

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

-@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-{staff-headword.ly}
-
-Notes, dynamic signs, rests, etc., are grouped with a set of horizontal
-lines, called a staff (plural @q{staves}).  In LilyPond, these
-lines are drawn using a separate layout object called @code{staff
-symbol}.
-
-Two or more staves can be grouped vertically in a @code{GrandStaff}, a
-@code{StaffGroup}, or a @code{ChoirStaff}.
+@lilypondfile[quote]{staff-headword.ly}

 
 

+This section explains how to influence the staff appearance, print
+scores with more than one staff, and how to apply specific
+performance marks to single staves.

 
 @menu
 * Displaying staves::           
 
 @menu
 * Displaying staves::           

+* Modifying single staves::     

 * Writing parts::               
 @end menu
 
 * Writing parts::               
 @end menu
 


@@ -30,179 +27,631 @@ Two or more staves can be grouped vertically in a @code{GrandStaff}, a
 @node Displaying staves
 @subsection Displaying staves
 
 @node Displaying staves
 @subsection Displaying staves
 

+This section shows the different possibilities to create and group
+staves into groups, which can be marked in the beginning of each
+line with either a bracket or a brace.
+

 @menu
 @menu

-* System start delimiters::     
-* Staff symbol::                
-* Hiding staves::               
+* Instantiating new staves::
+* Grouping staves:: 
+* Deeper nested staff groups::  

 @end menu
 
 @end menu
 

-@node System start delimiters
-@subsubsection System start delimiters
+@node Instantiating new staves
+@unnumberedsubsubsec Instantiating new staves
+
+@cindex new staff
+@cindex staff initiation
+@cindex staff instantiation
+@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}:
+
+@lilypond[verbatim,quote,relative=2]
+\new Staff { c4 d e f }
+@end lilypond
+
+@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,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,quote,relative=2]
+\new GregorianTranscriptionStaff { c4 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,quote,relative=2]
+\new RhythmicStaff { c4 d e f }
+@end lilypond
+
+@item
+@code{TabStaff} creates by default a tablature with six strings in
+standard guitar tuning.  See @ref{Default tablatures}.
+
+@lilypond[verbatim,quote,relative=2]
+\new TabStaff { c4 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 in the score.  This is done with the commands
+@code{\startStaff} and @code{\stopStaff}.  How to use it is
+explained in @ref{Staff symbol}.
+
+
+@seealso
+
+Music Glossary:
+@rglos{staff},
+@rglos{staves}.
+
+Notation Reference:
+@ref{Creating contexts},
+@ref{Percussion staves}, 
+@ref{Default tablatures},
+@ref{Gregorian chant contexts},
+@ref{Mensural contexts},
+@ref{Staff symbol},
+@ref{Pre-defined contexts},
+@ref{Showing melody rhythms}.
+
+Snippets:
+@rlsr{Staff notation}.
+
+Internals Reference:
+@rinternals{Staff},
+@rinternals{DrumStaff},
+@rinternals{GregorianTranscriptionStaff},
+@rinternals{RhythmicStaff},
+@rinternals{TabStaff},
+@rinternals{MensuralStaff},
+@rinternals{VaticanaStaff},
+@rinternals{StaffSymbol}.
+
+
+@node Grouping staves
+@unnumberedsubsubsec Grouping staves

 
 @cindex start of system
 @cindex staff, multiple
 
 @cindex start of system
 @cindex staff, multiple

+@cindex staves, multiple
+@cindex system start delimiters

 @cindex bracket, vertical
 @cindex brace, vertical
 @cindex grand staff
 @cindex bracket, vertical
 @cindex brace, vertical
 @cindex grand staff

+@cindex piano staff

 @cindex staff group
 @cindex staff, choir
 @cindex staff group
 @cindex staff, choir

+@cindex choir staff

 @cindex system
 
 @cindex system
 

-Many scores consist of more than one staff.  These staves can be
-grouped in several different ways:
+LilyPond provides different types of contexts to group single
+staves together.  These contexts influence in the first place the
+appearance of the system start delimiter, but they have also
+influence on the behavior of the bar lines.

 
 @itemize
 @item
 
 @itemize
 @item

-In a @code{GrandStaff}, the group is started with a brace
-at the left, and bar lines are connected between the staves. 
+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.  The name of the beginning bar line
+grob is @code{SystemStartBar}.  

 
 

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

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

-  \new Staff { c c }

 >>
 @end lilypond
 
 @item
 >>
 @end lilypond
 
 @item

-In a @code{StaffGroup}, the bar lines will be drawn through
-all the staves, but the group is started with a bracket.
+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 <<
+@lilypond[verbatim,quote,relative=2]
+\new StaffGroup <<
+  \new Staff { c1 c }

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

-  \new Staff { c c }

 >>
 @end lilypond
 
 @item
 >>
 @end lilypond
 
 @item

-In a @code{ChoirStaff}, the group is started with a
-bracket, but bar lines are not connected. 
+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 <<
+@lilypond[verbatim,quote,relative=2]
+\new ChoirStaff <<
+  \new Staff { c1 c }

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

-  \new Staff { c c }

 >>
 @end lilypond
 
 @item
 >>
 @end lilypond
 
 @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.  
+In a @code{GrandStaff}, the group is started with a brace at the
+left, and bar lines are connected between the staves. 
+
+@lilypond[verbatim,quote,relative=2]
+\new GrandStaff <<
+  \new Staff { c1 c }
+  \new Staff { c1 c }
+>>
+@end lilypond
+
+@item
+The @code{PianoStaff} behaves almost as the @code{GrandStaff} but
+is 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]
-\relative <<
+@lilypond[verbatim,quote,relative=2]
+\new PianoStaff <<
+  \new Staff { c1 c }

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

-  \new Staff { c c }

 >>
 @end lilypond
 >>
 @end lilypond

+

 @end itemize
 
 @end itemize
 

-@cindex Mensurstriche layout
-@cindex Renaissance music
+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.

 
 

-In addition to these four staff group types, other groupings can
-be produced 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, with
-the command @code{\override Staff.BarLine #'transparent = ##t}
+According to classic engraver rules an orchestral score consists
+of 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{<< ... >>}.

 
 

-@cindex staff, nested
+Each instrument family is grouped inside of a @code{StaffGroup}
+with a starting bracket.  A group of same instruments or an
+instrument using more than one staff is grouped with braces in a
+@code{GrandStaff}.

 
 

-Staff groups can be nested, using the context
-@code{InnerStaffGroup} or @code{InnerChoirStaff}; see
-@c @lsr{staff,staff-brackets.ly}
-@c snippet 137
+As the context names tell, @code{PianoStaff} is used for notating
+piano music and @code{ChoirStaff} for all kind of vocal ensemble
+music.

 
 

-@commonprop

 
 

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

 
 

-@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 }
->>
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{use-square-bracket-at-the-start-of-a-staff-group.ly}
+
+@lilypondfile[verbatim,lilyquote,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,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}.
+
+Notation Reference:
+@ref{Instrument names}.
+
+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
+@unnumberedsubsubsec 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 @{
+\relative c' <<
+  \new StaffGroup %woodwinds
+  <<
+  \new Staff @{ c1 d @} %flute
+  \new InnerStaffGroup <<
+    \new Staff @{ c1 d @} %sax 
+    \new Staff @{ c1 d @} %oboe
+    \new Staff @{ c1 d @} %English horn
+    >>
+  \new Staff @{ \clef bass c,1 d @} %bassoon
+  >>
+  \new StaffGroup %the brass group
+  <<
+    \new Staff @{ c'1 d @} %trumpet
+    \new Staff @{ \clef bass c,1 d @} %trombone
+    \new GrandStaff %the horns need a GrandStaff (same instrument)
+    <<
+      \new Staff @{ c'1 d @}
+      \new Staff @{ \clef bass c,1 d @}
+    >>
+  >>
+  \new ChoirStaff %for setting vocal music
+  <<
+   \new Staff @{ c'1 d @}
+    \new InnerChoirStaff <<
+     \new Staff @{ c1 d @}
+     \new Staff @{ c1 d @}
+    >>
+   \new Staff @{ c1 d @}
+  >>
+  \new PianoStaff %for the piano
+  <<
+    \new Staff @{ c1 d @}
+    \new Staff @{ \clef bass c,1 d @}
+  >>
+>> @}
+@end example
+
+@c no verbatim so instrument names are only in the music
+@lilypond[quote]
+\score {
+\relative c' <<
+  \new StaffGroup %woodwinds
+  <<
+  \new Staff { \set Staff.instrumentName = "fl" c1 d } %flute
+  \new InnerStaffGroup <<
+    \new Staff { \set Staff.instrumentName = "sax" c1 d } %sax 1
+    \new Staff { \set Staff.instrumentName = "ob" c1 d } %sax 2
+    \new Staff { \set Staff.instrumentName = "ca" c1 d }
+    >>
+  \new Staff { \set Staff.instrumentName = "bs" \clef bass c,1 d } %bassoon
+  >>
+  \new StaffGroup %the brass group
+  <<
+    \new Staff { \set Staff.instrumentName = "tr" c'1 d } %trumpet
+    \new Staff { \set Staff.instrumentName = "tb" \clef bass c,1 d } %trombone
+    \new GrandStaff %the horns need a GrandStaff (same instrument)
+    <<
+      \new Staff { \set Staff.instrumentName = "cor1" c'1 d }
+      \new Staff { \set Staff.instrumentName = "cor2" \clef bass c,1 d }
+    >>
+  >>
+  \new ChoirStaff %for setting vocal music
+  <<
+   \new Staff { \set Staff.instrumentName = "S" c'1 d }
+    \new InnerChoirStaff <<
+     \new Staff { \set Staff.instrumentName = "A1" c1 d }
+     \new Staff { \set Staff.instrumentName = "A2" c1 d }
+    >>
+   \new Staff { \set Staff.instrumentName = "T" c1 d }
+  >>
+  \new PianoStaff %for the piano
+  <<
+    \new Staff { c1 d }
+    \new Staff { \clef bass c,1 d }
+  >>
+>> }

 @end lilypond
 
 @end lilypond
 

-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

 
 

-@c FIXME: Graham will deal with this.  -gp
-@c snippet 201
-To display a bracket even if there is only one staff, see
-@c @lsr{staff,display-bracket-with-only-one-staff-in-a system.ly}
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{nesting-staves.ly}
+

 
 @seealso
 
 
 @seealso
 

-Music Glossary: @rglos{brace}, @rglos{staff}, @rglos{staves}
-@rglos{bracket}.
+Snippets:
+@rlsr{Staff notation}.
+
+Notation Reference:
+@ref{Grouping staves},
+@ref{Instrument names}.
+
+Internals Reference:
+@rinternals{InnerChoirStaffGroup}, 
+@rinternals{InnerStaffGroup},
+@rinternals{SystemStartBar}, 
+@rinternals{SystemStartBrace},
+@rinternals{SystemStartBracket},
+@rinternals{systemStartDelimiterHierarchy}.
+

 
 

-Snippets: @lsrdir{Staff,Staff-notation}
+@node Modifying single staves
+@subsection Modifying single staves

 
 

-Internals Reference: @internalsref{ChoirStaff},
-@internalsref{GrandStaff}, @internalsref{StaffGroup},
-@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
-@internalsref{SystemStartBracket},
-@internalsref{systemStartDelimiterHierarchy}.
+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.

 
 

+@menu
+* Staff symbol::   
+* Ossia staves::             
+* Hiding staves::    
+@end menu

 
 @node Staff symbol
 
 @node Staff symbol

-@subsubsection Staff symbol
+@unnumberedsubsubsec Staff symbol

 
 @cindex adjusting staff symbol
 
 @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
 
 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}.
+@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}.
+
+@lilypond[verbatim,quote,relative=2]
+\new Staff {
+  \override Staff.StaffSymbol #'line-count = #3
+  d4 d d d
+}
+@end lilypond
+
+@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.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+@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.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'thickness = #3
+}
+{ d4 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,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
+}
+{ d4 d d d }
+@end lilypond
+
+@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.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'staff-space = #1.5
+}
+{ a4 b c d }
+@end lilypond
+
+@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.

 
 

-In addition, staves may be started and stopped at will.  This is
-done with @code{\startStaff} and @code{\stopStaff}.
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'width = #23
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+@end itemize

 
 

-@lilypond[verbatim,relative=2,fragment]
+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,quote,relative=2]

 b4 b
 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
+
+@funindex \startStaff
+@code{\startStaff},
+@funindex \stopStaff
+@code{\stopStaff}.

 
 

-@cindex staves, Frenched
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{making-some-staff-lines-thicker-than-the-others.ly}
+
+@seealso
+
+Music Glossary:
+@rglos{line},
+@rglos{ledger line},
+@rglos{staff}.
+
+Notation Reference:
+@ref{Displaying pitches}.
+
+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
+@unnumberedsubsubsec Ossia staves
+
+@cindex staff, Frenched

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

+@cindex staff, resizing of
+@cindex resizing of staves
+
+Tweaking the staff object allows to resize the staff:
+
+@lilypond[verbatim,quote]
+\new Staff \with {
+  fontSize = #-3
+  \override StaffSymbol #'staff-space = #(magstep -3)
+  \override StaffSymbol #'thickness = #(magstep -3)
+}
+\relative c {
+  \clef bass
+  c8 c c c  c c c c
+}
+@end lilypond

 
 

-In combination with Frenched staves, this may be used to typeset
-@emph{ossia} sections.  An example is shown here
+@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}.

 
 

-@lilypond[verbatim,relative=2,quote]
+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'' {


@@ -219,71 +668,74 @@ 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[verbatim,lilyquote,texidoc,doctitle]
+@c {making-some-staff-lines-thicker-than-the-others.ly}
+@c snippet 277
+

 
 @seealso
 
 
 @seealso
 

-Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
+Music Glossary:
+@rglos{ossia},
+@rglos{staff},
+@rglos{Frenched staff}.
+
+Notation Reference:
+@ref{Setting the staff size}.

 
 

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

 
 

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

 
 
 @node Hiding staves
 
 
 @node Hiding staves

-@subsubsection Hiding staves
+@unnumberedsubsubsec Hiding staves

 
 @cindex Frenched scores
 
 @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]
+@lilypond[verbatim,quote]

 \layout {
 \layout {

-  \context { \RemoveEmptyStaffContext }
+  \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
 @code{\RemoveEmptyRhythmicStaffContext}.
 To remove other types of contexts, use
 @code{\AncientRemoveEmptyStaffContext} or
 @code{\RemoveEmptyRhythmicStaffContext}.


@@ -292,16 +744,15 @@ 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.
 

-
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]

 \score {
 \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


@@ -311,15 +762,74 @@ 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[verbatim,quote]
+\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
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{removing-the-first-empty-line.ly}
+
+
+@predefined
+
+@funindex \RemoveEmptyStaffContext
+@code{\RemoveEmptyStaffContext},
+@funindex \AncientRemoveEmptyStaffContext
+@code{\AncientRemoveEmptyStaffContext},
+@funindex \RemoveEmptyRhythmicStaffContext
+@code{\RemoveEmptyRhythmicStaffContext}.
+
+

 @seealso
 
 @seealso
 

-Notation Reference: @ref{Staff symbol}.
+Notation Reference:
+@ref{Staff symbol},
+@ref{Ossia staves}.
+
+Snippets:
+@rlsr{Staff notation}.

 
 

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

 
 

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

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


@@ -331,8 +841,9 @@ Internals Reference: @internalsref{ChordNames},
 * Formatting cue notes::        
 @end menu
 
 * Formatting cue notes::        
 @end menu
 

+

 @node Metronome marks
 @node Metronome marks

-@subsubsection Metronome marks
+@unnumberedsubsubsec Metronome marks

 
 @cindex Tempo
 @cindex beats per minute
 
 @cindex Tempo
 @cindex beats per minute


@@ -349,19 +860,20 @@ the layout output, a metronome marking is printed
 
 @funindex \tempo
 
 
 @funindex \tempo
 

-@lilypond[quote,ragged-right,verbatim,fragment]
-\tempo 8.=120 c''1
+@lilypond[verbatim,quote,relative=2]
+\tempo 8. = 120
+c1

 @end lilypond
 
 
 @end lilypond
 
 

-@commonprop
+@snippets

 
 To change the tempo in the MIDI output without printing anything,
 make the metronome marking invisible @example \once \override
 Score.MetronomeMark #'transparent = ##t @end example
 
 To print other metronome markings, use these markup commands
 
 To change the tempo in the MIDI output without printing anything,
 make the metronome marking invisible @example \once \override
 Score.MetronomeMark #'transparent = ##t @end example
 
 To print other metronome markings, use these markup commands

-@lilypond[quote,ragged-right,verbatim,relative,fragment]
+@lilypond[verbatim,quote,relative=1]

 c4^\markup {
   (
   \smaller \general-align #Y #DOWN \note #"16." #1
 c4^\markup {
   (
   \smaller \general-align #Y #DOWN \note #"16." #1


@@ -371,23 +883,29 @@ c4^\markup {
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

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

 
 
 @seealso
 
 
 
 @seealso
 

-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
-output}.
+Internals Reference:
+@rinternals{MetronomeMark},
+@ref{MIDI output}.

 
 
 
 

-@refbugs
+@knownissues

 
 Collisions are not checked.  If you have notes above the top line
 of the staff (or notes with articulations, slurs, text, etc), then
 
 Collisions are not checked.  If you have notes above the top line
 of the staff (or notes with articulations, slurs, text, etc), then


@@ -403,7 +921,7 @@ place it further away from the staff.
 
 
 @node Instrument names
 
 
 @node Instrument names

-@subsubsection Instrument names
+@unnumberedsubsubsec Instrument names

 
 @cindex instrument names
 @cindex instrument names, short
 
 @cindex instrument names
 @cindex instrument names, short


@@ -411,75 +929,61 @@ place it further away from the staff.
 In an orchestral score, instrument names are printed at the left
 side of the staves.
 
 In an orchestral score, instrument names are printed at the left
 side of the staves.
 

-This can be achieved by setting @code{Staff}.@code{instrumentName} and
-@code{Staff}.@code{shortInstrumentName}, or
+This can be achieved by setting @code{Staff}.@code{instrumentName}
+and @code{Staff}.@code{shortInstrumentName}, or

 @code{PianoStaff}.@code{instrumentName} and
 @code{PianoStaff}.@code{instrumentName} and

-@code{PianoStaff}.@code{shortInstrumentName}.  This will print text
-before the start of the staff.  For the first staff,
-@code{instrumentName} is used.  If set, @code{shortInstrumentName} is
-used for the following staves.
+@code{PianoStaff}.@code{shortInstrumentName}.  This will print
+text before the start of the staff.  For the first staff,
+@code{instrumentName} is used.  If set, @code{shortInstrumentName}
+is used for the following staves.

 
 

-@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
+@lilypond[verbatim,quote,relative=1]

 \set Staff.instrumentName = "Ploink "
 \set Staff.shortInstrumentName = "Plk "
 c1
 \break
 \set Staff.instrumentName = "Ploink "
 \set Staff.shortInstrumentName = "Plk "
 c1
 \break

-c''
+c''1

 @end lilypond
 
 You can also use markup texts to construct more complicated
 instrument names, for example
 
 @end lilypond
 
 You can also use markup texts to construct more complicated
 instrument names, for example
 

-@lilypond[quote,fragment,verbatim,ragged-right]
+@lilypond[verbatim,quote,relative=2]

 \set Staff.instrumentName = \markup {
   \column { "Clarinetti"
             \line { "in B" \smaller \flat } } }
 \set Staff.instrumentName = \markup {
   \column { "Clarinetti"
             \line { "in B" \smaller \flat } } }

-c''1
+c1

 @end lilypond
 
 @cindex instrument names, centering
 
 @end lilypond
 
 @cindex instrument names, centering
 

-If you wish to center the instrument names, you must center all of
-them individually:
-
-@lilypond[quote,verbatim,ragged-right]
-{ <<
-\new Staff {
-  \set Staff.instrumentName = \markup {
-    \center-align { "Clarinetti"
-      \line { "in B" \smaller \flat } } }
-  c''1
-}
-\new Staff {
-  \set Staff.instrumentName =
-       \markup{ \center-align { Vibraphone }}
-  c''1
-}
->>
-}
-@end lilypond
+As instrument names are centered by default, multi line names are
+better entered using @code{\center-align}:

 
 

-For longer instrument names, it may be useful to increase the
-@code{indent} setting in the @code{\layout} block.
-
-To center instrument names while leaving extra space to the right,
-
-@lilypond[quote,verbatim,ragged-right]
-\new StaffGroup \relative
+@lilypond[verbatim,quote,relative=2]

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

-    \set Staff.instrumentName =
-        \markup { \hcenter-in #10 "blabla" }
-    c1 c1
+    \set Staff.instrumentName = \markup \center-align {
+      Clarinetti
+      \line { "in B" \smaller \flat }
+    }
+    c1

   }
   \new Staff {
   }
   \new Staff {

-    \set Staff.instrumentName =
-         \markup { \hcenter-in #10 "blo" }
-    c1 c1
+    \set Staff.instrumentName = "Vibraphone"
+    c1

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

+For longer instrument names, it may be useful to increase the
+@code{indent} setting in the @code{\layout} block.
+
+Short instrument names, printed before the systems following the
+first one, are also centered by default, in a space which width is
+given by the @code{short-indent} variable of the @code{\layout}
+block.
+

 To add instrument names to other contexts (such as
 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
 engraver must be added to that context.
 To add instrument names to other contexts (such as
 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
 engraver must be added to that context.


@@ -498,7 +1002,7 @@ in @ref{Modifying context plug-ins}.
 
 Instrument names may be changed in the middle of a piece,
 
 
 Instrument names may be changed in the middle of a piece,
 

-@lilypond[quote,fragment,verbatim,ragged-right]
+@lilypond[verbatim,quote,relative=1]

 \set Staff.instrumentName = "First"
 \set Staff.shortInstrumentName = "one"
 c1 c c c \break
 \set Staff.instrumentName = "First"
 \set Staff.shortInstrumentName = "one"
 c1 c c c \break


@@ -512,16 +1016,20 @@ c1 c c c \break
 
 @seealso
 
 
 @seealso
 

-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

-@subsubsection Quoting other voices
+@unnumberedsubsubsec Quoting other voices

 
 @cindex cues
 @cindex quoting other voices
 
 @cindex cues
 @cindex quoting other voices


@@ -537,7 +1045,6 @@ command.
 \addQuote @var{name} @var{music}
 @end example
 
 \addQuote @var{name} @var{music}
 @end example
 

-

 @noindent
 Here, @var{name} is an identifying string.  The @var{music} is any
 kind of music.  Here is an example of @code{\addQuote}
 @noindent
 Here, @var{name} is an identifying string.  The @var{music} is any
 kind of music.  Here is an example of @code{\addQuote}


@@ -559,7 +1066,6 @@ clarinet = \relative c' @{
 \addQuote clarinet @{ \clarinet @}
 @end example
 
 \addQuote clarinet @{ \clarinet @}
 @end example
 

-

 After calling @code{\addQuote}, the quotation may then be done
 with @code{\quoteDuring} or @code{\cueDuring},
 
 After calling @code{\addQuote}, the quotation may then be done
 with @code{\quoteDuring} or @code{\cueDuring},
 


@@ -591,14 +1097,15 @@ Quotations take into account the transposition of both source and
 target instruments, if they are specified using the
 @code{\transposition} command.
 
 target instruments, if they are specified using the
 @code{\transposition} command.
 

-@lilypond[quote,ragged-right,verbatim]
-\addQuote clarinet \relative c' {
+@lilypond[verbatim,quote,relative=1]
+\addQuote clarinet
+{

   \transposition bes
   f4 fis g gis
 }
 
 {
   \transposition bes
   f4 fis g gis
 }
 
 {

-  e'8 f'8 \quoteDuring #"clarinet" { s2 }
+  e8 f8 \quoteDuring #"clarinet" { s2 }

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -617,7 +1124,21 @@ notes and rests of the quoted voice end up in the
 will quote notes (but no rests), together with scripts and
 dynamics.
 
 will quote notes (but no rests), together with scripts and
 dynamics.
 

-@refbugs
+
+@seealso
+
+Notation Reference:
+@ref{Instrument transpositions}.
+
+Snippets:
+@rlsr{Staff notation}.
+
+Internals Reference:
+@rinternals{QuoteMusic},
+@rinternals{Voice}.
+
+
+@knownissues

 
 Only the contents of the first @code{Voice} occurring in an
 @code{\addQuote} command will be considered for quotation, so
 
 Only the contents of the first @code{Voice} occurring in an
 @code{\addQuote} command will be considered for quotation, so


@@ -632,17 +1153,9 @@ Quoting nested triplets may result in poor notation.
 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
 written entirely in lower-case letters: @code{\addquote}.
 
 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
 written entirely in lower-case letters: @code{\addquote}.
 

-@seealso
-
-Notation Reference: @ref{Instrument transpositions}.
-
-Snippets: @lsrdir{Staff,Staff-notation}
-
-Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
-

 
 @node Formatting cue notes
 
 @node Formatting cue notes

-@subsubsection Formatting cue notes
+@unnumberedsubsubsec Formatting cue notes

 
 @cindex cues
 @cindex cue notes
 
 @cindex cues
 @cindex cue notes


@@ -662,14 +1175,13 @@ The syntax is
 @end example
 
 This will insert notes from the part @var{name} into a
 @end example
 
 This will insert notes from the part @var{name} into a

-@code{Voice} called @code{cue}.  This happens
-simultaneously with @var{music}, which usually is a rest.  When
-the cue notes start, the staff in effect becomes polyphonic for a
-moment.  The argument @var{updown} determines whether the cue
-notes should be notated as a first or second voice.
-
+@code{Voice} called @code{cue}.  This happens simultaneously with
+@var{music}, which usually is a rest.  When the cue notes start,
+the staff in effect becomes polyphonic for a moment.  The argument
+@var{updown} determines whether the cue notes should be notated as
+a first or second voice.

 
 

-@lilypond[verbatim,ragged-right]
+@lilypond[verbatim]

 smaller = {
   \set fontSize = #-2
   \override Stem #'length-fraction = #0.8
 smaller = {
   \set fontSize = #-2
   \override Stem #'length-fraction = #0.8


@@ -677,12 +1189,13 @@ smaller = {
   \override Beam #'length-fraction = #0.8
 }
 
   \override Beam #'length-fraction = #0.8
 }
 

-\addQuote clarinet \relative {
+\addQuote clarinet
+\relative c' {

   R1*20
   r2 r8 c' f f
 }
 
   R1*20
   r2 r8 c' f f
 }
 

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

 
   % setup a context for cue notes.
   \new Voice = "cue" { \smaller \skip 1*21 }
 
   % setup a context for cue notes.
   \new Voice = "cue" { \smaller \skip 1*21 }


@@ -699,7 +1212,6 @@ smaller = {
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-

 Here are a couple of hints for successful cue notes:
 
 @itemize
 Here are a couple of hints for successful cue notes:
 
 @itemize


@@ -725,7 +1237,7 @@ instruments which use a completely different octave range (for
 example, having a cue of a piccolo flute within a contra bassoon
 part).
 
 example, having a cue of a piccolo flute within a contra bassoon
 part).
 

-@lilypond[verbatim,ragged-right,quote]
+@lilypond[verbatim,quote]

 picc = \relative c''' {
   \clef "treble^8"
   R1 |
 picc = \relative c''' {
   \clef "treble^8"
   R1 |


@@ -742,15 +1254,17 @@ cbsn = \relative c, {
 }
 
 <<
 }
 
 <<

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

 >>
 @end lilypond
 
 >>
 @end lilypond
 

-@seealso

 
 

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

 
 

-Internals Reference: @internalsref{Voice}.
+Snippets:
+@rlsr{Staff notation}.

 
 

+Internals Reference:
+@rinternals{Voice}.