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

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index dcd935704300174d68f0efe40280064d9282aee0..45fbb4f885ae1eddf00440c97e376e3a5a7c4924 100644 (file)
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -89,6 +89,18 @@ With those particular definitions, LilyPond will try to recognize
 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

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index fbfca6e8f92e3623152238470914de805e8cf3e1..ef109528a19e01f1b238c60d0ce523de1f8236c2 100644 (file)
--- 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 (file)
index 0000000..8289bab
--- /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 8d737dce8b2b06e6d5a163a526f4232fd3cef776..484b9a5afe27252a8f46148f71b76d2cf2f31780 100644 (file)
--- 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 ecc75aef09a4a658be00bdffd7797ef6a60267e3..c6a70d50a36fa54c6a2c575514df0107e962b73d 100644 (file)
--- 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 b450f3bb7ab8ad2dd454891c660357536a6d2b4a..b141aa077eaf8eb7bcc58ce84858c9ae1679b035 100644 (file)
--- 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
 }