Re: add stencil-whiteout-outline function (issue 236480043 by address@hidden)

[k-ohara5a5a]

I realize I am changing my opinion here on a few points:
1) leave the old whiteout as a simple box and give the new function a
new name
2) enabling either type of whiteout through a single property looks
better
3) the thickness should be in terms of line-thickness rather than
staff-space

I hope you don't mind figuring out which of these were the wiser
opinions.  I'll just say this all looks good to me.

On 2015/05/29 04:03:06, paul_paulwmorris.com wrote:

> Question: should the whiteout property be a number rather than a
boolean, so
> that it sets the thickness of the white outline (and #0 replaces ##f)?
 Or
> should the whiteout property accept either a number or a boolean?

Yes, and more yes to the second option.  There is a type-checking
predicate 'boolean-or-symbol?' from which you could make the analogous
'boolean-or-number?'.
Existing uses of Xx.whiteout=##t could get the simple box, while
Xx.whiteout=1 gives the outline style.  I suspect the users who want the
outline will often want to adjust the thickness.

Most thicknesses are in terms of the staff-line thickness.  Using this
unit, the range of thicknesses for which the function was intended, and
works best without excessive copies of the stencil, are simple numbers
  \override Xx.whiteout = 4 %{ staffline thicknesses, rather than =#0.3
staff-spaces %}
Also, the whiteout border will more likely do the right thing if it
scales with the staffline thickness, rather than staff-space, when
people scale the output to make a pocket score for example.

Inconveniently for this patch, the stencil-translate works in units of
staff-spaces, and by design the stencil language keeps some things in
units of line-thickness, others in staff-spaces.  Each grob or markup is
built for a particular layout, so we can convert units where the grob or
markup asks for whiteout (see below).

> (A convert-ly rule may be needed… maybe in any case to
> change whiteout to whiteout-box? ...or maybe not?)

Looking at the existing uses of \whiteout Xxx.whiteout, it does seem
best to leave the plain box whiteout in existing scores.  Convert-ly to
\whiteout-box one way to preserve the behavior, but it would be better
to leave the old markup function \whiteout for the old behavior, and add
\whiteout-outline.



https://codereview.appspot.com/236480043/diff/20001/Documentation/notation/rhythms.itely
File Documentation/notation/rhythms.itely (right):

https://codereview.appspot.com/236480043/diff/20001/Documentation/notation/rhythms.itely#newcode555
Documentation/notation/rhythms.itely:555: collide with other objects in
a staff.
At first I thought the docs should use the new outline form of whiteout,
but here I see that the box is perfect for this case.

(The text should say ".. properties of objects that should cause a gap
in ties."  Later we might build this into the grob definitions.)

https://codereview.appspot.com/236480043/diff/20001/lily/grob.cc
File lily/grob.cc (right):

https://codereview.appspot.com/236480043/diff/20001/lily/grob.cc#newcode162
lily/grob.cc:162:
We could let  \override Xx.whiteout = 3
give a white outline 3 times the staffline thickness, by looking up the
staffline thickness here.
if scm_is_number(get_property("whiteout") {
  SCM wh_proc = y_lily_module_constant ("stencil-whiteout-outline");
  Real thickness = robust_scm2double (get_property("whiteout"), 3.0)
       * layout ()->get_dimension (ly_symbol2scm ("line-thickness"));
  retval = *unsmob<Stencil>( scm_call_2(wh_proc,
                                       retval.smobbed_copy,
                                       thickness));
}

https://codereview.appspot.com/236480043/diff/20001/scm/define-markup-commands.scm
File scm/define-markup-commands.scm (right):

https://codereview.appspot.com/236480043/diff/20001/scm/define-markup-commands.scm#newcode722
scm/define-markup-commands.scm:722: (stencil-whiteout (interpret-markup
layout props arg)))
Whatever the name for \whiteout-outline  you can let it read the
'thickness' property, to use the interface for optional arguments that
we have in the markup language
 g^\markup \override #'(thickness . 5) \whiteout-outline "hello"

(define-markup-command (whiteout-outline layout props arg)
  (markup?)
  #:category other
  #:properties ((thickness 4))
  (stencil-whiteout-outline
     (interpret-markup layout props arg)
      (* thickness
         (ly:output-def-lookup layout 'line-thickness))))

https://codereview.appspot.com/236480043/