Re: Is the cosine page wrong?
On 12/29/20 7:05 AM, Peter Scott wrote: On 12/28/20 11:49 PM, ToddAndMargo via perl6-users wrote: 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. We explained that there are two types of documentation, and that is the target audience for *reference* documentation. The other type of documentation is tutorial, which *is* for people 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. That page is a tutorial, not reference documentation. It does not attempt to provide a concise and complete description of one feature of Raku in formal notation. It provides narrative and examples proceeding from simple to complex forms in pursuit of a goal of explaining the use of classes in Raku. That is a tutorial. Not all tutorials assume the same starting point for the reader, and tutorials on more advanced features of a language must assume the reader has familiarity with more basic prerequisites. For instance, a tutorial on lookahead assertions in Perl 5 regular expressions will assume that the reader knows what character classes and quantifiers are and will not explain them again. Therefore tutorials need to be consumed and understood in a certain order by the newcomer. Designing and presenting that order so that the reader does not get lost takes considerable skill. Generally, it requires a veteran teacher working closely with an editorial team that provides feedback from expert peers and novices alike in a lengthy evaluation phase. The highest quality tutorials will include exercises. Fortunately, all that work has already been done for Raku by just such a teacher and team. You can find the result at https://learning.oreilly.com/library/view/learning-perl-6/9781491977675/ This thread is titled after the cosine page, which is reference documentation. You keep wanting reference documentation to be changed to do the job of tutorial documentation. It would end up being bad at both. That's not going to happen. Hi Peter, Interesting read. The tutorial I questioned was a tutorial for advanced users, not those learning Raku. If it was for those learning Raku, it would have defined the terms. In other words, the tutorial for those that do not need the tutorial. When I first saw the tutorial, I was very happy. It was going to tutor me on classes, objects and methods. When I started to read it, I could not believe how poorly it was done. It totally baffled me. It said "tutorial". I know what they are now though. I ask a fried on another programming forum who has an extreme gift for teaching. He taught me in *O-N-E S-I-N-G-L-E P-A-R-A-G-R-A-P-H*. OOP (object, orientated programming) is "elegant" and I can think of a ton of uses for it. I may never use an associative array (hash) again. And I ADORE hashes. Now when I look at that tutorial, I understand it (well most of it), BECAUSE I ALREADY KNEW WHAT OOP IS IN RAKU. So, I no longer need it. I do like your idea about using a teacher to put these things together. But you must be careful of teachers as you must with all professions. Teaching is a gift. I would posit that most teachers do not have it (arrogant, condescending blowhards with elbow patches and beards to make them look older). The ones that do have the gift, open a whole new world up for you. They are truly a gift to the world. And it is pretty easy to tell them apart. If you ever heard the phrase cross their lips "the solution is intuitively obvious and left up to the student to figure out for themselves" then you just found the bad ones. The bad ones also do not care if you do not understand them: you are just stupid. Now for cos. The "reference" for advanced users "presumes" a lot in the definition line: method cos() 1) it presumes you know what class it is in (Cool) 2) it presumes you know what the output structure will be (Num) How does this help ANY user, advanced or not? Well "the solution is intuitively obvious and left up to the student to figure out for themselves". The text later does fill things in a bit. Would it have killed ANYONE to have written it? method cos( Cool:d: --> Num ) Why do we even use these definition lines if we are not going to take advantage of their power?
Re: Is the cosine page wrong?
On 12/29/20 3:51 AM, Richard Hainsworth wrote: What it is would be what you stated previously: "Reference is written for a person who already knows how to program and who uses Raku" This is taken out of context. I said the Raku community has come to a consensus that DOCUMENTATION should contain both *tutorial* and *reference*. You specifically stated: 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. But Raku documentation could not be 'standard technical writing', if such a thing exists. They teach it in our universities. They call it "technical writing" Raku documentation should be compared to documentation about another newish language, such as Rust or Go, or Haskell. I think it compares well. A better comparison would be from where we came. A language also created by Larry Wall that transitioned into Perl6/Raku: Perl 5 and Perl Docs. Raku does not compare so well at all. Perl Docs is not written only for advanced users. Actually if I want an answer to a programming question, I would turn to StackOverflow, and Raku there does not give any ceramic references. I find them extremely helpful at times too.
Re: Is the cosine page wrong?
See inline below On Tue, Dec 29, 2020, 09:54 ToddAndMargo via perl6-users < perl6-users@perl.org> wrote: > On 12/29/20 1:12 AM, Richard Hainsworth wrote: > > 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. > > > > Would that it were that simple! But since you have some definite ideas > > about what's wrong, why don't you have a go? > > What the target audience? > > Hi Richard, > > What it is would be what you stated previously: > > "Reference is written for a person who already > knows how to program and who uses Raku" > This is taken out of context. I said the Raku community has come to a consensus that DOCUMENTATION should contain both *tutorial* and *reference*. > What I would like it to be is: > > for both new and advanced users > > Standard technical writing: define terms (links work), > start small and work up to advanced. And no showing off. > But Raku documentation could not be 'standard technical writing', if such a thing exists. Raku documentation should be compared to documentation about another newish language, such as Rust or Go, or Haskell. I think it compares well. > > It's clear that you are a member, but what about others? > > "member". That must be a British term. By context, I > presume you mean I am program in Raku. > I meant 'member of an audience'. Does USA English have another term for an individual in an audience? I think not. Brevity by ellipsis is an literary style that assumes an intelligent reader will supply the missing information from the context. You correctly assumed what I implied. Raku documentation uses a similar technique. > > > I use the > > documentation every time I program in Raku (or C or php) > > I always have the documentation pages open when I am > programming too. > > By the way, your statement > "who already knows how to program and who > uses Raku" > > would definitely apply to me and the docs drive me > around the bend (sometimes the actual source code > is easier for me to understand and I have starting > looking at that too), so I would posit that you > should change your statement to > > "Reference is written for a person who already > has an advanced knowledge of and programs in Raku" > > Oh and it does not help that a google search of > raku this and that turns up 1001 hits on pottery. > Actually if I want an answer to a programming question, I would turn to StackOverflow, and Raku there does not give any ceramic references. > > Richard
Re: Is the cosine page wrong?
On 12/29/20 1:12 AM, Richard Hainsworth wrote: 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. Would that it were that simple! But since you have some definite ideas about what's wrong, why don't you have a go? What the target audience? Hi Richard, What it is would be what you stated previously: "Reference is written for a person who already knows how to program and who uses Raku" What I would like it to be is: for both new and advanced users Standard technical writing: define terms (links work), start small and work up to advanced. And no showing off. It's clear that you are a member, but what about others? "member". That must be a British term. By context, I presume you mean I am program in Raku. I use the documentation every time I program in Raku (or C or php) I always have the documentation pages open when I am programming too. By the way, your statement "who already knows how to program and who uses Raku" would definitely apply to me and the docs drive me around the bend (sometimes the actual source code is easier for me to understand and I have starting looking at that too), so I would posit that you should change your statement to "Reference is written for a person who already has an advanced knowledge of and programs in Raku" Oh and it does not help that a google search of raku this and that turns up 1001 hits on pottery. I have both Windows 7 and Windows 10-20H2 on my system if you want me to run any tests for you. Write me off line. -T
Re: Is the cosine page wrong?
On Tue, Dec 29, 2020, 06:57 ToddAndMargo via perl6-users < perl6-users@perl.org> 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, > > > > > 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. > Would that it were that simple! But since you have some definite ideas about what's wrong, why don't you have a go? What the target audience? It's clear that you are a member, but what about others? I use the documentation every time I program in Raku (or C or php) > > Many thanks, > -T > >
Re: Is the cosine page wrong?
On 12/29/20 12:10 AM, Francis Grizzly Smit wrote: I assume what you need is a set of tutorials for beginners try https://www.google.com/search?channel=fs=ubuntu=raku+programming++for+beginners and hope for the best I guess. sorry I cannot help more just now Hi Francis, I find this one wonderfully well written: https://raku.guide I should stay away from the documentation as much as I can until I get a whole lot better at Raku, in which case I won't need it. My own documentation (Keepers) is getting to the pont where a lot of stuff I need is there. And although not for the faint of heart, I also find source code very enlightening at times too. Raku: source code: https://github.com/Rakudo/rakudo https://github.com/rakudo/rakudo/tree/master/src Thank you for the tips! -T
Re: Is the cosine page wrong?
On 29/12/2020 19:10, Francis Grizzly Smit wrote: On 29/12/2020 18:49, ToddAndMargo via perl6-users wrote: 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" I assume what you need is a set of tutorials for beginners try https://www.google.com/search?channel=fs=ubuntu=raku+programming++for+beginners and hope for the best I guess. sorry I cannot help more just now https://raku.guide/ looks good if you have specific questions some of us here may be able to help. 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 -- .~. In my life God comes first /V\ but Linux is pretty high after that :-D /( )\Francis (Grizzly) Smit ^^-^^http://www.smit.id.au/ -- .~. In my life God comes first /V\ but Linux is pretty high after that :-D /( )\Francis (Grizzly) Smit ^^-^^http://www.smit.id.au/
Re: Is the cosine page wrong?
On 29/12/2020 18:49, ToddAndMargo via perl6-users wrote: 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" I assume what you need is a set of tutorials for beginners try https://www.google.com/search?channel=fs=ubuntu=raku+programming++for+beginners and hope for the best I guess. sorry I cannot help more just now 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 -- .~. In my life God comes first /V\ but Linux is pretty high after that :-D /( )\Francis (Grizzly) Smit ^^-^^http://www.smit.id.au/
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: 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: 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
Re: Is the cosine page wrong?
> 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. >
Re: Is the cosine page wrong?
> On 24 Dec 2020, at 03:55, Matthias Peng wrote: > May I ask if there is any practical perl6 project running? For example, > homebrew by ruby, k8s by go, flask by python etc. https://raku-advent.blog/2020/12/20/day-20-a-raku-in-the-wild/ looks like a practical project to me.
Re: Is the cosine page wrong?
May I ask if there is any practical perl6 project running? For example, homebrew by ruby, k8s by go, flask by python etc. Thanks.
Re: Is the cosine page wrong?
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 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. Once you learn to read them, the definition lines can be really useful. My problem is that they are often incorrect, which put a hammer into learning them. > 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! This look right to me (but keep in mind I don't know what I am doing) method cos( Cool:D: --> Real:D ) These two look wrong to me: method cos() method cos( --> Cool:D ) or --> Real:D Thank you for the wonderful explanation. -T
Re: Is the cosine page wrong?
If a method does not explicitly specify its invocant type, it is set
to the type of the enclosing class.
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 is fine as is for the invocant.
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.
On Mon, Dec 21, 2020 at 12:05 AM ToddAndMargo via perl6-users
wrote:
>
> On 12/20/20 1:18 PM, Bruce Gray wrote:
> >
> >
> >> On Dec 20, 2020, at 2:54 AM, ToddAndMargo via perl6-users
> >> wrote:
> >
> > —snip--
> >
> >> I obviously can't feed it a string.
> >
> > Obviously you cannot, but actually you can!
> >
> > $ raku -e 'say .cos for 42, "42", ("4" ~ "2"), "5421".substr(1,2);'
> > -0.3999853149883513
> > -0.3999853149883513
> > -0.3999853149883513
> > -0.3999853149883513
> >
> > The subroutine form in https://docs.raku.org/routine/cos is declared as:
> > sub cos(Numeric(Cool))
> > and the text specifies:
> > Coerces the invocant (or in sub form, the argument) to Numeric,
> > interprets it as radians, returns its cosine.
> > , so the string “42” is coerced to the number 42 as it is passed to cos().
> > This kind of coercion is not often needed in user code, but the code of the
> > Raku core needs to coerce to maintain a key element of Perl design:
> > * If the coder treats something as a number, then the language acts
> > on it as if it is a number, even if it has to convert a string to a number
> > behind the scenes at runtime.
> > * If the coder treats something as a string, then the language acts
> > on it as if it is a string, even if it has to convert a number to a string
> > behind the scenes at runtime.
> > (BTW, both Perl and Raku use an amazingly efficient auto-caching of this
> > string-vs-number duality; many newcomers think the conversion must be a
> > performance hog, but it is not.)
> >
> > For details on the syntax of automatic coercion during a subroutine call,
> > see:
> > https://docs.raku.org/type/Signature#Coercion_type
> > (Most users never need in their own code, but you saw it by reading the
> > Raku core, so please take that as just for your curiosity and not as a new
> > technique looking for a place in your own designs.)
> >
> >> On Dec 20, 2020, at 2:17 AM, ToddAndMargo via perl6-users
> >> wrote:
> >> https://docs.raku.org/routine/cos
> >> method cos()
> >> Where is the definition of what is fed to the method?
> > —snip—
> > The definition is hiding right in front of us :^)
> > Just like (in another thread) you defined `method BadAdd () {…}`, the `cos`
> > method has open+close parens to show that it has empty Signature. It takes
> > no arguments, and will complain if you try to pass an argument to it.
> > All methods automatically have access to the invoking object, via “self”
> > (and other shortcuts like $.attribute_name).
> > When you call `42.cos`, `42` is the invoking object, and that one value is
> > all that .cos needs.
> >
> >
> >> On Dec 20, 2020, at 2:25 AM, ToddAndMargo via perl6-users
> >> wrote:
> >
> > —snip--
> >
> >> https://github.com/rakudo/rakudo/blob/master/src/core.c/Cool.pm6
> >>
> >> 13: method cos() { self.Numeric.cos }
> >>
> >> Whatever the heck "self” is
> >
> > “self” is the “current” object instance (called the “invocant”).
> > https://docs.raku.org/language/terms#term_self
> > When you define a method in a Class, you are writing sort of abstractly,
> > because at any given time you might have many objects (called “instances”)
> > of that Class, all alive and working in your program at the same time.
> > In most languages that support OO, there is a magic keyword like “this” or
> > “self” that refers to *only* that single instance that called the method.
> > In Raku, “self” is that keyword, but you can override it to a variable name
> > of your choice , if that makes more sense in your code.
> > my Str $a = ’15';
> > my Str $b = '37';
> > say $b.cos;
> > Inside method `cos`, during the .cos call in the code above, “self” is an
> > alias to $b .
> >
> >
> > —
> > Hope this helps,
> > Bruce Gray (Util of PerlMonks)
> >
>
>
> Going back to the original question,
>
> should not the doc page say?
>
> method cos( Cool:D: --> Cool:D )
Re: Is the cosine page wrong?
On 12/20/20 1:18 PM, Bruce Gray wrote:
On Dec 20, 2020, at 2:54 AM, ToddAndMargo via perl6-users
wrote:
—snip--
I obviously can't feed it a string.
Obviously you cannot, but actually you can!
$ raku -e 'say .cos for 42, "42", ("4" ~ "2"), "5421".substr(1,2);'
-0.3999853149883513
-0.3999853149883513
-0.3999853149883513
-0.3999853149883513
The subroutine form in https://docs.raku.org/routine/cos is declared as:
sub cos(Numeric(Cool))
and the text specifies:
Coerces the invocant (or in sub form, the argument) to Numeric,
interprets it as radians, returns its cosine.
, so the string “42” is coerced to the number 42 as it is passed to cos().
This kind of coercion is not often needed in user code, but the code of the Raku
core needs to coerce to maintain a key element of Perl design:
* If the coder treats something as a number, then the language acts on
it as if it is a number, even if it has to convert a string to a number behind
the scenes at runtime.
* If the coder treats something as a string, then the language acts on
it as if it is a string, even if it has to convert a number to a string behind
the scenes at runtime.
(BTW, both Perl and Raku use an amazingly efficient auto-caching of this
string-vs-number duality; many newcomers think the conversion must be a
performance hog, but it is not.)
For details on the syntax of automatic coercion during a subroutine call, see:
https://docs.raku.org/type/Signature#Coercion_type
(Most users never need in their own code, but you saw it by reading the Raku
core, so please take that as just for your curiosity and not as a new technique
looking for a place in your own designs.)
On Dec 20, 2020, at 2:17 AM, ToddAndMargo via perl6-users
wrote:
https://docs.raku.org/routine/cos
method cos()
Where is the definition of what is fed to the method?
—snip—
The definition is hiding right in front of us :^)
Just like (in another thread) you defined `method BadAdd () {…}`, the `cos`
method has open+close parens to show that it has empty Signature. It takes no
arguments, and will complain if you try to pass an argument to it.
All methods automatically have access to the invoking object, via “self” (and
other shortcuts like $.attribute_name).
When you call `42.cos`, `42` is the invoking object, and that one value is all
that .cos needs.
On Dec 20, 2020, at 2:25 AM, ToddAndMargo via perl6-users
wrote:
—snip--
https://github.com/rakudo/rakudo/blob/master/src/core.c/Cool.pm6
13: method cos() { self.Numeric.cos }
Whatever the heck "self” is
“self” is the “current” object instance (called the “invocant”).
https://docs.raku.org/language/terms#term_self
When you define a method in a Class, you are writing sort of abstractly,
because at any given time you might have many objects (called “instances”) of
that Class, all alive and working in your program at the same time.
In most languages that support OO, there is a magic keyword like “this” or
“self” that refers to *only* that single instance that called the method.
In Raku, “self” is that keyword, but you can override it to a variable name of
your choice , if that makes more sense in your code.
my Str $a = ’15';
my Str $b = '37';
say $b.cos;
Inside method `cos`, during the .cos call in the code above, “self” is an alias
to $b .
—
Hope this helps,
Bruce Gray (Util of PerlMonks)
Going back to the original question,
should not the doc page say?
method cos( Cool:D: --> Cool:D )
Re: Is the cosine page wrong?
> On Dec 20, 2020, at 2:54 AM, ToddAndMargo via perl6-users
> wrote:
—snip--
> I obviously can't feed it a string.
Obviously you cannot, but actually you can!
$ raku -e 'say .cos for 42, "42", ("4" ~ "2"), "5421".substr(1,2);'
-0.3999853149883513
-0.3999853149883513
-0.3999853149883513
-0.3999853149883513
The subroutine form in https://docs.raku.org/routine/cos is declared as:
sub cos(Numeric(Cool))
and the text specifies:
Coerces the invocant (or in sub form, the argument) to Numeric,
interprets it as radians, returns its cosine.
, so the string “42” is coerced to the number 42 as it is passed to cos().
This kind of coercion is not often needed in user code, but the code of the
Raku core needs to coerce to maintain a key element of Perl design:
* If the coder treats something as a number, then the language acts on
it as if it is a number, even if it has to convert a string to a number behind
the scenes at runtime.
* If the coder treats something as a string, then the language acts on
it as if it is a string, even if it has to convert a number to a string behind
the scenes at runtime.
(BTW, both Perl and Raku use an amazingly efficient auto-caching of this
string-vs-number duality; many newcomers think the conversion must be a
performance hog, but it is not.)
For details on the syntax of automatic coercion during a subroutine call, see:
https://docs.raku.org/type/Signature#Coercion_type
(Most users never need in their own code, but you saw it by reading the Raku
core, so please take that as just for your curiosity and not as a new technique
looking for a place in your own designs.)
> On Dec 20, 2020, at 2:17 AM, ToddAndMargo via perl6-users
> wrote:
> https://docs.raku.org/routine/cos
>method cos()
> Where is the definition of what is fed to the method?
—snip—
The definition is hiding right in front of us :^)
Just like (in another thread) you defined `method BadAdd () {…}`, the `cos`
method has open+close parens to show that it has empty Signature. It takes no
arguments, and will complain if you try to pass an argument to it.
All methods automatically have access to the invoking object, via “self” (and
other shortcuts like $.attribute_name).
When you call `42.cos`, `42` is the invoking object, and that one value is all
that .cos needs.
> On Dec 20, 2020, at 2:25 AM, ToddAndMargo via perl6-users
> wrote:
—snip--
> https://github.com/rakudo/rakudo/blob/master/src/core.c/Cool.pm6
>
> 13: method cos() { self.Numeric.cos }
>
> Whatever the heck "self” is
“self” is the “current” object instance (called the “invocant”).
https://docs.raku.org/language/terms#term_self
When you define a method in a Class, you are writing sort of abstractly,
because at any given time you might have many objects (called “instances”) of
that Class, all alive and working in your program at the same time.
In most languages that support OO, there is a magic keyword like “this” or
“self” that refers to *only* that single instance that called the method.
In Raku, “self” is that keyword, but you can override it to a variable name of
your choice , if that makes more sense in your code.
my Str $a = ’15';
my Str $b = '37';
say $b.cos;
Inside method `cos`, during the .cos call in the code above, “self” is an alias
to $b .
—
Hope this helps,
Bruce Gray (Util of PerlMonks)
Re: Is the cosine page wrong?
On 12/20/20 12:30 AM, Francis Grizzly Smit wrote: On 20/12/2020 19:17, ToddAndMargo via perl6-users wrote: Hi All, https://docs.raku.org/routine/cos method cos() Where is the definition of what is fed to the method? Should it no be something like: method cos( Cool:D --> Cool:D ) What am I missing? umm it looks right to me a method has a this or self argument (the invocant) so that would be what it operates on i.e. say0.cos; # OUTPUT: «1» saypi.cos; # OUTPUT: «-1» -T -- .~. In my life God comes first /V\ but Linux is pretty high after that :-D /( )\Francis (Grizzly) Smit ^^-^^http://www.smit.id.au/ Hi Francis, Oh I completely know how to use it. I am looking at the doc page and wondering why the definition line is missing. I obviously can't feed it a string. -T
Re: Is the cosine page wrong?
On 20/12/2020 19:17, ToddAndMargo via perl6-users wrote: Hi All, https://docs.raku.org/routine/cos method cos() Where is the definition of what is fed to the method? Should it no be something like: method cos( Cool:D --> Cool:D ) What am I missing? umm it looks right to me a method has a this or self argument (the invocant) so that would be what it operates on i.e. say0.cos; # OUTPUT: «1» saypi.cos; # OUTPUT: «-1» -T -- .~. In my life God comes first /V\ but Linux is pretty high after that :-D /( )\Francis (Grizzly) Smit ^^-^^http://www.smit.id.au/
Re: Is the cosine page wrong?
On 12/20/20 12:17 AM, ToddAndMargo via perl6-users wrote:
Hi All,
https://docs.raku.org/routine/cos
method cos()
Where is the definition of what is fed to the method?
Should it no be something like:
method cos( Cool:D --> Cool:D )
What am I missing?
-T
https://github.com/rakudo/rakudo/blob/master/src/core.c/Cool.pm6
13: method cos() { self.Numeric.cos }
Whatever the heck "self" is
So maybe the manual page should say
method cos( Numeric:D --> Numeric:D )
Is the cosine page wrong?
Hi All, https://docs.raku.org/routine/cos method cos() Where is the definition of what is fed to the method? Should it no be something like: method cos( Cool:D --> Cool:D ) What am I missing? -T
