Re: Is the cosine page wrong?
On 12/28/20 11:29 PM, Peter Scott wrote: On 12/28/20 10:57 PM, ToddAndMargo via perl6-users wrote: On 12/28/20 4:54 AM, Richard Hainsworth wrote: So please take what I say now as a plea for you to adapt a little, not to get pissed off with us even though you do seem to have pissed some of us off. You have very definite ideas about what the documentation should and shouldn't be. You have stated them over and over again. The Raku community at large - based on replies from multiple individuals over the years - disagrees with you. The Raku community has come to the concensus that there is a distinction between Tutorials and Reference, and that the Documentation site should contain both. Tutorials define how to use some aspect of Raku, with example text and explanation. Reference tries to cover as much of the language as possible, covering all the methods/subs/names/types etc as possible. Reference is written for a person who already knows how to program and who uses Raku. The assumption is that if a person reading a reference does not understand some term, then s/he will search in the documentation on that term to understand it. No set of documentation standards will please everyone - that's life. Even so, there ARE STILL areas of the Raku documentation that are lacking (just look at the issues on the Documentation repository, any of them raised by our indefatigable JJ). Hi Richard, When deciding to write a technical article, the VERY FIRST thing you have to do is determine your TARGET AUDIENCE. In a single sentence, please state for me what you believe the TARGET AUDIENCE is for the documentation. Richard stated the target audience for reference documentation quite clearly: Someone who already knows how to program and uses Raku. Multiple people have told you many times over several years that the purpose of reference documentation is to provide a complete description of the elements of a language expressed in concise formal notation, and is not to be confused with tutorials. Your condescending tone indicates you haven't listened and are still trying to convince them that they are wrong. It isn't going to work. Peter, I am, not being condescending. If you sense anything, it is frustration. I will accept your target audience: "Someone who already knows how to program and uses 'Raku.'" I will also accept that the documentation is not for me or anyone else trying to learn Raku. This is different than any other programming language I have used, but it is what it is. Not my call. And by your description of the target audience, I am correct when I say the documentation is meant for those that already know what they are doing. "language expressed in concise formal notation, and is not to be confused with tutorials" Well now, they need to get on the same page as you: https://docs.raku.org/language/classtut "A tutorial about creating and using classes in Raku" It is clearly stated that it is a tutorial, although it is not. It is what you describe above. This is part of my frustration. Please do not confuse frustration with condescension. -T
Re: Is the cosine page wrong?
On 12/28/20 10:57 PM, ToddAndMargo via perl6-users wrote: On 12/28/20 4:54 AM, Richard Hainsworth wrote: So please take what I say now as a plea for you to adapt a little, not to get pissed off with us even though you do seem to have pissed some of us off. You have very definite ideas about what the documentation should and shouldn't be. You have stated them over and over again. The Raku community at large - based on replies from multiple individuals over the years - disagrees with you. The Raku community has come to the concensus that there is a distinction between Tutorials and Reference, and that the Documentation site should contain both. Tutorials define how to use some aspect of Raku, with example text and explanation. Reference tries to cover as much of the language as possible, covering all the methods/subs/names/types etc as possible. Reference is written for a person who already knows how to program and who uses Raku. The assumption is that if a person reading a reference does not understand some term, then s/he will search in the documentation on that term to understand it. No set of documentation standards will please everyone - that's life. Even so, there ARE STILL areas of the Raku documentation that are lacking (just look at the issues on the Documentation repository, any of them raised by our indefatigable JJ). Hi Richard, When deciding to write a technical article, the VERY FIRST thing you have to do is determine your TARGET AUDIENCE. In a single sentence, please state for me what you believe the TARGET AUDIENCE is for the documentation. Richard stated the target audience for reference documentation quite clearly: Someone who already knows how to program and uses Raku. Multiple people have told you many times over several years that the purpose of reference documentation is to provide a complete description of the elements of a language expressed in concise formal notation, and is not to be confused with tutorials. Your condescending tone indicates you haven't listened and are still trying to convince them that they are wrong. It isn't going to work.
Re: Is the cosine page wrong?
On 12/28/20 4:54 AM, Richard Hainsworth wrote: But they may be useful to someone. Even worse, it is not possible for me to find a collection of your keepers because they are in posts to this email list, and I am not going to search through thousands of emails for your keepers on something whose keywords I would need to guess at. So the form you have made the keepers available is not easily accessible. Indeed. Maybe in the future. In the mean time, if you or anyone else on the list thinks I may have a Keeper that might help them, I would be more than glad to share it. Just place "Ping Todd" in the subject line.
Re: Is the cosine page wrong?
On 12/28/20 4:54 AM, Richard Hainsworth wrote: So please take what I say now as a plea for you to adapt a little, not to get pissed off with us even though you do seem to have pissed some of us off. You have very definite ideas about what the documentation should and shouldn't be. You have stated them over and over again. The Raku community at large - based on replies from multiple individuals over the years - disagrees with you. The Raku community has come to the concensus that there is a distinction between Tutorials and Reference, and that the Documentation site should contain both. Tutorials define how to use some aspect of Raku, with example text and explanation. Reference tries to cover as much of the language as possible, covering all the methods/subs/names/types etc as possible. Reference is written for a person who already knows how to program and who uses Raku. The assumption is that if a person reading a reference does not understand some term, then s/he will search in the documentation on that term to understand it. No set of documentation standards will please everyone - that's life. Even so, there ARE STILL areas of the Raku documentation that are lacking (just look at the issues on the Documentation repository, any of them raised by our indefatigable JJ). Hi Richard, When deciding to write a technical article, the VERY FIRST thing you have to do is determine your TARGET AUDIENCE. In a single sentence, please state for me what you believe the TARGET AUDIENCE is for the documentation. Many thanks, -T
Re: Is the cosine page wrong?
On 12/28/20 4:54 AM, Richard Hainsworth wrote: Todd, Some of what you have said in this email list over the years has been very valuable. You ask questions that get some very illuminating answers. I wrote a Module just for you (although I' still trying to get it to work on Windows) and it inspired me to look much more deeply at GTK::Simple, which I have just become the maintainer for. So please take what I say now as a plea for you to adapt a little, not to get pissed off with us even though you do seem to have pissed some of us off. You have very definite ideas about what the documentation should and shouldn't be. You have stated them over and over again. The Raku community at large - based on replies from multiple individuals over the years - disagrees with you. The Raku community has come to the concensus that there is a distinction between Tutorials and Reference, and that the Documentation site should contain both. Tutorials define how to use some aspect of Raku, with example text and explanation. Reference tries to cover as much of the language as possible, covering all the methods/subs/names/types etc as possible. Reference is written for a person who already knows how to program and who uses Raku. The assumption is that if a person reading a reference does not understand some term, then s/he will search in the documentation on that term to understand it. No set of documentation standards will please everyone - that's life. Even so, there ARE STILL areas of the Raku documentation that are lacking (just look at the issues on the Documentation repository, any of them raised by our indefatigable JJ). However, the balances between prolixity and brevity, examples and assumption of knowledge, exhibited in the Raku Documentation do by and large reflect a community consensus. It is polite in a community of rational human beings to accept what seems to be the general consensus, even if you do not agree with it. By continuing to demand your views about documentation should be accepted without any support from anyone else, is quite irritating. So please try to find a different way to express ways to improve the documentation that will not piss people off. You have suggested in this email list a variety of 'keepers', which seem to be the way you document your use of Raku. However, these 'keeper' texts are full of spelling mistakes, indicating you do not use a spell-checker, and also are ambiguous or technically wrong. Personally, I have not found your keepers to have been any use at all. But they may be useful to someone. Even worse, it is not possible for me to find a collection of your keepers because they are in posts to this email list, and I am not going to search through thousands of emails for your keepers on something whose keywords I would need to guess at. So the form you have made the keepers available is not easily accessible. In addition, the way the Raku community has evolved to work is to make changes to Documentation, whether Tutorials or Reference, by actually suggesting changes. If you look on the upper right of any primary document (the docs.raku.org site displays pages that are both automatically generated from primary documents, and the primary documents themselves - basically the documents referenced from the home page), you will see a Pencil icon. Click on that, and you will be taken to the github site and you can directly edit the document. The change is then submitted as a Pull Request, and it will be reviewed. If the change is seen to be reasonable, it is included. In this way, every single member of the Raku Community has the ability to make or suggest a contribution. However, a word of caution about human nature. If you go and try to completely change all the documentation to the way you want it, trashing everything that has already been contributed, it is extremely unlikely that your amendments will ever be accepted. Further, you run the risk that contributions with your name will never be considered by the Core Developers because they have rejected PRs you made before. Contribute in a way that enhances the Documentation, and your work will be praised. I hope whatever end of year, mid-winter or religious festival you celebrated was festive, even in our pandemic afflicted world, and I wish you a safe and productive CE 2021. Regards, Richard Hi Richard, Thank you for the insightful letter. Please know that I do deeply appreciate the help people give me here and think the world of everyone who helps me. I have zero intention of pissing anyone off. That would be a very foolish move on my part. I do not believe the documentation should be completely changed, but instead added to make things more understandable. I do believe the framework is generally good. I believe the documentation should be build on and not trashed and redone. I do apologize for any misconception/misunderstanding I may
Re: I need help understanding ".contains" method construction
On 12/28/20 7:11 AM, Parrot Raiser wrote:
"Definition of invoke
transitive verb
1a : to petition for help or support
b : to appeal to or cite as authority
2 : to call forth by incantation : conjure
3 : to make an earnest request for : solicit
4 : to put into effect or operation : implement
5 : bring about, cause"
2,3,4 and possibly even #5 relate to methods.
Simply referring to a method by name, like .rand invokes it directly.
Giving it a value (24.cos) is closer to #3 ("please give me this
value"), and it doesn't matter whether that's a literal or generated
from a variable of some sort.
" invocantn. One who calls upon or invokes."
It could be argued that the calling program is the invocant, but if a
process snoozes until something arrives in its in-box, then does an
action in response, it's a reasonable extension to call the
"something" an invocant. Think of dropping a coin into a soft-drink
machine; the coin invokes the can, even if the former owner of the
coin started the process.
Hi Parrot,
I feel a bit guilty as you put so much work and
thought into your response. I still don't know
what you mean.
$A = 24.cos;
$B = .rand;
Who is invoking? The "=" sign? The "24"?
The ".cos" or ".rand"? Or all of them.
I really do prefer the term "call".
Please do no feel frustrated though, in my Perl 5
days, I could never tell if I was being hosed
when I got told "it's lexiconical". At least
"invokant" is a real word.
-T
Re: Checking for nil return
The closest to null is actually an undefined type object
On Mon, Dec 28, 2020, 3:36 PM yary wrote:
> Been thinking about this, and checked out the Rakudo repository to peek
> into the source.
>
> Allowing Failure as a return always makes sense to me– every block needs
> to be capable of passing along a failure, that's how the language is
> designed.
>
> On the other hand, Nil is not a Failure. Conceptually it is a lack of an
> answer, similar to SQL's null concept.
>
> What's the usefulness of having Nil skip return type checking-
> specifically Nil and not its Failure descendents?
>
> This example under https://docs.raku.org/type/Nil shows what I think is a
> less-than-awesome specification, and I am curious about the reasoning
> behind it being defined as valid
>
> sub a( --> Int:D ) { return Nil }
>
>
>
> -y
>
>
> On Sun, Dec 20, 2020 at 7:18 PM Brad Gilbert wrote:
>
>> Nil is always a valid return value regardless of any check.
>>
>> This is because it is the base of all failures.
>>
>> On Sat, Dec 19, 2020, 8:17 PM yary wrote:
>>
>>> Is this a known issue, or my misunderstanding?
>>>
>>> > subset non-Nil where * !=== Nil;
>>> (non-Nil)
>>> > sub out-check($out) returns non-Nil { return $out }
>>>
>>> > out-check(44)
>>> 44
>>> > out-check(Nil)
>>> Nil
>>>
>>> ^ Huh, I expected an exception on "out-check(Nil)" saying the return
>>> value failed the "returns" constraint.
>>>
>>> The subtype works as I expect as an the argument check
>>>
>>> > sub in-check (non-Nil $in) { $in }
>>>
>>> > in-check(33)
>>> 33
>>> > in-check(Nil)
>>> Constraint type check failed in binding to parameter '$in'; expected
>>> non-Nil but got Nil (Nil)
>>> in sub in-check at line 1
>>> in block at line 1
>>>
>>> $ raku --version
>>> This is Rakudo version 2020.07 built on MoarVM version 2020.07
>>> implementing Raku 6.d.
>>>
>>> Is this my understanding of return type checking that's off, or a known
>>> issue, or something I should add to an issue tracker?
>>>
>>> -y
>>>
>>
Re: Checking for nil return
Been thinking about this, and checked out the Rakudo repository to peek
into the source.
Allowing Failure as a return always makes sense to me– every block needs to
be capable of passing along a failure, that's how the language is designed.
On the other hand, Nil is not a Failure. Conceptually it is a lack of an
answer, similar to SQL's null concept.
What's the usefulness of having Nil skip return type checking- specifically
Nil and not its Failure descendents?
This example under https://docs.raku.org/type/Nil shows what I think is a
less-than-awesome specification, and I am curious about the reasoning
behind it being defined as valid
sub a( --> Int:D ) { return Nil }
-y
On Sun, Dec 20, 2020 at 7:18 PM Brad Gilbert wrote:
> Nil is always a valid return value regardless of any check.
>
> This is because it is the base of all failures.
>
> On Sat, Dec 19, 2020, 8:17 PM yary wrote:
>
>> Is this a known issue, or my misunderstanding?
>>
>> > subset non-Nil where * !=== Nil;
>> (non-Nil)
>> > sub out-check($out) returns non-Nil { return $out }
>>
>> > out-check(44)
>> 44
>> > out-check(Nil)
>> Nil
>>
>> ^ Huh, I expected an exception on "out-check(Nil)" saying the return
>> value failed the "returns" constraint.
>>
>> The subtype works as I expect as an the argument check
>>
>> > sub in-check (non-Nil $in) { $in }
>>
>> > in-check(33)
>> 33
>> > in-check(Nil)
>> Constraint type check failed in binding to parameter '$in'; expected
>> non-Nil but got Nil (Nil)
>> in sub in-check at line 1
>> in block at line 1
>>
>> $ raku --version
>> This is Rakudo version 2020.07 built on MoarVM version 2020.07
>> implementing Raku 6.d.
>>
>> Is this my understanding of return type checking that's off, or a known
>> issue, or something I should add to an issue tracker?
>>
>> -y
>>
>
Re: Is the cosine page wrong?
P.R. submitted for step #2 On 12/28/20, Richard Hainsworth wrote: > This seems to have been fixed already. > > The speed this problem was noted and fixed demonstrates (a) the > importance given to documentation, and (b) the diligence of JJ. > > Kudos to JJ and those who helped fix the problem. > > Richard > > On 28/12/2020 15:35, Elizabeth Mattijsen wrote: >> https://github.com/Raku/doc/issues/3753 >> >>> On 28 Dec 2020, at 16:23, Parrot Raiser <1parr...@gmail.com> wrote: >>> >>> I just went to the page at docs.raku.org on multi-line comments, to >>> suggest a couple of clarifying edits. The pencil icon invoked a 404 >>> from GitHub. >>> >>> When one goes to make a fix, and the fixer is broken, it's a bit >>> recursive. Can anyone cure problem #1, so I can get to step #2? :-)* >>> >>> On 12/28/20, Elizabeth Mattijsen wrote: ❤️ > On 28 Dec 2020, at 13:54, Richard Hainsworth > wrote: > > Todd, > > Some of what you have said in this email list over the years has been > very > valuable. You ask questions that get some very illuminating answers. I > wrote a Module just for you (although I' still trying to get it to work > on > Windows) and it inspired me to look much more deeply at GTK::Simple, > which > I have just become the maintainer for. > > So please take what I say now as a plea for you to adapt a little, not > to > get pissed off with us even though you do seem to have pissed some of > us > off. > > You have very definite ideas about what the documentation should and > shouldn't be. You have stated them over and over again. The Raku > community > at large - based on replies from multiple individuals over the years - > disagrees with you. > > The Raku community has come to the concensus that there is a > distinction > between Tutorials and Reference, and that the Documentation site > should > contain both. Tutorials define how to use some aspect of Raku, with > example text and explanation. Reference tries to cover as much of the > language as possible, covering all the methods/subs/names/types etc as > possible. Reference is written for a person who already knows how to > program and who uses Raku. The assumption is that if a person reading > a > reference does not understand some term, then s/he will search in the > documentation on that term to understand it. > > No set of documentation standards will please everyone - that's life. > Even > so, there ARE STILL areas of the Raku documentation that are lacking > (just > look at the issues on the Documentation repository, any of them raised > by > our indefatigable JJ). > > However, the balances between prolixity and brevity, examples and > assumption of knowledge, exhibited in the Raku Documentation do by and > large reflect a community consensus. > > It is polite in a community of rational human beings to accept what > seems > to be the general consensus, even if you do not agree with it. By > continuing to demand your views about documentation should be accepted > without any support from anyone else, is quite irritating. So please > try > to find a different way to express ways to improve the documentation > that > will not piss people off. > > You have suggested in this email list a variety of 'keepers', which > seem > to be the way you document your use of Raku. However, these 'keeper' > texts > are full of spelling mistakes, indicating you do not use a > spell-checker, > and also are ambiguous or technically wrong. Personally, I have not > found > your keepers to have been any use at all. But they may be useful to > someone. Even worse, it is not possible for me to find a collection of > your keepers because they are in posts to this email list, and I am > not > going to search through thousands of emails for your keepers on > something > whose keywords I would need to guess at. So the form you have made the > keepers available is not easily accessible. > > In addition, the way the Raku community has evolved to work is to make > changes to Documentation, whether Tutorials or Reference, by actually > suggesting changes. If you look on the upper right of any primary > document > (the docs.raku.org site displays pages that are both automatically > generated from primary documents, and the primary documents themselves > - > basically the documents referenced from the home page), you will see a > Pencil icon. Click on that, and you will be taken to the github site > and > you can directly edit the document. The change is then submitted as a > Pull > Request, and it will be reviewed. If the change is seen to be > reasonable, > it is included. > > In this way, every
Re: Is the cosine page wrong?
This seems to have been fixed already. The speed this problem was noted and fixed demonstrates (a) the importance given to documentation, and (b) the diligence of JJ. Kudos to JJ and those who helped fix the problem. Richard On 28/12/2020 15:35, Elizabeth Mattijsen wrote: https://github.com/Raku/doc/issues/3753 On 28 Dec 2020, at 16:23, Parrot Raiser <1parr...@gmail.com> wrote: I just went to the page at docs.raku.org on multi-line comments, to suggest a couple of clarifying edits. The pencil icon invoked a 404 from GitHub. When one goes to make a fix, and the fixer is broken, it's a bit recursive. Can anyone cure problem #1, so I can get to step #2? :-)* On 12/28/20, Elizabeth Mattijsen wrote: ❤️ On 28 Dec 2020, at 13:54, Richard Hainsworth wrote: Todd, Some of what you have said in this email list over the years has been very valuable. You ask questions that get some very illuminating answers. I wrote a Module just for you (although I' still trying to get it to work on Windows) and it inspired me to look much more deeply at GTK::Simple, which I have just become the maintainer for. So please take what I say now as a plea for you to adapt a little, not to get pissed off with us even though you do seem to have pissed some of us off. You have very definite ideas about what the documentation should and shouldn't be. You have stated them over and over again. The Raku community at large - based on replies from multiple individuals over the years - disagrees with you. The Raku community has come to the concensus that there is a distinction between Tutorials and Reference, and that the Documentation site should contain both. Tutorials define how to use some aspect of Raku, with example text and explanation. Reference tries to cover as much of the language as possible, covering all the methods/subs/names/types etc as possible. Reference is written for a person who already knows how to program and who uses Raku. The assumption is that if a person reading a reference does not understand some term, then s/he will search in the documentation on that term to understand it. No set of documentation standards will please everyone - that's life. Even so, there ARE STILL areas of the Raku documentation that are lacking (just look at the issues on the Documentation repository, any of them raised by our indefatigable JJ). However, the balances between prolixity and brevity, examples and assumption of knowledge, exhibited in the Raku Documentation do by and large reflect a community consensus. It is polite in a community of rational human beings to accept what seems to be the general consensus, even if you do not agree with it. By continuing to demand your views about documentation should be accepted without any support from anyone else, is quite irritating. So please try to find a different way to express ways to improve the documentation that will not piss people off. You have suggested in this email list a variety of 'keepers', which seem to be the way you document your use of Raku. However, these 'keeper' texts are full of spelling mistakes, indicating you do not use a spell-checker, and also are ambiguous or technically wrong. Personally, I have not found your keepers to have been any use at all. But they may be useful to someone. Even worse, it is not possible for me to find a collection of your keepers because they are in posts to this email list, and I am not going to search through thousands of emails for your keepers on something whose keywords I would need to guess at. So the form you have made the keepers available is not easily accessible. In addition, the way the Raku community has evolved to work is to make changes to Documentation, whether Tutorials or Reference, by actually suggesting changes. If you look on the upper right of any primary document (the docs.raku.org site displays pages that are both automatically generated from primary documents, and the primary documents themselves - basically the documents referenced from the home page), you will see a Pencil icon. Click on that, and you will be taken to the github site and you can directly edit the document. The change is then submitted as a Pull Request, and it will be reviewed. If the change is seen to be reasonable, it is included. In this way, every single member of the Raku Community has the ability to make or suggest a contribution. However, a word of caution about human nature. If you go and try to completely change all the documentation to the way you want it, trashing everything that has already been contributed, it is extremely unlikely that your amendments will ever be accepted. Further, you run the risk that contributions with your name will never be considered by the Core Developers because they have rejected PRs you made before. Contribute in a way that enhances the Documentation, and your work will be praised. I hope whatever end of year, mid-winter or religious festival you celebrated was festive, even in our
Re: Is the cosine page wrong?
https://github.com/Raku/doc/issues/3753 > On 28 Dec 2020, at 16:23, Parrot Raiser <1parr...@gmail.com> wrote: > > I just went to the page at docs.raku.org on multi-line comments, to > suggest a couple of clarifying edits. The pencil icon invoked a 404 > from GitHub. > > When one goes to make a fix, and the fixer is broken, it's a bit > recursive. Can anyone cure problem #1, so I can get to step #2? :-)* > > On 12/28/20, Elizabeth Mattijsen wrote: >> ❤️ >> >>> On 28 Dec 2020, at 13:54, Richard Hainsworth >>> wrote: >>> >>> Todd, >>> >>> Some of what you have said in this email list over the years has been very >>> valuable. You ask questions that get some very illuminating answers. I >>> wrote a Module just for you (although I' still trying to get it to work on >>> Windows) and it inspired me to look much more deeply at GTK::Simple, which >>> I have just become the maintainer for. >>> >>> So please take what I say now as a plea for you to adapt a little, not to >>> get pissed off with us even though you do seem to have pissed some of us >>> off. >>> >>> You have very definite ideas about what the documentation should and >>> shouldn't be. You have stated them over and over again. The Raku community >>> at large - based on replies from multiple individuals over the years - >>> disagrees with you. >>> >>> The Raku community has come to the concensus that there is a distinction >>> between Tutorials and Reference, and that the Documentation site should >>> contain both. Tutorials define how to use some aspect of Raku, with >>> example text and explanation. Reference tries to cover as much of the >>> language as possible, covering all the methods/subs/names/types etc as >>> possible. Reference is written for a person who already knows how to >>> program and who uses Raku. The assumption is that if a person reading a >>> reference does not understand some term, then s/he will search in the >>> documentation on that term to understand it. >>> >>> No set of documentation standards will please everyone - that's life. Even >>> so, there ARE STILL areas of the Raku documentation that are lacking (just >>> look at the issues on the Documentation repository, any of them raised by >>> our indefatigable JJ). >>> >>> However, the balances between prolixity and brevity, examples and >>> assumption of knowledge, exhibited in the Raku Documentation do by and >>> large reflect a community consensus. >>> >>> It is polite in a community of rational human beings to accept what seems >>> to be the general consensus, even if you do not agree with it. By >>> continuing to demand your views about documentation should be accepted >>> without any support from anyone else, is quite irritating. So please try >>> to find a different way to express ways to improve the documentation that >>> will not piss people off. >>> >>> You have suggested in this email list a variety of 'keepers', which seem >>> to be the way you document your use of Raku. However, these 'keeper' texts >>> are full of spelling mistakes, indicating you do not use a spell-checker, >>> and also are ambiguous or technically wrong. Personally, I have not found >>> your keepers to have been any use at all. But they may be useful to >>> someone. Even worse, it is not possible for me to find a collection of >>> your keepers because they are in posts to this email list, and I am not >>> going to search through thousands of emails for your keepers on something >>> whose keywords I would need to guess at. So the form you have made the >>> keepers available is not easily accessible. >>> >>> In addition, the way the Raku community has evolved to work is to make >>> changes to Documentation, whether Tutorials or Reference, by actually >>> suggesting changes. If you look on the upper right of any primary document >>> (the docs.raku.org site displays pages that are both automatically >>> generated from primary documents, and the primary documents themselves - >>> basically the documents referenced from the home page), you will see a >>> Pencil icon. Click on that, and you will be taken to the github site and >>> you can directly edit the document. The change is then submitted as a Pull >>> Request, and it will be reviewed. If the change is seen to be reasonable, >>> it is included. >>> >>> In this way, every single member of the Raku Community has the ability to >>> make or suggest a contribution. >>> >>> However, a word of caution about human nature. If you go and try to >>> completely change all the documentation to the way you want it, trashing >>> everything that has already been contributed, it is extremely unlikely >>> that your amendments will ever be accepted. Further, you run the risk that >>> contributions with your name will never be considered by the Core >>> Developers because they have rejected PRs you made before. >>> >>> Contribute in a way that enhances the Documentation, and your work will be >>> praised. >>> >>> I hope whatever end of year,
Re: Is the cosine page wrong?
I just went to the page at docs.raku.org on multi-line comments, to suggest a couple of clarifying edits. The pencil icon invoked a 404 from GitHub. When one goes to make a fix, and the fixer is broken, it's a bit recursive. Can anyone cure problem #1, so I can get to step #2? :-)* On 12/28/20, Elizabeth Mattijsen wrote: > ❤️ > >> On 28 Dec 2020, at 13:54, Richard Hainsworth >> wrote: >> >> Todd, >> >> Some of what you have said in this email list over the years has been very >> valuable. You ask questions that get some very illuminating answers. I >> wrote a Module just for you (although I' still trying to get it to work on >> Windows) and it inspired me to look much more deeply at GTK::Simple, which >> I have just become the maintainer for. >> >> So please take what I say now as a plea for you to adapt a little, not to >> get pissed off with us even though you do seem to have pissed some of us >> off. >> >> You have very definite ideas about what the documentation should and >> shouldn't be. You have stated them over and over again. The Raku community >> at large - based on replies from multiple individuals over the years - >> disagrees with you. >> >> The Raku community has come to the concensus that there is a distinction >> between Tutorials and Reference, and that the Documentation site should >> contain both. Tutorials define how to use some aspect of Raku, with >> example text and explanation. Reference tries to cover as much of the >> language as possible, covering all the methods/subs/names/types etc as >> possible. Reference is written for a person who already knows how to >> program and who uses Raku. The assumption is that if a person reading a >> reference does not understand some term, then s/he will search in the >> documentation on that term to understand it. >> >> No set of documentation standards will please everyone - that's life. Even >> so, there ARE STILL areas of the Raku documentation that are lacking (just >> look at the issues on the Documentation repository, any of them raised by >> our indefatigable JJ). >> >> However, the balances between prolixity and brevity, examples and >> assumption of knowledge, exhibited in the Raku Documentation do by and >> large reflect a community consensus. >> >> It is polite in a community of rational human beings to accept what seems >> to be the general consensus, even if you do not agree with it. By >> continuing to demand your views about documentation should be accepted >> without any support from anyone else, is quite irritating. So please try >> to find a different way to express ways to improve the documentation that >> will not piss people off. >> >> You have suggested in this email list a variety of 'keepers', which seem >> to be the way you document your use of Raku. However, these 'keeper' texts >> are full of spelling mistakes, indicating you do not use a spell-checker, >> and also are ambiguous or technically wrong. Personally, I have not found >> your keepers to have been any use at all. But they may be useful to >> someone. Even worse, it is not possible for me to find a collection of >> your keepers because they are in posts to this email list, and I am not >> going to search through thousands of emails for your keepers on something >> whose keywords I would need to guess at. So the form you have made the >> keepers available is not easily accessible. >> >> In addition, the way the Raku community has evolved to work is to make >> changes to Documentation, whether Tutorials or Reference, by actually >> suggesting changes. If you look on the upper right of any primary document >> (the docs.raku.org site displays pages that are both automatically >> generated from primary documents, and the primary documents themselves - >> basically the documents referenced from the home page), you will see a >> Pencil icon. Click on that, and you will be taken to the github site and >> you can directly edit the document. The change is then submitted as a Pull >> Request, and it will be reviewed. If the change is seen to be reasonable, >> it is included. >> >> In this way, every single member of the Raku Community has the ability to >> make or suggest a contribution. >> >> However, a word of caution about human nature. If you go and try to >> completely change all the documentation to the way you want it, trashing >> everything that has already been contributed, it is extremely unlikely >> that your amendments will ever be accepted. Further, you run the risk that >> contributions with your name will never be considered by the Core >> Developers because they have rejected PRs you made before. >> >> Contribute in a way that enhances the Documentation, and your work will be >> praised. >> >> I hope whatever end of year, mid-winter or religious festival you >> celebrated was festive, even in our pandemic afflicted world, and I wish >> you a safe and productive CE 2021. >> >> Regards, >> >> Richard >> >> On 28/12/2020 11:55, ToddAndMargo via
Re: I need help understanding ".contains" method construction
"Definition of invoke
transitive verb
1a : to petition for help or support
b : to appeal to or cite as authority
2 : to call forth by incantation : conjure
3 : to make an earnest request for : solicit
4 : to put into effect or operation : implement
5 : bring about, cause"
2,3,4 and possibly even #5 relate to methods.
Simply referring to a method by name, like .rand invokes it directly.
Giving it a value (24.cos) is closer to #3 ("please give me this
value"), and it doesn't matter whether that's a literal or generated
from a variable of some sort.
" invocantn. One who calls upon or invokes."
It could be argued that the calling program is the invocant, but if a
process snoozes until something arrives in its in-box, then does an
action in response, it's a reasonable extension to call the
"something" an invocant. Think of dropping a coin into a soft-drink
machine; the coin invokes the can, even if the former owner of the
coin started the process.
On 12/28/20, ToddAndMargo via perl6-users wrote:
> On 12/26/20 2:50 PM, Ralph Mellor wrote:
>>> Is this .self with a better name?
>> No.
>>
>> I know you've been progressing in your understanding of
>> OO in general, and Raku's in particular, since you wrote
>> this email. So I won't explain it for now, but rather just try
>> to confirm you now know what that bit of code is doing.
>>
>> So, would you say you now understand that `.value` is a
>> method call on an "invocant" that is either explicitly written
>> to the left of the `.` or is implicitly whatever the current topic
>> is where the `.value` appears?
>
> No idea since you hinted to a newbie like myself.
>
> I do know that .value comes from the class definition
>
> https://github.com/rakudo/rakudo/blob/5df809e29cd2e7ae496a33013b27d2f7b52c7f7d/src/Perl6/bootstrap.c/BOOTSTRAP.nqp#L3427
>
> 3427: Str.HOW.add_attribute(Str, BOOTSTRAPATTR.new(:name<$!value>,
> :type(str), :box_target(1), :package(Str)));
>
> And I would not say it was a method call. I would say
> it is a "class" from
>
> https://github.com/rakudo/rakudo/blob/5df809e29cd2e7ae496a33013b27d2f7b52c7f7d/src/Perl6/bootstrap.c/BOOTSTRAP.nqp#L19
>
> 19: my class BOOTSTRAPATTR {
>
>
> So I still find the word "invocant" a bit bizarre.
>
> https://www.merriam-webster.com/dictionary/invocant
> Definition of invocant
> : one that invokes
>
> https://www.merriam-webster.com/dictionary/invokes
> Definition of invoke
>
> transitive verb
> 1a : to petition for help or support
> b : to appeal to or cite as authority
> 2 : to call forth by incantation : conjure
> 3 : to make an earnest request for : solicit
> 4 : to put into effect or operation : implement
> 5 : bring about, cause
>
> So from "context", what I pick up is that
>
>1. it is an awful term to have used
>
>2. that
> 24.cos
> either the 24 appeals/requests to cos to do something
> making the 24 the invocant,
>or
> .cos is the invocant and takes the 24 and appeals to
> the code inside the method to "bring about" something.
> The 24 may or may not be needed for the appeal, as
> in ".rand"
>
> So it is better to just tell me and not hint around.
> I do appreciate your efforts a lot though. Who
> "executes what" who be a better tactic.
>
> -T
>
>
>
>
Re: Is the cosine page wrong?
❤️ > On 28 Dec 2020, at 13:54, Richard Hainsworth wrote: > > Todd, > > Some of what you have said in this email list over the years has been very > valuable. You ask questions that get some very illuminating answers. I wrote > a Module just for you (although I' still trying to get it to work on Windows) > and it inspired me to look much more deeply at GTK::Simple, which I have just > become the maintainer for. > > So please take what I say now as a plea for you to adapt a little, not to get > pissed off with us even though you do seem to have pissed some of us off. > > You have very definite ideas about what the documentation should and > shouldn't be. You have stated them over and over again. The Raku community at > large - based on replies from multiple individuals over the years - disagrees > with you. > > The Raku community has come to the concensus that there is a distinction > between Tutorials and Reference, and that the Documentation site should > contain both. Tutorials define how to use some aspect of Raku, with example > text and explanation. Reference tries to cover as much of the language as > possible, covering all the methods/subs/names/types etc as possible. > Reference is written for a person who already knows how to program and who > uses Raku. The assumption is that if a person reading a reference does not > understand some term, then s/he will search in the documentation on that term > to understand it. > > No set of documentation standards will please everyone - that's life. Even > so, there ARE STILL areas of the Raku documentation that are lacking (just > look at the issues on the Documentation repository, any of them raised by our > indefatigable JJ). > > However, the balances between prolixity and brevity, examples and assumption > of knowledge, exhibited in the Raku Documentation do by and large reflect a > community consensus. > > It is polite in a community of rational human beings to accept what seems to > be the general consensus, even if you do not agree with it. By continuing to > demand your views about documentation should be accepted without any support > from anyone else, is quite irritating. So please try to find a different way > to express ways to improve the documentation that will not piss people off. > > You have suggested in this email list a variety of 'keepers', which seem to > be the way you document your use of Raku. However, these 'keeper' texts are > full of spelling mistakes, indicating you do not use a spell-checker, and > also are ambiguous or technically wrong. Personally, I have not found your > keepers to have been any use at all. But they may be useful to someone. Even > worse, it is not possible for me to find a collection of your keepers because > they are in posts to this email list, and I am not going to search through > thousands of emails for your keepers on something whose keywords I would need > to guess at. So the form you have made the keepers available is not easily > accessible. > > In addition, the way the Raku community has evolved to work is to make > changes to Documentation, whether Tutorials or Reference, by actually > suggesting changes. If you look on the upper right of any primary document > (the docs.raku.org site displays pages that are both automatically generated > from primary documents, and the primary documents themselves - basically the > documents referenced from the home page), you will see a Pencil icon. Click > on that, and you will be taken to the github site and you can directly edit > the document. The change is then submitted as a Pull Request, and it will be > reviewed. If the change is seen to be reasonable, it is included. > > In this way, every single member of the Raku Community has the ability to > make or suggest a contribution. > > However, a word of caution about human nature. If you go and try to > completely change all the documentation to the way you want it, trashing > everything that has already been contributed, it is extremely unlikely that > your amendments will ever be accepted. Further, you run the risk that > contributions with your name will never be considered by the Core Developers > because they have rejected PRs you made before. > > Contribute in a way that enhances the Documentation, and your work will be > praised. > > I hope whatever end of year, mid-winter or religious festival you celebrated > was festive, even in our pandemic afflicted world, and I wish you a safe and > productive CE 2021. > > Regards, > > Richard > > On 28/12/2020 11:55, ToddAndMargo via perl6-users wrote: >> On 12/25/20 8:10 AM, Ralph Mellor wrote: On 12/23/20 4:28 PM, Ralph Mellor wrote: > If a method does not explicitly specify its invocant type, it is set > to the type of the enclosing class. But it does not specify an invocant. It just leaves it blank >>> >>> This is how it works in Raku source code. If there's
Re: Is the cosine page wrong?
Todd, Some of what you have said in this email list over the years has been very valuable. You ask questions that get some very illuminating answers. I wrote a Module just for you (although I' still trying to get it to work on Windows) and it inspired me to look much more deeply at GTK::Simple, which I have just become the maintainer for. So please take what I say now as a plea for you to adapt a little, not to get pissed off with us even though you do seem to have pissed some of us off. You have very definite ideas about what the documentation should and shouldn't be. You have stated them over and over again. The Raku community at large - based on replies from multiple individuals over the years - disagrees with you. The Raku community has come to the concensus that there is a distinction between Tutorials and Reference, and that the Documentation site should contain both. Tutorials define how to use some aspect of Raku, with example text and explanation. Reference tries to cover as much of the language as possible, covering all the methods/subs/names/types etc as possible. Reference is written for a person who already knows how to program and who uses Raku. The assumption is that if a person reading a reference does not understand some term, then s/he will search in the documentation on that term to understand it. No set of documentation standards will please everyone - that's life. Even so, there ARE STILL areas of the Raku documentation that are lacking (just look at the issues on the Documentation repository, any of them raised by our indefatigable JJ). However, the balances between prolixity and brevity, examples and assumption of knowledge, exhibited in the Raku Documentation do by and large reflect a community consensus. It is polite in a community of rational human beings to accept what seems to be the general consensus, even if you do not agree with it. By continuing to demand your views about documentation should be accepted without any support from anyone else, is quite irritating. So please try to find a different way to express ways to improve the documentation that will not piss people off. You have suggested in this email list a variety of 'keepers', which seem to be the way you document your use of Raku. However, these 'keeper' texts are full of spelling mistakes, indicating you do not use a spell-checker, and also are ambiguous or technically wrong. Personally, I have not found your keepers to have been any use at all. But they may be useful to someone. Even worse, it is not possible for me to find a collection of your keepers because they are in posts to this email list, and I am not going to search through thousands of emails for your keepers on something whose keywords I would need to guess at. So the form you have made the keepers available is not easily accessible. In addition, the way the Raku community has evolved to work is to make changes to Documentation, whether Tutorials or Reference, by actually suggesting changes. If you look on the upper right of any primary document (the docs.raku.org site displays pages that are both automatically generated from primary documents, and the primary documents themselves - basically the documents referenced from the home page), you will see a Pencil icon. Click on that, and you will be taken to the github site and you can directly edit the document. The change is then submitted as a Pull Request, and it will be reviewed. If the change is seen to be reasonable, it is included. In this way, every single member of the Raku Community has the ability to make or suggest a contribution. However, a word of caution about human nature. If you go and try to completely change all the documentation to the way you want it, trashing everything that has already been contributed, it is extremely unlikely that your amendments will ever be accepted. Further, you run the risk that contributions with your name will never be considered by the Core Developers because they have rejected PRs you made before. Contribute in a way that enhances the Documentation, and your work will be praised. I hope whatever end of year, mid-winter or religious festival you celebrated was festive, even in our pandemic afflicted world, and I wish you a safe and productive CE 2021. Regards, Richard On 28/12/2020 11:55, ToddAndMargo via perl6-users wrote: On 12/25/20 8:10 AM, Ralph Mellor wrote: On 12/23/20 4:28 PM, Ralph Mellor wrote: > If a method does not explicitly specify its invocant type, it is set > to the type of the enclosing class. But it does not specify an invocant. It just leaves it blank This is how it works in Raku source code. If there's no signature at all, or if the invocant is blank, or if the invocant's type is not specified, its type is the type of the class which encloses or composes the method (or `Mu` for a mainline `my` method). Hi Ralph, What is used in the
Re: Is the cosine page wrong?
On 12/25/20 8:10 AM, Ralph Mellor wrote: On 12/23/20 4:28 PM, Ralph Mellor wrote: > If a method does not explicitly specify its invocant type, it is set > to the type of the enclosing class. But it does not specify an invocant. It just leaves it blank This is how it works in Raku source code. If there's no signature at all, or if the invocant is blank, or if the invocant's type is not specified, its type is the type of the class which encloses or composes the method (or `Mu` for a mainline `my` method). Presuming the same for the doc maintains consistency between what signatures look in Raku source code, and what they look like in doc. Raku is explicitly designed with context in mind as an essential driver for its design, and for comprehending code. This may not work for you. But it's presumably ideal for newbies and experts that take cues from context -- which is to say almost all of those who I would expect to ever enjoy working with Raku. That's not to say you can't do the work to improve things from your perspective. Provided you don't make things worse for those who appreciate the language (and the doc) presuming that Raku devs will in general be happy to take context into account, you are of course free to do, and advocate, as you wish. > So, the doc is fine as is for the invocant. I was not asking if you could pick it up by context with other things written on the page. I was specifically asking about the definition line. I wasn't saying you *could* pick it up from context. I was implying you *should* pick it up from context. I presumed you care to learn what makes Raku Raku, including contextual clues to which attention *must* be paid when one is comprehending code, and which cues are also readily available for comprehending the doc. The context is there; why *not* pay attention to it? Why *not* learn how Raku code works? And if you learn how Raku signatures work, which isn't difficult, why *not* apply the exact same rules to the doc? Imo introducing redundancy often makes sense for tutorials, but less often, imo, for reference doc. In particular, I see blank invocants in a method signature as an ideal way to convey that a method's invocant type is determined by its context. Once you learn to read them, the definition lines can be really useful. Yes. And you have now presumbly both learned how to read the type of the invocant if it's blank, and learned that it's a really easy rule to learn. My problem is that they are often incorrect, which put a hammer into learning them. I hear that. But the response to that issue should be to correct the errors. Manually adding redundant information will inevitably *increase* the number of errors unless it's automated. It may also *reduce* the doc's usability for those who do not benefit from the redundancy. If you are willing to write good automation code to solve this doc problem, and design doc changes to minimize the harm done for those who do not benefit from the redundancy, and do the work to gain consensus that the work you prepare to make this change should be applied, and commit to doing the work to make sure it gets properly applied, then I definitely wouldn't stand in your way, even if I think it would be a mistake to apply such a change. Or, if you are *not* willing to do that work, you can presumably just acknowledge that you could resolve the problem you thought you saw by no longer seeing it as a problem, but rather just something you have come to learn along the way. > The returned value is a cosine, which, per the linked doc, > is a real number. The doc could perhaps show a return value > of Real:D. I like it! To be clear, I'm not saying the doc *should* show that return value. Just that it *could*, and that *perhaps* that would be appropriate, in contrast to my opinion about the invocant type. This look right to me (but keep in mind I don't know what I am doing) method cos( Cool:D: --> Real:D ) As I hopefully made clear at the start of this email, redundantly explicitly specifying the invocant in the signature despite it being already explicitly specified by the enclosing context seems ill-advised to me, but if you do the work to introduce automation of its insertion, you should be able to make it optional, and that would work fine for me if other documenters agree it's an acceptable thing to introduce. love, raiph On Thu, Dec 24, 2020 at 2:42 AM Todd Chester via perl6-users wrote: Going back to the original question, should not the doc page say? method cos( Cool:D: --> Cool:D ) On 12/23/20 4:28 PM, Ralph Mellor wrote: > If a method does not explicitly specify its invocant type, it is set > to the type of the enclosing class. But it does not specify an invocant. It just leaves it blank > > The `cos` method is declared in the `Cool` class, so that is its > invocant type. > > The doc shows that it's declared in the `Cool` class. > > So, the doc
