Issue 5364048: Adds some info about pure properties to the CG. (Closed)
|
Created:
13 years, 4 months ago by MikeSol Modified:
13 years, 4 months ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionAdds some info about pure properties to the CG.
Patch Set 1 #Patch Set 2 : Compiles in make all #
Total comments: 15
Patch Set 3 : Incorporates suggestions from Keith and Joe. #
Total comments: 1
Patch Set 4 : Adds @end itemize #MessagesTotal messages: 11
passes make and a full make doc. James
Sign in to reply to this message.
sure, looks fine. It's more important to get stuff into the CG than it is to fuss about the formatting or literary references. http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... File Documentation/contributor/programming-work.itexi (right): http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1805: example; Stem #'length has a pure property that will @emph{always} normally we'd want a @code{} around this, but you can push it as-is and just make a minor change later. oh wait, this is the CG. never mind; it's fine as-is. http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1820: Of course, like Gregory Peck and Tintin, some Grobs will have properties ... what? I get Tintin, but "Gregory Peck" ?
Sign in to reply to this message.
http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... File Documentation/contributor/programming-work.itexi (right): http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1836: LilyPond). Purity is not only about returning predictable values. It's also about not having any side effects. http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1844: meaningful notion of estimation. For example, even if a color was I would argue that the reason for lacking pure estimation for color is that we haven't found a use for it rather than because of any intrinsic properties of color. http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1888: taken from the stencil. Actually, the requirement is different: the print function must not have any side effects. The print function doesn't necessarily have to deliver the same result at all stages in the compilation process. For example, if some side-effect modifies the font size of a grob mid-compilation, then note-head::print will deliver a stencil of a different height. http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1901: @end itemize I think the preceding four lists can be understood as follows: if you have a Grob and you want to estimate its height, what can you do? - If its Y-extent callback is pure, just use it (pure-functions) - If its Y-extent callback is ly:grob::stencil-height and the stencil callback is pure, then it's safe to use ly:grob::stencil-height (pure-print-functions) - If we have a manually-created pure version of its Y-extent callback, use that (pure-conversions-alist and pure-print-to-height-conversions)
Sign in to reply to this message.
On Nov 16, 2011, at 2:19 AM, joeneeman@gmail.com wrote: > > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... > File Documentation/contributor/programming-work.itexi (right): > > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... > Documentation/contributor/programming-work.itexi:1836: LilyPond). > Purity is not only about returning predictable values. It's also about > not having any side effects. > > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... > Documentation/contributor/programming-work.itexi:1844: meaningful notion > of estimation. For example, even if a color was > I would argue that the reason for lacking pure estimation for color is > that we haven't found a use for it rather than because of any intrinsic > properties of color. > True. Text changed. > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... > Documentation/contributor/programming-work.itexi:1888: taken from the > stencil. > Actually, the requirement is different: the print function must not have > any side effects. The print function doesn't necessarily have to deliver > the same result at all stages in the compilation process. For example, > if some side-effect modifies the font size of a grob mid-compilation, > then note-head::print will deliver a stencil of a different height. > Then I misunderstood what pure means in lily-speak. I thought that a pure function had the dual condition that it (a) always return the same value for a given begin and end range; and (b) not trigger any side effects. Are there any cases where pure functions do deliver different results for the same range before line breaking? And, if not, would this even be conceivable/desirable? Lastly, the idea of "not trigger any side effects" is something that I grok more than I understand. Is there any way to communicate what it means to "not trigger side effects" (i.e. never calls (or results in the calling of) set_property on another property with a pure estimation, etc.) to someone who doesn't know what these side effects are? > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... > Documentation/contributor/programming-work.itexi:1901: @end itemize > I think the preceding four lists can be understood as follows: if you > have a Grob and you want to estimate its height, what can you do? > > - If its Y-extent callback is pure, just use it (pure-functions) > - If its Y-extent callback is ly:grob::stencil-height and the stencil > callback is pure, then it's safe to use ly:grob::stencil-height > (pure-print-functions) > - If we have a manually-created pure version of its Y-extent callback, > use that (pure-conversions-alist and pure-print-to-height-conversions) I agree, but is this not clear from the document as it stands and, if not, how should it be modified so that it is clear? My biggest worry is clarity, as I often don't understand what I'm saying, so I'd imagine that others will have an even harder time. Thanks for your feedback! Cheers, MS
Sign in to reply to this message.
Bah, I just wrote out a nice reply on the codereview site and it got eaten... On Fri, Nov 18, 2011 at 12:03 AM, mike@apollinemike.com < mike@apollinemike.com> wrote: > On Nov 16, 2011, at 2:19 AM, joeneeman@gmail.com wrote: > > > > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... > > Documentation/contributor/programming-work.itexi:1888: taken from the > > stencil. > > Actually, the requirement is different: the print function must not have > > any side effects. The print function doesn't necessarily have to deliver > > the same result at all stages in the compilation process. For example, > > if some side-effect modifies the font size of a grob mid-compilation, > > then note-head::print will deliver a stencil of a different height. > > > > Then I misunderstood what pure means in lily-speak. I thought that a pure > function had the dual condition that it (a) always return the same value > for a given begin and end range; and (b) not trigger any side effects. > > Are there any cases where pure functions do deliver different results for > the same range before line breaking? And, if not, would this even be > conceivable/desirable? > I can't think of a situation where it's desirable, but it's certainly conceivable. If I write lily code that, for whatever reason, has a callback which changes Slur 'height-limit then Slur::calc_pure_height will also change. We tend to avoid the use of set_property after the translation step, so this sort of thing is unlikely; the point is, though, that the pure callback itself doesn't worry about such things. It just tries to avoid side-effects, and if something else with side effects messes with grob properties then the pure callback can change its value accordingly. Lastly, the idea of "not trigger any side effects" is something that I grok > more than I understand. Is there any way to communicate what it means to > "not trigger side effects" (i.e. never calls (or results in the calling of) > set_property on another property with a pure estimation, etc.) to someone > who doesn't know what these side effects are? > The main side effects in lilypond are set_property, set_object and suicide. These are easy to avoid; the trickier part is that any call to get_property could conceivably trigger a callback that will itself have side effects. > > > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... > > Documentation/contributor/programming-work.itexi:1901: @end itemize > > I think the preceding four lists can be understood as follows: if you > > have a Grob and you want to estimate its height, what can you do? > > > > - If its Y-extent callback is pure, just use it (pure-functions) > > - If its Y-extent callback is ly:grob::stencil-height and the stencil > > callback is pure, then it's safe to use ly:grob::stencil-height > > (pure-print-functions) > > - If we have a manually-created pure version of its Y-extent callback, > > use that (pure-conversions-alist and pure-print-to-height-conversions) > > I agree, but is this not clear from the document as it stands and, if not, > how should it be modified so that it is clear? My biggest worry is > clarity, as I often don't understand what I'm saying, so I'd imagine that > others will have an even harder time. > I'm not sure which version is better for new readers. It's just that you're explaining these lists in terms of what they contain, while I find it easier to think of them in terms of their role in call-pure-function (which also helps to explain why we would bother to have these lists in the first place). Cheers, Joe
Sign in to reply to this message.
On Sun, 20 Nov 2011 15:19:03 -0800, Joe Neeman wrote: > Bah, I just wrote out a nice reply on the codereview site and it got > eaten... > > On Fri, Nov 18, 2011 at 12:03 AM, mike@apollinemike.com [3] wrote: > >> On Nov 16, 2011, at 2:19 AM, joeneeman@gmail.com [1] wrote: >> >> > >> > > http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... >> [2] >> > Documentation/contributor/programming-work.itexi:1888: taken >> from the >> > stencil. >> > Actually, the requirement is different: the print function must >> not have >> > any side effects. The print function doesn't necessarily have to >> deliver >> > the same result at all stages in the compilation process. For >> example, >> > if some side-effect modifies the font size of a grob >> mid-compilation, >> > then note-head::print will deliver a stencil of a different >> height. >> > >> >> Then I misunderstood what pure means in lily-speak. I thought >> that a pure function had the dual condition that it (a) always >> return the same value for a given begin and end range; and (b) not >> trigger any side effects. >> >> Are there any cases where pure functions do deliver different >> results for the same range before line breaking? And, if not, >> would this even be conceivable/desirable? > > I can't think of a situation where it's desirable, but it's certainly > conceivable. If I write lily code that, for whatever reason, has a > callback which changes Slur 'height-limit then Slur::calc_pure_height > will also change. We tend to avoid the use of set_property after the > translation step, so this sort of thing is unlikely; the point is, > though, that the pure callback itself doesn't worry about such > things. > It just tries to avoid side-effects, and if something else with side > effects messes with grob properties then the pure callback can change > its value accordingly. > >> Lastly, the idea of "not trigger any side effects" is something > that >> I grok more than I understand. Is there any way to communicate >> what it means to "not trigger side effects" (i.e. never calls (or >> results in the calling of) set_property on another property with a >> pure estimation, etc.) to someone who doesn't know what these side >> effects are? > > The main side effects in lilypond are set_property, set_object and > suicide. These are easy to avoid; the trickier part is that any call > to get_property could conceivably trigger a callback that will itself > have side effects. OK, will write some more prose. > > xi#newcode1901 >> > Documentation/contributor/programming-work.itexi:1901: @end >> itemize >> > I think the preceding four lists can be understood as follows: >> if you >> > have a Grob and you want to estimate its height, what can you >> do? >> > >> > - If its Y-extent callback is pure, just use it (pure-functions) >> > - If its Y-extent callback is ly:grob::stencil-height and the >> stencil >> > callback is pure, then it's safe to use ly:grob::stencil-height >> > (pure-print-functions) >> > - If we have a manually-created pure version of its Y-extent >> callback, >> > use that (pure-conversions-alist and >> pure-print-to-height-conversions) >> >> I agree, but is this not clear from the document as it stands and, >> if not, how should it be modified so that it is clear? My biggest >> worry is clarity, as I often don't understand what I'm saying, so >> I'd imagine that others will have an even harder time. >> >> I'm not sure which version is better for new readers. It's just >> that you're explaining these lists in terms of what they contain, >> while I find it easier to think of them in terms of their role in >> call-pure-f > h also helps to explain why we would bother to have these lists in > the first place). I'm going to leave it this way if that's all right with you for the purely selfish reason that I grasp these lists better in terms of what they contain. This then can be edited later by anyone who wants to improve the ease of reading of the document (which I'm sure can benefit from other changes as well - I hope that someone who has no clue about pure properties actually takes the time to read this thing so that I can learn what is graspable on a first read and what is not). The AMSTERDAM AIRPORT is currently blocking me from uploading the patch set (Han-Wen...Jan...do something...), but I'll get it up on Rietveld once I'm back in a civilized country. Cheers, MS
Sign in to reply to this message.
On 2011/11/21 07:44:36, mike_apollinemike.com wrote: > I'm going to leave it this way if that's all right with you for the > purely selfish reason that I grasp these lists better in terms of what > they contain. That's definitely ok with me. Thanks for taking the time to document this!
Sign in to reply to this message.
http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... File Documentation/contributor/programming-work.itexi (right): http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1832: a @emph{prima face}. If you write a pure-function, you are promising What does 'prima face' mean? http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1858: @var{start} and @var{end} is facultative, as items only occupy one 'facultative' is an odd word here. I guess you mean it in the sense of 'optional', where the user of the optional thing can turn to a substitute if it is not provided. Then just say start and end are optional parameters where the function provides the defaults. http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1861: @var{end} are important, as we may can get a `purer' estimation of a I'm getting confused. "pure(lilypond)" generally means 'crappy' in the sense of pure-height of a slur being the crappy estimate of height one can get without triggering the line-breaking and note-spacing. When you say 'purer' above, you seem to be using the superlative of "pure(English)" rather than "pure(LilyPond)". http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1913: LilyPond is smart enough to know if a series of chained functions are So if one function in the series has no pure equivalent, but you call the first function at a time when only pure functions may be called, what is LilyPond smart enough to do? http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1959: Pure Y values should be used in any functions that are called before should or must? http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1996: overly-distort the Y-extent of an system, which could result in a very extra-spacing-height does not distort the Y-extent http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1997: @q{loose} looking score with lots of space between systems. So, to Prove it. http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:2041: not be changed later in the compiling process due to other changes? This sounds like "pure(ComputerScience)" in the sense of a function that depends only on its arguments, not on any other program state. Does "pure(LilyPond)" include this concept.
Sign in to reply to this message.
http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... File Documentation/contributor/programming-work.itexi (right): http://codereview.appspot.com/5364048/diff/4001/Documentation/contributor/pro... Documentation/contributor/programming-work.itexi:1832: a @emph{prima face}. If you write a pure-function, you are promising On 2011/11/21 08:02:00, Keith wrote: > What does 'prima face' mean? That would be "prima facie" and mean "at first sight". Which does not make all that much sense in this context.
Sign in to reply to this message.
http://codereview.appspot.com/5364048/diff/11002/Documentation/contributor/pr... File Documentation/contributor/programming-work.itexi (right): http://codereview.appspot.com/5364048/diff/11002/Documentation/contributor/pr... Documentation/contributor/programming-work.itexi:1809: @item @code{suicide} Mike you need an @end itemize Here else it doesn't compile. Make fails. @itemize @item @item @end itemize
Sign in to reply to this message.
|
