More questions on beam properties

[Andrew Bernard]

What does the property Beam.positions actually represent? I have seen code that treats it as the y position coordinates of the end points of the beam, but I cannot make sense of this. Nor can I make sense of the manual page for Beam, which gives, as far as I can see, negative information! -

positions (pair of numbers):

beam::place-broken-parts-individually

Pair of staff coordinates (left . right), where both left and right are in staff-space units of the current staff. For slurs, this value selects which slur candidate to use; if extreme positions are requested, the closest one is taken.

How anybody can read that and understand what it says about beams is somewhat beyond me. This makes it difficult to program with the properties in question. What on earth is ‘beam::place-broken-parts-individually’ in the context of beam start end vertical positioning? Dear me.

[I hate to continually complain about the IR manuals, and I dearly wish I was in a position to understand this material enough to rewrite these unclear sections, but I apologise, I don’t.]

I can post scheme code to clarify my question and show the strange behaviour of Beam.properties if requested, but I thought I would ask the qualitative question first, as it is most likely to be just my failure to grasp what the manual is trying to say.

Andrew