Re: Extending: 2.3.2 - Music Function usage (issue 108110043 by address@hidden)

[dak]

https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/programming-interface.itely
File Documentation/extending/programming-interface.itely (right):

https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/programming-interface.itely#newcode337
Documentation/extending/programming-interface.itely:337: @node Music
function usage
I think I'm responsible for most of this section.  What an
incomprehensible mess.  Definitely a good idea to clean this up, but you
are probably keeping too close to my original.  Basically, the original
text was focused around categorizing several cases with different
syntactic behavior due to parser/syntax artifacts.  Most of that has
been levied by now.  I'll try to point out what is left.

A "music function" has to return an expression matching the predicate
ly:music?.  This makes music function calls suitable as argument of type
ly:music? for another music function call.

When using a music function call in other contexts, the context may
cause further semantic restrictions.

https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/programming-interface.itely#newcode346
Documentation/extending/programming-interface.itely:346: At the top
level in a music expression.  No restrictions apply here.
Well, not your fault, but at top level LilyPond does not actually accept
a post-event.  That's been the case since issue 3012, version 2.17.10.

https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/programming-interface.itely#newcode349
Documentation/extending/programming-interface.itely:349: As a
post-event, explicitly started with a direction indicator (one of
When a music function (as opposed to an event function) returns an
expression of type post-event, LilyPond requires one of the named
direction indicators in order to properly integrate the post-event
produced by the music function call into the surrounding expression.

https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/programming-interface.itely#newcode352
Documentation/extending/programming-interface.itely:352: In this case,
you can't use an @emph{open} music expression as the last
This paragraph can be stricken as of issue 3723, version 2.19.0.  Yeah!

https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/programming-interface.itely#newcode362
Documentation/extending/programming-interface.itely:362: The special
rules for trailing arguments make it possible to write
"The special rules for trailing arguments" is nonsense that may have had
some rooting in reality a long time ago.  But even then, this was just
ominous hand-waving.

The point was that you can use \tweak, a music function, on post-events,
chord constituents (which required totally different semantics before
issue 2240, version 2.15.28) and top level music expressions.

At the current point of time, there is probably not much of a point in
distinguishing more than post-event and non-post-event here.  Being able
to use a music function inside of a chord is nice enough to be worth
mentioning, but there are no specific syntactic restrictions associated
with it any more.

https://codereview.appspot.com/108110043/