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}
 @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}
 @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
 
 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}:
 
 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.
 
 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
 @c TODO Add visibility of cautionary accidentals before notes
 
 @subsubsubheading Automatic bars