X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fstaff.itely;h=c306d65f0743ba403e650dc2308a6ddf52d5d78f;hb=5a462e8c890f6ea8c7e027fa899f583c34b76d61;hp=ee40671d525a568bc6dc16f2b91ab96c459b91b8;hpb=b80fd169a769326b32b3b1fb42467a84c9a19189;p=lilypond.git

diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely
index ee40671d52..c306d65f07 100644
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -9,20 +9,16 @@
 @node Staff notation
 @section Staff notation
 
-@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-{staff-headword.ly}
+@lilypondfile[quote]{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}.
 
+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::           
+* Modifying single staves::     
 * Writing parts::               
 @end menu
 
@@ -30,129 +26,286 @@ Two or more staves can be grouped vertically in a @code{GrandStaff}, a
 @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
-* System start delimiters::     
-* Staff symbol::                
-* Hiding staves::               
+* Instantiating new staves::
+* Grouping staves:: 
+* Deeper nested staff groups::  
 @end menu
 
-@node System start delimiters
-@subsubsection System start delimiters
+@node Instantiating new staves
+@subsubsection 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 transciption staff
+@cindex rhythmic staff
+@cindex tabstaff
+@cindex tablature
+
+The lines of a staff (pl. staves) are produced by the @code{staff symbol} 
+layout object.  Staves 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,ragged-right,quote]
+\relative c'' {
+  \new Staff { c 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,ragged-right,quote]
+\new DrumStaff { 
+  \drummode { cymc hh ss tomh }
+}
+@end lilypond
+
+@item
+@code{GregorianTranscriptionStaff} sets up a staff to notate modern
+Gregorian chant. It does not show bar lines.
+@lilypond[verbatim,ragged-right,quote]
+\relative c'' {
+  \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]
+\relative c'' {
+  \new RhythmicStaff { c d e f }
+}
+@end lilypond
+
+@item
+@code{TabStaff} creates by default a tabulature with six strings in 
+standard guitar tuning. See @ref{Tablatures basic}.
+@lilypond[verbatim,ragged-right,quote]
+\relative c'' {
+  \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
+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{Percussion staves}, 
+@ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
+@ref{Mensural contexts}.
+
+Snippets: @lsrdir{Staff,Staff-notation}.
+
+Internals Reference: @internalsref{Staff}, @internalsref{DrumStaff},
+@internalsref{GregorianTranscriptionStaff}, @internalsref{RhythmicStaff},
+@internalsref{TabStaff}, @internalsref{MensuralStaff},
+@internalsref{VaticanaStaff}.
+
+
+
+@node Grouping staves
+@subsubsection Grouping staves
 
 @cindex start of system
 @cindex staff, multiple
+@cindex staves, multiple
+@cindex system start delimiters
 @cindex bracket, vertical
 @cindex brace, vertical
 @cindex grand staff
+@cindex piano staff
 @cindex staff group
 @cindex staff, choir
+@cindex choir staff
 @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
+behaviour of the bar lines.
+
+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. The usage of this last delimiter is shown in the
+snippet section in @ref{Deeper nested staff groups}.
+
 
 @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.  
 
 @lilypond[verbatim,ragged-right,quote]
-\new GrandStaff
-\relative <<
+\relative 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, but the group is started with a bracket.
+all the staves, and the group is started with a bracket.
 
 @lilypond[verbatim,ragged-right,quote]
-\new StaffGroup
-\relative <<
-  \new Staff { c1 c }
-  \new Staff { c c }
->>
+\new StaffGroup {
+  \relative c'' <<
+    \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. 
+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 <<
-  \new Staff { c1 c }
-  \new Staff { c c }
->>
+\new ChoirStaff {
+  \relative c'' <<
+    \new Staff { c1 c }
+    \new Staff { c c }
+  >>
+}
 @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,ragged-right,quote]
-\relative <<
-  \new Staff { c1 c }
-  \new Staff { c c }
->>
+\new GrandStaff {
+  \relative c'' <<
+    \new Staff { c1 c }
+    \new Staff { c c }
+  >>
+}
 @end lilypond
-@end itemize
 
-@cindex Mensurstriche layout
-@cindex Renaissance music
+@item
+The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is
+optimized for setting piano music.
 
-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}
+@lilypond[verbatim,ragged-right,quote]
+\new PianoStaff {
+  \relative c'' <<
+    \new Staff { c1 c }
+    \new Staff { c c }
+  >>
+}
+@end lilypond
 
-@cindex staff, nested
+@end itemize
 
-Staff groups can be nested, using the context
-@code{InnerStaffGroup} or @code{InnerChoirStaff}; see
-@c @lsr{staff,staff-brackets.ly}
-@c snippet 137
+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{<< ... >>}.
 
-@commonprop
+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}.
 
-More complex nesting can be accomplished using the property
-@code{systemStartDelimiterHierarchy}: 
+As the context names tell, @code{PianoStaff} is used for notating
+piano music and @code{ChoirStaff} for all kind of vocal ensemble music.
 
-@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
 
-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
+@snippets
 
 @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}
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@c {staff,display-bracket-with-only-one-staff-in-a system.ly}
+@lilypond[verbatim,ragged-right,quote]
+\score {
+  \new StaffGroup << 
+    % Must be one lower than your actual amount off staff lines
+    \override StaffGroup.SystemStartBracket #'collapse-height = #4 
+    \new Staff { 
+      c'4 d' e' f' 
+    }
+  >> 
+  } 
+  {
+  \new PianoStaff << 
+    \override PianoStaff.SystemStartBrace #'collapse-height = #4 
+    \new Staff { 
+      c'4 d' e' f' 
+    }
+  >> 
+  } 
+@end lilypond
+
+
+@cindex mensurstriche layout
+@cindex renaissance music
+@cindex transcription of mensural music
+@cindex mensural music, transcription of
+
+
+@c FIXME: not yet in master
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@c {mensurstriche-layout.ly}
+
+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:
+
+@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
+
 
 @seealso
 
-Music Glossary: @rglos{brace}, @rglos{staff}, @rglos{staves}
+Music Glossary: @rglos{brace}, 
 @rglos{bracket}.
 
 Snippets: @lsrdir{Staff,Staff-notation}
@@ -160,14 +313,146 @@ Snippets: @lsrdir{Staff,Staff-notation}
 Internals Reference: @internalsref{ChoirStaff},
 @internalsref{GrandStaff}, @internalsref{StaffGroup},
 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
-@internalsref{SystemStartBracket},
+@internalsref{SystemStartBracket}.
+
+
+
+@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 omited from the
+source code, see @ref{Instrument names} how to set them.
+
+
+@cindex staff, nested
+@cindex staves, nested
+@cindex nesting of staves
+
+
+@example
+\score @{ <<
+  \new StaffGroup %woodwinds
+  <<
+  \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 Staff @{ c' d' @} %trumpet
+    \new Staff @{ \clef bass c d @} %trombone
+    \new GrandStaff %the horns need a GrandStaff (same instrument)
+    <<
+      \new Staff @{ c' d' @}
+      \new Staff @{ \clef bass c d @}
+    >>
+  >>
+  \new ChoirStaff %for setting vocal music
+  <<
+   \new Staff @{ c' d' @}
+    \new InnerChoirStaff <<
+     \new Staff @{ c' d' @}
+     \new Staff @{ c' d' @}
+    >>
+   \new Staff @{ c' d' @}
+  >>
+  \new PianoStaff %for the piano
+  <<
+    \new Staff @{ c' d' @}
+    \new Staff @{\clef bass c d @}
+  >>
+>> @}
+@end example
+
+@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 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 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 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 PianoStaff %for the piano
+  <<
+    \new Staff { c' d' }
+    \new Staff {\clef bass c d }
+  >>
+>> }
+@end lilypond
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{nesting-staves.ly}
+
+
+@seealso
+
+Internals Reference: @internalsref{SystemStartBar}, 
+@internalsref{SystemStartBrace}, @internalsref{SystemStartBracket},
 @internalsref{systemStartDelimiterHierarchy}.
 
 
+
+@node Modifying single staves
+@subsection Modifying single staves
+
+@menu
+* Staff symbol::   
+* Ossia staves::             
+* Hiding staves::    
+@end menu
+
 @node Staff symbol
 @subsubsection Staff symbol
 
 @cindex adjusting staff symbol
+@cindex drawing staff symbol
+@cindex stop staff lines
+@cindex start staff lines
+@cindex staff lines, amount of
+@cindex staff line, thickness of
+@cindex amount of staff lines
+@cindex thickness 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 the number,
@@ -189,6 +474,9 @@ b b
 b b
 @end lilypond
 
+@node Ossia staves
+@subsubsection Ossia staves
+
 @cindex staves, Frenched
 @cindex ossia
 @cindex Frenched staves
@@ -233,6 +521,11 @@ In combination with Frenched staves, this may be used to typeset
 @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}.
@@ -354,7 +647,7 @@ the layout output, a metronome marking is printed
 @end lilypond
 
 
-@commonprop
+@snippets
 
 To change the tempo in the MIDI output without printing anything,
 make the metronome marking invisible @example \once \override
@@ -387,7 +680,7 @@ Internals Reference: @internalsref{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
@@ -603,7 +896,7 @@ notes and rests of the quoted voice end up in the
 will quote notes (but no rests), together with scripts and
 dynamics.
 
-@refbugs
+@knownissues
 
 Only the contents of the first @code{Voice} occurring in an
 @code{\addQuote} command will be considered for quotation, so