Issue 4418/6 edits to docs, tests, and changelog

6 files changed, 70 insertions, 11 deletions

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index dcd9357043..45fbb4f885 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -90,6 +90,18 @@ legacy use of @code{parser} and @code{location} arguments,
 providing backwards-compatible semantics for some time.
 
 @item
+The @code{whiteout} grob property and @code{\whiteout} markup command
+now create a white background built from multiple displaced copies of
+the glyph in order to approximate the contours of its outline.
+The previous rounded box white background can be achieved with the
+new @code{whiteout-box} grob property and @code{\whiteout-box} markup
+command.  Setting the @code{whiteout} property to a number now sets
+the thickness of the white outline as a multiple of staff-line
+thickness.  Similarly, overriding the @code{thickness} property of
+the @code{\whiteout} markup command sets the thickness of the white
+outline it produces.
+
+@item
 In the "english" notename language, the long notenames for pitches
 with accidentals now contain a hyphen for better readability.  You
 now have to write
diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index fbfca6e8f9..ef109528a1 100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -551,8 +551,8 @@ Dash pattern definitions for ties have the same structure as dash
 pattern definitions for slurs. For more information about complex dash
 patterns, see @ref{Slurs}.
 
-Override @var{whiteout} and @var{layer} layout properties for ties that
-collide with other objects in a staff.
+Override @var{whiteout-box} and @var{layer} layout properties of objects
+that should cause a gap in ties.
 
 @lilypond[verbatim,quote,ragged-right,relative=2]
 \override Tie.layer = #-2
diff --git a/Documentation/snippets/new/using-the-whiteout-property.ly b/Documentation/snippets/new/using-the-whiteout-property.ly
new file mode 100644
index 0000000000..8289bab8b8
--- /dev/null
+++ b/Documentation/snippets/new/using-the-whiteout-property.ly
@@ -0,0 +1,33 @@
+\version "2.19.22"
+
+\header {
+  lsrtags = "editorial-annotations, expressive-marks"
+
+  texidoc = "
+Any graphical object can be printed over a white background to mask
+parts of objects that lie beneath.  This can be useful to improve the
+appearance of collisions in complex situations when repositioning
+objects is impractical.  It is necessary to explicitly set the
+@code{layer} property to control which objects are masked by the white
+background.
+
+In this example the collision of the tie with the time signature is
+improved by masking out the part of the tie that crosses the time
+signature by setting the @code{whiteout-box} property of
+@code{TimeSignature}. To do this @code{TimeSignature} is moved to a
+layer above @code{Tie}, which is left in the default layer of 1, and
+@code{StaffSymbol} is moved to a layer above @code{TimeSignature} so it
+is not masked.
+
+"
+  doctitle = "Using the whiteout property"
+}
+
+{
+  \override Score.StaffSymbol.layer = #4
+  \override Staff.TimeSignature.layer = #3
+  b'2 b'~
+  \once \override Staff.TimeSignature.whiteout-box = ##t
+  \time 3/4
+  b' r4
+}
diff --git a/input/regression/markup-syntax.ly b/input/regression/markup-syntax.ly
index 8d737dce8b..484b9a5afe 100644
--- a/input/regression/markup-syntax.ly
+++ b/input/regression/markup-syntax.ly
@@ -40,7 +40,8 @@
       \italic Norsk
       \super "2"
       " "
-      \raise #3.0 \whiteout-box white-out
+      \raise #3.0 \whiteout white-out
+      \raise #3.0 \whiteout-box white-out-box
       \circle \dynamic p
       \with-color #green Green
       \dynamic sfzp
diff --git a/input/regression/whiteout-lower-layers.ly b/input/regression/whiteout-lower-layers.ly
index ecc75aef09..c6a70d50a3 100644
--- a/input/regression/whiteout-lower-layers.ly
+++ b/input/regression/whiteout-lower-layers.ly
@@ -1,10 +1,11 @@
 \version "2.19.22"
 
 \header { texidoc = "If the 'whiteout property of a
-grob is set to #t, that part of all objects in lower
-layers which falls under the extent of the grob is
-whited out.  Here the TimeSignature whites out the
-Tie but not the StaffSymbol.
+grob is set to a number or #t, or if the 'whiteout-box
+property is set to #t, that part of all objects
+in lower layers which falls under the extent of
+the grob's whiteout area is whited out.  Here the
+TimeSignature whites out the Tie but not the StaffSymbol.
 "
 }
 
@@ -13,9 +14,19 @@ Tie but not the StaffSymbol.
   \override Staff.StaffSymbol.layer = #4
   \once \override Tie.layer = #2
   b'2.~
-  \once \override Staff.TimeSignature.whiteout-box = ##t
+  \once \override Staff.TimeSignature.whiteout = #3
   \once \override Staff.TimeSignature.layer = #3
   \time 5/4
   b4
 }
 
+\relative c' {
+  \time 3/4
+  \override Staff.StaffSymbol.layer = #4
+  \once \override Tie.layer = #2
+  b'2.~
+  \once \override Staff.TimeSignature.whiteout-box = ##t
+  \once \override Staff.TimeSignature.layer = #3
+  \time 5/4
+  b4
+}
diff --git a/input/regression/whiteout.ly b/input/regression/whiteout.ly
index b450f3bb7a..b141aa077e 100644
--- a/input/regression/whiteout.ly
+++ b/input/regression/whiteout.ly
@@ -1,7 +1,8 @@
 \header {
 
-  texidoc = "The whiteout command underlays a white box under a
-markup.  "
+  texidoc = "The whiteout command underlays a white background under a
+markup that approximates the outline of the markup.  The whiteout-box
+command underlays a rounded white box under a markup. "
 
 }
 \version "2.19.22"
@@ -14,5 +15,6 @@ markup.  "
 \relative {
   \override TextScript.layer = #'2
   \override TextScript.extra-offset = #'(2 . 4)
-  c''4-\markup  { \whiteout-box \pad-markup #0.5 foo } c
+  c''4-\markup { \whiteout foo } c
+  c4-\markup { \whiteout-box \pad-markup #0.5 foo } c
 }