Doc: Clarify \relative inside \repeat issue.

diff --git a/Documentation/notation/repeats.itely b/Documentation/notation/repeats.itely
index 9e2b53e61db8021610ecbd34622870bee06c9035..113b6810a2735d4a35b4445e627c30b454b64002 100644 (file)
--- a/Documentation/notation/repeats.itely
+++ b/Documentation/notation/repeats.itely
@@ -109,9 +109,10 @@ Normal repeats with alternate endings:
 c1
 @end lilypond
 
-@warning{Do not include @code{@bs{}relative} inside a
-@code{@bs{}repeat}.  It will cause unwanted staves to appear.
-See @rprogram{An extra staff appears}.}
+@warning{If you include @code{@bs{}relative} inside a
+@code{@bs{}repeat} without explicitly instantiating the
+@code{Voice} context, extra (unwanted) staves will appear.  See
+@rprogram{An extra staff appears}.}
 
 @cindex repeat with upbeat
 @cindex upbeat in a repeat
@@ -385,6 +386,11 @@ c1
 c1
 @end lilypond
 
+@warning{If you include @code{@bs{}relative} inside a
+@code{@bs{}repeat} without explicitly instantiating the
+@code{Voice} context, extra (unwanted) staves will appear.  See
+@rprogram{An extra staff appears}.}
+
 
 @seealso
 Snippets:

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 93c0c3a3a78aee2769c4b6d7b56499d230d5e112..eeba9e8f41b6f653358f9e757cdc293c684e586d 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -649,17 +649,17 @@ line to break.  For details, see @ruser{Bar lines}.
 @node An extra staff appears
 @unnumberedsubsec 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.
+If contexts are not created explicitly with @code{\new} or
+@code{\context}, 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
@@ -680,23 +680,25 @@ correct code to color all note heads red is
 @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
+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' { c d e f }
+  \relative c' { c4 d e f }
 }
 @end lilypond
 
-The correct way is to reverse the @code{\repeat} and
-@code{\relative} commands, like this:
+Explicitly instantiating the @code{Voice} context fixes the
+problem:
 
 @lilypond[quote,verbatim]
-\relative c' {
-  \repeat unfold 2 { c d e f }
+\new Voice {
+  \repeat unfold 2 {
+    \relative c' { c4 d e f }
+  }
 }
 @end lilypond