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

[paulwmorris]

On 2015/05/31 01:07:47, Keith wrote:
> 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.

Ok, see below.

> On 2015/05/29 04:03:06, http://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?'.

Ok, sounds good.

> 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.

I see the appeal of having just one property and avoiding a convert-ly
rule.  It does seem a little odd if the kind of whiteout changes whether
the property is a number or boolean (but that may just be a matter of
getting used to it).  One potential problem is if we wanted to allow the
old box whiteout function to also take an optional thickness argument to
provide some "padding" for the whiteout box around its grob/stencil.  I
don't see a good way to do that with one property, but if there were two
properties then it would be easy.

> 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).

Using staffline thickness does seem like the better approach.  I need to
look closer at the implementation details.

> > (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.

Here I'd prefer a convert-ly rule for \whiteout --> \whiteout-box, and
then we can use \whiteout for the new outline style whiteout.

To sum up, you're suggesting:

Grob Property:
  whiteout (T/F for old box style, numbers for new outline style)
Markup functions:
  \whiteout (old box style)
  \whiteout-outline (new style)
SCM Functions:
  stencil-whiteout (old box style)
  stencil-whiteout-outline (new style)
Convert-ly:
  none

But I think I prefer the following which has a consistent parallel
structure across all the categories and where the new style of whiteout
is named in a way that conveys that it is the default, with the old box
style getting a more specialized name.  This requires convert-ly rules
and for users to learn the new names, but I think it's worth it.

Grob Properties:
  whiteout (new style, T/F or numbers)
  whiteout-box (old style, T/F, could allow numbers for padding)
Markup functions:
  \whiteout (new style)
  \whiteout-box (old style)
SCM Functions:
  stencil-whiteout (new style)
  stencil-whiteout-box (old style, optional number arg for padding)
Convert-ly:
  markups: \whiteout --> \whiteout-box
  grob properties: whiteout --> whiteout-box

(Hmmm... seems a convert-ly rule that would replace all "whiteout" with
"whiteout-box" would do the trick here for grob properties, markup
functions, and scm functions.)


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