#5262 LM: incorrect staff-staff-spacing example (regression)

[Simon Albrecht]

Reported by Paul Hodges:

In the example on the documentation page

http://lilypond.org/doc/v2.19/Documentation/learning/building-a-score-from-scratch
the command
\override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
is used to modify the spacing of the pedal staff in an organ score.

The result shown on the documentation page (which I also get at home
with 2.19.80) does not match the result on the corresponding page for
2.18, and is clearly wrong.

[Torsten Hämmerle]

A critical error sounds pretty intimidating, but nevertheless, I've had a look...

What's the goal?

By default, when a score has to vertically streched, LilyPond will keep grouped staves closer together and allow bigger gaps between the groups.
In organ music, however, the three staves should equally spaced, even if the two manual staves are grouped by a PianoStaff.

The example coding attemps to reduce the stretchability between manual two and pedal stave.

Analysis

In the LilyPond documentation coding, only one single property of staff-staff-spacing is set:

\override VerticalAxisGroup.staff-staff-spacing.stretchability = 5

That way, all the other sub properties still are unset and so we have a 0 basic-distance, a 0 minimum-distance and 0 padding.
Result: Manual two stave and pedal stave stick together.

We definitely have to specify a full set of sub properties and everything will work as desired.

\override VerticalAxisGroup.staff-staff-spacing = #'((basic-distance . 9)
                                                         (minimum-distance . 7)
                                                         (padding . 1)
                                                         (stretchability . 5))

Why did it "work" in 2.18.2?

The plain truth is that it actually didn't work at all in 2.18.2!
I've even re-installed an old 2.14.2 LilyPond to see that it didn't work there, either.

In fact, the
\override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
statement didn't have any effect, because the attempetd \override was unsuccessful:

Reason:
The assignment of VerticalAxisGroup.staff-staff-spacing.stretchabiliy failed.
See log:

warning: type check for `staff-staff-spacing' failed; value `5' must be of type `list'

As a result, staff-staff-spacing hasn't been changed and therefore, the staves didn't collapse. The stretchability wasn't changed as desired, either.

Now, in version 2.19, this syntax works and the effect of 0 distance is much more strinking than the unsuccessful stretchability override of former releases.

Solution

Specify a full set of staff-staff-spacing sub properties. as proposed in "Analysis".
I'll upload a patch shortly.
I had to re-install my LilyDev due to virtual disk problems that prevented me from complilng the documentation. Let's see...

By the way: the German explanatory text (and only the German as far as I've seen) even mentions the fact that a full set of variables has to be supplied:
"Im Moment kann man nicht nur die strechability {sic!] (Spreizbarkeit)-Untereigenschaft verändern, darum müssen hier auch die anderen Untereigenschaften kopiert werden."

All the best,
Torsten

[Trevor Daniels]

In this example of the Learning Manual we do not want to introduce all the complexity of flexible vertical spacing. I'd suggest we simply replace stretchability with minimum-distance. This

\override VerticalAxisGroup.staff-staff-spacing.minimum-distance = 9

seems to work perfectly well and is quite understandable in the context of the LM.