Documentation about unpure-pure containers is unclear

[Pavel Roskin]

Hello!

The issue 2275 has "Patch-needs_work" now.  I guess the needed work is
asking some questions in the list, so that the documentation becomes
easier to understand and the example would actually illustrate it.

This is the page I'm taking about:
http://lilypond.org/doc/v2.15/Documentation/notation/unpure_002dpure-containers

Quote:

"When a function overrides a Y-offset and/or Y-extent it is assumed that
this will trigger line breaking calculations too early during
compilation. So the function is not evaluated at all"

squareLineCircleSpace doesn't override Y-offset or Y-extent, yet the
output is ugly.  Why?

Why do stems have to be hidden?  Do they force calculations that would
otherwise be delayed?  Or do they reserve horizontal space that the
noteheads with overridden stencil won't reserve?

Why is this showing correct output?

roundNotes = {
  \override NoteHead #'stencil = #(make-circle-stencil 0.5 0.1 #f)
}
smartRoundNotes = {
  \roundNotes
  \override NoteHead #'Y-extent =
   #(ly:make-unpure-pure-container
      ly:grob::stencil-height
      (lambda (grob start end) (ly:grob::stencil-height grob)))
}
\new Voice
\relative c'' {
  \time 4/1
  \roundNotes
  cis1 ces cisis c
  \smartRoundNotes
  cis1 ces cisis c
}

And why does the output break if roundNotes is rewritten with a
lambda?

roundNotes = {
  \override NoteHead #'stencil =
   #(lambda (grob) (make-circle-stencil 0.5 0.1 #f))
}

What's so different between the above stencil definitions?  Does
Lilypond actually try to classify functions as pure and unpure by
parsing them?

-- 
Regards,
Pavel Roskin