Doc: cautionary accidentals after a key change (3000)

  Add text and examples to NR 5.4.6 "Using break-visibility"
  to cover the printing of cautionary accidentals following
  an explicit key change.

  (Thanks to Paul Morris for the suggestion)

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index f473176eec8d9bc262e0cabb77a0d1a7cd9e06a3..23ff6976b021cdde609049d44519c298bb56345a 100644 (file)
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -3179,8 +3179,7 @@ default setting of this property:
 @item @code{Clef}                @tab @code{Staff}          @tab @code{begin-of-line-visible}
 @item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
 @item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
-@c omit KeyCancellation until it can be explained -td
-@c @item @code{KeyCancellation}  @tab ??             @tab @code{begin-of-line-invisible}
+@item @code{KeyCancellation}     @tab @code{Staff}          @tab @code{begin-of-line-invisible}
 @item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
 @c omit LeftEdge until it can be explained -td
 @c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
@@ -3276,9 +3275,9 @@ f4 g a b
 f4 g a b
 @end lilypond
 
-@subsubsubheading Visibility of cautionary accidentals
+@subsubsubheading Visibility of cancelling accidentals
 
-To remove the cautionary accidentals printed at an explicit key
+To remove the cancelling accidentals printed at an explicit key
 change, set the Staff context property @code{printKeyCancellation}
 to @code{#f}:
 
@@ -3297,6 +3296,37 @@ f4 g a b
 With these overrides only the accidentals before the notes remain
 to indicate the change of key.
 
+Note that when changing the key to C@tie{}major or A@tie{}minor
+the cancelling accidentals would be the @emph{only} indication of
+the key change.  In this case setting @code{printKeyCancellation} to
+@code{#f} has no effect:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+To suppress the cancelling accidentals even when the key is
+changed to C@tie{}major or A@tie{}minor, override
+the visibility of the @code{KeyCancellation} grob instead:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeyCancellation.break-visibility = #all-invisible
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
 @c TODO Add visibility of cautionary accidentals before notes
 
 @subsubsubheading Automatic bars