Re: vert. spacing: Rename properties (lily, scm). (issue3031041)

[Carl . D . Sorensen]

On 2010/11/11 03:53:44, Mark Polesky wrote:
> Here's a new patch-set for renaming the vertical spacing
> grob properties.  But...

> I'm kind of going in circles trying to decide where to put
> some things:

> 1) individual alist-key descriptions
> 2) individual grob-property descriptions
> 3) non-staff line reference-points

> I wanted to move the property descriptions to the IR.  Easy
> enough, and this removes clutter from the NR.

I'm not sure exactly what you're talking about here -- we don't have a
patch covering this part.

I'm a little concerned with the verbosity of the property descriptions
in the IR.  Such verbose descriptions represent a change in style that I
think might need to be discussed.

> Now, the
> alist-keys -- currently they're explained via a
> cross-reference to the section on the \paper variables.
> However, I began to think that a better place for the
> alist-key descriptions is at the top of the
> axis-group-interface page in the IR

In my opinion, this is too much detail in the IR.

> (much like the 'details
> keys are explained at the top of the beam-interface page).

The details keys are not really explained -- it's more that they're
listed.

> But it felt weird to refer to "reference points" in the IR
> without also explaining them too, so I included the table
> explaining that, and now the axis-group-interface page is
> looking cluttered.

Yes -- IMO it's definitely too much.  Go ahead and leave the "reference
points" in the IR without explanation.


> Furthermore, if I'm going to put alist-key descriptions on
> the axis-group-interface page, I really should put them also
> on the staff-grouper-interface page, so now things seem even
> more cluttered than before.

I agree.  In order to avoid clutter, these need to be more terse, I
think.


> One thing that may help is a dedicated
> vertical-axis-group-interface page, which we don't currently
> have.  Shouldn't we add one?

> Anyway, this patch set ends up having some duplication:

> reference-points are discussed in
>    NR 4.4.1 Within-system spacing properties

Keep this one.

>    IR 3.2.7 axis-group-interface

Lose this one, IMO.


> spacing alist-keys are discussed in
>    NR 4.1.2 Flexible vertical dimensions

Keep this one.

>    IR 3.2.7 axis-group-interface
>    IR 3.2.97 staff-grouper-interface

Lose (or severely trim) these, IMO.


> If anyone has a better idea, let me know.

I actually really like the way it's currently done in the IR.
next-staff-spacing has the description of the alist properties; all the
rest of the spacing properties just refer to next-staff-spacing.

I think that staff-staff-spacing should probably have the description,
and everything else should refer to staff-staff-spacing.

I appreciate your working hard on this project.  It's a HUGE project,
and I think it will make a big difference to the LilyPond documentation.

But I do have a concern that it's too verbose, in general.  Way back in
the dark ages when we started on the GDP, Graham said something that I
didn't really agree with, but now I do.  Basically it was "You'll know
we've got good documentation when we can't think of anything else to
remove".  He was speaking of the Notation Reference, not the Learning
Manual, which should be a bit less terse.

I think in this proposed patch there is some stuff that can be removed.
It seems too much in Learning Manual style, and not enough in Notation
Reference style.

That being said, you're much more of an expert on this than me.  And I
think this patch is better than what's currently there.  It would be an
improvement to have it, so I wouldn't stand in its way.

Thanks for the great work!

Carl


http://codereview.appspot.com/3031041/