|
|
Created:
9 years, 9 months ago by pkx166h Modified:
9 years, 8 months ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionExtending: 2.3.2 - Music Function usage
Issue 3955
Added words to sentences for clarity. (Hopefully) Improved sentence
syntax and some minor grammer nits.
Patch Set 1 #
Total comments: 2
Patch Set 2 : Trevor's suggestions #
Total comments: 10
Patch Set 3 : David K's suggestions - please check as I don't really understand this technically. #MessagesTotal messages: 7
Alternative suggestion. Trevor https://codereview.appspot.com/108110043/diff/1/Documentation/extending/progr... File Documentation/extending/programming-interface.itely (right): https://codereview.appspot.com/108110043/diff/1/Documentation/extending/progr... Documentation/extending/programming-interface.itely:341: parse them unambiguously. The result a music function returns must be This first sentence makes no sense. The original two sentences are clearer. How about the following as an alternative: Move the sentence about the return value to the first in the paragraph, followed with "In order to parse a music function unambiguously, the following context-dependent restrictions apply:" Trevor
Sign in to reply to this message.
Trevor's suggestions
Sign in to reply to this message.
Thanks Trevor https://codereview.appspot.com/108110043/diff/1/Documentation/extending/progr... File Documentation/extending/programming-interface.itely (right): https://codereview.appspot.com/108110043/diff/1/Documentation/extending/progr... Documentation/extending/programming-interface.itely:341: parse them unambiguously. The result a music function returns must be On 2014/06/22 16:54:04, Trevor Daniels wrote: > This first sentence makes no sense. The original two sentences are clearer. > > How about the following as an alternative: > > Move the sentence about the return value to the first in the paragraph, followed > with > > "In order to parse a music function unambiguously, the following > context-dependent restrictions apply:" > > Trevor Done, thanks that does look better (even I understand it!).
Sign in to reply to this message.
https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... File Documentation/extending/programming-interface.itely (right): https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... 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/p... 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/p... 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/p... 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/p... 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.
Sign in to reply to this message.
David K's suggestions - please check as I don't really understand this technically.
Sign in to reply to this message.
Thanks David, Please check my changes as I really don't pretend to understand this other than from a conceptual basis. https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... File Documentation/extending/programming-interface.itely (right): https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... Documentation/extending/programming-interface.itely:337: @node Music function usage On 2014/06/23 07:46:23, dak wrote: > 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. Done. https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... Documentation/extending/programming-interface.itely:346: At the top level in a music expression. No restrictions apply here. On 2014/06/23 07:46:23, dak wrote: > 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. Done. https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... Documentation/extending/programming-interface.itely:349: As a post-event, explicitly started with a direction indicator (one of On 2014/06/23 07:46:23, dak wrote: > 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. Done. https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... Documentation/extending/programming-interface.itely:352: In this case, you can't use an @emph{open} music expression as the last On 2014/06/23 07:46:23, dak wrote: > This paragraph can be stricken as of issue 3723, version 2.19.0. Yeah! Done. https://codereview.appspot.com/108110043/diff/20001/Documentation/extending/p... Documentation/extending/programming-interface.itely:362: The special rules for trailing arguments make it possible to write On 2014/06/23 07:46:24, dak wrote: > "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. Done.
Sign in to reply to this message.
authorJames Lowe <pkx166h@gmail.com> Sat, 21 Jun 2014 11:48:55 +0000 (12:48 +0100) committerJames Lowe <pkx166h@gmail.com> Wed, 2 Jul 2014 17:52:11 +0000 (18:52 +0100) commitefbd70007a36271965a57cd45a2ecad5eabb1c1c
Sign in to reply to this message.
|