Re: Gets rid of length in the docs. (issue 4965053)

[Mike Solomon]

On Aug 30, 2011, at 12:06 PM, Trevor Daniels wrote:

> 
> Mike Solomon wrote Monday, August 29, 2011 9:11 AM
> 
>> On Mon, Aug 29, 2011 at 07:45:04AM +0000, address@hidden wrote:
>> 
>>> I can't say I like this change: it makes a complex user
>>> interface more complex.  Shouldn't we be moving in the
>>> opposite direction?
>> 
>> I disagree.
> 
> [snip description of change]
> 
> I quite agree the code simplification is good.
> 
> My point was about the user interface.  Many of
> our users have difficulty with even simple overrides.
> Changing the stem length was a simple concept for
> them to understand: changing Y-extent is not.
> Neither is using stem::length.  stem-begin and
> stem-end are pretty irrelevant for most users; they
> are not documented anywhere except the IR, so removing
> them does not simplify the UI in a practical way.
> 
> Clearly this patch has to be applied; sorry if
> you interpreted my comment to mean I was objecting
> to it.  My intention was to raise a concern about
> the general direction the UI was taking, and this
> seems a further move away from simplification.
> 
> Fortunately the changed example appears quite deep
> in the LM so this change is not too serious, even
> though neither extents nor callbacks are covered
> there (in the LM we try never to use a concept that
> has not been explained earlier.)
> 
> Trevor
> 

It would be trivial to add a property "length" to Stem and add a few lines of 
code in the internal height function to look for this property and, if it 
exists, to work with it.

I am probably the worst person to make any claims about simplification, but I 
would say that the tradeoff goes as follows:

KEEP LENGTH
Good: have a property that is more UI-friendly
Bad: have two properties that do the same thing, resulting in Y-extent trumping 
length if both are overridden (which could be nightmarish for someone with lots 
of overrides who forgets to do a revert somewhere).  It also results in harder 
code maintainability, as it is more difficult to determine in which properties 
a grob's true height lie and how these properties combine together to result in 
the height.

GET RID OF LENGTH
Good: have one property (Y-extent) that is the sole determinant of the stem's 
height, which simplifies knowing what property does what.  This also puts Stems 
more in line with almost every other grob, where Y-extent is the sole 
determinant of the grob's height.
Bad: the user has to use a new syntax - instead of \override Stem #'length = 
#5, they need to type \override Stem #'Y-extent = #(stem::length 5)

Clearly, from the way I phrase this, you can see that I have a hard time 
imagining why one would want to keep length, especially as the stem property 
list is sprawly and this tidies it up (less properties, to me, means easier to 
understand).  However, as I stated above, it is a less-than-10-liner to change 
in the current code base to re-introduce length.

A mid-way solution may be to start building deprecation warnings into Lilypond. 
 Put length back in, warn the user it will be deprecated in the not-too-distant 
future, give the user the new syntax in the warning, and then deprecate it 
whenever we feel like it.

Also, for the LM, it seems like it'd be more useful for the user to learn about 
Y-extents (which exist in many grobs and do the same thing in all of them) than 
length (which exists in two, I think, and do different things in both).

Cheers,
MS