Long live length in the docs.

Long live length in the docs.

[MikeSol, 2011-08-28 10:12:58]

This gets rid of Stem #'length in the docs.  I haven't run make doc yet, but I
will right after this and will report back in a couple hours with a new patch
that makes any additional necessary changes.

Cheers,
MS

[Graham Percival (old account), 2011-08-28 10:29:01]

amusingly, I have no trouble compiling the docs without this patch, but it fails
with this patch applied:

/main/src/lilypond/build/out/lybook-db/b5/lily-2dcca534.ly:1097:9: warning: no
viable initial configuration found: may not find good beam slope
        <
         c ees>8 f g
Segmentation fault


I think that came from the essay, in case you want to just compile that specific
manual to test.  (instructions recently added to the CG)

[MikeSol, 2011-08-28 12:21:34]

New patch set uploaded - haven't finished building docs yet, but I think this
will go through to the end.  Will report back in a couple hours (make doc nearly
done, but I have to leave the house).

Cheers,
MS

[MikeSol, 2011-08-28 12:22:40]

Ha...how about that.

I'll look into it when I get back, but good to know that the docs are compilable
without this patch applied.

Cheers,
MS

[MikeSol, 2011-08-28 17:23:02]

Hey all,

I got a clean doc build with this newest patch set - please confirm.

Cheers,
MS

[Trevor Daniels, 2011-08-29 07:45:04]

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?

http://codereview.appspot.com/4965053/diff/4001/Documentation/learning/tweaks...
File Documentation/learning/tweaks.itely (right):

http://codereview.appspot.com/4965053/diff/4001/Documentation/learning/tweaks...
Documentation/learning/tweaks.itely:3479: @code{length} to @code{8},
Remove talking through code.  Rewrite as just
"we can lengthen the stem:"

[Graham Percival, 2011-08-29 07:54:06]

On Mon, Aug 29, 2011 at 07:45:04AM +0000, tdanielsmusic@googlemail.com 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?

On general principle I agree, but I believe that this patch simply
brings the docs in line with actual git master.  I assume that the
examples about stem length currently just do nothing.  As such, I
think we should go ahead with it.

32570e8ac85561afc1f59712301ee80c0d69d2b3
The one-line summary doesn't mention anything about syntax
changes, but the detailed commit message makes it clear.

Moral of the story?  pay more attention to patch countdowns, I
guess.  I wouldn't be adverse to asking developers to clearly
state a syntax change in the 50-character summary (although this
gets tricky; maybe simply adding "(syntax)" would be ok?)... but
at the end of the day, the patch went through the countdown.

Cheers,
- Graham

[mikesol_ufl.edu, 2011-08-29 08:11:20]

On Aug 29, 2011, at 9:53 AM, Graham Percival wrote:

> On Mon, Aug 29, 2011 at 07:45:04AM +0000, tdanielsmusic@googlemail.com 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.
There used to be length, stem-begin, stem-end, and Y-extent properties for stem
- all of which were combinations of each other in some form.  In theory,
stem-begin + length * dir = stem-end.  (cons stem-begin . stem-end) = Y'extent
for up-pointing stems.  etc.  This also messed up pure heights.  For example:
let's say that the user modified the stem-begin in the old master.  This would
not have been taken into account for pure heights in certain situations. 
Furthermore, a modification of stem-end with a modification of length could
result in one trumping the other in certain circumstances.  In general, when
there are 4 properties (length, stem-begin, stem-end, and Y-extent) that
represent one, and when three of these properties lead to bad pure heights, I
think it is important to slim it down to one property (Y-extent).  To me, this
seems less complex.  And, if the user wants to set length with the beginning at
the note-head, stem::length is the appropriate function that will preserve pure
heights (with my pure-closure patch, which I believe will be going on a
countdown soon).

> On general principle I agree, but I believe that this patch simply
> brings the docs in line with actual git master.

Yes

> I assume that the
> examples about stem length currently just do nothing.

True

> As such, I
> think we should go ahead with it.
> 

Agreed.

> 32570e8ac85561afc1f59712301ee80c0d69d2b3
> The one-line summary doesn't mention anything about syntax
> changes, but the detailed commit message makes it clear.
> 

Yes.

> Moral of the story?  pay more attention to patch countdowns, I
> guess.

Agreed.

> I wouldn't be adverse to asking developers to clearly
> state a syntax change in the 50-character summary (although this
> gets tricky; maybe simply adding "(syntax)" would be ok?)... but
> at the end of the day, the patch went through the countdown.
> 

This I'll do from here on out.

Cheers,
MS

[t.daniels_treda.co.uk, 2011-08-29 08:17:12]

Graham Percival wrote Monday, August 29, 2011 8:53 AM

> Moral of the story?  pay more attention to patch countdowns, I

I've given up looking at code-change patch count-downs.
There's no way I can spare the time required.  Each
one requires the time to understand the area of code,
analyse the patch, download it, try it.  This can easily
require several hours if the area of code is complex,
as many are.  If you force patches through at the present 
rate they're not going to be carefully reviewed.

Trevor

[Graham Percival, 2011-08-29 08:56:00]

On Mon, Aug 29, 2011 at 09:15:54AM +0100, Trevor Daniels wrote:
> 
> Graham Percival wrote Monday, August 29, 2011 8:53 AM
> 
> >Moral of the story?  pay more attention to patch countdowns, I
> 
> I've given up looking at code-change patch count-downs.
...
> If you force patches through at the present rate
> they're not going to be carefully reviewed.

I'm open to suggestions.  The development team is producing
approximately 20 patches (including drafts) per week.  We could
always tell some programmers to bugger off, but that seems highly
counter-productive.  :)
Another idea would be to try forcing people to review patches.  I
don't see that going well, either.

As long as we have regular development releases -- which we don't
at the moment -- then I think it's as good as we're going to get.

Cheers,
- Graham

[mikesol_ufl.edu, 2011-08-29 09:04:23]

On Aug 29, 2011, at 10:55 AM, Graham Percival wrote:

> On Mon, Aug 29, 2011 at 09:15:54AM +0100, Trevor Daniels wrote:
>> 
>> Graham Percival wrote Monday, August 29, 2011 8:53 AM
>> 
>>> Moral of the story?  pay more attention to patch countdowns, I
>> 
>> I've given up looking at code-change patch count-downs.
> ...
>> If you force patches through at the present rate
>> they're not going to be carefully reviewed.
> 
> I'm open to suggestions.  The development team is producing
> approximately 20 patches (including drafts) per week.  We could
> always tell some programmers to bugger off, but that seems highly
> counter-productive.  :)

I'm also against this.  I do not have time during the school year to do as much
development as I'd like (I think several of us are in this situation).  I try to
review as much as possible in my areas of expertise, but I agree that review
cannot happen as fast as development is currently happening.  However, I believe
that everyone on the current development team is willing to take responsibility
for their work and, if it does result in bugs, to spend the time necessary to
eliminate them as fast as possible.  Obviously, the faster a process moves, the
more prone it is to error.  I would rather, however, see LilyPond develop at its
current pace and put confidence in its developers to take responsibility for
their actions then slow down development.

> Another idea would be to try forcing people to review patches.  I
> don't see that going well, either.
> 

I also agree that this is bad.  On this subject (though not directly related), I
will say that when people have solicited me individually for review, I have
always done it.  Similarly, whenever I have asked for certain individual's
feedback, I have always gotten it.  It would be great to have a culture of
informal requests this to get extra revisions on Rietveld - we all more or less
know who does what well, and part of the confidence I talk about in the
paragraph above is the confidence to be able to evaluate one's own abilities in
a domain and to seek help when necessary.

Cheers,
MS

[janek, 2011-08-29 09:58:01]

2011/8/29 Graham Percival <graham@percival-music.ca>:
> On Mon, Aug 29, 2011 at 09:15:54AM +0100, Trevor Daniels wrote:
>>
>> I've given up looking at code-change patch count-downs.
> ...
>> If you force patches through at the present rate
>> they're not going to be carefully reviewed.
>
> I'm open to suggestions.  The development team is producing
> approximately 20 patches (including drafts) per week.

From my point of view, commit messages, descriptions in tracker and on
Rietveld are essential.  Some patches have no description and i cannot
say anything about them.

cheers,
Janek

[t.daniels_treda.co.uk, 2011-08-29 22:33:19]

Graham Percival wrote Monday, August 29, 2011 9:55 AM


> On Mon, Aug 29, 2011 at 09:15:54AM +0100, Trevor Daniels wrote:
>> 
>> If you force patches through at the present rate
>> they're not going to be carefully reviewed.
> 
> I'm open to suggestions.  The development team is producing
> approximately 20 patches (including drafts) per week.  We could
> always tell some programmers to bugger off, but that seems highly
> counter-productive.  :)

Indeed.  Perhaps we could make a clearer distinction
between patches that must be reviewed, like those
which cause syntax changes, those which add new
features and those by relative newcomers, and those
that should simply be pushed without review, like
bug fixes by experienced developers, minor doc changes,
etc, with the aim of reducing further the number going 
to Reitveld and lengthening the queue.  Another GOP 
topic?
 
> Another idea would be to try forcing people to review patches.  I
> don't see that going well, either.

No, sounds pretty impractical too.
 
Trevor

[t.daniels_treda.co.uk, 2011-08-30 10:08:05]

Mike Solomon wrote Monday, August 29, 2011 9:11 AM

> On Mon, Aug 29, 2011 at 07:45:04AM +0000, 
> tdanielsmusic@googlemail.com 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

[mikesol_ufl.edu, 2011-08-30 11:08:12]

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, tdanielsmusic@googlemail.com 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

[Graham Percival, 2011-08-30 11:27:04]

On Tue, Aug 30, 2011 at 01:07:46PM +0200, Mike Solomon wrote:
> 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)

What's the difference (from your end) between #(stem::length 5)
and #5 ?

> A mid-way solution may be to start building deprecation warnings into
Lilypond.

that's a common complaint; we'll discuss deprecation in a future
GOP.

Cheers,
- Graham

[mikesol_ufl.edu, 2011-08-30 11:45:18]

On Aug 30, 2011, at 1:27 PM, Graham Percival wrote:

> On Tue, Aug 30, 2011 at 01:07:46PM +0200, Mike Solomon wrote:
>> 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)
> 
> What's the difference (from your end) between #(stem::length 5)
> and #5 ?
> 

Aside from the fact that one uses stem::length and one doesn't, I don't know,
which is why I'm the wrong guy to ask about UI :)

In current master, #'Y-extent = #(stem::length 5) does exactly what #'length =
#5 did a week ago.

I believe that Trevor is claiming that #(stem::length 5) is worse from a
UI-perspective than #5.  I think he is right insofar as stem::length means there
are more things to type, but I think that if the person has gotten to the point
where they are doing tweaks, they can write #(stem::length 5) instead of #5 with
little to no extra mental overhead (especially if it is explained in the docs). 
However, I may be underestimating how difficult the LilyPond user experience is
- I do know that when I started using LilyPond, numbers seemed friendlier to me
than things in parentheses.

Cheers,
MS

[Graham Percival, 2011-08-30 11:53:18]

On Tue, Aug 30, 2011 at 01:45:20PM +0200, Mike Solomon wrote:
> In current master, #'Y-extent = #(stem::length 5) does exactly what #'length =
#5 did a week ago.

There is essentially no different in going frmo
  \override Stem #'length = #5
to
  \override Stem #'Y-extent = #5

as far as users are concerned, that would be much better than
  \override Stem #'Y-extent = #(stem::length 5)

as far as I'm concerned... I've never even seen a (foo::bar x)
command before!  If we could still use #5, that would be
preferred.

Cheers,
- Graham

[brownian.box, 2011-08-30 12:02:24]

On Tue 30 Aug 2011, 12:53 Graham Percival wrote:
> On Tue, Aug 30, 2011 at 01:45:20PM +0200, Mike Solomon wrote:
> > In current master, #'Y-extent = #(stem::length 5) does exactly what #'length
= #5 did a week ago.
> 
> There is essentially no different in going frmo
>   \override Stem #'length = #5
> to
>   \override Stem #'Y-extent = #5
>
> as far as users are concerned, that would be much better than
>   \override Stem #'Y-extent = #(stem::length 5)
> 
> as far as I'm concerned... I've never even seen a (foo::bar x)
> command before!  If we could still use #5, that would be
> preferred.
Please, excuse my jumping in.

Being a user, I often used to override 'Y-extent for some specific purposes:

{
  \override Stem #'Y-extent = #'(-10 . 0)
  c''_\fermata
}

Yes, it's a stupid example, but it's quite good that 'length and 'Y-extent can
do _different_ things.

begin - end = extent -- isn't it "simply default value" for extent?

-- 
  Dmytro O. Redchuk                        "Easy to use" is easy to say.
  Bug Squad                                             -- Jeff Garbers

[brownian.box, 2011-08-30 12:31:51]

On Tue 30 Aug 2011, 15:02 I wrote:
> Being a user, I often used to override 'Y-extent for some specific purposes:
> 
> {
>   \override Stem #'Y-extent = #'(-10 . 0)
>   c''_\fermata
> }
Oh, yes, 2.15.9 changes stem's length.

2.15.8 and below did not change it.

2.15.8 and below changed grob's _extent_, but not appearance. It was good. For
some/other grobs there are (a lot of?) places in the docs, when it's suggested
to set 'Y-extent to (-inf.0 . +inf.0) for some purposes. If I can remember.
Or to set in to (0 . 0) to make grob "to have no extent". But it didn't change
grob's appearance.


Sorry my jumping in though. Very probably, I've missed something important.

-- 
  Dmytro O. Redchuk                        "Easy to use" is easy to say.
  Bug Squad                                             -- Jeff Garbers

[t.daniels_treda.co.uk, 2011-08-30 13:05:20]

Mike Solomon wrote Tuesday, August 30, 2011 12:45 PM

> I believe that Trevor is claiming that 
> #(stem::length 5) is worse from a UI-perspective 
> than #5.

Yes.  
  
> I think he is right insofar as stem::length 
> means there are more things to type, 

No.  That's not the point.  A user wanting to
change the length of a stem has to work out how
to do it.  Looking up 'length in the IR was
do-able, as the LM explains in some detail how 
to do that.  Relating "length" to Y-extent is not 
an obvious step, more so for a user unfamiliar with
extents.  Then having to use an unusual construct
makes it even worse.  Users have a hard enough
time with {}, #s, ' and `.  Now we have ::.

> but I think that if the person has gotten to the 
> point where they are doing tweaks, they can write 
> #(stem::length 5) instead of #5 with little to 
> no extra mental overhead 

Wrong.  It is not capable of being determined a
priori.  Much less remembered by anyone unversed
in scheme.

> (especially if it is explained in the docs).  

I guess I may have to do this :(  It's quite an
extension to the LM though, and one we decided
against when laying out the schema for the
documentation.  All the scheme stuff goes in
the Extending manual under Interfaces for
programmers.  Not a comfortable place for the
typical user. 

Trevor

[mikesol_ufl.edu, 2011-08-30 13:22:20]

On Aug 30, 2011, at 1:53 PM, Graham Percival wrote:

> On Tue, Aug 30, 2011 at 01:45:20PM +0200, Mike Solomon wrote:
>> In current master, #'Y-extent = #(stem::length 5) does exactly what #'length
= #5 did a week ago.
> 
> There is essentially no different in going frmo
>  \override Stem #'length = #5
> to
>  \override Stem #'Y-extent = #5
> 
> as far as users are concerned, that would be much better than
>  \override Stem #'Y-extent = #(stem::length 5)
> 
> as far as I'm concerned... I've never even seen a (foo::bar x)
> command before!  If we could still use #5, that would be
> preferred.
> 

To use #'Y-extent = #5, we'd have to invent a new type for Y-extent
(number-or-pair?) and then come up with rules for how to convert the number into
a pair for certain grobs and how to throw warning messages otherwise.  This is
certainly doable, but I'm not sure how kosher it is UI-wise.

Cheers,
MS

[mikesol_ufl.edu, 2011-08-30 14:08:19]

On Aug 30, 2011, at 2:31 PM, Dmytro O. Redchuk wrote:

> On Tue 30 Aug 2011, 15:02 I wrote:
>> Being a user, I often used to override 'Y-extent for some specific purposes:
>> 
>> {
>>  \override Stem #'Y-extent = #'(-10 . 0)
>>  c''_\fermata
>> }
> Oh, yes, 2.15.9 changes stem's length.
> 
> 2.15.8 and below did not change it.
> 
> 2.15.8 and below changed grob's _extent_, but not appearance. It was good. For
> some/other grobs there are (a lot of?) places in the docs, when it's suggested
> to set 'Y-extent to (-inf.0 . +inf.0) for some purposes. If I can remember.
> Or to set in to (0 . 0) to make grob "to have no extent". But it didn't change
> grob's appearance.
> 
> Sorry my jumping in though. Very probably, I've missed something important.

Not at all - you're absolutely right, and I certainly think you make a valid
argument for having a property that controls the grob's look.  It could be
#'length, although the problem with length is that it presupposes that the
length is from the stem's natural starting point instead of from the stem's
natural ending point.

Currently, the stem stencil function is doable in Scheme, which means that the
result from 2.15.8 can be achieved via :

#(define (my-stem grob)
  (let*
    ((dir (ly:grob-property grob 'direction))
     (half-space (* 0.5 (ly:staff-symbol-staff-space grob)))
     (y1 (* half-space (ly:stem::calc-stem-begin-position grob)))
     (y2 (* half-space (ly:stem::calc-stem-end-position grob)))
     (half-thick (* (* (ly:grob-property grob 'thickness)
                       (ly:staff-symbol-line-thickness grob))
                    0.5))
     (beam (ly:grob-object grob 'beam))
     (y2 (+ y2 (if (null? beam)
                   0.0
                   (* dir (* (ly:grob-property beam
                                               'beam-thickness)
                             half-space)))))
     (my-down (if (< y2 y1) y2 y1))
     (my-up (if (< y2 y1) y1 y2))
     (blot (ly:paper-get-number (ly:grob-layout grob) 'blot-diameter)))
   (ly:make-stencil `(round-filled-box ,half-thick
                                       ,half-thick
                                       ,(- my-down)
                                       ,my-up
                                       ,blot)
                    (cons (- half-thick) half-thick)
                    (cons my-down my-up))))

{
 c''_\fermata
 \override Stem #'Y-extent = #'(-10 . 0)
 \override Stem #'stencil = #my-stem
 c''_\fermata
}

I'm not sure of a good way to deal with this from a UI perspective, but at least
the function above allows you to achieve the result you're talking about with
only one extra override

Cheers,
MS

[brownian.box, 2011-08-30 14:14:21]

On Tue 30 Aug 2011, 16:08 Mike Solomon wrote:
> Currently, the stem stencil function is doable in Scheme, which means that
> the result from 2.15.8 can be achieved via :
Thank you for your work! I've "bookmarked" this hint/thread, of course.

I am still wondering, is stem the single grob so far, which 'Y-extent property
"overrides" its appearance? Or other grobs will be (or already are) changed,
too?

Sorry for dumb questions, if any. Thank you for bearing with me.)


> #(define (my-stem grob)
>   (let*
>     ((dir (ly:grob-property grob 'direction))
>      (half-space (* 0.5 (ly:staff-symbol-staff-space grob)))
>      (y1 (* half-space (ly:stem::calc-stem-begin-position grob)))
>      (y2 (* half-space (ly:stem::calc-stem-end-position grob)))
>      (half-thick (* (* (ly:grob-property grob 'thickness)
>                        (ly:staff-symbol-line-thickness grob))
>                     0.5))
>      (beam (ly:grob-object grob 'beam))
>      (y2 (+ y2 (if (null? beam)
>                    0.0
>                    (* dir (* (ly:grob-property beam
>                                                'beam-thickness)
>                              half-space)))))
>      (my-down (if (< y2 y1) y2 y1))
>      (my-up (if (< y2 y1) y1 y2))
>      (blot (ly:paper-get-number (ly:grob-layout grob) 'blot-diameter)))
>    (ly:make-stencil `(round-filled-box ,half-thick
>                                        ,half-thick
>                                        ,(- my-down)
>                                        ,my-up
>                                        ,blot)
>                     (cons (- half-thick) half-thick)
>                     (cons my-down my-up))))
> 
> {
>  c''_\fermata
>  \override Stem #'Y-extent = #'(-10 . 0)
>  \override Stem #'stencil = #my-stem
>  c''_\fermata
> }
> 
> I'm not sure of a good way to deal with this from a UI perspective, but at
> least the function above allows you to achieve the result you're talking
> about with only one extra override

-- 
  Dmytro O. Redchuk                        "Easy to use" is easy to say.
  Bug Squad                                             -- Jeff Garbers

[mikesol_ufl.edu, 2011-08-30 14:44:42]

On Aug 30, 2011, at 3:04 PM, Trevor Daniels wrote:

> 
> Mike Solomon wrote Tuesday, August 30, 2011 12:45 PM
> 
>> I believe that Trevor is claiming that #(stem::length 5) is worse from a
UI-perspective than #5.
> 
> Yes.   
>> I think he is right insofar as stem::length means there are more things to
type, 
> 
> No.  That's not the point.  A user wanting to
> change the length of a stem has to work out how
> to do it.  Looking up 'length in the IR was
> do-able, as the LM explains in some detail how to do that.  Relating "length"
to Y-extent is not an obvious step, more so for a user unfamiliar with
> extents.  Then having to use an unusual construct
> makes it even worse.  Users have a hard enough
> time with {}, #s, ' and `.  Now we have ::.
> 

I'll certainly take your word for it - UI is not my specialty by a long shot.

>> but I think that if the person has gotten to the point where they are doing
tweaks, they can write #(stem::length 5) instead of #5 with little to no extra
mental overhead 
> 
> Wrong.  It is not capable of being determined a
> priori.  Much less remembered by anyone unversed
> in scheme.
> 
>> (especially if it is explained in the docs).  
> 
> I guess I may have to do this :(  It's quite an
> extension to the LM though, and one we decided
> against when laying out the schema for the
> documentation.  All the scheme stuff goes in
> the Extending manual under Interfaces for
> programmers.  Not a comfortable place for the
> typical user. 
> Trevor
> 
> 

As I stated in a previous mail, it is easy to re-instate a length property in
the stem-interface and then build it into either Stem::internal_height or
Stem::print.  I have no problem with this.

What do you mean when you say that all the Scheme stuff goes in the Extending
manual?  #5 is Scheme, as is #(stem::length 5), as is ly:note-head::print.  All
I think should be explained in the docs is Y-extent: I'm certainly not
suggesting that advanced Scheme concepts be explained here.  But, again, this is
outside my realm of expertise - whatever you feel is best for UI is what you
should go with.  If you ask me "please write length back into the source so that
it does what it did in 2.15.8," I'll do it tomorrow afternoon and have it on
Rietveld before I leave so that someone can push it in my absence if they so
choose.

Cheers,
MS

[t.daniels_treda.co.uk, 2011-08-30 15:41:17]

Mike, you wrote Tuesday, August 30, 2011 3:41 PM


> As I stated in a previous mail, it is easy to 
> re-instate a length property in the stem-interface 
> and then build it into either Stem::internal_height 
> or Stem::print.  I have no problem with this.

I'd vote for this.  Let's see what others think.

> What do you mean when you say that all the Scheme 
> stuff goes in the Extending manual?  #5 is Scheme, 
> as is #(stem::length 5), as is ly:note-head::print.  

Yes, I should have explained a little more clearly.
The LM, which we expect all users to read, does not
explain Scheme syntax.  Introducing overrides, it 
simply says:

"For now, don't worry about the #', which must precede 
the layout property, and the #, which must precede the 
value.  These must always be present in exactly this form."

Even the NR doesn't venture much further, mentioning
only alists.

Everything else was moved to the Extending manual,
after a short Scheme primer.  (Although in passing
I should say this is still very unsatisfactory.)
Few users will read this.

> All I think should be explained in the docs is 
> Y-extent: I'm certainly not suggesting that advanced 
> Scheme concepts be explained here.

Yes, but this use of Y-extent is different from all(?)
others, isn't it?  Normally Y-extent affects only the
placement of following grobs, IIUC, not the size of
them.  So the explanation would not be trivial, and
to my mind unsuitable for a Learning Manual.
  
> But, again, this 
> is outside my realm of expertise - whatever you feel 
> is best for UI is what you should go with.  If you 
> ask me "please write length back into the source so 
> that it does what it did in 2.15.8," I'll do it 
> tomorrow afternoon and have it on Rietveld before I 
> leave so that someone can push it in my absence if 
> they so choose.

I don't think it's that urgent.  Let's see what view
emerges first.

Trevor

[mikesol_ufl.edu, 2011-08-30 15:49:11]

On Aug 30, 2011, at 4:14 PM, Dmytro O. Redchuk wrote:

> On Tue 30 Aug 2011, 16:08 Mike Solomon wrote:
>> Currently, the stem stencil function is doable in Scheme, which means that
>> the result from 2.15.8 can be achieved via :
> Thank you for your work! I've "bookmarked" this hint/thread, of course.
> 
> I am still wondering, is stem the single grob so far, which 'Y-extent property
> "overrides" its appearance? Or other grobs will be (or already are) changed,
> too?
> 

Hey Dmytro,

It could very well be - nothing comes to mind that works this way other than
stems.  The more I think about it, the more I realize that Y-extent is more
meant to be the vertical portion of a bounding box and, thus, can greatly
overshoot or undershoot the actual grob.

The most computation-friendly way to decouple Y-extent from the stencil without
having to do calculations twice is to do what is done in spanners like
TupletBracket and Beam - namely, use a positions property to hold an interval of
y positions.  stem::height and its pure equivalent would simply pass back these
values, and stem::print would use them to print the stencil.  Then, an override
to Y-extent would not besmirch the stencil.

Alternatively, to avoid the addition of a property, the stem stencil function
could make a call to Stem::internal_height instead of making a call to extent,
although this would duplicate a long series of calculations.

Both of these are 15 minutes of work and, hopefully, if it becomes pressing
during my absence, someone can implement them.  If anyone foresees needing to
implement this during my absence and does not understand what I'm talking about
above and/or would like more explanation, don't hesitate to get in touch!

Cheers,
MS

[MikeSol, 2011-08-30 19:52:40]

Hey all,

I've made a pretty significant change to this patch resulting from the
conversation on the list tonight.  master builds clean and I'm halfway into a
clean doc build.  Will check regtests tomorrow.  I'd like this to stay on the
countdown in spite of the change, although if people want me to pull it off,
then I will.

Cheers,
MS

[Reinhold, 2011-08-30 20:00:37]

Can you add a regtest for overriding Stem #'length?

[Trevor Daniels, 2011-08-30 20:39:25]

Thanks Mike :)  

LGTM (with one query) AFAICT in this complex area.

http://codereview.appspot.com/4965053/diff/9004/scm/define-grob-properties.scm
File scm/define-grob-properties.scm (right):

http://codereview.appspot.com/4965053/diff/9004/scm/define-grob-properties.sc...
scm/define-grob-properties.scm:841: (stem-begin-position ,ly:dimension? "User
override for the
shouldn't this be number? ?

[MikeSol, 2011-08-30 20:53:16]

On 2011/08/30 20:39:25, Trevor Daniels wrote:
> Thanks Mike :)  
> 
> LGTM (with one query) AFAICT in this complex area.
> 
> http://codereview.appspot.com/4965053/diff/9004/scm/define-grob-properties.scm
> File scm/define-grob-properties.scm (right):
> 
>
http://codereview.appspot.com/4965053/diff/9004/scm/define-grob-properties.sc...
> scm/define-grob-properties.scm:841: (stem-begin-position ,ly:dimension? "User
> override for the
> shouldn't this be number? ?

I'm not sure - what's the difference between the two types?

Cheers,
MS

[t.daniels_treda.co.uk, 2011-08-30 21:17:47]

>
http://codereview.appspot.com/4965053/diff/9004/scm/define-grob-properties.sc...
>> scm/define-grob-properties.scm:841: (stem-begin-position
> ,ly:dimension? "User
>> override for the
>> shouldn't this be number? ?
>
> I'm not sure - what's the difference between the two types?

Someone more familiar with the typing will hopefully
give a precise answer, but I see dimension used only
for distances, not positions.

Trevor

[MikeSol, 2011-08-31 09:36:20]

make all ok and make doc ok until it crashes on the file that Graham sent an
e-mail about to the list (has this been fixed yet?  do i need to do something in
my doc directory to register the change? i'm running make doc-clean before the
doc build).

It passes regtests just fine, and i can't see any visual changes save one or two
tests (and even these are mostly microscopic).  This is (I think) because the
patch lightly shortens a couple beamed stem pure heights that were incorrect by
0.5 * beam_thickness in my previous work.

Cheers,
MS

[Graham Percival, 2011-09-01 05:13:02]

On Wed, Aug 31, 2011 at 09:36:20AM +0000, mtsolo@gmail.com wrote:
> i'm running make doc-clean before the doc build).

Don't ever, **ever**, run make doc-clean, unless/until explicitly
told that it is fixed.  I consider doc-clean completely broken.
Whenever you are thinking about running doc-clean, you should
instead completely delete your build/ tree and compile again from
scratch.

Cheers,
- Graham

[MikeSol, 2011-09-01 08:52:36]

Pushed as 6465274e66a851cccd4cd32a521abc853f3e79dd.

Thanks to all for their help.

A couple things:

1) Trevor - I still haven't heard word back about ly:dimension?.  If it turns
out this is not what's supposed to be used, please feel free to change it to
number? in a separate commit.

2) While perusing the visual output of the docs, I noticed that Trevor's cary.ly
example looks different from the 2.14 site.  I'll try to post a patch to get it
to its normal state before I leave.

Cheers,
MS

[t.daniels_treda.co.uk, 2011-09-02 11:21:34]

> 1) Trevor - I still haven't heard word back about ly:dimension?. 
> If it
> turns out this is not what's supposed to be used, please feel free 
> to
> change it to number? in a separate commit.

The dimension type was first introduced in 2003 in
lily/lily-guile.cc: a2a77093b49bca4f040944a0b4ec16f3beca05ec

+LY_DEFINE(ly_dimension_p,  "ly:dimension?", 1, 0, 0, (SCM d),
+   "Return @var{d} is a number. Used to distinguish length "
+   "variables from normal numbers.")
+{
+  return scm_number_p (d);
+}

It's now in lily/general-scheme.cc, essentially unchanged:

LY_DEFINE (ly_dimension_p, "ly:dimension?", 1, 0, 0, (SCM d),
           "Return @var{d} as a number.  Used to distinguish length"
           " variables from normal numbers.")
{
  return scm_number_p (d);
}

So the check for the dimension type is identical to that
for number.  Nevertheless, the two appear to be consistently
used in ly sources to indicate their different natures.
As 'stem-begin-position is not a length I'll change its
type to number.

Trevor