Docs: LM: add "extra staff" common error

diff --git a/Documentation/learning/working.itely b/Documentation/learning/working.itely
index 855c52c460504b2b10b65bc29e4e07abfe421d6d..892734e2b03ae9a5dcb6d023a97c1335d526cafc 100644 (file)
--- a/Documentation/learning/working.itely
+++ b/Documentation/learning/working.itely
@@ -621,6 +621,7 @@ are easily handled.
 
 @menu
 * Music runs off the page::
+* An extra staff appears::
 * Apparent error in ../ly/init.ly::
 * Error message Unbound variable %::
 @end menu
@@ -650,6 +651,60 @@ If you actually intend to have a series of such carry-over measures
 you will need to insert an invisible bar line where you want the
 line to break.  For details, see @ruser{Bar lines}.
 
+
+@node An extra staff appears
+@unnumberedsubsubsec An extra staff appears
+
+If contexts are not created explicitly with @code{\new} they will be
+silently created as soon as a command is encountered which cannot
+be applied to an existing context.  In simple scores the automatic
+creation of contexts is useful, and most of the examples in the
+LilyPond manuals take advantage of this simplification.  But
+occasionally the silent creation of contexts can give rise to
+unexpected new staves or scores.  For example, it might be expected
+that the following code would cause all note heads within the
+following staff to be colored red, but in fact it results in two
+staves with the note heads remaining the default black in the lower
+staff.
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.NoteHead #'color = #red
+\new Staff { a }
+@end lilypond
+
+This is because a @code{Staff} context does not exist when the
+override is processed, so one is implicitly created and the override
+is applied to it, but then the @code{\new Staff} command creates
+another, separate, staff into which the notes are placed.  The
+correct code to color all note heads red is
+
+@lilypond[quote,verbatim,relative=2]
+\new Staff {
+  \override Staff.NoteHead #'color = #red
+  a
+}
+@end lilypond
+
+As a second example, if a @code{\relative} command is placed inside
+a @code{\repeat} command two staves result, the second offset from
+the first, because the @code{\repeat} command generates two
+@code{\relative} blocks, which each implicitly create @code{Staff}
+and @code{Voice} blocks.
+
+@lilypond[quote,verbatim]
+\repeat unfold 2 \relative { c d e f }
+@end lilypond
+
+The correct way is to reverse the @code{\repeat} and
+@code{\relative} commands, like this:
+
+@lilypond[quote,verbatim]
+\relative {
+  \repeat unfold 2 { c d e f }
+}
+@end lilypond
+
+
 @node Apparent error in ../ly/init.ly
 @unnumberedsubsubsec Apparent error in @code{../ly/init.ly}
 

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 17b30b69e3f3f577709dcd0807c65a49f35af013..6527f6cb6d396afb39de7617cb72144622ec61b9 100644 (file)
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -2014,11 +2014,12 @@ Note that a context will be silently created implicitly if a command
 is encountered when there is no suitable context available to
 contain it.  This can give rise to unexpected new staves or scores.
 
-@c TODO add example of this
-
 The default order in which contexts are laid out and the
 @qq{accepts} list can be changed, see @ref{Aligning contexts}.
 
+@seealso
+Learning Manual:
+@rlearning{An extra staff appears}.
 
 @node Distances and measurements
 @subsection Distances and measurements