Update from Till.

1 files changed, 154 insertions, 125 deletions

diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely
index c6f8411095..dba6f138fa 100644
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -18,8 +18,8 @@ print scores with more than one staff, and
 how to apply specific performance marks to single staves.
 
 @menu
-* Displaying staves::  
-* Modifying single staves::         
+* Displaying staves::           
+* Modifying single staves::     
 * Writing parts::               
 @end menu
 
@@ -31,12 +31,9 @@ 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
-* Initiating new staves::
-* Grouping staves::     
-* Deeper nested staff groups::  
+* Initiating new staves::       
+* Grouping staves::             
 @end menu
 
 @node Initiating new staves
@@ -46,7 +43,8 @@ line with either a bracket or a brace.
 @cindex staff initiation
 @cindex staff, new
 
-The lines of a staff are produced by a @code{staff symbol} layout object.
+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
@@ -66,18 +64,21 @@ in the score. This is done with the commands @code{\startStaff} and
 Besides the default @code{Staff} context there are also
 specialized staff contexts for setting percussion, Guitar music,
 and ancient music.
-@c No need to mention all the other contexts?
 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}
+Music Glossary: @rglos{staff}, @rglos{staves}.
 
-Snippets: @lsrdir{Staff,Staff-notation}
+Notation Reference: @ref{Printing chord names}, @ref{Percussion staves}, 
+@ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
+@ref{Mensural contexts}.
 
-Internals Reference: @internalsref{Staff}
+Snippets: @lsrdir{Staff,Staff-notation}.
+
+Internals Reference: @internalsref{Staff}.
 
 
 
@@ -109,59 +110,62 @@ 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,relative=2]
-  <<
-    \new Staff { c1 c }
-    \new Staff { c c }
-  >>
+@lilypond[verbatim,ragged-right,quote]
+\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, and the group is started with a bracket.
 
-@lilypond[verbatim,ragged-right,quote,relative=2]
-  \new StaffGroup
-  <<
+@lilypond[verbatim,ragged-right,quote]
+\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. 
 
-@lilypond[verbatim,ragged-right,quote,relative=2]
-  \new ChoirStaff
-  <<
+@lilypond[verbatim,ragged-right,quote]
+\new ChoirStaff {
+  \relative c'' <<
     \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. 
 
-@lilypond[verbatim,ragged-right,quote,relative=2]
-  \new GrandStaff
-  <<
+@lilypond[verbatim,ragged-right,quote]
+\new GrandStaff {
+  \relative c'' <<
     \new Staff { c1 c }
     \new Staff { c c }
   >>
+}
 @end lilypond
 
 @item
 The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is
 optimized for setting piano music.
 
-@lilypond[verbatim,ragged-right,quote,relative=2]
-  \new PianoStaff
-  <<
-    \new Staff { c1 c }
-    \new Staff { c c }
-  >>
+@lilypond[verbatim,ragged-right,quote]
+\new PianoStaff
+\relative c'' <<
+  \new Staff { c1 c }
+  \new Staff { c c }
+>> }
 @end lilypond
 
 @end itemize
@@ -175,116 +179,102 @@ 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}.
 
-Piano music is notated with the @code{PianoStaff} context, that produces
-a starting brace and conntects the bar lines between the systems.
-
-Choral music (vocal music for more than one voice) is notated using the
-@code{ChoirStaff} context that produces a starting bracket but does not
-connect the bar lines between the staves so the lyrics will not collide 
-with bar lines.
+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,relative=2]
-  \score{
+@lilypond[verbatim,ragged-right,quote]
+\score{ \relative c' {
+<<
+  \new StaffGroup %the woodwinds group
   <<
-    \new StaffGroup %the woodwinds group
-    <<
-      \new Staff { c1 c }
-      \new Staff { c c }
-      \new Staff { c c }
-    >>
-    \new StaffGroup %the brass group
-    <<
-      \new Staff { c c }
-      \new Staff { c c }
-      \new GrandStaff %the horns need two staves
-      <<
-        \new Staff { c c }
-        \new Staff {\clef bass c c }
-      >>
-    >>
-    \new ChoirStaff
-    <<
-      \new Staff { c c }
-      \new Staff {\clef alto c c }
-      \new Staff {\clef bass c c }
-    >>
-    \new PianoStaff %for the piano
+    \new Staff { c1 c }
+    \new Staff { c c }
+    \new Staff { c c }
+  >>
+  \new StaffGroup %the brass group
+  <<
+    \new Staff { c c }
+    \new Staff { c c }
+    \new GrandStaff %the horns need a GrandStaff (same instrument)
     <<
       \new Staff { c c }
       \new Staff {\clef bass c c }
     >>
   >>
-  }
-@end lilypond
-
-@cindex mensurstriche layout
-@cindex renaissance music
-@cindex transcription of mensural music
-@cindex mensural music, transcription of
-
-Other groupings may be achieved by changin 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,relative=2]
-  global = {\override Staff.BarLine #'transparent = ##t
-            s1 s
-            %the final bar line is not interupted
-            \once \override Staff.BarLine #'transparent = ##f
-            \bar "|."}
-  \new StaffGroup
+  \new ChoirStaff %for a vocal part
   <<
-    \new Staff {<< \global { c1 c } >>}
-    \new Staff {<< \global { c c } >>}
+    \new Staff { c c }
+    \new Staff {\clef alto c c }
+    \new Staff {\clef bass c c }
   >>
+  \new PianoStaff %for the piano
+  <<
+    \new Staff { c c }
+    \new Staff {\clef bass c c }
+  >>
+>>
+} }
 @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}.
 
-@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}
-
-@seealso
-
-Music Glossary: @rglos{brace}, 
-@rglos{bracket}.
-
-Snippets: @lsrdir{Staff,Staff-notation}
-
-Internals Reference: @internalsref{ChoirStaff},
-@internalsref{GrandStaff}, @internalsref{StaffGroup},
-@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
-@internalsref{SystemStartBracket}.
-
+@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}. 
 
-@node Deeper nested staff groups
-@subsubsection Deeper nested staff groups
+Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
+grouping contexts. They can both be inside an inner staff context, though.
 
-The last section explained the grouping of staves and also the nesting
-of different types of staves together. So the @q{Horn section} in our
-example above is contained both in a @code{StaffGroup} and a 
-@code{GrandStaff}.
+@c snippet staff-brackets.ly
+@lilypond[verbatim,ragged-right,quote]
+\score { 
+<<
+  \new StaffGroup << 
+  \new Staff {c' d' e' f'}
+  \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 ChoirStaff <<
+   \new Staff {c' d' e' f'}
+    \new InnerStaffGroup <<
+     \new Staff {c' d' e' f'}
+    >>
+   \new Staff {c' d' e' f'}
+  >>
+  >>
+  \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'}
+  >>
+>> }
+@end lilypond
 
-Here about innerChoirStaff and innerStaffGroup
 
-@cindex staff, nested
+@snippets
 
-Staff groups can be nested, using the context
-@code{InnerStaffGroup} or @code{InnerChoirStaff}; see
-@c @lsr{staff,staff-brackets.ly}
-@c snippet 137
+@c FIXME: not yet in master
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@c {nesting-staves.ly}
 
-@snippets
 
 More complex nesting can be accomplished using the property
 @code{systemStartDelimiterHierarchy}: 
@@ -312,17 +302,56 @@ instantiated manually
 
 
 
-Internals Reference: @internalsref{SystemStartBar}, 
-@internalsref{SystemStartBrace}, @internalsref{SystemStartBracket},
-@internalsref{systemStartDelimiterHierarchy}.
+@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
 
 
 
+@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}
 
+@seealso
 
+Music Glossary: @rglos{brace}, 
+@rglos{bracket}.
+
+Snippets: @lsrdir{Staff,Staff-notation}
+
+Internals Reference: @internalsref{ChoirStaff},
+@internalsref{GrandStaff}, @internalsref{PianoStaff}, 
+@internalsref{StaffGroup},
+@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
+@internalsref{SystemStartBracket}, @internalsref{SystemStartSquare}.
 
 
 
@@ -330,9 +359,9 @@ Internals Reference: @internalsref{SystemStartBar},
 @subsection Modifying single staves
 
 @menu
-* Staff symbol::   
-* Ossia staves::             
-* Hiding staves::    
+* Staff symbol::                
+* Ossia staves::                
+* Hiding staves::               
 @end menu
 
 @node Staff symbol