Doc: NR 4.1.2: Reorganize vertical dimensions.

Doc: NR 4.1.2: Reorganize vertical dimensions.

[Mark Polesky, 2010-10-02 06:06:06]

The vertical dimensions docs in NR 4.1.2 "Page formatting"
are (in my opinion) incredibly confusing.  Here's a patch to
reorganize that section.  One big disclaimer: the
information here is presented according to *my*
understanding of how these variables were *intended* to
behave (or in some cases, how I think they *should* behave).

I'm fully aware that some of the text is verifiably
inaccurate, with respect to what the actual current behavior
is.  So, hold back the finger-pointing (for those so
inclined), and let's discuss this.  I'm not about to push
the patch impulsively.

- Mark

[Trevor Daniels, 2010-10-02 08:51:35]

Looks a lot clearer to me, Mark, but I can't vouch for the accuracy as I've
never tried to use vertical spacing.  If the variable table came before the keys
table giving a top-down approach it would be even clearer.
Trevor

[perpeduumimmobile, 2010-10-02 09:17:15]

Hi, Mark,

very nice work, and this is indeed a lot easier to read.  I strongly favor to
polish this patch of yours instead of <http://codereview.appspot.com/1710046/>.
Inline comments to follow...

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
File Documentation/notation/spacing.itely (right):

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:200: @table @code
Hm. As long as vertical spacing is not absolutely bullet-proof specified, I
don't like to see this sections deleted.  The NR is a reference, so it's okay to
have per-entry specifications therein.
I'd leave them, but push them below your introductory part.

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:239: the combined items.
Yes, but this somehow sounds like a rectangle you can put between two staves or
something, and this is _not_ correct (because padding specifies whitespace
between the skylines).
I'm not sure why we avoid the "skyline" term in the NR; it's not too hard a
concept IMHO.  But if we don't use it, you might think again over this sentence.

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:246: reference point of a system is the
middle line of the nearest
For markups, things are different (and yet to specify). It'd make sense to use
either the top or bottom corner of a markup depending on where the specified
space lies, but that's not what currently works. (As you recognized yourself.)

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:248: @code{padding} or
@code{minimum-distance} are not meaningful,
Yes, they are.  They can be stretched, and the resulting space will be larger
than padding or minimum-distance.

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:264: @code{+inf.0}.
Again, it's a reference. We can mentioned Hooke's law, don't we?

Joe said that a reasonable default for stretchability is space, because this
keeps proportions of 'space values and actual whitespace constant, if possible
due to the constraints. This might be good to mention (and actually, why isn't
this the default)?

[Mark Polesky, 2010-10-02 16:09:22]

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
File Documentation/notation/spacing.itely (right):

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:200: @table @code
On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> Hm. As long as vertical spacing is not absolutely
> bullet-proof specified, I don't like to see this
> sections deleted.  The NR is a reference, so it's
> okay to have per-entry specifications therein.
> I'd leave them, but push them below your
> introductory part.

Are you saying you'd prefer to define the four keys individually for each of the
eight variables?  Even though the NR is a reference, I think this would be
needlessly crufty.  But I could be convinced if you feel strongly about it.

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:239: the combined items.
On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> Yes, but this somehow sounds like a rectangle you
> can put between two staves or something, and this
> is _not_ correct (because padding specifies
> whitespace between the skylines).  I'm not sure
> why we avoid the "skyline" term in the NR; it's
> not too hard a concept IMHO.  But if we don't use
> it, you might think again over this sentence.

Well, that's why I used the word "unobstructed".  But I could easily change it
to:

  "the minimum required amount of unobstructed vertical whitespace between the
skylines of the two items."

Though that's slightly inaccurate, since markups don't have skylines, as far as
I know.  But the idea may be clearer anyway.

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:246: reference point of a system is the
middle line of the nearest
On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> For markups, things are different (and yet to
> specify).

You mean code-wise, I presume (I did cover markups in this paragraph).

> It'd make sense to use either the top or bottom
> corner of a markup depending on where the
> specified space lies...

That would be my preference.

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:248: @code{padding} or
@code{minimum-distance} are not meaningful,
On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> Yes, they are.  They can be stretched, and the
> resulting space will be larger than padding or
> minimum-distance.

"Yes they are meaningful", or "yes they are possible"?  Can you give a
meaningful example where

  space < padding < minimum-distance

such that the behavior changes when space is increased to equal
minimum-distance?  Are there cases where setting space below padding and/or
minimum-distance is necessary to achieve some desired effect?

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:264: @code{+inf.0}.
On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> Again, it's a reference.  We can mentioned Hooke's
> law, don't we?

Okay, here we go...

  Hooke's law:  F=-kx

  "x" is the displacement of the end of the spring
  from its equilibrium position (in SI units: "m");

  "F" is the restoring force exerted by the material
  (in SI units: N or kg·m/s^2); and

  "k" is the force constant (or spring constant) (in
  SI units: N/m or kg/s^2).

So, according to Joe, stretchability is equal to 1/k.  So, if we use "s" for
stretchability, then

   F=-x/s

Now, hopefully you realize that this is completely uninformative unless we
explain the following, all of which remain unclear to me:

1) what is the "equilibrium position" of the stretchable space?

2) what is its "displacement" from the equilibrium?

3) what is the "restoring force" exerted by the stretchable space and what is
its unit of measurement?

> Joe said that a reasonable default for
> stretchability is space, because this keeps
> proportions of 'space values and actual whitespace
> constant, if possible due to the constraints.

I don't mean to be difficult, but this still confuses me.  What is the unit of
measurement of stretchability?  If the stretchable space were a spring, we could
speak of an "inverse Newton" or "time squared divided by mass" (s^2/kg).  So
then with regard to the stretchable space, what is the "time" and what is the
"mass"?

Consequently, when 'stretchability equals 'space, what are the resulting values
of the "displacement" and "restoring force"?  And what is it about those values
that "keeps proportions of 'space values and actual whitespace constant (where
possible)"?

I feel that simply mentioning Hooke's law does little to help the LilyPond user
understand how to select meaningful values to achieve the desired vertical
spacing.  Is there anyone here for whom the Hooke's law analogy clarifies the
spacing behavior?  (Carl?)

> (and actually, why isn't this the default)?

That's a good question.

[Carl, 2010-10-02 16:32:06]

On 2010/10/02 16:09:22, Mark Polesky wrote:
 On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> > Again, it's a reference.  We can mentioned Hooke's
> > law, don't we?
> 
> Okay, here we go...
> 
>   Hooke's law:  F=-kx
> 
>   "x" is the displacement of the end of the spring
>   from its equilibrium position (in SI units: "m");
> 
>   "F" is the restoring force exerted by the material
>   (in SI units: N or kg·m/s^2); and
> 
>   "k" is the force constant (or spring constant) (in
>   SI units: N/m or kg/s^2).
> 
> So, according to Joe, stretchability is equal to 1/k.  So, if we use "s" for
> stretchability, then
> 
>    F=-x/s
> 
> Now, hopefully you realize that this is completely uninformative unless we
> explain the following, all of which remain unclear to me:
> 
> 1) what is the "equilibrium position" of the stretchable space?
> 

As I understand it, the space value is the equilibrium (zero penalty) position
of the stretchable space.

> 2) what is its "displacement" from the equilibrium?
>

The displacement is the (actual proposed space) - (space)
 
> 3) what is the "restoring force" exerted by the stretchable space and what is
> its unit of measurement?

The restoring force is a penalty value that is used to calculate the location of
objects; we try to minimize the total page penalty.

So I think we get penalty = [(proposed actual space) - (space)]/stretchability

> 
> I feel that simply mentioning Hooke's law does little to help the LilyPond
user
> understand how to select meaningful values to achieve the desired vertical
> spacing.  Is there anyone here for whom the Hooke's law analogy clarifies the
> spacing behavior?  (Carl?)

Yes, I understand the Hooke's law analogy.  But it would seem to me that others
would understand how springs work, even if they don't know Hooke's law.

I'd try an explanation something like this:

When laying out a page, LilyPond makes a stack of the layout items (staves,
lyrics lines, chordnames, etc.) on the page, with a variable spacing item
between each pair of layout items.  When calculating the desired location of
each layout item, the code treats the page as if the layout items were rigid
blocks and the spacing items were springs, and the whole assembly of blocks and
springs is made to fit in the space of the page.  In order to make it fit, the
springs will be stretched or compressed.

The spacing variables affect the size and strength of the springs, as well as
the size of the rigid blocks.  'padding is added to rigid block above.  'space
determines the size of the spring -- it's the space that would be used if no
squeezing or stretching would be required to fit the systems together. 
'stretchability determines the strengths of the springs.  Higher values of
'stretchability make the spring weaker; lower values of stretchability make the
spring stronger.  'minimum-space is the shortest-possible length of the spring. 
When the space between the two layout items reaches 'minimum-space, the two
layout items can be placed no closer together.



End of sample

Now, I haven't tested this functionality carefully.  Nor have I carefully
followed it through the code.  But I have browsed the code, and tested some
spacing examples.  I believe that this is how the code works.  I'd welcome any
corrections.

Thanks,

Carl

[t.daniels_treda.co.uk, 2010-10-02 22:48:39]

markpolesky wrote Saturday, October 02, 2010 5:09 PM

> Okay, here we go...
>
>   Hooke's law:  F=-kx
>
>   "x" is the displacement of the end of the spring
>   from its equilibrium position (in SI units: "m");
>
>   "F" is the restoring force exerted by the material
>   (in SI units: N or kg·m/s^2); and
>
>   "k" is the force constant (or spring constant) (in
>   SI units: N/m or kg/s^2).
>
> So, according to Joe, stretchability is equal to 1/k.  So, if we 
> use "s"
> for stretchability, then
>
>    F=-x/s

That's not really needed.  Here's the point:

For each spring  y = -sF, so dy = -sdF  (1)

When the contents of a page are being stretched the
same force is applied to every spring, so the ratio
of the increase in length of any two springs is equal
to the ratio of their stretchabilities.

So if you need to stretch the contents of a page by
an amount y, y = sum(dy's) = -dF sum(s's)

sum(s's) is known, a constant, so that gives dF, and
then all the separate dy's can be calculated from (1).

Units are irrelevant, as it's only the ratios of the
s's that are important.

Trevor


 

[Mark Polesky, 2010-10-03 02:49:30]

On 2010/10/02 16:32:06, Carl wrote:
> When laying out a page, LilyPond makes a stack of the
> layout items (staves, lyrics lines, chordnames, etc.)
> on the page, with a variable spacing item between each
> pair of layout items.  When calculating the desired
> location of each layout item, the code treats the page
> as if the layout items were rigid blocks and the
> spacing items were springs, and the whole assembly of
> blocks and springs is made to fit in the space of the
> page.  In order to make it fit, the springs will be
> stretched or compressed.
> 
> The spacing variables affect the size and strength of
> the springs, as well as the size of the rigid blocks.
> 'padding is added to the rigid block above.  'space
> determines the size of the spring -- it's the space
> that would be used if no squeezing or stretching would
> be required to fit the systems together. 
> 'stretchability determines the strengths of the
> springs.  Higher values of 'stretchability make the
> spring weaker; lower values of stretchability make the
> spring stronger.  'minimum-space is the
> shortest-possible length of the spring.  When the
> space between the two layout items reaches
> 'minimum-space, the two layout items can be placed no
> closer together.

I like this a lot.  But I think it's misleading to say
that 'padding is added to the "rigid block" above,
because this implies that 'space is measured from the
bottom of the 'padding block, whereas 'space should be
measured (IIUC) from what I called the "reference
point" of the upper item, and when the upper item is a
title or markup, that reference point is the lowest
point of the title/markup.  So at least in that case,
the upper Y-coordinates of 'padding and 'space would
be the same.  Is that right?

These 2 paragraphs still leave 'stretchability somewhat
abstract, but this other line from Carl so far is the
most promising explanation:

penalty = [(proposed actual space) - (space)]/stretchability

I think we're a lot closer to a suitable explanation.
We still need to go through and agree what the most
natural "reference points" are, and then make sure the
code agrees with that.

- Mark

[Carl, 2010-10-03 03:08:54]

On 2010/10/03 02:49:30, Mark Polesky wrote:
> On 2010/10/02 16:32:06, Carl wrote:
> > When laying out a page, LilyPond makes a stack of the
> > layout items (staves, lyrics lines, chordnames, etc.)
> > on the page, with a variable spacing item between each
> > pair of layout items.  When calculating the desired
> > location of each layout item, the code treats the page
> > as if the layout items were rigid blocks and the
> > spacing items were springs, and the whole assembly of
> > blocks and springs is made to fit in the space of the
> > page.  In order to make it fit, the springs will be
> > stretched or compressed.
> > 
> > The spacing variables affect the size and strength of
> > the springs, as well as the size of the rigid blocks.
> > 'padding is added to the rigid block above.  'space
> > determines the size of the spring -- it's the space
> > that would be used if no squeezing or stretching would
> > be required to fit the systems together. 
> > 'stretchability determines the strengths of the
> > springs.  Higher values of 'stretchability make the
> > spring weaker; lower values of stretchability make the
> > spring stronger.  'minimum-space is the
> > shortest-possible length of the spring.  When the
> > space between the two layout items reaches
> > 'minimum-space, the two layout items can be placed no
> > closer together.
> 
> I like this a lot.  But I think it's misleading to say
> that 'padding is added to the "rigid block" above,
> because this implies that 'space is measured from the
> bottom of the 'padding block, whereas 'space should be
> measured (IIUC) from what I called the "reference
> point" of the upper item, and when the upper item is a
> title or markup, that reference point is the lowest
> point of the title/markup.  So at least in that case,
> the upper Y-coordinates of 'padding and 'space would
> be the same.  Is that right?

I don't think so.  I think 'padding is added as a rigid space interval, hence my
saying that it is added to the layout item above.

'space should begin below 'padding IIUC.

> 
> These 2 paragraphs still leave 'stretchability somewhat
> abstract, but this other line from Carl so far is the
> most promising explanation:
> 
> penalty = [(proposed actual space) - (space)]/stretchability
> 

Trevor pointed out that the absolute value of 'stretchability doesn't matter. 
It's just that if one space has twice the 'stretchability of another, it will be
twice as far from the 'space value.  So it's ratios of 'stretchability of the
different spaces that makes a difference.

However, I think it is possible (although I haven't checked) that lower values
of stretchability will allow less stretching to try to fit a page, because they
should raise the penalty value for an equivalent amount of stretching.

> I think we're a lot closer to a suitable explanation.
> We still need to go through and agree what the most
> natural "reference points" are, and then make sure the
> code agrees with that.
> 

Maybe.  It may be that the most natural reference points aren't easily
available.

I think we should document what we have, and make enhancement requests for what
we would *like* to have.  I don't think the exercise of "write the documents for
what we wish we had and then change the code to match" is the best way to
proceed.  But if Joe's ok with it, then my opinion is irrelevant.

AFAICS, if spacing code is going to be fixed, it will be by Joe.

Thanks,

Carl

[joeneeman, 2010-10-03 04:50:12]

On Sat, Oct 2, 2010 at 8:08 PM, <Carl.D.Sorensen@gmail.com> wrote:

> On 2010/10/03 02:49:30, Mark Polesky wrote:
>
>> On 2010/10/02 16:32:06, Carl wrote:
>> > When laying out a page, LilyPond makes a stack of the
>> > layout items (staves, lyrics lines, chordnames, etc.)
>> > on the page, with a variable spacing item between each
>> > pair of layout items.  When calculating the desired
>> > location of each layout item, the code treats the page
>> > as if the layout items were rigid blocks and the
>> > spacing items were springs, and the whole assembly of
>> > blocks and springs is made to fit in the space of the
>> > page.  In order to make it fit, the springs will be
>> > stretched or compressed.
>> >
>> > The spacing variables affect the size and strength of
>> > the springs, as well as the size of the rigid blocks.
>> > 'padding is added to the rigid block above.  'space
>> > determines the size of the spring -- it's the space
>> > that would be used if no squeezing or stretching would
>> > be required to fit the systems together.
>> > 'stretchability determines the strengths of the
>> > springs.  Higher values of 'stretchability make the
>> > spring weaker; lower values of stretchability make the
>> > spring stronger.  'minimum-space is the
>> > shortest-possible length of the spring.  When the
>> > space between the two layout items reaches
>> > 'minimum-space, the two layout items can be placed no
>> > closer together.
>>
>
>  I like this a lot.  But I think it's misleading to say
>> that 'padding is added to the "rigid block" above,
>> because this implies that 'space is measured from the
>> bottom of the 'padding block, whereas 'space should be
>> measured (IIUC) from what I called the "reference
>> point" of the upper item, and when the upper item is a
>> title or markup, that reference point is the lowest
>> point of the title/markup.  So at least in that case,
>> the upper Y-coordinates of 'padding and 'space would
>> be the same.  Is that right?
>>
>
> I don't think so.  I think 'padding is added as a rigid space interval,
> hence my saying that it is added to the layout item above.
>
> 'space should begin below 'padding IIUC.


The attachment point of 'space doesn't depend on 'padding (or
'minimum-distance). If you think in terms of springs, the beginning of one
spring is always glued to the end of the previous one. 'padding and
'minimum-distance are only useful in determining the minimum lengths of the
springs.




 These 2 paragraphs still leave 'stretchability somewhat
> abstract, but this other line from Carl so far is the
> most promising explanation:
>

 penalty = [(proposed actual space) - (space)]/stretchability
>


Trevor pointed out that the absolute value of 'stretchability doesn't
> matter.  It's just that if one space has twice the 'stretchability of
> another, it will be twice as far from the 'space value.  So it's ratios
> of 'stretchability of the different spaces that makes a difference.
>
> However, I think it is possible (although I haven't checked) that lower
> values of stretchability will allow less stretching to try to fit a
> page, because they should raise the penalty value for an equivalent
> amount of stretching.


Trevor is correct here. The page-breaking routines use a simple and fast
heuristic for figuring out where to break pages. All of these spacing
variables are only used for the page-layout (after the page-breaking has
decided where the breaks go).




 I think we're a lot closer to a suitable explanation.
> We still need to go through and agree what the most
> natural "reference points" are, and then make sure the
> code agrees with that.
>


Maybe.  It may be that the most natural reference points aren't easily
> available.
>

The springs are always attached to the (0, 0) coordinate relative to each
staff or markup. That is, each staff or markup draws itself and returns some
stencil. The spacing code just attaches to the (0, 0) coordinate of that
stencil. For staves, it's the middle staff line (unless you fiddle with
line-positions). For markups, it used to be the baseline (I think). As long
as the various drawing routines can be altered so that the stencil is drawn
relative to its "most natural" reference point, then the spacing code will
handle it.


> I think we should document what we have, and make enhancement requests
> for what we would *like* to have.  I don't think the exercise of "write
> the documents for what we wish we had and then change the code to match"
> is the best way to proceed.  But if Joe's ok with it, then my opinion is
> irrelevant.
>

I don't have a strong opinion on this point. If you want to document the
desired behaviour and add a critical issue, I'll probably be able to fix it
in a reasonable time frame.

Cheers,
Joe

[Graham Percival (old account), 2010-10-03 16:20:04]

On 2010/10/03 04:50:12, joeneeman wrote:
> On Sat, Oct 2, 2010 at 8:08 PM, <mailto:Carl.D.Sorensen@gmail.com> wrote:
> 
> > I think we should document what we have, and make enhancement requests
> > for what we would *like* to have.  I don't think the exercise of "write
> > the documents for what we wish we had and then change the code to match"
> > is the best way to proceed.  But if Joe's ok with it, then my opinion is
> > irrelevant.
> >
> 
> I don't have a strong opinion on this point. If you want to document the
> desired behaviour and add a critical issue, I'll probably be able to fix it
> in a reasonable time frame.

If the desired behaviour is a Critical thing to fix, then go ahead and document
the desired behaviour.  If it would just be an Medium-priority enhancement
request, then document the current behaviour.

On a related note, since the spacing is in flux, I'm ok with having more
@knownissues than we have in other doc chapters.

[Graham Percival (old account), 2010-10-03 16:26:35]

LGTM, although I have no knowledge of the spacing code.

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
File Documentation/notation/spacing.itely (right):

http://codereview.appspot.com/2316042/diff/1/Documentation/notation/spacing.i...
Documentation/notation/spacing.itely:198: @strong{@i{Fixed vertical dimensions}}
Please use @subsubheading for this kind of stuff.

In the long term, we might even make "Vertical dimensions" into a @subsection,
then make things like "Fixed vertical dimensions", "Flexible vertical
dimensions", etc., into @unnumberedsubsubsec.  But for this first patch, I'd
rather keep on focusing on documenting the behaviour rather than playing games
with texinfo sectioning.  :)

[Mark Polesky, 2010-10-03 17:59:40]

I've uploaded a new patch set for review, but I still have
some questions.

First, some questions for Joe Neeman:

Joe, with commit 7d410b9 (from 2009-12-17), in NR 4.4.1
"Vertical spacing inside a system - Spacing between staves",
you wrote:
  If unset, stretchability defaults to
  space - minimum-distance.

But 4 months later, with commit d701703 (2010-04-20), in
lily/spacing-basic.cc, you wrote:
  By default, the spring will have an
  inverse_stretch_strength of space+min_dist.

Is this a contradiction?  Could you confirm the default
calculation of 'stretchability?  (Unfortunately, I don't
speak C/C++).

Also, I rewrote the 'stretchability entry; can you
double-check that there's nothing erroneous/misleading?
Should I remove the +inf.0 bit?

* * * * * * * * * *

Joe Neeman wrote:
> The springs are always attached to the (0, 0) coordinate
> relative to each staff or markup.

So then (correct me if I'm wrong) my patch here is
completely correct except for one detail: the "reference
point" of a title/markup, which could be aligned with
reality with this diff:

 result, and no stretching or compressing is in effect.  The
-reference point of a title or markup is either its highest point
-(for spaces above) or its lowest point (for spaces below).  The
+reference point of a title or markup is its highest point, and the
 reference point of a system is the middle line of the nearest

* * * * * * * * * *

Graham Percival wrote:
> Please use @subsubheading for this kind of stuff.

Done.

* * * * * * * * * *

And Alexander, are there still things you'd like me to
change after reading my rationale (re: "unobstructed",
"meaningful [values]", etc.)?

* * * * * * * * * *

Otherwise, okay to push?

- Mark

[c_sorensen, 2010-10-03 18:26:14]

On 10/2/10 10:50 PM, "Joe Neeman" <joeneeman@gmail.com> wrote:
> 
> On Sat, Oct 2, 2010 at 8:08 PM,  <Carl.D.Sorensen@gmail.com> wrote:
>> On 2010/10/03 02:49:30, Mark Polesky wrote:
>>> On 2010/10/02 16:32:06, Carl wrote:
>> 
>> I don't think so.  I think 'padding is added as a rigid space interval,
>> hence my saying that it is added to the layout item above.
>> 
>> 'space should begin below 'padding IIUC.
> 
> The attachment point of 'space doesn't depend on 'padding (or
> 'minimum-distance). If you think in terms of springs, the beginning of one
> spring is always glued to the end of the previous one. 'padding and
> 'minimum-distance are only useful in determining the minimum lengths of the
> springs.
> 

What is the difference between 'padding and 'minimum-distance, then?

> 
>> Maybe.  It may be that the most natural reference points aren't easily
>> available.
> 
> The springs are always attached to the (0, 0) coordinate relative to each
> staff or markup. That is, each staff or markup draws itself and returns some
> stencil. The spacing code just attaches to the (0, 0) coordinate of that
> stencil. For staves, it's the middle staff line (unless you fiddle with
> line-positions). For markups, it used to be the baseline (I think). As long as
> the various drawing routines can be altered so that the stencil is drawn
> relative to its "most natural" reference point, then the spacing code will
> handle it. 
>  
>> I think we should document what we have, and make enhancement requests
>> for what we would *like* to have.  I don't think the exercise of "write
>> the documents for what we wish we had and then change the code to match"
>> is the best way to proceed.  But if Joe's ok with it, then my opinion is
>> irrelevant.
> 
> I don't have a strong opinion on this point. If you want to document the
> desired behaviour and add a critical issue, I'll probably be able to fix it in
> a reasonable time frame.

Great!

Carl

[joeneeman, 2010-10-03 19:53:18]

On Sun, Oct 3, 2010 at 11:26 AM, Carl Sorensen <c_sorensen@byu.edu> wrote:

> On 10/2/10 10:50 PM, "Joe Neeman" <joeneeman@gmail.com> wrote:
> >
> > On Sat, Oct 2, 2010 at 8:08 PM,  <Carl.D.Sorensen@gmail.com> wrote:
> >> On 2010/10/03 02:49:30, Mark Polesky wrote:
> >>> On 2010/10/02 16:32:06, Carl wrote:
> >>
> >> I don't think so.  I think 'padding is added as a rigid space interval,
> >> hence my saying that it is added to the layout item above.
> >>
> >> 'space should begin below 'padding IIUC.
> >
> > The attachment point of 'space doesn't depend on 'padding (or
> > 'minimum-distance). If you think in terms of springs, the beginning of
> one
> > spring is always glued to the end of the previous one. 'padding and
> > 'minimum-distance are only useful in determining the minimum lengths of
> the
> > springs.
> >
>
> What is the difference between 'padding and 'minimum-distance, then?
>

They both add minimum-length constraints to the spring. The length of a
spring is constrained to be larger than minimum-distance and it is
constrained to be large enough so that there is at least 'padding white
space between the actual stencils. If you like, you can think of
minimum-distance as being "attached" to the same attachment point as the
spring (eg. middle staff line), while padding is "attached" to the
bottom-most part of the stencil.

Cheers,
Joe

[joeneeman, 2010-10-03 20:09:17]

On Sun, Oct 3, 2010 at 10:59 AM, <markpolesky@gmail.com> wrote:

> I've uploaded a new patch set for review, but I still have
> some questions.
>
> First, some questions for Joe Neeman:
>
> Joe, with commit 7d410b9 (from 2009-12-17), in NR 4.4.1
> "Vertical spacing inside a system - Spacing between staves",
> you wrote:
>  If unset, stretchability defaults to
>  space - minimum-distance.
>

This isn't quite accurate: actually, our "ideal" springs have two different
spring constants, one for compressing and one for stretching. The default
stretchability is (space - minimum-distance) for compressing and space for
stretching (the stretching one is probably more important in practice).


> But 4 months later, with commit d701703 (2010-04-20), in
> lily/spacing-basic.cc, you wrote:
>  By default, the spring will have an
>  inverse_stretch_strength of space+min_dist.
>
> Is this a contradiction?  Could you confirm the default
> calculation of 'stretchability?  (Unfortunately, I don't
> speak C/C++).
>

This is for horizontal spacing, not vertical spacing. Also, the comment
means to say: "if not for the next line of code, the default _would be_
space+min_dist,

>
> Also, I rewrote the 'stretchability entry; can you
> double-check that there's nothing erroneous/misleading?
> Should I remove the +inf.0 bit?
>

+inf.0 will cause a programming_error (and it will be ignored). Internally,
we use 1e7 for an almost infinitely stretchable spring.

Cheers,
Joe

[Mark Polesky, 2010-10-03 23:36:17]

Latest patch set up.  Okay to push?
- Mark

[joeneeman, 2010-10-04 00:55:37]

On Sun, Oct 3, 2010 at 4:36 PM, <markpolesky@gmail.com> wrote:

> Latest patch set up.  Okay to push?
>
> - Mark
>
> http://codereview.appspot.com/2316042/
>

It's ok with me.

[perpeduumimmobile, 2010-10-04 11:11:58]

In short: great work, push it.  Two slight remarks on skylines (I prefer the
wording in your answer on my post), and perhaps about Hooke's law.  But I don't
have a strong point on the latter.


On 2010/10/02 16:09:22, Mark Polesky wrote:
> Documentation/notation/spacing.itely:200: @table @code
> On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> > Hm. As long as vertical spacing is not absolutely
> > bullet-proof specified, I don't like to see this
> > sections deleted. [...]
> Are you saying you'd prefer to define the four keys individually
> for each of the eight variables?

Okay, I withdraw...  I somehow thought there are places where markups have their
"origin" on the top, and others on the bottom, but this is plainly wrong.  Looks
like this is still in a flux...  But when we have the natural choices, we should
include them in the docs.  (Distance USA - Portugal from L.A. ...)

> Documentation/notation/spacing.itely:239: the combined items.
> On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> > Yes, but this somehow sounds like a rectangle you
> > can put between two staves or something, and this
> > is _not_ correct (because padding specifies
> > whitespace between the skylines).  I'm not sure
> > why we avoid the "skyline" term in the NR; it's
> > not too hard a concept IMHO.  But if we don't use
> > it, you might think again over this sentence.
> 
> Well, that's why I used the word "unobstructed".  But I could
> easily change it to: 
>   "the minimum required amount of unobstructed vertical whitespace
>   "between the skylines of the two items."
> Though that's slightly inaccurate, since markups don't have skylines, as far
as
> I know.  But the idea may be clearer anyway.

I'd prefer this, but that's just me...

> Documentation/notation/spacing.itely:246: reference point of a system is the
> middle line of the nearest
> On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> > For markups, things are different (and yet to
> > specify).
> You mean code-wise, I presume (I did cover markups in this paragraph).

Yup.

> Documentation/notation/spacing.itely:248: @code{padding} or
> @code{minimum-distance} are not meaningful,
> On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> > Yes, they are.  They can be stretched, and the
> > resulting space will be larger than padding or
> > minimum-distance.
> 
> "Yes they are meaningful", or "yes they are possible"?

"Yes they are possible."  I admit I can't tell you an example, but I'll never
say it will never be useful... ;-)

> Documentation/notation/spacing.itely:264: @code{+inf.0}.
> On 2010/10/02 09:17:16, perpeduumimmobile wrote:
> > Again, it's a reference.  We can mentioned Hooke's
> > law, don't we?
> 
> Okay, here we go... [...]

Oops, sorry.  I just meant a sentence like "stretchability is the inverse spring
constant in Hooke's law", perhaps in parenthesis; your explanation is perfect! 
It's just for those who already know the law that they have the right (or even
better) understanding from just one sentence.  I would not expect a physicist's
explanation of the law...

> I feel that simply mentioning Hooke's law does little to help the LilyPond
user

Well, not each and every one, but some of the users are math- and
science-addicts, and quite a number of them will have heard of the law.