Re: ly:grob-system not working as expected

[Mark Polesky]

David Kastrup wrote:


> Marek Klein <address@hidden> writes:
>>>  ly:grob-system only returns the system after is has been set in the
>>>  PaperColumn which is after line breaking.  What you see as #<Grob
>>>  System > above is a single system encompassing the entire score.
>> 
>>  Sorry, I do not understand this language... do we need a tracker issue here
>>  or not?
> 
> Well, ly:grob-system could probably make do with a better DOC string
> along the above lines.  So this might be worth a Documentation issue in
> order to not let this be forgotten.

Actually, I would say the vast majority of scheme functions
in that list ought to have clearer docstrings:
http://lilypond.org/doc/v2.17/Documentation/internals/scheme-functions

Those docstrings read like they're written from one core
developer to another, whereas medium-advanced users (like
myself) are left swimming in confusion, which is a shame,
because this is the page we end up consulting when we're
trying to write our own callbacks and music-functions.

Here are some examples of things that were not at all 
obvious to people like me: 

ly:grob-object should mention that it is used to access the 
`internal properties' listed on the grob-interface pages.

ly:make-stencil should describe how the `expression'
argument can be constructed.

ly:prob-immutable-properties should describe the difference
between `mutable' and `immutable'.

ly:grob-system should incorporate David's description from
earlier in this thread.

etc.

There are probably many more things to add, but I wouldn't
know, because I don't understand most of them.

Again, what's the protocol here, should I wait for someone
on the bug squad to add a tracker issue, or should I add it
myself?

Thanks
- Mark